Difference between revisions of "Documentation Components"
(→Source file templates: GDP 2 vs.GDU) |
(→Processing: Catalogs) |
||
| (14 intermediate revisions by the same user not shown) | |||
| Line 2: | Line 2: | ||
== Supported Output formats == | == Supported Output formats == | ||
| − | + | Our primary target is the context sensitive help <code>F1</code> for the program. It's format is OS dependent: | |
| − | * Docbook for Gnome's Yelp | + | * '''Docbook''' - current source format: |
| − | * HTML | + | ** for ''Gnome'''s Yelp (+ .OMF for its catalog rarian, but only up to yelp version 2.23 [[https://code.gnucash.org/logs/2018/10/14.html#T09:36:39 IRC log]]), |
| − | ** plain for MacOs's browser | + | * '''HTML''' - currently processed by gdp:2002 stylesheets |
| − | ** compiled for Windows help viewer. | + | ** plain for ''MacOs'''s browser, |
| − | Additional supported are for offline reading: | + | ** compiled for ''Windows'' help viewer, |
| + | ** plain for ''KDE'''s Khelpcenter (+ .desktop for its catalog) - currently not implemented. | ||
| + | Additional supported are for offline reading - processed by standard stylesheets: | ||
* PDF | * PDF | ||
* Mobi | * Mobi | ||
* ePub | * ePub | ||
| − | == | + | ==Currently used templates== |
| − | Current Source files have a marker | + | ===Documents=== |
| − | <syntaxhighlight lang="xml"> | + | Current Source files have a marker <syntaxhighlight lang="xml"> |
<!-- | <!-- | ||
(Do not remove this comment block.) | (Do not remove this comment block.) | ||
| Line 23: | Line 25: | ||
--> | --> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | [[User:Fell|Fell]] ([[User talk:Fell|talk]]) considers replacement by [[Gnome Doc Utils]]. | + | |
| + | ===XSL etc.=== | ||
| + | According the [https://github.com/Gnucash/gnucash-docs/blob/maint/xsl/ChangeLog XSL Changelog] it is a slightly adjusted copy of gdp's xsl from 2003. That is the reason some formats of the docs still look like GNOME1. | ||
| + | |||
| + | The architecture of the build system seems to date back to the same roots. | ||
| + | |||
| + | [[User:Fell|Fell]] ([[User talk:Fell|talk]]) considers replacement by it's GNOME2 successor [[Gnome Doc Utils]], which was maintained until 2012. | ||
== Processing == | == Processing == | ||
| + | === XML === | ||
The processing is done by Extensible Stylesheet Language Transformations (XSLT), where <code>xsltproc</code> applies on the elements of the source XML file the instructions of the respective XSL file. | The processing is done by Extensible Stylesheet Language Transformations (XSLT), where <code>xsltproc</code> applies on the elements of the source XML file the instructions of the respective XSL file. | ||
| − | For that reason the repository contains in the <code>xsl</code> directory a copy of docbook-xsl, currently | + | For that reason the repository contains in the <code>xsl</code> directory |
| + | * a copy of '''docbook-xsl''', currently 2018 in version 1.79.2 in a respective named subdirectory and | ||
| + | * in the directories <tt>stylesheet</tt> and <tt>xsl</tt> itself that of the ''GNOME Documentation Project'' from 2002 [[https://github.com/Gnucash/gnucash-docs/commit/f2f6d683b114eccf3eddb37f3d24de0575d5de6e#diff-4204e4de3fc1f8bffa6f77c383d2d6a0 commit changes to move to gdp stylesheets, generate html files in sub…]] . They expect at least DocBook XML 4.1.2, which requires at least docbook-xsl-1.45. | ||
| + | Additional there are .png images in <code>stylesheets</code>, copied from (an old version of) docbook-xslt/images. We should consider an update. | ||
| + | |||
| + | '''xsl/README''' suggests to verify, that | ||
| + | <syntaxhighlight lang="sh"> | ||
| + | xmlcatalog /etc/xml/catalog http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl | ||
| + | </syntaxhighlight> | ||
| + | returns a local path. If not read xmlsoft.org's [http://xmlsoft.org/catalog.html Catalog support] and run the script from [http://xmlsoft.org/XSLT/docbook.html DocBook] | ||
| + | |||
| + | |||
| + | After you installed ''docbook-xsl'' locally, you should have its ''reference documentation'' under <code>file:///usr/share/doc/packages/docbook-xsl-stylesheets/html/index.html</code>. For the ''HowTo'' see Bob Stayton's [http://www.sagehill.net/docbookxsl/index.html DocBook XSL: The Complete Guide]. | ||
| + | |||
| + | Because we use a standard xsl package we should not adjust them or we had to track our patches. Instead we can use a CSS | ||
| + | |||
| + | === Catalogs === | ||
| + | Catalogs hold meta information for faster access. | ||
| + | |||
| + | ==== OMF ==== | ||
| + | Our omf.make has in its header <syntaxhighlight lang="sh"> | ||
| + | # This file was taken from scrollkeeper_example2, a package illustrating | ||
| + | # how to install documentation and OMF files for use with ScrollKeeper | ||
| + | # 0.3.x and 0.4.x. For more information, see: | ||
| + | # http://scrollkeeper.sourceforge.net/ | ||
| + | # Version: 0.1.2 (last updated: March 20, 2002) | ||
| + | </syntaxhighlight> | ||
| + | GDU would have replaced this template by extracting special tags. This was never applied by us. | ||
| + | As said before, it is no longer used by yelp, but it is unknown if they have a replcement. | ||
| − | === Alternatives by yelp === | + | ==== desktop file ==== |
| − | Yelp offers its own tools and stylesheets | + | KDE's Helpcenter would use a XDG desktop file for metainformation. Eventualy a desktop file could be used in other places, too. |
| + | |||
| + | === Alternatives to docbook-xslt === | ||
| + | |||
| + | ==== by yelp ==== | ||
| + | Yelp offers its own tools and stylesheets [https://wiki.gnome.org/Apps/Yelp], which are significant smaller: <code>file:///usr/share/yelp-xsl/xslt</code>. | ||
yelp-build can process | yelp-build can process | ||
| Line 37: | Line 79: | ||
* to: HTML, EPUB, ... | * to: HTML, EPUB, ... | ||
It might be useful to run sometimes <code>yelp-check</code> to verify the compatibility. | It might be useful to run sometimes <code>yelp-check</code> to verify the compatibility. | ||
| + | |||
| + | ==== by GDU ==== | ||
| + | is based on the usually make and has his own xslts, too: | ||
| + | <code>file:///usr/share/xml/gnome/xslt</code> | ||
| + | [[Category:Documentation Development]] | ||
Latest revision as of 20:42, 10 June 2020
The Docbook based Gnucash documentation makes use of several components to produce the different output forms. See also the README file.
Contents
Supported Output formats
Our primary target is the context sensitive help F1 for the program. It's format is OS dependent:
- Docbook - current source format:
- for Gnome's Yelp (+ .OMF for its catalog rarian, but only up to yelp version 2.23 [IRC log]),
- HTML - currently processed by gdp:2002 stylesheets
- plain for MacOs's browser,
- compiled for Windows help viewer,
- plain for KDE's Khelpcenter (+ .desktop for its catalog) - currently not implemented.
Additional supported are for offline reading - processed by standard stylesheets:
- Mobi
- ePub
Currently used templates
Documents
Current Source files have a marker<!--
(Do not remove this comment block.)
Template Maintained by the GNOME Documentation Project:
http://developer.gnome.org/projects/gdp
Template version: 2.0 beta
Template last modified Feb 12, 2002
-->
XSL etc.
According the XSL Changelog it is a slightly adjusted copy of gdp's xsl from 2003. That is the reason some formats of the docs still look like GNOME1.
The architecture of the build system seems to date back to the same roots.
Fell (talk) considers replacement by it's GNOME2 successor Gnome Doc Utils, which was maintained until 2012.
Processing
XML
The processing is done by Extensible Stylesheet Language Transformations (XSLT), where xsltproc applies on the elements of the source XML file the instructions of the respective XSL file.
For that reason the repository contains in the xsl directory
- a copy of docbook-xsl, currently 2018 in version 1.79.2 in a respective named subdirectory and
- in the directories stylesheet and xsl itself that of the GNOME Documentation Project from 2002 [commit changes to move to gdp stylesheets, generate html files in sub…] . They expect at least DocBook XML 4.1.2, which requires at least docbook-xsl-1.45.
Additional there are .png images in stylesheets, copied from (an old version of) docbook-xslt/images. We should consider an update.
xsl/README suggests to verify, that
xmlcatalog /etc/xml/catalog http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl
returns a local path. If not read xmlsoft.org's Catalog support and run the script from DocBook
After you installed docbook-xsl locally, you should have its reference documentation under file:///usr/share/doc/packages/docbook-xsl-stylesheets/html/index.html. For the HowTo see Bob Stayton's DocBook XSL: The Complete Guide.
Because we use a standard xsl package we should not adjust them or we had to track our patches. Instead we can use a CSS
Catalogs
Catalogs hold meta information for faster access.
OMF
Our omf.make has in its header# This file was taken from scrollkeeper_example2, a package illustrating
# how to install documentation and OMF files for use with ScrollKeeper
# 0.3.x and 0.4.x. For more information, see:
# http://scrollkeeper.sourceforge.net/
# Version: 0.1.2 (last updated: March 20, 2002)
GDU would have replaced this template by extracting special tags. This was never applied by us. As said before, it is no longer used by yelp, but it is unknown if they have a replcement.
desktop file
KDE's Helpcenter would use a XDG desktop file for metainformation. Eventualy a desktop file could be used in other places, too.
Alternatives to docbook-xslt
by yelp
Yelp offers its own tools and stylesheets [1], which are significant smaller: file:///usr/share/yelp-xsl/xslt.
yelp-build can process
- from: Mallard, DocBook, man, info, and HTML documents
- to: HTML, EPUB, ...
It might be useful to run sometimes yelp-check to verify the compatibility.
by GDU
is based on the usually make and has his own xslts, too:
file:///usr/share/xml/gnome/xslt
