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
