Hi Gil, any chance for your next posting to get an idea of what you have done and come up to? Maybe with a bird eyes's view how you now would suggest to create the documentation according to your analysis, tests?
Also, would you have already suggestions for the software to use, e.g. xsltproc (how about using Apache Xalan [1] for this), the FOP is probably Apache FOP [2]. Guessing that everyone has been waiting eagerly for your next insights and directions of how to duplicate your efforts to successfully create the documentation! :) ---rony [1] Apache Xalan Project: <https://xalan.apache.org/> [2] Apache FOP: <https://xmlgraphics.apache.org/fop/> On 06.01.2020 20:07, Gil Barmwater wrote: > 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. > _______________________________________________ Oorexx-devel mailing list Oorexx-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/oorexx-devel
