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/>
[2] Apache 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
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
