[GNC-dev] Long Term Documentation Directions

[John Ralls]

> On Sep 11, 2018, at 8:13 AM, David Cousens <davidcousens at bigpond.com> wrote:
> 
> Hi Geert 
> 
> "I know you can define these links in docbook. However my remark earlier in 
> this thread is how will they work in practice ? How can one document on the 
> system know where the other is stored ? I presume this means we should have 
> strict rules about the relative locations of documents. And those should be 
> communicated properly to gnucash-documentation packagers for various 
> distributions"
> 
> The links between different docbook documents can be handled with XML
> catalogues. 
> It looks like you define generic paths for links during the document build
> and use those generic names as the URLs in the code you call to bring them
> up in the program. The generic names are linked by  xsltprocto the actual
> URLs in the catalog.xml  file which resides by default in /etc/xml/catalog
> but can be redirected to something like /usr/share/gnucash/xml/catalog.xml
> with an environment variable  XML_CATALOGUE_FILE during the document build.
> xsltproc appears to construct the links between the files. Not sure how the
> program handles that. I'll keep digging to see what i can come up with.
> 
> Not sure about what happens with the PDF etc  but I think xsltproc uses
> specific  xsl files to process them the same as it does now. 
> 
> (http://sagehill.net/docbookxsl/Catalogs.html#WhyCatalogs)

Well, it's "PDF etc" (where etc. means the various HTML formats including epub, mobi, and chm, in which most users read the docs) that's the issue. Only Yelp directly reads Docbook-formatted documents, so that's not useful to most of our users.

Docbook may well be the eighth wonder of the documentation world but for our purposes it's only a way of marking up document sources. We can't use any of its feature that don't map to HTML and PDF.

Regards,
John Ralls