Hi Rony,
In looking at the documentation files on SF, I saw a number of .css
files which I assumed were needed/used by the HTML build process.
Perhaps all they need is some tweaking to fix the problems P.O. is seeing?
I've forgotten but does Jean-Louis' process produce the same railroad
diagrams that we are using now? The link you provided just leads to the
diary of his work.
I agree that color coding the examples would be nice but I believe that
is a "feature" of DocBook that may require a different transform
program. This link
<http://www.sagehill.net/docbookxsl/SyntaxHighlighting.html> describes
how to do something like this but I have not delved into the details so
I don't know how one would tell the highlighting program that the code
was ooRexx and then how to color it. Sounds like a project for someone
to undertake after we get the new process up and running. It appears
that each example would require as least some modification and, by my
count, there are more than 6400(!) instances of the <programlisting> tag
in our documents. I did that research because I know why* we are getting
extra blank lines in our examples and I wanted to see how hard it would
be to fix. Based on the number of instances, I decided to use Erich's
program to strip the blanks instead.
Finally, I have been working exclusively on Windows 10 since Erich noted
that Publican was not stable on the platform and we therefore needed
some other toolchain in order to be able to reliably produce our
documentation for ooRexx. I try to keep my systems up to date and a
"ver" command gives:
Microsoft Windows [Version 10.0.18363.592]
*The reason we get leading blanks in our examples is that we are coding
them wrong! Docbook says that the contents of the <programlisting>
element are treated "verbatim" and, because Docbook is XML and not HTML,
whitespace is preserved, including line breaks. So when we code the tag
on one line but start the example on the next line, the first
"character" of the example is a line break(!) and we get a blank line in
the output. Simply starting the example code immediately after the tag
solves the problem. There were several examples in the "common" files
which I fixed that way along with the DTD changes.
Gil
On 2/1/2020 8:59 AM, Rony G. Flatscher wrote:
On 31.01.2020 22:09, P.O. Jonsson wrote:
many thanks for your feedback, I read your thread and I think you gave me just
the hint I needed
to inject Erichs cleaning script in to my build toolchain (it works slightly
different to Erichs
setup). I will let you know if it worked.
When I compare what you write with the process I see using Publican the
differences are not very
big, except you use more up-to-date tools, I use Publican 3.0 and fop 1.1 and
something called
LIBXSLT, an extension written in Python (in 2008!) to replace XSLTPROC that you
have chosen, so I
have good hope that your toolchain will produce very similar results to what we
are used to.
What about the html - are they needed at all? They do not render very well in
comparison to the
PDFs and the output looks different on different browsers (surprise), but the
main deficiency I
see is that some diagrams overwrite text, they are simply to large in
comparison. Skipping the
html would cut the rendering time with approx 40%.
Well, having HTML renderings would allow one to place all of the ooRexx
documentation on the web and
allow it to be indexed by search machines, so I would think it to be very
useful and makes ooRexx
more researchable, more visible. If you succeed in making the documentation an
automated task on
Jenkins, then it should not be a problem at all. Additionally, changes to the
documentation do not
occur frequently, such that time stamped regenerations would be relatively
scarce.
Ad formatting: this could be fixed by defining a CSS (as a separate text file,
referred to by the
HTML renderings in the head's style element) with formatting definitions for
the HTML version, such
that all browsers render it the same. This could also be used to control the
size and floating rules
regarding the diagrams.
Ad rendering code samples: it would be great if future versions (once the
documentation can be
reliably created again on all platforms) would syntax highlight the code, also
it would be great if
the syntax diagrams could be generated the way Jean-Louis Faucher has been
doing it [1]. Maybe we
could ask Jean-Louis to give a hand then?
The Windows 10 platform is there and it is just rolling its thumbs between
Windows build, I would
say 23 hours out of 24 it is idling.
This would mean that creating the HTML documentation would not really impact
the machine (assuming
it is one of your kindly provided computers for Jenkins and automated creation
of ooRexx [2]), once
the ooRexx documentation can be created on that platform as well?
BTW, did you try whether the toolset you are using would work on Windows 10 in
addition to Windows 7?
Thinking of it, Gil, what platform have you been using for your work on a
"future-safe" generation
of the ooRexx documentation, Windows 7, 8 or Windows 10, or a different
platform?
Please keep up your great work!
---rony
[1] Jean-Louis Faucher's diary on creating the syntax diagrams for his
experimental extensions to
ooRexx:
<https://github.com/jlfaucher/executor/blob/master/incubator/DocMusings/railroad/_diary.txt>
[2] P.O. Jonsson's presentation on the 2019 International Rexx Symposium,
"Jenkins - what is it and
how is it used for NetRexx/ooRexx":
<https://www.rexxla.org/events/2019/presentations/Jenkins%20with%20notes.pdf>
_______________________________________________
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
