Dear Gil, This is great news! I will gladly go over your version of rexxref.pdf with a magnifying glass (Beyond Compare) and compare it with the version I have made using Publican.
If you want to do some comparisons as well I have all the Docs in my Dropbox here: https://www.dropbox.com/sh/p66c7g01h4jz5ss/AAAZd_Q2yQddrTHagxPo_UiTa?dl=0 <https://www.dropbox.com/sh/p66c7g01h4jz5ss/AAAZd_Q2yQddrTHagxPo_UiTa?dl=0> In a folder ooRexxDocs In order to make the comparison meaningful we should be using the same build, please let me know which one you have done and I will rebuild mine using the same. Hälsningar/Regards/Grüsse, P.O. Jonsson oor...@jonases.se > Am 19.02.2020 um 22:29 schrieb Gil Barmwater <gbarmwa...@alum.rpi.edu>: > > And we have success! I found the reason for my previous failure and a way > around it that only involved one change to a parameter in the stylesheet. At > P.O.'s suggestion, I also bumped up the heap space for FOP to 1536Mb (my > laptop couldn't support 2Gb). The resulting PDF appears almost identical to > the most recent version on Source Forge - same number of pages, no extra > lines in the examples, railroad diagrams are good - but I get more entries in > the Table Of Contents. This has been the case with all the documents I've > built so I suspect something has changed in the DocBook stylesheets; the > Publican process uses an old version I believe as I see one in the > windows-build-tools directory on SVN while my process retrieves it from the > web. I suspect that most folks would prefer the "current" style of TOC so I > will continue to investigate this issue. If anyone is interested in going > over the rexxref PDF I built with a fine tooth comb to see if there are other > issues, I will zip it up and put it in my Dropbox. In the meantime, I will > update the package files that I've modified in order to make this work and > zip them up into a package that folks can download and try. Stay tuned... > > Gil B. > On 2/17/2020 11:59 AM, P.O. Jonsson wrote: >> Dear Gil, >> >> Have you tried an even higher value? When I built using Publican it balked >> at 950 kb (value set be Erich I think) for rexxref so I raised it to 2 GB >> and then it passed. It is worth a try, memory is not a bottleneck nowadays >> :-) >> >> Hälsningar/Regards/Grüsse, >> P.O. Jonsson >> oor...@jonases.se <mailto:oor...@jonases.se> >> >> >> >>> Am 17.02.2020 um 15:12 schrieb Gil Barmwater <gbarmwa...@alum.rpi.edu >>> <mailto:gbarmwa...@alum.rpi.edu>>: >>> >>> An update on my progress is long overdue but Real Life sometimes gets in >>> the way! >>> >>> I have "put the pieces together" and zipped them up along with two files of >>> documentation and have been able to take that package to another computer, >>> install it and successfully build the rxmath book. I also researched the >>> article on Java heap space and found a way to specify a larger value - >>> currently using 1GB - without having to change the FOP package. Then, >>> because I know that folks will want to build the rexxref book right away, I >>> decided to try it, mainly to see if 1GB would be large enough. And, of >>> course, it failed! But the problem was not with FOP but rather with the >>> xsltproc step. It seems that the Publican stylesheet is looking for a piece >>> of Perl code which is obviously not present. So I'm back in debug mode, >>> trying to determine what tag rexxref is using that wasn't used by rxmath >>> and then what I can do about it. If I can get the rexxref book to build, I >>> will make the tool package available so we can find any other problems that >>> may be lurking. >>> >>> Gil B. >>> >>> On 1/30/2020 10:26 AM, Rony G. Flatscher wrote: >>>> Dear Gil: >>>> >>>> thank you *very* much for this interesting and informative update! Looking >>>> forward to your tooling! :-) >>>> >>>> --- >>>> >>>> Ad "Java heap space": just skim over >>>> <https://alvinalexander.com/blog/post/java/java-xmx-xms-memory-heap-size-control >>>> >>>> <https://alvinalexander.com/blog/post/java/java-xmx-xms-memory-heap-size-control>>. >>>> >>>> Maybe helpful: there are two command line help information given by Java, >>>> one ("java --help") the >>>> default help, and another giving extended help ("java -X") which documents >>>> the switches for >>>> controlling the heap size Java should reserve. >>>> >>>> Best regards >>>> >>>> ---rony >>>> >>>> >>>> On 29.01.2020 21:38, Gil Barmwater wrote: >>>>> Previously I wrote: One other bit of good news is that the combination of >>>>> these patches and the >>>>> Common_Content sub-folder work-around are the only required changes in >>>>> order to use the XSLTPROC >>>>> and FOP tools to successfully build our documents. I will describe that >>>>> process in my next post. >>>>> ... >>>>> >>>>> So this is that next post but I am replying to Rony's post as I wanted to >>>>> also address the >>>>> questions that he raised. The process I came up with is very similar to >>>>> that used with the >>>>> Publican tools - run a transform tool, either Publican or XSLTPROC, to >>>>> create an XSL-FO file from >>>>> our Docbook/XML files and a (modified) Docbook stylesheet. Run an ooRexx >>>>> program written by Erich >>>>> to remove extra blank lines in the .fo file. Run FOP to create a PDF from >>>>> the (modified) .fo file. >>>>> But as always, the devil is in the details. >>>>> >>>>> I chose XSLTPROC as several web sites suggested it although other tools >>>>> like Xalan were mentioned >>>>> as well. I was attempting to follow some step by step directions for >>>>> building a PDF from Docbook >>>>> source but, of course, those web sites are never up to date and I had to >>>>> adapt the directions as I >>>>> encountered problems. I also wanted to minimize the number of changes to >>>>> our Publican process as >>>>> we are generally happy with the results it produces. So substituting >>>>> XSLTPROC for Publican as the >>>>> XSL transform tool seemed a good starting point. Likewise, I kept the >>>>> Publican stylesheet - an >>>>> override to the standard Docbook stylesheet - that we had further >>>>> modified but I was able to >>>>> eliminate a part of it as Docbook had corrected a problem that it was >>>>> fixing, something to do with >>>>> footnote spacing. And, of course, I used the most current versions of the >>>>> tools that were >>>>> available, both for XSLTPROC and FOP (ver. 2.4). >>>>> >>>>> Now I know that some folks are "chomping at the bit" to replicate what I >>>>> have done but before you >>>>> run off and start searching for the tools to download, let me give you a >>>>> list of the "pieces" that >>>>> are needed. First there is the XSLTPROC transform tool: this is actually >>>>> 4 packages(!) which need >>>>> to be downloaded, unzipped, and the executable folders (bin) added to the >>>>> path. Then of course >>>>> there is the FOP package which needs to be downloaded, unzipped and the >>>>> appropriate sub-folder >>>>> added to the path. In order to get the same "look" to the documents as >>>>> produced by Publican, you >>>>> need to add some special fonts - 2 packages - to your system. And then >>>>> there are the two Publican >>>>> stylesheets, one of which has been modified, and a configuration file for >>>>> FOP so that it can find >>>>> the graphic files to be included and use the special fonts that were >>>>> installed. Finally, you need >>>>> to retrieve the blank-stripping program by Erich from the SVN repository. >>>>> And once you have all >>>>> the "pieces" in place, you need to checkout the latest version of the >>>>> documents from SVN, copy the >>>>> "common" folder to the working copy for the book you will be building and >>>>> add the fop >>>>> configuration file to it. Then you can run xsltproc, the blank-line >>>>> stripping program and then >>>>> FOP. Piece of cake! >>>>> >>>>> Because the above might seem overwhelming(!), I have been developing a >>>>> "package" that simplifies >>>>> it to a large degree. If you were to use this package, it contains all >>>>> the "pieces" and a set of >>>>> CMD files to execute the process steps. It is designed to be unzipped >>>>> into a folder that will >>>>> become the working location for building one or more? documents. After >>>>> installing it, you would >>>>> need to install the fonts (included) and then you could build a document. >>>>> The first cmd file to be >>>>> run is DOCPATH which takes one argument - the path to the SVN working >>>>> copy of the documents. That >>>>> path is saved in an environment variable for use by the remaining steps. >>>>> Then you run DOCPREP >>>>> which also takes one argument - the name of the "book" you want to build, >>>>> e.g. rxmath. It takes >>>>> care of creating the "Common_Content" sub-folder and adding the FOP >>>>> configuration file to it as >>>>> well as saving the document name in another environment variable. Next >>>>> you run DOC2FO which runs >>>>> the transform step. And finally, FO2PDF which runs FOP. The .fo file, the >>>>> .pdf file and a .log >>>>> file containing all the (many) messages from FOP are placed in a >>>>> sub-directory named e.g. out-rxmath. >>>>> >>>>> The cmd files are written and have been tested on the rxmath "book". I >>>>> need to put the pieces >>>>> together and zip them up which is my next step. Then I will provide a >>>>> link so anyone interested >>>>> can download it and give it a try. Note that I have NOT tried this on any >>>>> other "books" so I >>>>> expect there will be issues with some of them. E.g. as P.O. noted in a >>>>> different thread and >>>>> mentioned by Erich as well, the Java heap space needs to be increased for >>>>> some of our documents. I >>>>> do not know how to do that <blush> but it was not necessary for the >>>>> rxmath book. Any other issues >>>>> should be "book-related", not process-related and can be fixed as they >>>>> are uncovered. And any >>>>> process issues or enhancements I am willing to investigate. >>>>> >>>>> If it is the consensus that I should run this process on "all" the >>>>> documents before I release it, >>>>> i.e. actually do a full test(!), I would be willing to do so. >>>>> >>>>> Your thoughts and comments are welcome. >>>>> >>>>> Gil B. >>>>> >>>>> On 1/7/2020 9:28 AM, Rony G. Flatscher wrote: >>>>>> 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/ >>>>>> <https://xalan.apache.org/>> >>>>>> [2] Apache FOP:<https://xmlgraphics.apache.org/fop/ >>>>>> <https://xmlgraphics.apache.org/fop/>>u >>>>>> >>>>>> >>>>>> 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 >>>> <mailto:Oorexx-devel@lists.sourceforge.net> >>>> https://lists.sourceforge.net/lists/listinfo/oorexx-devel >>>> <https://lists.sourceforge.net/lists/listinfo/oorexx-devel> >>> >>> -- >>> Gil Barmwater >>> >>> >>> >>> _______________________________________________ >>> Oorexx-devel mailing list >>> Oorexx-devel@lists.sourceforge.net >>> <mailto:Oorexx-devel@lists.sourceforge.net> >>> https://lists.sourceforge.net/lists/listinfo/oorexx-devel >>> <https://lists.sourceforge.net/lists/listinfo/oorexx-devel> >> >> >> >> >> _______________________________________________ >> Oorexx-devel mailing list >> Oorexx-devel@lists.sourceforge.net >> <mailto:Oorexx-devel@lists.sourceforge.net> >> https://lists.sourceforge.net/lists/listinfo/oorexx-devel >> <https://lists.sourceforge.net/lists/listinfo/oorexx-devel> > -- > Gil Barmwater > _______________________________________________ > Oorexx-devel mailing list > Oorexx-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/oorexx-devel
_______________________________________________ Oorexx-devel mailing list Oorexx-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/oorexx-devel
