The notes and tools in my GitHub repository are for the old format of documentation, before the work made by David to switch to Publican. Nothing you can reuse for the current version.
> On 1 Feb 2020, at 19:49, Gil Barmwater <gbarmwa...@alum.rpi.edu> wrote: > > 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> >> >> <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> >> >> <https://www.rexxla.org/events/2019/presentations/Jenkins%20with%20notes.pdf> >> >> >> >> >> _______________________________________________ >> Oorexx-devel mailing list >> Oorexx-devel@lists.sourceforge.net >> <mailto:Oorexx-devel@lists.sourceforge.net> >> https://lists.sourceforge.net/lists/listinfo/oorexx-devel >> <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
_______________________________________________ Oorexx-devel mailing list Oorexx-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/oorexx-devel
