opensuse / suse-xsl Goto Github PK
View Code? Open in Web Editor NEWDocBook XSL Stylesheets for SUSE branding
License: Other
DocBook XSL Stylesheets for SUSE branding
License: Other
@tomschr I was transforming our DAPS Quick-Start Guide into the pdf grayscale format but there are some remaining colored lines left.
Command: daps -vv -d DC-daps-quick pdf --grayscale
From @tomschr on March 3, 2015 15:13
Reported by fsundermeyer on 2013-05-21 14:30 UTC
Support Arabic as good as possible by providing an Arabic localization file for DAPS.
The stylesheet package needs a dependency on the kacst-fonts font package (if these fonts are sufficient).
Copied from original issue: openSUSE/daps#153
Since DocBook 5, we can use the <revhistory>
element to markup our documentation changes. This has some benefits:
<info>
The lifecycle would be:
revision
element and describe your changes.revnumber
.Let's say, we have this XML snippet for <revhistory>
in a file:
<info>
<revhistory>
<revision>
<revnumber>1.1</revnumber>
<date>2015-07-17</date>
<revdescription>
<para>Rewrote section A, B, and D.</para>
</revdescription>
</revision>
<revision>
<revnumber>1.0</revnumber>
<date>2014-07-17</date>
<revdescription>
<para>Added new section ABC</para>
</revdescription>
</revision>
</revhistory>
</info>
Some rules which needs to be checked if they are applicable:
revhistory
. However, this is a pure readability issue and not a technical one.use.revnumber
which can (and should) be set to a specific revision number (matches the <revnumber>
element).revhistory
elements.revision
elements which is equal to $use.revnumber
and the content in <revnumber>
.revision
elements appear in document order.For example, if we would set $use.revnumber=1.1
only the first entry ("Rewrote section A, B, and D") will be used. The second is discarded and will not appear in the output.
Our susedoc schema does not have prompt
. We should add this.
From @tomschr on March 3, 2015 15:19
Reported by tom_schr on 2013-09-17 12:41 UTC
Our stylesheets (for both HTML and FO) use a customized version of the xref template. They resolve links to "foreign" books in a set if you are only interested in a specific book.
The code in this template is verbose and overly complicated. After 1.78.2 version of the original stylesheets is released, the code should be refactored and use the xref-to-suffix mode.
Copied from original issue: openSUSE/daps#177
From @tomschr on March 3, 2015 15:15
Reported by fsundermeyer on 2013-06-10 11:44 UTC
HIGH Priority:
The stylesheets are lacking FOP support for the following languages:
Please fix. Make sure the changes are also applied to the new stylesheets developed by Stefan.
Copied from original issue: openSUSE/daps#158
Error at xsl:stylesheet on line 20 of file:/usr/share/xml/docbook/stylesheet/suse2013-ns/fo/fo.xsl:
Namespace prefix d has not been declared
Transformation failed: Failed to compile stylesheet. 1 error detected.
remake: *** [/data/git/doc-cloud/build/.tmp/susecloud-all-fop_color_en.fo] Error 2
From @tomschr on March 3, 2015 12:32
Reported by fsundermeyer on 2012-05-09 13:42 UTC
Currently this feature only exists for HTML builds when using --remarks or --meta.
We should make this avilable for PDF builds as well - according to tom_schr the
SUSE stylesheets already support it.
Copied from original issue: openSUSE/daps#74
Currently, the parameter is definied as runinhead.default.title.end.punct='.'
by default. This is unfortunate, as other languages needs other characters.
For example, Chinese and Japanese require a double-byte colon character here: (:
) (U+FF1A).
It is probably a good idea to do the same for the parameter runinhead.title.end.punct
.
Things to do:
common/l10n/
; for example, the en.xml
file should contain the following line: <l:gentext key="runinhead.default.title.end.punct" text="."/>
fo/block.xsl
and replace <xsl:value-of select="$runinhead.default.title.end.punct"/>
with the code below.xhtml/block.xsl
and copy the code from the original template in /usr/share/xml/docbook/stylesheet/nwalsh/current//xhtml/block.xsl
. Adapt the copied code as shown for fo/block.xsl
.Code:
<xsl:call-template name="gentext">
<xsl:with-param name="key" select="'runinhead.default.title.end.punct'"/>
</xsl:call-template>
Titles of admonitions look too prominent compared to e.g. sect3, especially on b/w printouts.
Removing bold might be enough. Then again, we need to make sure that contrast is good enough on color printouts too.
(Brought up by toms.)
From @tomschr on March 3, 2015 12:35
Reported by fsundermeyer on 2012-07-13 08:27 UTC
http://doccookbook.sf.net/html/en/dbc.html.sh.google-code-prettifiy.html describes how to implement Code Syntax Highlighting for HTML documents.
Would be nice to have it in DAPS.
License issues for the HTML buuilds shipping with CSS and JS from Google Code Prettify need to be checked first.
Copied from original issue: openSUSE/daps#86
How to reproduce:
<example><title/><screen/></example>
as HTMLThis is caused by the title above which is using negative margin trickery. While the negative margin trickery must end anyway, because it leads to bad UX, like text that is not selectable etc., this bug is just fixing about this small symptom.
From @tomschr on March 3, 2015 14:2
Reported by tom_schr on 2013-02-26 16:20 UTC
At the moment, $base.dir is not really correctly implemented IMHO.
It is set to the "OEBPS/" string by default. This is very annoying as you set $base.dir to an absolute path and create all the files in it. You have to change the directory before applying the stylesheets (as the Ruby dbtoepub script does).
TODO: Make all the parameters which rely on output directory or filenames relative to $base.dir ($img.src.path, $admon.graphics.path, $callout.graphics.path, etc.)
Copied from original issue: openSUSE/daps#134
Add xi:xincludes to susedoc. The code should already be in schema/novdocxi.rnc
In our HTML, each section (or title) contains a "Report Bug" link. At the moment, this points to Bugzilla. It would be nice, to make this customizable, for example, to link to GitHub.
At the moment, this file is responsible for that: suse2013/static/js/script.js
@jcayouette Is that good enough?
From @tomschr on March 3, 2015 17:50
Reported by taroth21 on 2013-11-28 16:49 UTC
I just had the case of a listitem that included a URL at the end and only some words in front of the URL that would not fill a line completely. As URLs must not be wrapped in XEP, the URL is moved to the second line but the text in the first line is abnormally stretched which looks weird. (For an example, build the "Documentation Update" appendix of the current DAPS User Guide and look for "EpubCheck"). When using FOP instead, the text in front of the URL appears normal, but the URL is wrapped to the next line.
Copied from original issue: openSUSE/daps#199
From @tomschr on March 3, 2015 11:47
Reported by tom_schr on 2012-02-03 14:50 UTC
The parameter ulink.hyphenate is used to allow URLs to be hyphenated automatically. Usually it is set Zero Width Space (ZWS, U+200B). This ZWS is included in certain positions (like before '/' or '-') to mark a hyphenation possibility. The complete URL is set to hyphenate=false to avoid breaking it in the middle of a word.
However, it does not work for FOP as advertised. It is creates overly long spaces like this:
| The quick brown fox jumps over the lazy dog. See /usr/share/doc/ |
| packages/lazy-dog/README. for more |
| information.
For the time being, ulink.hyphenate is set to '' for FOP. Other formatters get their ZWS.
Marking this ticket as 'pending'. It "works", but it looks not nice. Maybe future versions of FOP can improve this situation.
See also https://bugzilla.novell.com/show_bug.cgi?id=706452
Copied from original issue: openSUSE/daps#33
From @tomschr on March 3, 2015 17:58
Reported by taroth21 on 2014-05-13 14:53 UTC
Our proofreaders spotted a (rare) cornercase in the PDF layout where a discontinued underline in the following command can lead to a misinterpretation of the dot in "package.rpm" as a full stop for the sentence (see attachment, p. 15, proofing comment by Jack):
Normally, the installation of an RPM archive is quite simple:
rpm -ipackage.rpm.
For the source code, see http://svn.opensuse.org/svn/opensuse-doc/trunk/documents/sle/en/xml/rpm.xml, line 111.
In the HTML layout, the whole command is underlined completely (which is correct).
Copied from original issue: openSUSE/daps#225
From @tomschr on March 3, 2015 17:56
Reported by tom_schr on 2014-01-30 09:52 UTC
Currently, we don't use any syntax highlighting (SH) in our documents. We should think about this, if this is worth to investigate more.
We need two things:
At the moment, SH in DocBook is done by a Saxon extension from the XSLTHL project. You need to add the JAR file into the classpath and basically it works.
However, XSLTHL has some drawbacks:
Another alternative could be to implement a replacement for xsltproc as a Python script using lxml. That way, we could integrate pygments as SH.
Copied from original issue: openSUSE/daps#216
From @tomschr on March 3, 2015 15:26
Reported by taroth21 on 2013-10-17 12:46 UTC
An itemizedlist with a title and an ID gets a permalink in the HTML output, whereas a variablelist (also equipped with ID and title) currently does not get one. I believe that treatment is unfair ;), therefore please fix it.
Copied from original issue: openSUSE/daps#185
From @tomschr on March 3, 2015 11:48
Reported by tom_schr on 2012-02-07 09:42 UTC
The original DocBook XSL stylesheets have been documented through a Literate Programming mechanism. Investigate how this can be used to improve developer documentation.
Useful links:
Copied from original issue: openSUSE/daps#37
From @tomschr on March 3, 2015 15:7
Reported by fsundermeyer on 2013-04-04 09:30 UTC
<varlistentry>
<term>FOO</term>
<term>BAR</term>
<listitem>...</listitem>
</varlistentry>
Shows up like this in the PDF:
FOO , BAR
FOO[:space],[:space:][:space:]BAR
Should be
FOO, BAR
FOO,[:space:]BAR
Copied from original issue: openSUSE/daps#145
From @tomschr on March 3, 2015 12:41
Reported by tom_schr on 2012-08-11 15:50 UTC
Currently, the Webhelp output from the upstream DocBook stylesheet project is refactored by a Google Summer of Code student.
After this is done, we need to look at it again and change or adapt our customizations to the latest code base.
Copied from original issue: openSUSE/daps#93
When we set an ID to a variablelist/varlistentry
, no permalink is created. It would be useful to propagate the ID into a permalink in HTML.
From @tomschr on March 3, 2015 15:15
Reported by keichwa on 2013-06-17 12:54 UTC
If building with fop, suse xsl style-sheets break pages between a sect1 title and the following para.
Copied from original issue: openSUSE/daps#160
From @tomschr on March 3, 2015 15:14
Reported by tom_schr on 2013-05-28 13:05 UTC
This ticket just collects some information about a migration of our sources and toolchain to DocBook 5.
DocBook 5.x is the successor of DocBook 4. Any future changes will be integrated into version 5, the former is in maintenance mode.
There are some changes between DocBook 4 and DocBook 5. Although they are not really difficult, it's important to know. Here are the major changes:
Find more changes at http://docbook.org/tdg51/en/html/ch01.html#introduction-whats-new and http://docbook.org/docs/howto/#changes.
Currently, DAPS supports validation of DocBook 5 files with jing already.
We need to create a special version of Novdoc for DocBook 5; see also openSUSE/daps#179. The primary schema language is RELAX NG (probably the compact version). DTD is derived from the RNC version.
The current customization doesn't recognize the DocBook 5 namespace.
Use the stylesheet https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxng/tools/db4-upgrade.xsl to upgrade your DocBook 4 document.
Copied from original issue: openSUSE/daps#155
Bug tracker information is tracked in DocManager. However, this is only possible for DocBook5. For DocBook4, this is not possible as we need to add these elements into Novdoc schema (which we would like to avoid).
One way to do it is to add the following PI before the root element:
<?suse-bugtracker url="https://bugzilla.suse.com/enter_bug.cgi"
product="SUSE Linux Enterprise Server 12 in Public Clouds"
component="Other"
?>
The pseudo-attributes (url
, product
, etc.) mean the same as the DM elements (dm:url
, dm:product
, etc.)
The stylesheet first searches for DM elements in the DM namespace urn:x-suse:ns:docmanager
. If it cannot find a bugtracker URL, it falls back to searching for the above PI.
Normally, formalparas use dots (".") at the end of the title.
We also have some documentation that (inconsistently) uses colons at the end of formalpara titles (e. g. apps_evolution.xml).
<formalpara>
<title>Something:</title>
<para>Something something.</para>
</formalpara>
However, I almost think it would make sense to use colons as the default. And it should be easy too, toms remembered that there was some kind of parameter.
Currently, productname
and productnumber
has to be included in book
and article
. This is ok, but if you have a set of books or articles, it would be convenient to add this information only once into setinfo
.
The following rules should be applied:
bookinfo
with productname
and productnumber
. If found use it.articleinfo
with productname
and productnumber
. If found use it.productname
and productnumber
cannot be found, use the parent element:
book/bookinfo
set/setinfo
productname
and productnumber
can be found, display an error/warning message.https://bugzilla.suse.com/show_bug.cgi?id=937209
When building PDF for zh_CN, the text is too small.
Maintaining CSS can be tedious and error-prune.
Maintaining our CSS with SASS (Syntactically Awesome Stylesheets) could make life a bit easier. SASS is a preprocessor and compiles a SASS script into CSS. SASS supports variables, mixins (kind of functions), and more.
rubygem-sass
From @tomschr on March 3, 2015 15:14
Reported by tom_schr on 2013-05-29 12:50 UTC
The Chinese openSUSE fonts should go to Factory too.
Additionally, check if we could use the openSUSE fonts for SLE too (replace ttf-founder-simplified with wgy-*)
Copied from original issue: openSUSE/daps#156
The new stylesheets should be able to display the following metadata:
Maybe it would also be useful to display all metadata that is available within the document (for example, as a table: key - value)
From @tomschr on March 3, 2015 12:35
Reported by tom_schr on 2012-07-18 06:43 UTC
Building the JSP output gives me the following output (example for SUSE Manager):
Writing /local/doc/opensuse-doc/documents/susemanager/en/build/susemanager-reference/jsp/susemanager-reference/reference/en-US/cha.manager.glossary.jsp for glossary(cha.manager.glossary)
Writing /local/doc/opensuse-doc/documents/susemanager/en/build/susemanager-reference/jsp/susemanager-reference/reference/en-US/index.jsp for book(book.susemanager.ref)
However, the final message locates the book in a different place:
Find the JSP book at:
/local/doc/opensuse-doc/documents/susemanager/en/build/susemanager-reference/jsp/susemanager-reference/index.jsp
Copied from original issue: openSUSE/daps#87
From @tomschr on March 3, 2015 17:56
Reported by sknorr on 2013-12-18 15:28 UTC
We need some way to reliably get SVGs into DAPS-created PDFs.
Converting SVGs to PDFs first and then embedding those PDFs into the final output PDFs is clearly not an option (because PDF embedding is even more buggy than SVG embedding). We should find a way to convert SVGs to a maximally compatible subset of tags.
Copied from original issue: openSUSE/daps#212
From @tomschr on March 3, 2015 11:41
Reported by tom_schr on 2012-01-26 19:49 UTC
We have some stylesheets which extracts different information (like image paths, document structure, etc.). These "administrative" stylesheets currently supports DocBook 4 only.
These stylesheets has to be improved to also match for DocBook 5 elements.
Copied from original issue: openSUSE/daps#28
From @tomschr on March 3, 2015 17:51
Reported by taroth21 on 2013-12-09 09:42 UTC
In the EPUB stylesheets, the information about product name and product version should be provided next to the book title.
Currently, it is missing, that's why I received the following mail:
"Actually, I would ask that the product name be in the title. If you download the ePub editions of the documentation for all of our products, it feels like half of them are called "Administrator's Guide" or some variant of that. Thus, you end up opening 3-4 of them looking for the one that is for the product you're looking for."
Copied from original issue: openSUSE/daps#206
At the moment, we don't have any test suite for FO/PDF. This is unfortunate as we do not know when we create a regression, for example, when the FO renderer doesn't find the correct CJK fonts (which leads to # marks throughout the document).
In theory, we could use OpenCV to create a test driven PDF development cycle. OpenCV is used by the openQA team, written in this article.
The procedure would be:
Hi,
if you create a PDF documentation with
daps -vv -d DC-SLE-RT-shielding pdf
the documentation contains a wrong company name:
SUSE Linux Products GmbH
I think this is a stylesheet problem.
The footer used to have the productname in it. However, then came DB5, and with it, {article,book,set}info
were replaced by just info
.
The product
template started to fail and it seems that was not corrected, just adjusted for in some parts of the stylesheets. Another aspect of this is that the productname is not displayed anymore on the title page of books.
The footer should also better handle the case when there really is no productname.
From @tomschr on March 3, 2015 17:51
Reported by tom_schr on 2013-12-06 14:36 UTC
The HA guide contains in ha_nfs_quick_config_i.xml a kind of "mini toc" where xrefs are listed in an ordered list.
However, the xrefstyle attribute seems not to be recognized at all. The stylesheets resolve it always as
Section "Defining Authentication Settings, Chapter 3, Installation and Basic Setup, High Availability Guide
With the xrefstyle attribute, the expected output would be:
Section "Defining Authentication Settings"
Fixing it would probably also involve talking to upstream.
Copied from original issue: openSUSE/daps#205
From @tomschr on March 3, 2015 18:4
Reported by fsundermeyer on 2014-10-21 16:31 UTC
Token ';' not allowed here, expecting a property value
value of attribute "width" is invalid; must be an integer
<colgroup>
<col style="width: ; " class="1"/>
<col style="width: ; " class="2"/>
<col style="width: ; " class="3"/>
</colgroup>
could not parse OEBPS/part.virt.intro.xhtml: duplicate id: part.virt.intro'
<div class="part" title="Part I. Introduction" epub:type="part" id="part.virt.intro">
<div class="titlepage"><div><div><h1 class="title" id="part.virt.intro">
This file should declare in opf the property: svg
????
<img class="symbol" alt="Note" title="Note" src="static/images/icon-note.svg"/>
<item id="idm140486407262576" href="static/images/icon-note.svg" media-type="image/svg+xml"/>
OEBPS/toc.ncx fragment identifier is not defined in 'OEBPS/cha.kvm.inst.xhtml'
<navPoint id="idm140084606559568" playOrder="44">
<navLabel><text>Memory Ballooning with Windows Guests</text></navLabel>
<content src="cha.kvm.inst.xhtml#libvirt.advanced.balloon"/>
</navPoint>
hyperlink to resource outside spine 'OEBPS/xen_master_fong_a.png'
hyperlink to non-standard resource 'OEBPS/kvm_qemu.png' of type 'image/png'
<div class="figure-contents">
<div class="mediaobject">
<a href="xen_master_fong_a.png">
<img src="xen_master_fong_a.png" width="" alt="Xen Virtualization Architecture"/>
</a>
</div>
</div>
'gloss.vt.lxc.chroot': fragment identifier is not defined in 'OEBPS/gloss.vt.glossary.xhtml'
<a class="xref" href="gloss.vt.glossary.xhtml#gloss.vt.lxc.chroot" title="chroot">chroot</a>
Copied from original issue: openSUSE/daps#241
From @tomschr on March 3, 2015 12:23
Reported by taroth21 on 2012-03-23 08:58 UTC
Currently, the number of structure levels visible in both the TOC and the left-hand side TOC for navigation (in PDFs, etc.) is fixed. But to allow for customization, a parameter for the level of detail should be added. That would allow to define the visible section levels individually (e.g. up to sect2, up to sect3 or up to sect5).
Copied from original issue: openSUSE/daps#57
Idea discussed with @jcayouette
Let's assume we have a glossary with lots of glossary items (glossentry
in DocBook's lingo). Usually, when you create HTML from your DocBook sources, it resolves an glossterm
or firstterm
in your paragraph and points to the corresponding glossary item. That's easy as it's a 1:1 relationship. So far, so good.
However, sometimes, it is needed to make the reverse: link from the glossary to the first(!) glossterm
or firstterm
where it's mentioned. This needs a little bit more effort as it's a 1:n relationship.
This can be done with xsl:key
efficiently. A first working proof of concept can be found here:
https://gist.github.com/tomschr/e4debf714d2149ede1e8
TODO: Integrate it into the DocBook stylesheets:
glossary.backlink
) to param.xsl
so we can switch on/off this feature (some don't like it or don't need it).glossary.xsl
and the template rule glossentry
.Using qandaset
and structuring with qandadiv
, the title of qandadiv
appears to be printed in black and bold (instead of using a more greenish style) for PDF.
From @tomschr on March 3, 2015 17:48
Reported by sknorr on 2013-11-12 16:45 UTC
It seems, DAPS now adds copious amounts of whitespace to certain screens.
E.g. in the SUSE cloud admin guide (File: xml/admin_dashboard.xml
+1117), we have this humble screen:
<screen><replaceable>DESTINATION_CIDR</replaceable>,<replaceable>NEXTHOP</replaceable></screen>
Which is turned into this after profiling (File: build/.profiled/p_sles/admin_dashboard.xml
+2760)*:
<screen>
<replaceable>DESTINATION_CIDR</replaceable>,<replaceable>NEXTHOP</replaceable>
</screen>
Copied from original issue: openSUSE/daps#192
From @tomschr on March 3, 2015 17:51
Reported by sknorr on 2013-12-02 16:06 UTC
Somewhere, there appears to be a bug that leads to the en dash being used in place of an em dash.
This happens in both HTML and PDF (FOP and XEP) output and with both Saxon and Xsltproc.
Copied from original issue: openSUSE/daps#202
From @tomschr on March 3, 2015 12:41
Reported by taroth21 on 2012-07-30 13:20 UTC
When using a xref element that points to the title of a variablelist,
the variablelist's title appears in PDF output, but the page number cannot be resolved or shown: the xref is followed by: "(page ?)". This is not an effect of building with ROOTID, checked that already.
Copied from original issue: openSUSE/daps#91
Needs to be done... output is <span class="package">...</span>
.
Not sure if PDF is affected.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.