Hi Gil, On 01.02.2020 19:49, Gil Barmwater wrote: > 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? That would be great! > > 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. > Oh, sorry, here the link with Jean-Louis' railroad diagrams in: <https://github.com/jlfaucher/executor>.
> 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. > [1] below is a little program that would make sure that all of the documenation's xml files get processed and leading and trailing CR-LF of programlisting text content get stripped, if that helps. It could be run always before creating the documentation or after checking in new edits on the xml files. > 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] > That is great! Chances are that then we could create the documentation on the other platforms as well! > *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. > Thanks to this description I wrote [1] below. Keep up the great work! Best regards ---rony > 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> >> [1] Program ("stripBlankLinesFromProgramlisting.rex") that removes leading and trailing CR-LF from programlistings. Run it in the doc-branch you want to work with, e.g. from "oorexx/doc/trunk": ---rgf, 2020-02-02: strip CR-LF from ooRexx xml program listings start=.dateTime~new call sysfiletree "*.xml", "files.", "FOS" end =.dateTime~new say "SysFileTree duration:" end-start", about to process" files.0 "files" len=files.0~length do i=1 to files.0 say i~right(len)":" files.i call stripBlankLines files.i end end =.dateTime~new say "processed" .count~counter "<programlisting> elements, duration:" end-start ::routine stripBlankLines parse arg fileName inStr=.stream~new(fileName)~~open("read") chars=inStr~chars allChars=inStr~charin(1,chars) inStr~close startNeedle="<programlisting>" endNeedle ="</programlisting>" crlf ="0d0a"x mbOut=.mutableBuffer~new(,chars) do while allChars<>"" parse var allChars before (startNeedle) program (endNeedle) allChars if program="" then do if allChars="" then -- arrived at end of file mbOut~append(before) else -- maybe a placeholder of whitespace mbOut~append(before, startNeedle, program, endNeedle) end else -- strip leading and trailing CR-LF characters do mbOut~append(before, startNeedle, program~strip("both",crlf), endNeedle) .count~increase end end -- write new file .stream~new(fileName)~~open("write replace")~~charout(mbOut~string)~close ::class count ::attribute counter class ::method init class expose counter counter=0 ::method increase class expose counter counter+=1 The output on my PC was: F:\work\svn\oorexx\docs\trunk>stripBlankLinesFromProgramlisting.rex SysFileTree duration: 00:00:00.000000, about to process 301 files 1: F:\work\svn\oorexx\docs\trunk\buildmachine\en-US\admin.xml 2: F:\work\svn\oorexx\docs\trunk\buildmachine\en-US\Author_Group.xml 3: F:\work\svn\oorexx\docs\trunk\buildmachine\en-US\Book_Info.xml 4: F:\work\svn\oorexx\docs\trunk\buildmachine\en-US\guestos.xml ... cut ... 299: F:\work\svn\oorexx\docs\trunk\winextensions\en-US\winole.xml 300: F:\work\svn\oorexx\docs\trunk\winextensions\en-US\winprogmanager.xml 301: F:\work\svn\oorexx\docs\trunk\winextensions\en-US\winregistry.xml processed 6108 <programlisting> elements, duration: 00:00:02.995000
_______________________________________________ Oorexx-devel mailing list Oorexx-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/oorexx-devel
