Hi Chip, AFAIK Jean-Louis was able to define most, if not all aspects of rendering to graphical rail diagrams, be it stroke intensities, arrows, fonts and the like. Hoping, that Jean-Louis can shed some light about the infrastructure he has used and his assessment how difficult/easy it is to set up the environment for creating grammatically, nice looking svg graphics.
---rony P.S.: One remark ad renderings and correctness: in JLF's rendering the semi-colon could (should?) be defined to be the default value and optional. On 15.06.2015 15:06, Chip Davis wrote: > We all can agree that the existing ASCII-art rail diagrams are > unacceptable, from both an esthetic and information-transfer > standpoint. We must adopt an alternative. > > While Jean-Louis' renderings are much better, they suffer from the > visual clutter of unnecessary arrowheads. The flow through a rail > diagram is left-to-right except for a repetition of a term, which in > ASCII-art required a back-arrow (e.g. MIN) to distinguish it from a > default value. > > Erich's arrow-free diagrams accomplish this distinction with curved > lines. J-L's approach uses the same curved lines but inserts multiple > arrowheads which add nothing but visual clutter. > > I very much prefer the clean renderings of Erich's approach because it > has no internal arrowheads at all. Also, it has the ability to use > bold fonts, which is useful to denote a value taken as a constant. > > Regardless of the tool eventually adopted, we really must go back > through the diagrams and verify their accuracy. I happened to notice > that the diagrams differ in their depictions of Overlay() and I'm not > sure either one is totally correct. > > It must be noted that Erich's RexxRef5 file is only 6 Meg whereas the > JLF RexxRef4.2 is not quite twice as large. I doubt all those extra > arrowheads made that much difference, but it's worth comparing the > size of the two approaches within the same document. > > -Chip- > > On 6/14/2015 11:55 AM, Rony G. Flatscher wrote: >> The syntax rail-diagrams that currently get created are wrong in the >> areas, where there are optional arguments. The optional arguments are >> not identifiable and it is not clear what the default values would be, >> if an optional value is left out. >> >> This is probably due to a limitation in the rail-diagram tool that is >> being used, which I understand is some service on the WWW which has >> these limitations. Judging from studying the thread that David Ashley >> started (2014-07-31, 17:57) >> <https://sourceforge.net/p/oorexx/mailman/message/32669824/> until the >> last post where this shortcoming was pointed out, without any further >> feedback by David Ashley: >> <https://sourceforge.net/p/oorexx/mailman/message/32699294/> >> (2014-08-09, 18:32, by J. Leslie Turriff). >> >> --- >> >> Not all developers may be aware, that years before that Jean-Louis has >> suggested svn-syntax-rail-diagrams to replace the (rather ugly) >> ASCII-syntax-rail-diagrams already. He not only suggested it but did >> all the necessary work and came up with beautiful PDFs and HTMLs >> renderings that include syntax rail-diagrams that are able to document >> optional arguments and default values. Unfortunately (and for no >> apparent reasons that I am aware of), years ago, his hard work was not >> picked up and put into production for the ooRexx distributions. >> >> Maybe it is worthwhile at this point of development to take a look at >> the different presentations of syntax-rail-diagrams, >> >> * rendered as ASCII-snytax-rail-diagrams (just load the ooRexx 4.2.0 >> rexxref.pdf from your ooRexx installation), >> * the current 5.0 rexxref.pdf rendering (thanks to Erich in his >> svn-sandbox, 'sandbox/erich/docs/build' which one gets when >> checking out the ooRexx project with svn) at >> >> <https://sourceforge.net/p/oorexx/code-0/HEAD/tarball?path=/sandbox/erich/docs/build> >> named "rexxref5.pdf" and >> * the ooRexx 4.2.0 rexxref.pdf by Jean-Louis at >> >> <https://dl.dropboxusercontent.com/u/20049088/oorexx/docs/trunk/index.html>. >> >> You can find all three versions of the PDF-documentation at >> <http://wi.wu.ac.at/rgf/rexx/tmp/docs.tmp/> so it is easier for you to >> load and compare them (listed in the same order is above): >> >> * ooRexx 4.2.0 official ASCII-syntax-rail-diagrams: >> <http://wi.wu.ac.at/rgf/rexx/tmp/docs.tmp/rexxref.pdf>, >> * ooRexx 5.0.0, Erich's preliminary rendering >> <http://wi.wu.ac.at/rgf/rexx/tmp/docs.tmp/rexxref5.pdf>, >> * ooRexx 4.2.0, Jean Louis's renderings: >> <http://wi.wu.ac.at/rgf/rexx/tmp/docs.tmp/rexxref4.2-jlf.pdf>. >> >> Then in all three versions go to chapter "Functions -> Built-in >> Functions -> Stream" and compare the syntax rail-diagrams of the >> three, and I think you will see for yourself, why I suggest to go with >> Jean-Louis' solution for creating correct and still very nice looking >> syntax rail-diagrams for the project. >> >> ---rony >> >> ------------------------------------------------------------------------------ _______________________________________________ Oorexx-devel mailing list Oorexx-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/oorexx-devel
