Missing Appendix in NRL

[Kermit Kiser]

In my printed copies of NRL and in the NRL (version 1) pdf, there is a section titled:

Appendix A: NetRexx Syntax Diagrams

I find this section to be one of the most useful documents available for NetRexx as it constitutes a very concise summary of the syntax of NetRexx statements which is all the reference that an experienced user usually needs to access while coding.

This section is missing from the NRL version 2 and 3 pdf files.

Does anyone know what happened to this appendix and whether or not it can be restored? (With updates for V3, of course.)  It does not even have to be a direct part of the NRL - it could be part of a separate "NetRexx Quick Reference" guide. The syntax diagrams are still in the main NRL text so perhaps the summary appendix could be auto-generated somehow.

-- Kermit


_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[rvjansen]

Kermit,

this appendix never has been in the converted document. My guess is
that the 'railroad track diagrams' have used something very specific to
the script/dcf/gtml family of text processors which was hard to convert
at the time. I believe that the ooRexx documentation, which is
docbook-based, still has these included as graphics files. I'll add it
to the list of things to do.

Note that antlr, as in the parser generator tool, has a gui available
that automatically produces these - one more argument (in addition to
the generation of the NetBeans plugin) to get the antlr grammar working.

best regards,

René.

On Sun, 20 Nov 2011 19:25:10 -0800, Kermit Kiser wrote:

> In my printed copies of NRL and in the NRL (version 1) pdf,
> there is a section titled:
>
>  _Appendix A: NetRexx Syntax Diagrams_
>
>  I find this section to be one of the most useful documents available
> for NetRexx as it constitutes a very concise summary of the syntax of
> NetRexx statements which is all the reference that an experienced
> user
> usually needs to access while coding.
>
>  This section is missing from the NRL version 2 and 3 pdf files.
>
>  Does anyone know what happened to this appendix and whether or not
> it can be restored? (With updates for V3, of course.) It does not
> even
> have to be a direct part of the NRL - it could be part of a separate
> "NetRexx Quick Reference" guide. The syntax diagrams are still in the
> main NRL text so perhaps the summary appendix could be auto-generated
> somehow.
>
>  -- Kermit

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Robert L Hamilton]

You might try

http://www.rexxinfo.org/html/functions.html#translate

which seems inclusive and Accurate.

Bob Hamilton
Richardson Texas USA

On Sun, Nov 20, 2011 at 9:25 PM, Kermit Kiser <[hidden email]> wrote:

In my printed copies of NRL and in the NRL (version 1) pdf, there is a section titled:

Appendix A: NetRexx Syntax Diagrams

I find this section to be one of the most useful documents available for NetRexx as it constitutes a very concise summary of the syntax of NetRexx statements which is all the reference that an experienced user usually needs to access while coding.

This section is missing from the NRL version 2 and 3 pdf files.

Does anyone know what happened to this appendix and whether or not it can be restored? (With updates for V3, of course.)  It does not even have to be a direct part of the NRL - it could be part of a separate "NetRexx Quick Reference" guide. The syntax diagrams are still in the main NRL text so perhaps the summary appendix could be auto-generated somehow.

-- Kermit

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Mike Cowlishaw]

[Sorry for delay .. was offline yesterday and most of Sunday]

In my printed copies of NRL and in the NRL (version 1) pdf, there is a section titled:

Appendix A: NetRexx Syntax Diagrams

I find this section to be one of the most useful documents available for NetRexx as it constitutes a very concise summary of the syntax of NetRexx statements which is all the reference that an experienced user usually needs to access while coding.

This section is missing from the NRL version 2 and 3 pdf files.

Does anyone know what happened to this appendix and whether or not it can be restored? (With updates for V3, of course.)  It does not even have to be a direct part of the NRL - it could be part of a separate "NetRexx Quick Reference" guide. The syntax diagrams are still in the main NRL text so perhaps the summary appendix could be auto-generated somehow.

In the original book, the syntax diagrams at the top of each instruction section were formatted using the SCRIPT Mathematical Formula Formatter.  One feature of doing it that way was that I could put them in a library and then include them in two places in the document while keeping a single copy of the source for each diagram (hence having only one place to modify when enhancements were made).

 

When converting to use ODT the text of the book was/is largely converted automatically, but I had to manually recreate the syntax diagrams inline (which is why they are not quite as well formatted in a few cases).  I could not find a way to have them be duplicated automatically to the appendix so had to drop the appendix -- sorry.

 

There may be a way to do this, or Open Office may have a feature to make this easier now.   But creating the Appendix by copy & paste (so two copies of each diagram would exist) is probably a bad idea.

 

Mike

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Rony G. Flatscher (wu-wien)]

On 22.11.2011 10:15, Mike Cowlishaw wrote:

[Sorry for delay .. was offline yesterday and most of Sunday]

In my printed copies of NRL and in the NRL (version 1) pdf, there is a section titled:

Appendix A: NetRexx Syntax Diagrams

I find this section to be one of the most useful documents available for NetRexx as it constitutes a very concise summary of the syntax of NetRexx statements which is all the reference that an experienced user usually needs to access while coding.

This section is missing from the NRL version 2 and 3 pdf files.

Does anyone know what happened to this appendix and whether or not it can be restored? (With updates for V3, of course.)  It does not even have to be a direct part of the NRL - it could be part of a separate "NetRexx Quick Reference" guide. The syntax diagrams are still in the main NRL text so perhaps the summary appendix could be auto-generated somehow.

In the original book, the syntax diagrams at the top of each instruction section were formatted using the SCRIPT Mathematical Formula Formatter.  One feature of doing it that way was that I could put them in a library and then include them in two places in the document while keeping a single copy of the source for each diagram (hence having only one place to modify when enhancements were made).

 

When converting to use ODT the text of the book was/is largely converted automatically, but I had to manually recreate the syntax diagrams inline (which is why they are not quite as well formatted in a few cases).  I could not find a way to have them be duplicated automatically to the appendix so had to drop the appendix -- sorry.

 

There may be a way to do this, or Open Office may have a feature to make this easier now.   But creating the Appendix by copy & paste (so two copies of each diagram would exist) is probably a bad idea.

AFAICT syntax diagrams are a boon for newcomers to a language. In my environment (thousands of business administration students) being ledgible and comprehensible has been very important.

In the ooRexx project all the syntax diagrams were actually ASCII diagrams. If a syntax got changed/enhanced it has meant to change the ASCII drawing of the syntax (rail) diagram manually. Over time, in complex diagrams, little typos would create wrong (!) diagrams. It has been a tedious task.

One possibility to ease creating and maintaining syntax (rail) diagrams would be to have a tool that would allow to define one owns eEBNF (extended Backus-Naur-Form), such that different EBNF dialects could be used by different people and projects. If these eBNFs would then serve as the source to create syntax (rail) diagrams as ASCII or HTML and allowing to create graphics of them, then it should become possible again to deploy syntax diagrams with no real overhead anymore (just maintain the eBNF, the rest gets created automatically).

In OOo one could link to syntax (rail) diagram graphic files, such that in the main text and in the appendix the same physical graphics is referred to.

---

Now, some time ago I found a student, Franz Hohenegger, who took over the task of creating a little set of scripts and tools, which is intended to support people in the need of a syntax diagrams. He wrote the scripts in Rexx/ooRexx and in addition used the OOo writer module as a GUI. The GUI allows one to import eBNF definition files, render them to syntax (rail) diagrams and allows to export all definitions (e.g. edits) to external files, including the ability to create graphic files of it.

In addition he created a mapping to an eBNF-XML-format, which can be fed to utilities which are able to create the nicest rail-diagrams in the industry by using another set of opensource tools.

If interested then point your browser to: <http://wi.wu.ac.at/rgf/diplomarbeiten/index.htm#dipl_201110>. The paper in PDF being almost a picture book such that one can see right away what this project is about, what it does and allows for: <http://wi.wu.ac.at/rgf/diplomarbeiten/index.htm#dipl_201110>.

---rony

















_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[rvjansen]

Mike,

can I have the source anyway so we can think of a conversion method?
Because the parser itself does not use some kind of grammar
specification expression language, this probably still is the best way
to have syntax diagrams available some time.

best regards,

René.


On Tue, 22 Nov 2011 09:15:47 -0000, Mike Cowlishaw wrote:

>
> In the original book, the syntax diagrams at the top of each
> instruction section were formatted using the SCRIPT Mathematical
> Formula Formatter. One feature of doing it that way was that I could
> put them in a library and then include them in two places in the
> document while keeping a single copy of the source for each diagram
> (hence having only one place to modify when enhancements were made).
>
> When converting to use ODT the text of the book was/is largely
> converted automatically, but I had to manually recreate the syntax
> diagrams inline (which is why they are not quite as well formatted in
> a few cases). I could not find a way to have them be duplicated
> automatically to the appendix so had to drop the appendix -- sorry.
>
> There may be a way to do this, or Open Office may have a feature to
> make this easier now. But creating the Appendix by copy & paste (so
> two copies of each diagram would exist) is probably a bad idea.
>
> Mike

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[rvjansen]

very interesting - I have sure I have seen it before - so we have
nearly all pieces of the puzzle

1) math script reference diagrams
2) javacc grammar by Bill
3) antlr grammar by Chad Slaughter
4) ebnf conversion tooling by Franz
5) the actual implementation of the NetRexx parser

but we also have

1) no production process for math script - dcf
2) some limitations in the form of fixed keywords (correct me if I am
wrong, Bill)
3) reports that the antlr grammar (v2 and not v3) is not entirely
working for some cases
4) no ebnf representation of NetRexx grammar
5) no way to create a grammar representation from the parser

I would suggest we have a workshop/session planned at the Rexx Language
symposium to sketch the shortest way to fix this all, and have
conversions to ebnf and integrate these in our toolset. This not only
with the goal of having railroad diagrams, but in the wider perspective
of IDE's and language tools.

best regards,

René.


On Tue, 22 Nov 2011 11:13:07 +0100, Rony G. Flatscher wrote:

>
>  Now, some time ago I found a student, Franz Hohenegger, who took
> over the task of creating a little set of scripts and tools, which is
> intended to support people in the need of a syntax diagrams. He wrote
> the scripts in Rexx/ooRexx and in addition used the OOo writer module
> as a GUI. The GUI allows one to import eBNF definition files, render
> them to syntax (rail) diagrams and allows to export all definitions
> (e.g. edits) to external files, including the ability to create
> graphic files of it.
>
>  In addition he created a mapping to an eBNF-XML-format, which can be
> fed to utilities which are able to create the nicest rail-diagrams in
> the industry by using another set of opensource tools.
>
>  If interested then point your browser to:  [1]. The paper in PDF
> being almost a picture book such that one can see right away what
> this
> project is about, what it does and allows for:  [2].
>
>  ---rony
>
>
>
> Links:
> ------
> [1] http://wi.wu.ac.at/rgf/diplomarbeiten/index.htm#dipl_201110
> [2] http://wi.wu.ac.at/rgf/diplomarbeiten/index.htm#dipl_201110

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[billfen]

A grammar used for documentation and a grammar used as input to a parser
generator are not necessarily the same.

Generally parser generators like Antlr, JavaCC, Bison, etc. all have to
handle problems like ambiguity and look ahead.  The scanner (lexer or
tokenizer) mechanism, sometimes built into the parser generator or
separate like JFlex, Flex, etc. also has to be considered.  Since there
are numerous way to define a grammar for a given language, often various
tricks have to be used to allow the successful generation of a parser.  
Those distortions are not necessarily desirable if the grammar is
intended for documentation.

For example, because blanks are significant in NetRexx and the Eclipse
editing environment needs to tie all characters to tokens and upward, my
JavaCC grammar includes whitespace tokens.  Of course that may not be
appropriate for a grammar which is intended for documentation.

Another problem with a dynamic language like NetRexx is that keywords
may be overloaded, and documenting that behavior unambiguously in a
grammar is awkward.

Assuming that a preliminary (documentation oriented) grammar is easily
converted to a practical, robust parser by simply providing it as input
to a parser generator is often a mistake.  When a programmer asks "Is
there a grammar for NetRexx?"  he may be asking "Is there a working
grammar and parser generator combination?".  Two very different things.

Writing a grammar for documentation is generally straight forward.  In
some cases an Extended BNF is a bit more convenient than standard BNF,
but the actual work involved may not be all that different.

As has been pointed out, syntax ("railroad track") diagrams are somewhat
easier to understand than a machine readable grammar.  If the objective
is to generate syntax diagram graphics, probably the best approach is
let the tool which does that dictate the grammar type and syntax, and
just write the documentation grammar for it.  If the tool described by
Rony has an existing OORexx grammar, using that tool and modifying that
grammar might work.

Some languages provide a traditional BNF grammar, typically as an
appendix to the language definition.  Unfortunately there are various
versions of EBNF.  There is an ANSI Standard for EBNF, but it is
problematic and not commonly used.  It is likely that whatever machine
readable grammar is provided, an implementer may need to adapt it to
whatever tool is being used.

I think there is some value in having an explicit, formal language
definition so that implementers of the language have an unambiguous
reference which can be adapted to tools which take a grammar input.  
NetRexx is a relatively simple language, but there are some devilish
details if the grammar is input for a generator.

Bill

PS Rene, there is no problem with the form of keywords, just that they
may not be treated as such depending on the environment.

PPS The reference implementation does not use a grammar, and making sure
that its behavior is accurately described by a grammar is not simple -
I'm still working at that.

On 11/22/2011 7:27 AM, rvjansen wrote:

> very interesting - I have sure I have seen it before - so we have
> nearly all pieces of the puzzle
>
> 1) math script reference diagrams
> 2) javacc grammar by Bill
> 3) antlr grammar by Chad Slaughter
> 4) ebnf conversion tooling by Franz
> 5) the actual implementation of the NetRexx parser
>
> but we also have
>
> 1) no production process for math script - dcf
> 2) some limitations in the form of fixed keywords (correct me if I am
> wrong, Bill)
> 3) reports that the antlr grammar (v2 and not v3) is not entirely
> working for some cases
> 4) no ebnf representation of NetRexx grammar
> 5) no way to create a grammar representation from the parser
>
> I would suggest we have a workshop/session planned at the Rexx
> Language symposium to sketch the shortest way to fix this all, and
> have conversions to ebnf and integrate these in our toolset. This not
> only with the goal of having railroad diagrams, but in the wider
> perspective of IDE's and language tools.
>
> best regards,
>
> René.
>
>
> On Tue, 22 Nov 2011 11:13:07 +0100, Rony G. Flatscher wrote:
>>
>>  Now, some time ago I found a student, Franz Hohenegger, who took
>> over the task of creating a little set of scripts and tools, which is
>> intended to support people in the need of a syntax diagrams. He wrote
>> the scripts in Rexx/ooRexx and in addition used the OOo writer module
>> as a GUI. The GUI allows one to import eBNF definition files, render
>> them to syntax (rail) diagrams and allows to export all definitions
>> (e.g. edits) to external files, including the ability to create
>> graphic files of it.
>>
>>  In addition he created a mapping to an eBNF-XML-format, which can be
>> fed to utilities which are able to create the nicest rail-diagrams in
>> the industry by using another set of opensource tools.
>>
>>  If interested then point your browser to:  [1]. The paper in PDF
>> being almost a picture book such that one can see right away what this
>> project is about, what it does and allows for:  [2].
>>
>>  ---rony
>>
>>
>>
>> Links:
>> ------
>> [1] http://wi.wu.ac.at/rgf/diplomarbeiten/index.htm#dipl_201110
>> [2] http://wi.wu.ac.at/rgf/diplomarbeiten/index.htm#dipl_201110
>

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/

[Mike Cowlishaw]

 
The original SMFF source would not be of much use as it was used only for the
NetRexx book, and was not updated to NRL2/3 level.

Mike

> -----Original Message-----
>
>
> can I have the source anyway so we can think of a conversion method?
> Because the parser itself does not use some kind of grammar
> specification expression language, this probably still is the
> best way to have syntax diagrams available some time.
>
> best regards,
>
> René.
>
>
> On Tue, 22 Nov 2011 09:15:47 -0000, Mike Cowlishaw wrote:
> >
> > In the original book, the syntax diagrams at the top of each
> > instruction section were formatted using the SCRIPT Mathematical
> > Formula Formatter. One feature of doing it that way was
> that I could
> > put them in a library and then include them in two places in the
> > document while keeping a single copy of the source for each diagram
> > (hence having only one place to modify when enhancements were made).
> >
> > When converting to use ODT the text of the book was/is largely
> > converted automatically, but I had to manually recreate the syntax
> > diagrams inline (which is why they are not quite as well
> formatted in
> > a few cases). I could not find a way to have them be duplicated
> > automatically to the appendix so had to drop the appendix -- sorry.
> >
> > There may be a way to do this, or Open Office may have a feature to
> > make this easier now. But creating the Appendix by copy & paste (so
> > two copies of each diagram would exist) is probably a bad idea.
> >
> > Mike
>
> _______________________________________________
> Ibm-netrexx mailing list
> [hidden email]
> Online Archive : http://ibm-netrexx.215625.n3.nabble.com/
>

_______________________________________________
Ibm-netrexx mailing list
[hidden email]
Online Archive : http://ibm-netrexx.215625.n3.nabble.com/