> > what Erich et.al. think about this Rony, I use what we have now. Finishing content additions, changes, and fixes for a 5.0 release is my priority.
On Wed, Jun 17, 2015 at 10:54 PM, Rony G. Flatscher <[email protected] > wrote: > Hi Jean-Louis, > > thank you for your feedback and your interesting information! I see that > you have also "diary.txt" that document what you have done and how the > development has gone on. > > On 16.06.2015 23:10, Jean-Louis Faucher wrote: > > The graphical syntax diagrams were generated by parsing the ascii syntax > diagrams > and generating a DITA representation. > http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/syntaxdiagram.html > > Since the ascii syntax diagrams have been removed, this approach is no > longer > possible. Editing the DITA representation manually would be too tedious. > It should be possible to generate a DITA representation from an ebnf file, > but I lack of motivation to work on that. > > The tool is here : > http://svn.code.sf.net/p/oorexx/code-0/incubator/DocMusings > > Example of DITA representation : > railroad/declarations.xml > > The tool which generates the SVG from the DITA representation : > railroad/syntaxdiagram2svg/ > Adapted from a DITA plugin, this is a mix of XSLT, JavaScript and CSS. > Regarding the graphical notation, I have no idea if it would be easy to > remove the arrows. > > Maybe it is worthwhile to look into the student's work as it would allow > to define the EBNFs including optionality and default values. I am not sure > (will have to look into his work), but I think he used the DITA XML > encoding too. (In any case his scripts create the old ASCII syntax diagrams > from the EBNF, so it would be possible to have those ASCII syntax diagrams > created, if needed.) > > Ad DITA rail diagram generation: this will have to be researched too, but > given, that this is an opensource, professional tool for creating technical > documentation (and render it to all kind of formats), I would be > optimistic, that it can be customized and e.g. remove the arrows (which I > like very much, BTW, as people who rarely are exposed to raildiagrams will > intuitively see how they can and should be read) should that be really > necessary. > > But before doing any further work in this corner, it would be necessary to > first assess the current situation, where syntactically incorrect > raildiagrams get created. Then we could discuss how to best move on to > arrive at syntactically correct diagrams as efficiently as possible. > > So, the question would be, what Erich et.al. think about this and how to > best proceed? > > ---rony > > > > > 2015-06-16 17:36 GMT+02:00 Rony G. Flatscher <[email protected]>: > >> 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 > [email protected] > https://lists.sourceforge.net/lists/listinfo/oorexx-devel > >
------------------------------------------------------------------------------
_______________________________________________ Oorexx-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/oorexx-devel
