Re: [Oorexx-devel] Current rail-diagrams in ooRexx 5.0 docs wrong
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 rony.flatsc...@wu.ac.at mailto:rony.flatsc...@wu.ac.at: 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
Re: [Oorexx-devel] Current rail-diagrams in ooRexx 5.0 docs wrong
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 -- ___
Re: [Oorexx-devel] Current rail-diagrams in ooRexx 5.0 docs wrong
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. Jean-Louis 2015-06-16 17:36 GMT+02:00 Rony G. Flatscher rony.flatsc...@wu.ac.at: 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
Re: [Oorexx-devel] Current rail-diagrams in ooRexx 5.0 docs wrong
Ahem, sorry, forgot the URL: http://wi.wu.ac.at/rgf/diplomarbeiten/.
---rony
On 15.06.2015 13:34, Rony G. Flatscher wrote:
Maybe Jean-Louis Faucher can chime in and explain how he did the syntactical
correct svg diagrams.
Also, there was a student of mine who worked on EBNF to allow OpenOffice to
be used as an editor
which was able to render the EBNF to ASCII syntax-diagrams (the current
style, but with glyphs
that made the lines appear to be solid, like the ones in the old IBM Object
Rexx documentations)
et.al., taking also advantage of DITA, which is (was?) employed by Jean-Louis
(Jean-Louis was kind
enough back then to give the student some feedback). The student's name is
Hohenegger, so pick
his name in the right upper list (or pick BNF from the left keyword list)
to get his thesis
named BNF4OOo - Managing Backus-Naur-Forms with OpenOffice (from 2010-10).
Franz Hohenegger's EBNF to syntax diagrams work is implemented in ooRexx.
He has also
implemented the functionality to use OpenOffice writer as a GUI and allows to
create, render, save
and load EBNF and renderings. (Also this work was pointed out to the
developers back then, but got
not picked up. The code is nevertheless available and should be still
operational. If you wish to
use OpenOffice, you would have to use Apache OpenOffice and install
BSF4ooRexx which makes ooRexx
available as a scripting and macro language to Apache OpenOffice.)
---rony
On 15.06.2015 10:46, Erich Steinböck wrote:
However, the syntax diagrams for default values are still incorrect in
rexxref5.pdf; they
should appear on a branch Above the main line, not on the main line
itself:
When David changed from the ASCII to the SVG diagrams, he chose
bottlecaps.de/rr
http://bottlecaps.de/rr. This raiload generator doesn't support all of
the features the ASCII
diagrams were using.You may want to test bottlecaps.de/rr
http://bottlecaps.de/rr with the
stream BIF
http://bottlecaps.de/rr/ui?text=stream%20::=%20%27STREAM%28%27%20name%20%28%20%27,%27%20%28%20%27State%27%20%7C%27Command%27%20%27,%27%20stream_command%20%7C%27Description%27%20%29%20%29?%20%27%29%27stream_command%20::=%20%28%20%28%20%27Open%27%20%28%20%27BOth%27%20write_options%20%7C%20%27REAd%27%20%7C%20%27Write%27%20write_options%20%29?%20options%20%29%20%7C%28%20%27Close%27%20%29%20%7C%28%20%27Flush%27%20%29%20%7C%28%20%28%20%27Seek%27%20%7C%20%27Position%27%20%29%20%28%20%27=%27%20%7C%20%27%3C%27%20%7C%20%27+%27%20%7C%20%27;%27%20%7C%20%28%29%20%29%20offset%20%28%20%27Read%27%20%7C%20%27Write%27%20%7C%20%29%20%28%20%27Char%27%20%7C%20%27Line%27%29%20%29%20%7C%28%20%27Query%27%20%28%20%27Datetime%27%20%7C%27Exists%27%20%7C%27Handle%27%20%7C%28%20%27Seek%27%20%7C%20%27Position%27%20%29%20%28%20%28%27Read%27%20%7C%20%27Write%27%20%29%20%28%20%27Char%27%20%7C%27Line%27%29?%20%7C%27Sys%27%20%29%20%7C%28%20%27SIze%27%20%29%20%7C%28%20%27STreamtype%27%20%29%20%7C%28%20%27Timesta%0Amp%27%20%29%20%29%20%29%29%20%27%29%27stream_write_options%20::=%20%28%20%28%29%20%7C%20%27APpend%27%20%7C%20%27REPlace%27%20%29stream_options%20::=%20%28%20%27SHARED%27%20%7C%20%27SHARERead%27%20%7C%20%27SHAREWrite%27%20%29?%28%20%27NOBuffer%27%20%7C%20%27BInary%27%20%28%20%27REClength%27%20length%20%29?%20%29*.
stream ::= 'STREAM(' name ( ',' ( 'State' |
'Command' ',' stream_command |
'Description' ) )? ')'
stream_command ::= ( ( 'Open' ( 'BOth' write_options | 'REAd' | 'Write'
write_options )? options ) |
( 'Close' ) |
( 'Flush' ) |
( ( 'Seek' | 'Position' ) ( '=' | '' | '+' | ';' | ()
) offset ( 'Read' |
'Write' | ) ( 'Char' | 'Line') ) |
( 'Query' ( 'Datetime' |
'Exists' |
'Handle' |
( 'Seek' | 'Position' ) ( ('Read' | 'Write'
) ( 'Char' |
'Line')? |
'Sys' ) |
( 'SIze' ) |
( 'STreamtype' ) |
( 'Timestamp' ) ) )
) ')'
stream_write_options ::= ( () | 'APpend' | 'REPlace' )
stream_options ::= ( 'SHARED' | 'SHARERead' | 'SHAREWrite' )?
( 'NOBuffer' | 'BInary' ( 'REClength' length )? )*
Only a small fraction of diagrams use the default-above-main path
convention, many default values
easily cannot be described in that way.
bottlecaps.de/rr http://bottlecaps.de/rr doesn't support the
default-above-line convention, so
you would need to find another tool to generate the SVG's or convince the
bottlecaps.de/rr
http://bottlecaps.de/rr owner to implement it. I've already talked to him
about a) displaying
the main path /above /any
Re: [Oorexx-devel] Current rail-diagrams in ooRexx 5.0 docs wrong
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 -- ___ Oorexx-devel mailing list Oorexx-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/oorexx-devel
Re: [Oorexx-devel] Current rail-diagrams in ooRexx 5.0 docs wrong
However, the syntax diagrams for default values are still incorrect in
rexxref5.pdf; they should appear on a branch Above the main line, not on
the main line itself:
When David changed from the ASCII to the SVG diagrams, he chose
bottlecaps.de/rr. This raiload generator doesn't support all of the
features the ASCII diagrams were using.You may want to test bottlecaps.de/rr
with the stream BIF
http://bottlecaps.de/rr/ui?text=stream%20::=%20%27STREAM%28%27%20name%20%28%20%27,%27%20%28%20%27State%27%20|%27Command%27%20%27,%27%20stream_command%20|%27Description%27%20%29%20%29?%20%27%29%27stream_command%20::=%20%28%20%28%20%27Open%27%20%28%20%27BOth%27%20write_options%20|%20%27REAd%27%20|%20%27Write%27%20write_options%20%29?%20options%20%29%20|%28%20%27Close%27%20%29%20|%28%20%27Flush%27%20%29%20|%28%20%28%20%27Seek%27%20|%20%27Position%27%20%29%20%28%20%27=%27%20|%20%27%3C%27%20|%20%27+%27%20|%20%27;%27%20|%20%28%29%20%29%20offset%20%28%20%27Read%27%20|%20%27Write%27%20|%20%29%20%28%20%27Char%27%20|%20%27Line%27%29%20%29%20|%28%20%27Query%27%20%28%20%27Datetime%27%20|%27Exists%27%20|%27Handle%27%20|%28%20%27Seek%27%20|%20%27Position%27%20%29%20%28%20%28%27Read%27%20|%20%27Write%27%20%29%20%28%20%27Char%27%20|%27Line%27%29?%20|%27Sys%27%20%29%20|%28%20%27SIze%27%20%29%20|%28%20%27STreamtype%27%20%29%20|%28%20%27Timestamp%27%20%29%20%29%20%29%29%20%27%29%27stream_write_options%20::=%20%28%20%28%29%20|%20%27APpend%27%20|%20%27REPlace%27%20%29stream_options%20::=%20%28%20%27SHARED%27%20|%20%27SHARERead%27%20|%20%27SHAREWrite%27%20%29?%28%20%27NOBuffer%27%20|%20%27BInary%27%20%28%20%27REClength%27%20length%20%29?%20%29*
.
stream ::= 'STREAM(' name ( ',' ( 'State' |
'Command' ',' stream_command |
'Description' ) )? ')'
stream_command ::= ( ( 'Open' ( 'BOth' write_options | 'REAd' | 'Write'
write_options )? options ) |
( 'Close' ) |
( 'Flush' ) |
( ( 'Seek' | 'Position' ) ( '=' | '' | '+' | ';' | ()
) offset ( 'Read' | 'Write' | ) ( 'Char' | 'Line') ) |
( 'Query' ( 'Datetime' |
'Exists' |
'Handle' |
( 'Seek' | 'Position' ) ( ('Read' |
'Write' ) ( 'Char' |
'Line')? |
'Sys' ) |
( 'SIze' ) |
( 'STreamtype' ) |
( 'Timestamp' ) ) )
) ')'
stream_write_options ::= ( () | 'APpend' | 'REPlace' )
stream_options ::= ( 'SHARED' | 'SHARERead' | 'SHAREWrite' )?
( 'NOBuffer' | 'BInary' ( 'REClength' length )? )*
Only a small fraction of diagrams use the default-above-main path
convention, many default values easily cannot be described in that way.
bottlecaps.de/rr doesn't support the default-above-line convention, so you
would need to find another tool to generate the SVG's or convince the
bottlecaps.de/rr owner to implement it. I've already talked to him about
a) displaying the main path *above *any optional items (bottlecaps.de/rr
currently generates the main path *below *optional items), b) I mentioned
the default-above-line convention, and c) asked about italic font for
non-terminal items (which we use as variables). He says, he has done
some tests regarding a) but he hasn't published that yet. He isn't
convinced about b) or c).
I would be glad to work on the syntax diagrams, if someone would be kind
enough to explain the tools involved (SVG, DocBook, ...?).
I'll gladly share everything I know about that. When just working on the
diagrams you will not need any knowledge of DocBook or Publican. You'll
just need to generate SVG's from the EBNF files in SVN.
Note that there are currently 1000+ SVG's in the SVN.
I have worked on (checked corrected) some of the SVG's. You can
recognized the ones I went through - those already use italic font for
variables (I'm adding italic font in a special SVG post-processing step).
Erich
On Mon, Jun 15, 2015 at 3:06 AM, J. Leslie Turriff jlturr...@mail.com
wrote:
However, the syntax diagrams for default values are still incorrect in
rexxref5.pdf; they should appear on a branch Above the main line, not on
the main line itself:
►►─command┬default┬──►◄
├option1┤
├option2┤
└option3┘
should look like this:
┌default┐
►►─command┼───┼──►◄
├option1┤
├option2┤
└option3┘
I would be glad to work on the syntax diagrams, if someone would be kind
enough to explain the tools involved (SVG, DocBook, ...?).
Leslie
On Sunday 14 June 2015 10:56:55 Rony G. Flatscher wrote:
Hi there,
just saw that Erich committed an actual set of the PDF documentation at
https://sourceforge.net/projects/oorexx/files/oorexx-docs/5.0.0alpha/
a
few moments ago where you can get rexxref5.pdf from!
---rony
--
It’s good to be
Re: [Oorexx-devel] Current rail-diagrams in ooRexx 5.0 docs wrong
Hi there, just saw that Erich committed an actual set of the PDF documentation at https://sourceforge.net/projects/oorexx/files/oorexx-docs/5.0.0alpha/ a few moments ago where you can get rexxref5.pdf from! ---rony On 14.06.2015 17:55, 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
Re: [Oorexx-devel] Current rail-diagrams in ooRexx 5.0 docs wrong
However, the syntax diagrams for default values are still incorrect in rexxref5.pdf; they should appear on a branch Above the main line, not on the main line itself: ►►─command┬default┬──►◄ ├option1┤ ├option2┤ └option3┘ should look like this: ┌default┐ ►►─command┼───┼──►◄ ├option1┤ ├option2┤ └option3┘ I would be glad to work on the syntax diagrams, if someone would be kind enough to explain the tools involved (SVG, DocBook, ...?). Leslie On Sunday 14 June 2015 10:56:55 Rony G. Flatscher wrote: Hi there, just saw that Erich committed an actual set of the PDF documentation at https://sourceforge.net/projects/oorexx/files/oorexx-docs/5.0.0alpha/ a few moments ago where you can get rexxref5.pdf from! ---rony -- It’s good to be open-minded, but not so open-minded that your brain falls out.-- ___ Oorexx-devel mailing list Oorexx-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/oorexx-devel
