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!
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.
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.
Gil B.
On 2/28/2020 4:37 AM, P.O. Jonsson wrote:
Dear Gil,
This is just to say that I have set up the Jenkins Win build machine
to build the docs now, I will add your changes when they are ready.
I am currently building all documents (17 books), one could consider
to split the building in two different runs for ooRexx/ooDialog. Also,
since the Windows builds need the documentation it would make sense to
run the docs before building Windows. Currently the documentation is
picked up in oorexxDocs, that would need to be changed
to??ooRexx-docs-build\oorexxDocs. @Erich: can you make this change?
I had expected the build to take more time on a weaker CPU but nope -
the time is approximately the same - 1 hour 15 minutes for all (and I
mean all) documents. Building only the basic documents will take
around 40 minutes.
H??lsningar/Regards/Gr??sse,
P.O. Jonsson
oor...@jonases.se <mailto:oor...@jonases.se>
Am 27.02.2020 um 17:08 schrieb Gil Barmwater <gbarmwa...@alum.rpi.edu
<mailto:gbarmwa...@alum.rpi.edu>>:
P.O.,
I am almost ready to upload an updated version of the package which
includes: the TOC with 3 levels, warning messages about the time it
takes to run doc2fo, timestamps (thanks to you!) for the start and
end of both doc2fo and fo2pdf, the ability to specify parameters to
both FOP and xsltproc, and probably the changes you suggested in your
previous post. Give me a bit more time to test my changes and I will
make it available.
Gil
On 2/27/2020 9:36 AM, P.O. Jonsson wrote:
Dear Gil,
I did not find out how to set the index to 3 levels rather than 4,
where do you change this?
Personally I prefer 3 levels (as it is today) rather that with 4,
where you cannot see the forest for all the threes :-) but I can
live with whatever is decided.
H??lsningar/Regards/Gr??sse,
P.O. Jonsson
oor...@jonases.se <mailto:oor...@jonases.se>
Am 26.02.2020 um 20:30 schrieb Gil Barmwater
<gbarmwa...@alum.rpi.edu <mailto:gbarmwa...@alum.rpi.edu>>:
Hi P.O.,
Thanks for the kind words about the ease of use of the package. It
was one of my main goals to make it so that anyone could use it,
even if they were not a "power" Windows user.
Per the comment re. the output folders: I chose that setup as there
are three files generated for each book and it then becomes easy to
"clean up" afterward by just deleting the entire folder. However,
it really could be just a single folder for all documents. Or maybe
just three folders, one for each of the three types of output -
pdfs, logs, and fos?
I like the idea of adding echo %time% and will put that in my
command files. Thanks!
As I suspected, there is a "surprise" in the rxxpg book. The
Publican version has syntax highlighting for the C++ examples and,
unfortunately, the xsltproc version does not :-(. I would ask Erich
and Rick if they feel this is a serious issue or if we can live
with it for now.
Gil
On 2/26/2020 1:36 PM, P.O. Jonsson wrote:
Dear Gil,
I have downloaded your package and started to build the documents.
It is an *Incredibly* simple setup! WOW! Having fiddled with
Publican some time now it is a real ease. I have built the
complete set of documents (including oodialog docs) 3 times now
and the results are identical every time, this was not always the
case with Publican???
I notice you create one folder out-<item> for each item, for me 16
folders in total, maybe it is sufficient with one output folder?
It would be easier to pick the documents up in an automated
process (from Jenkins). But this is not a big thing.
It is not possible to build all documents in parallel, as I could
do with Publican, but building all documents sequentially took 1
hour and 12 minutes on a i7 Windows 10 Machine. Leaving out the
ooDialog documents will cut the time considerably.
A simple way to get some timing data is to echo %time% before and
after each build. I also made a batch file that launches the build
of all the documents one after the other.
I have not tried your version with 3 levels, I have build with 4
levels in the TOC.
I found several examples where your build process excels over the
current Publican process
- your process get the Copyright dates correct (up to build year,
not to 2017 or 2018 as in Publican build)
-I have seen pages where text what pushed over the edge of a page
in Publican where your process gets it correct
-your process renders text in drawings better than Publican.
I hope the attached document is not stripped of for the list, here
I have made the comparison in the built documents.
H??lsningar/Regards/Gr??sse,
P.O. Jonsson
oor...@jonases.se <mailto:oor...@jonases.se>
Am 25.02.2020 um 20:43 schrieb Gil Barmwater
<gbarmwa...@alum.rpi.edu <mailto:gbarmwa...@alum.rpi.edu>>:
I have now added a warning message to the doc2fo.cmd script that
running it may take several minutes. I experimented with the
--timing switch but most of the time is spent in one spot so it
still appears to be "hung" there so I didn't put it in. I have
added the ability, however, to provide additional parameters to
the xsltproc program so that the user could specify that they
wanted to use that flag (or others) without having to modify
doc2fo.cmd.
I also found the parameter that controls the TOC depth! I have
set it to 3 to match our historical document appearance but, by
using the same mechanism mentioned above, a user could change it
to 4 if they prefer that look. I need to document how to use this
option (as well as a corresponding one for FOP which would allow
one to change the JAVA heap space) and build a new package. I
will wait a day, however, in case there is additional feedback
that I can incorporate.
Gil
On 2/25/2020 9:57 AM, Rony G. Flatscher wrote:
Dear Gil,
On 25.02.2020 15:31, Gil Barmwater wrote:
Thanks so much for the feedback! I was unaware of the "timing "
switch so will consider adding
that to my package in order to give the user some indication
that things are still running. On my
laptop the transform step also takes >5 minutes when building
the rexxref so some visual feedback
would be helpful.
Yes, or simple warning that some books may take ten minutes or
more (if they get built faster and
faster over time, no one would complain ;) ), then the user's
expectation are "managed" to take time
and patience to wait...
Ad the TOC: the build of ooRexx 5.0.0 that I have installed is
at 11978 which includes a rexxref
at 11974. That version only has three levels of entries
compared to what my package produces which
has four. I have not checked any other more recent versions of
the rexxref so I'm not sure when
the fourth level was introduced. As I mentioned to P.O., the
extra level seems to me a bit
distracting but I am happy to leave it in if that is the
general consensus of the development
team. It should also be noted that even if there are only three
levels in the TOC, the "bookmarks"
displayed by Acrobat Reader on the left of the document do
contain all four levels making
navigation to a specific section simple.
Oh, o.k. I see now.
Personally, I actually like it as one can get an even better
overview of the structure and the
concepts that get documented there.
---rony
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
<mailto:Oorexx-devel@lists.sourceforge.net>
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
_______________________________________________
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
<mailto: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
--
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
_______________________________________________
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
