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.
