Hi Rony,
First of all, thanks for the kind comments! And I really appreciate the
feedback and suggestions as well.
Now to the specific items in the order you listed them. The issue with
the "missing folders" is one I ran into as well. It comes from the fact
that I was not able to include empty folders in the zip file and so had
to create them the first time they were needed. I chose to do that in
the docprep step when all the other "housekeeping" is done. Since you
(and I) had already run docprep with the previous version, the
"housekeeping section" had already run so the folders were not created.
This should only be a problem for you, P.O. and I (or anyone else with
v1) that had run version 1 of the package.
I will look into a change to only issue the "PDF created" if the file
actually exists as I don't know that the FOP .bat file gives any kind of
"errorlevel" that I could test. This approach could give a false
"success"?? message if there was a previous file but the step had failed.
The svn revision on the cover page of the rexxref is "hard coded"; i.e.
a DTD entity supplies this value which is set in the file rexxref.ent.
So a manual update of that file is required which doesn't always happen
when other parts of the book are modified.
Assuming ooRexx is installed is pretty safe but it could be verified
using the "where" command. The difficulty in using Rexx scripts however
comes from my decision to use environment variables to hold e.g. docpath
and whichdoc. I also wanted the various steps to be able to be run
independently so those variables need to "persist" between steps. Using
simple "set" commands in a Rexx script will not accomplish that as they
"go away" when the script ends. I believe one could use the registry
class(?) to make them "permanent" but that then precludes a *ix solution.
I have not done anything with HTML as I am not sure what our Publican
process does to build them. This is surely another work item if we are
to completely remove our dependency on Publican.
The package does not make use of either the makefile or publican.cfg
file that appear in the book directories. The only Publican-related
files that the package uses are the two stylesheets - pdf.xsl and
defaults.xsl which are in the package itself. BTW, the sources.txt file
in the package documents all the pieces and from where they are derived.
Thanks again for the feedback and suggestions. They are always welcome!
Gil B.
On 2/29/2020 10:11 AM, Rony G. Flatscher wrote:
Dear Gil:
On 28.02.2020 19:12, Gil Barmwater wrote:
I have just uploaded version 1.1 of the package to my Dropbox. In
addition to the changes I mentioned earlier (see below), I have
modified the location of the output files. There are now only three
folders - fo_files, log_files, and PDF_files - instead of a folder
per document. The link I supplied earlier will still work but here
<https://www.dropbox.com/s/s5d9mwx63xru1tk/orxbldoc.zip?dl=0> it is
again so you don't need to hunt for it. Again, feedback is welcome!
Used your new version 1.1, but got into (small) troubles using
"doc2pdf rexxref":
G:\oorexx.tmp\gilDocs\orxbldoc-1.1>doc2pdf rexxref
F:\work\svn\oorexx\docs\trunk\rexxref\en-US\Common_Content already exists.
15:40:34 - Transforming
F:\work\svn\oorexx\docs\trunk\rexxref\en-US\rexxref.xml to fo_files\rexxref.fo
This may take more than 5 minutes!
Making portrait pages on A4 paper (210mmx297mm)
15:49:19 - Transformation complete
15:49:19 - Creating PDF_files\rexxref.pdf from fo_files\rexxref.fo using
Apache FOP
The system cannot find the path specified.
15:49:19 - PDF created
Remarks:
* Please note that in my case the doc2fo step takes almost 9
minutes, hence I would suggest to give the warning 10 minutes
instead of the current 5 minutes (otherwise users may fear that
the process hung up if one has to wait more than 5 minutes).
* the fo2pdf step was not carried out, because of missing
directories ("log_files", "PDF_files"), here the double-check:
G:\oorexx.tmp\gilDocs\orxbldoc-1.1>fo2pdf
15:51:35 - Creating PDF_files\rexxref.pdf from fo_files\rexxref.fo using
Apache FOP
The system cannot find the path specified.
15:51:35 - PDF created
* after creating the two missing subdirectories "log_files" and
"PDF_files" manually the process concluded successfully in the
fo2pdf step:
G:\oorexx.tmp\gilDocs\orxbldoc-1.1>md log_files PDF_files
G:\oorexx.tmp\gilDocs\orxbldoc-1.1>fo2pdf
15:52:21 - Creating PDF_files\rexxref.pdf from fo_files\rexxref.fo using
Apache FOP
15:52:47 - PDF created
Maybe the success message "PDF created" should only be given if the
fo2pdf step was carried out?
One more observation: I updated the documentation via svn to revision
11985, yet the book reads 5.0.0.r11982 on the title page (this may
stem from my prior tests a few days ago). Doing a "svnversion
%docpath%" yields currently revision 11985.
---
Overall, *extremely impressed* how easy and straight forward it has
become to create rexxref.pdf, something I (and many others) simply
would not have been able to do before your hard work and making the
toolchain and the scripts available to us! Kudos!!
The time, work and efforts you have invested here is really great for
the entire community!
Ad oodguide errors: I have added some code to create the files that
book is trying to include but be aware that they are in the PARENT
folder of the folder specified for docpath. This will cause a problem
if you should have that folder on say a portable drive but not under
another directory. E.g using d:\rexx\theDocs for docpath would be OK
but d:\theDocs would fail. I would prefer to have those files be
created down one level but that will need a change to the source for
the oodguide book. If that change gets made I will update the package.
Ad the errors (32) in the winextensions book: I have not had a chance
to investigate why they are being generated but they seem to
correspond to the 32 occurrences of (???) in the PDF file on SVN.
Ad syntax highlighting of C++ code: this appears to be a built-in
feature of Publican which is not available for xsltproc. More
investigation is needed to determine what to do about it.
While I have accomplished what I intended - allowing anyone to build
the ooRexx documentation on Windows 10 - there is more work to be
done going forward. I would be happy to provide assistance to anyone
wishing to port the package to *ix. This would involve using the *ix
versions of the xsltproc tools and writing shell scripts to replace
the *.cmd files.
+1
Just an idea/a question: how about assuming that ooRexx 5.0 is
installed and because of that writing a small Rexx script that would
replace the shell scripts for all operating systems (differences among
the operating systems could be taken care of in such a Rexx script)?
E.g. this would allow .datetime to be used for measuring the different
steps (the different commands)
And we should look into moving from Docbook 4.5 to 5.0, a non-trivial
task from what I have determined. Investigating other tools to do the
transformation could give us the ability to syntax-highlight not only
the C++ code but also the ooRexx.
May I just ask a question ad html-production: have you been able to
look into that corner? P.O. reported that with his Publican, Windows 7
confined version the html text would not look good. It would be great
to have all of ooRexx' documentation on the web, such that people can
quickly find it by searching the Internet (very much like finding the
documentation e.g. for any Java class).
Another question maybe: I notice that in the book directories there
are two Publican related files: Makefile and publican.cfg. Are they
needed (or any of the Publican related files) for your solution?
Best regards
---rony
_______________________________________________
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
