This thread is a continuation of the thread titled "Questions ad
generating the documentation (publican, pandoc)" with a different
Subject since Pandoc is no longer being considered as an alternative.
To review, the ooRexx documentation is written in DocBook and has been
turned into PDFs and HTML files using a system called Publican,
originally developed by RedHat. Publican is no longer supported and
works only occasionally under Windows 10. Under the covers, Publican
transforms the DocBook XML into XSL-FO using xsltproc, probably the Perl
bindings based on comments by Erich, and modified DocBook stylesheets.
It then runs the FOP program to convert the xsl-fo output into a PDF
file. In between those two steps, we run a Rexx program written by Erich
to remove extra blank lines from the examples.
The new process uses the latest XSLTPROC programs directly along with
the latest version of FOP. However, Publican imposes some unique
structure to the DocBook XML which must be accounted for. Publican has
the concept of a "brand" which lets one define common text and graphics
that should appear the same in all of a project's documentation. One
denotes those common text/graphic files in the XML by preceding their
names with "Common_Content/". As Publican merges the various parts of
the document together so that it can be transformed by the stylesheets,
it resolves any references to Common_Content so that the correct file is
merged into the complete source. As this process is unique to Publican,
we must account for it in order to use XSLTPROC instead.
One approach we could take would be to replace Common_Content/ with
either a relative or absolute path to the location in our source tree
where the files actually are located. For the sake of this discussion, I
will assume the working copy of the documentation has been checked out
to a directory named docs. Then the main xml file for the rxmath book
would be located at docs\rxmath\en-US\rxmath.xml. And the files
referenced by Common_Content would be in docs\oorexx\en-US\. The
relative path would then be ..\..\oorexx\en-US\. The only problem with
this approach is the number of places this would need to be changed. My
analysis shows over 140 locations in over 50 files.
A more expedient approach, and the one I would advocate, is to create a
"temporary" sub-directory for the purpose of building the documentation
and then to copy everything from docs\oorexx\en-US\ into it. So if one
were going to build the rxmath book, one would create
docs\rxmath\en-US\Common_Content\ and copy into it. This allows XSLTPROC
to locate the files that need to be merged without having to make any
changes to our source. The disadvantage is that one needs to do this for
each book being built. It is however a simple step that can be done
either with File Explorer or automated using the xcopy or robocopy commands.
Having gotten by the Common_Content issue, running XSLTPROC reveals
another problem caused by the way Publican does the merge of the
Common_Content files which I will describe in the next posting.
--
Gil Barmwater
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
