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
