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 > [email protected] > https://lists.sourceforge.net/lists/listinfo/oorexx-devel > ------------------------------------------------------------------------------ _______________________________________________ Oorexx-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/oorexx-devel
