ooRexx Reference Manual syntax diagrams

[Jennifer Murphy]

Am I the only one who thinks that the syntax diagrams in the ooRexx
Reference Manual are unusable?

Here's the one for RxMessageBox:

>>-RxMessageBox(text-------------------------------------------->
>--+--------------------------------------------+--)-----------><
+-,--+-------+--+--------------------------+-+
+-title-+ +-,--+--------+--+-------+-+
+-button-+ +-,icon-+

What genius concocted this mess?

[Jeremy Nicoll - news posts]

It's an 'ASCII art' version of the diagrams from the original IBM manuals, I
think. They're a bit easier to read because, for example,

--+--
+-

is shown in the originals as a line drawing with eg a T-junction above a
box's bottom-lefthand-corner etc, if you see what I mean.

--
Jeremy C B Nicoll - my opinions are my own.

Email sent to my from-address will be deleted. Instead, please reply
to newsre...@wingsandbeaks.org.uk replacing "aaa" by "284".

[LesK]

As Jeremy said, it's the best approximation of the real diagrams that
IBM used in their printed manuals. It can be a real eyesore if you're
looking at html with your own fonts & size preferences.

For an example of an IBM manual, see (watch out for the line break):

http://publibz.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/DMSE2A04/1.3.1?DT=19931019123248

--

Les (Change Arabic to Roman to email me)

[Jennifer Murphy]

On Thu, 28 Aug 2014 00:56:41 +0100, Jeremy Nicoll - news posts
<jn.nntp....@wingsandbeaks.org.uk> wrote:

>Jennifer Murphy <JenM...@jm.invalid> wrote:
>
>>Am I the only one who thinks that the syntax diagrams in the ooRexx
>>Reference Manual are unusable?
>>
>>Here's the one for RxMessageBox:
>>
>> >>-RxMessageBox(text-------------------------------------------->
>> >--+--------------------------------------------+--)-----------><
>> +-,--+-------+--+--------------------------+-+
>> +-title-+ +-,--+--------+--+-------+-+
>> +-button-+ +-,icon-+
>
>It's an 'ASCII art' version of the diagrams from the original IBM manuals, I
>think. They're a bit easier to read because, for example,
>
> --+--
> +-
>
>is shown in the originals as a line drawing with eg a T-junction above a
>box's bottom-lefthand-corner etc, if you see what I mean.

In my opinion, this is not art, ASCII or otherwise. It's ridiculous and
essentially useless.

What's wrong with somthing like:

result = RxMessageBox(message, [title], [button], [icon])

It's simple, easy to read, and more or less standard.

[Jennifer Murphy]

On Wed, 27 Aug 2014 22:10:42 -0400, LesK <5mr...@tampabay.rr.com> wrote:

>On 8/27/2014 12:46 PM, Jennifer Murphy wrote:
>> Am I the only one who thinks that the syntax diagrams in the ooRexx
>> Reference Manual are unusable?
>>
>> Here's the one for RxMessageBox:
>>
>> >>-RxMessageBox(text-------------------------------------------->
>> >--+--------------------------------------------+--)-----------><
>> +-,--+-------+--+--------------------------+-+
>> +-title-+ +-,--+--------+--+-------+-+
>> +-button-+ +-,icon-+
>>
>> What genius concocted this mess?
>>
>As Jeremy said, it's the best approximation of the real diagrams that
>IBM used in their printed manuals. It can be a real eyesore if you're
>looking at html with your own fonts & size preferences.

It *IS* an eyesore.

>For an example of an IBM manual, see (watch out for the line break):
>
>http://publibz.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/DMSE2A04/1.3.1?DT=19931019123248

That's not much better. Maintaining compatibility with a bad idea is a
doubly bad idea, because we ought to learn from what doesn't work. I
cannot believe these manuals are maintained this way.

[Rony]

No, it is wrong (it implies that you must give the commas, even if the trailing arguments are all
omitted).

Your example would need to read something like:

result=RxMessageBox(text [, [title] [, [button] [, icon]]]])

Then, as you see, it is not so easy anymore to immediately grasp the syntax variants that function
allows for.

---

A couple of years ago Jean Louis Faucher (a member of the ooRexx developer team) created nice
looking rail diagrams for all of the ooRexx documentation, but somehow they got not picked up by the
ooRexx development team. With the help of Google I just located his versions of the ooRexx 4.2.0
documentations from August 2012:
<https://dl.dropboxusercontent.com/u/20049088/oorexx/docs/trunk/index.html>. Download the PDFs and
compare the syntax diagrams with the current ones. [Arrived at the above URL after googling and
getting the following hit: <https://sites.google.com/site/jfaucherfr/oorexx/syntax-diagrams>, a
document from September 2011 giving further links that contained newer versions of his renderings.]


A few weeks ago David Ashley (another member of the ooRexx developer team) started out from zero to
come up with nicer looking rail-diagrams and is in the process of finishing them. There was one
posting on the ooRexx developer mailing list to the effect, that the EBNF the used generation tool
defines does not allow for default values, which would be a bummer, as default values for omitted
arguments is extremely important for the Rexx language (cf.
<http://sourceforge.net/p/oorexx/mailman/message/32699294/>). Though, no reaction to that e-mail
took place there, so we will need to see in the final outcome, whether default values can
nevertheless be documented in David's syntax rail diagrams or not. No actual URL that I am aware of
to see the updated ooRexx documentation.

---rony

[Jennifer Murphy]

On Thu, 28 Aug 2014 13:00:24 +0200, Rony <rony.fl...@wu-wien.ac.at>
wrote:

Fine. I'm not going to debate whether this little nit is worth picking
except to say that only a pathological obsessive-compulsive of the order
of Dr. Sheldon Cooper* would not immediately understand that the commas
are NOT required.

>Your example would need to read something like:
>
> result=RxMessageBox(text [, [title] [, [button] [, icon]]]])

I'm OK with this slightly more complicated diagram, although I find it
totally unnecessary.

>Then, as you see, it is not so easy anymore to immediately grasp the syntax variants that function
>allows for.

No, I do NOT see. It's only difficult if you allow perfect to be the
enemy of good.

>A couple of years ago Jean Louis Faucher (a member of the ooRexx developer team) created nice
>looking rail diagrams for all of the ooRexx documentation, but somehow they got not picked up by the
>ooRexx development team. With the help of Google I just located his versions of the ooRexx 4.2.0
>documentations from August 2012:
><https://dl.dropboxusercontent.com/u/20049088/oorexx/docs/trunk/index.html>. Download the PDFs and
>compare the syntax diagrams with the current ones. [Arrived at the above URL after googling and
>getting the following hit: <https://sites.google.com/site/jfaucherfr/oorexx/syntax-diagrams>, a
>document from September 2011 giving further links that contained newer versions of his renderings.]

I find that diagram only a little better than the character-based
diagram in the Reference Manual. They are both unnecessarily complex.

>A few weeks ago David Ashley (another member of the ooRexx developer team) started out from zero to
>come up with nicer looking rail-diagrams and is in the process of finishing them. There was one
>posting on the ooRexx developer mailing list to the effect, that the EBNF the used generation tool
>defines does not allow for default values, which would be a bummer, as default values for omitted
>arguments is extremely important for the Rexx language (cf.
><http://sourceforge.net/p/oorexx/mailman/message/32699294/>). Though, no reaction to that e-mail
>took place there, so we will need to see in the final outcome, whether default values can
>nevertheless be documented in David's syntax rail diagrams or not. No actual URL that I am aware of
>to see the updated ooRexx documentation.

Default values are easy to accommodate in the standard line syntax:

result = RxMessageBox(message, [title|"Error"], [button|"OK"], [icon])

If the syntax is too too long for one line, it can be continued in
several ways:

result = RxMessageBox(message, [title|"Error"],
[button|"OK"], [icon])

or

result = RxMessageBox(message, [title|"Error"], [flags])

flags = [button|"OK"], [icon]

Cheers

PS: The 4.1.1 documentation is riddled with errors and typos. Most of
them are fairly minor. But I find it highly ironic that the ooRexx
developers would be so obsessive about a useless syntax diagram while
leaving hundreds of actual errors uncorrected.

Here are a few examples just in the description for RxMessageBox:

Page 443

Incorrect: If a message box has a "CANCEL" button, the function returns
the 2 value if either the ESC key is pressed or the "CANCEL" button is
selected. If the message box has no "CANCEL" button, pressing ESC has no
effect.

Correct: For some incomprehensible reason, the ESC key has a variable
effect depending on what buttons are present:

CANCEL OK Result
Y -- 2
N Y 1
N N No effect

Page 443 under *title*

Incorrect: The default title is "Error!".

Correct: The default title is "Error". (No "!".)

Page 443

Incorrect: "NONE"
No icon is displayed.

Correct: "NONE" is not a valid argument. It will generate an error. The
action described is what till happen if no argument is specified.

Page 444

The *icon* descriptions are all screwed up.

The correct behavior is:

Default: No icon

STOP/ERROR/HAND: A Red button with an "X".

QUESTION/QUERY: A question mark ("?") in a white balloon.

EXCLAMATION/WARNING: An exclamation point ("!") in a yellow triangle.

INFORMATION/ASTERISK: An "i" in a white balloon.

And there is no mention of the sound and how they are tied to the
Windows settings.

That's 3 errors on just two pages for one function.




* From *The Big Bang Theory*, a sitcom.

[Shmuel Metz]

In <kv7uv991ck6ig2kgd...@4ax.com>, on 08/28/2014

at 06:12 AM, Jennifer Murphy <JenM...@jm.invalid> said:

>Fine. I'm not going to debate whether this little nit is worth
>picking except to say that only a pathological obsessive-compulsive
>of the order of Dr. Sheldon Cooper* would not immediately
>understand that the commas are NOT required.

Only a fool with delusions of adequacy would dismiss legitimate
concerns for accuracy as anal retentive. Only the king of the country
of fools would believe that such errors never trip anybody up.

>PS: The 4.1.1 documentation is riddled with errors and typos.

Have you reported them?

--
Shmuel (Seymour J.) Metz, SysProg and JOAT <http://patriot.net/~shmuel>

Unsolicited bulk E-mail subject to legal action. I reserve the
right to publicly post or ridicule any abusive E-mail. Reply to
domain Patriot dot net user shmuel+news to contact me. Do not
reply to spam...@library.lspace.org

[Shmuel Metz]

In <ltm330$huj$1...@speranza.aioe.org>, on 08/27/2014

at 10:10 PM, LesK <5mr...@tampabay.rr.com> said:

>As Jeremy said, it's the best approximation of the real diagrams
>that IBM used in their printed manuals.

Well, best given the limitations of ASCII. They could do better using
UTF-8, but TANSTAAFL.

[Jennifer Murphy]

On Thu, 28 Aug 2014 10:15:51 -0400, Shmuel (Seymour J.) Metz
<spam...@library.lspace.org.invalid> wrote:

>In <kv7uv991ck6ig2kgd...@4ax.com>, on 08/28/2014
> at 06:12 AM, Jennifer Murphy <JenM...@jm.invalid> said:
>
>>Fine. I'm not going to debate whether this little nit is worth
>>picking except to say that only a pathological obsessive-compulsive
>>of the order of Dr. Sheldon Cooper* would not immediately
>>understand that the commas are NOT required.
>
>Only a fool with delusions of adequacy would dismiss legitimate
>concerns for accuracy as anal retentive.

"Delusions of adequacy"? Now you're just making stuff up.

The key word here is "legitimate". In my opinion, it must also be
significant. Of course, the Dr. Cooper's of the world are never able to
deal in anything but absolutes.

I agree with you about the commas. I just don't think it's a big deal.
Compared to the utter uselessness of the

>Only the king of the country
>of fools would believe that such errors never trip anybody up.

Again with the absolutes. If you really want a document that can can
*NEVER* trip anyone up, prepare for an infinite development cycle.

[Shmuel Metz]

In <12huv9pt981gnmnv7...@4ax.com>, on 08/28/2014

at 08:08 AM, Jennifer Murphy <JenM...@jm.invalid> said:

>I agree with you about the commas. I just don't think it's a big
>deal. Compared to the utter uselessness of the

>>Only the king of the country
>>of fools would believe that such errors never trip anybody up.

Humor is such a subjectiove thing.

>I agree with you about the commas.

Really? Then why did you write "only a pathological

obsessive-compulsive of the order of Dr. Sheldon Cooper* would not

immediately understand that the commas are NOT required."?That may be
your opinion, but it is certainly not mine.

[Jennifer Murphy]

On Thu, 28 Aug 2014 16:38:03 -0400, Shmuel (Seymour J.) Metz
<spam...@library.lspace.org.invalid> wrote:

>In <12huv9pt981gnmnv7...@4ax.com>, on 08/28/2014
> at 08:08 AM, Jennifer Murphy <JenM...@jm.invalid> said:
>
>>I agree with you about the commas. I just don't think it's a big
>>deal. Compared to the utter uselessness of the
>
>>>Only the king of the country
>>>of fools would believe that such errors never trip anybody up.
>
>Humor is such a subjectiove thing.
>
>>I agree with you about the commas.
>
> Really? Then why did you write "only a pathological
>obsessive-compulsive of the order of Dr. Sheldon Cooper* would not
>immediately understand that the commas are NOT required."?That may be
>your opinion, but it is certainly not mine.

I agree with you that my original syntax diagram could be interpreted to
say that the commas are required. My point is that no rational person
who has any programming experience would read it that way. But then I
think you knew that.

[Jeremy Nicoll - news posts]

Jennifer Murphy <JenM...@jm.invalid> wrote:

>On Wed, 27 Aug 2014 22:10:42 -0400, LesK <5mr...@tampabay.rr.com> wrote:

>>For an example of an IBM manual, see (watch out for the line break):
>>
>>http://publibz.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/DMSE2A04/1.3.1?DT=19931019123248
>
>That's not much better.

Hmm, looking at that here in Firefox, it seems pretty bad; I don't know why.
But here's a screenshot of the RxMessageBox diagram in an IBM manual:

http://www.wingsandbeaks.org.uk/IBMmanual01.jpg 40 KB


Personally I don't find that hard to read; here's another example where I
think the format is significantly easier to read than something text-based:

http://www.wingsandbeaks.org.uk/IBMmanual02.jpg 35 KB

[LesK]

The fact is, it *does* work, as years and years of IT and customer
experience can attest to. It's similar to an EBNF visualizer, but much
simpler to create, although the diagrams created in the 'old days' by
IBM's SCRIPT/VS and GML for high-quality printing are a lot nicer (as
Jeremy's post shows) than what is sometimes created in ASCII or html.

*You* may not like them, but these diagrams are heavily used in IT to
easily and concisely describe syntax.

[Jennifer Murphy]

I guess we'll have to agree to disagree about which type of syntax
diagram is better and for which audience, but what we have in the
Reference Manual is an unmitigated disaster. Character art should have
died with the card punch or, at least, with the character-based
terminals like the 3270. This is 2014, for crying out loud.

[Shmuel Metz]

In <mpro.nb1ngu...@wingsandbeaks.org.uk.invalid>, on
08/29/2014
at 02:14 AM, Jeremy Nicoll - news posts

<jn.nntp....@wingsandbeaks.org.uk> said:

>Hmm, looking at that here in Firefox, it seems pretty bad; I don't
>know why.

Probably due to the font; those diagrams are generated for a monopitch
font.

[Shmuel Metz]

In <t6avv9d61p7p7u5cq...@4ax.com>, on 08/28/2014

at 03:12 PM, Jennifer Murphy <JenM...@jm.invalid> said:

>I agree with you that my original syntax diagram could be
>interpreted to say that the commas are required. My point is that
>no rational person who has any programming experience would read
>it that way.

That's not a point, it's an incorrect assumption.

>But then I think you knew that.

What I knew, tonto, was that you were making an ad hominem argument.
Believe it or not, people with a lot more experience than you disagree
with your view.

[LesK]

But would you be happy if the syntax diagrams were prettier? I can, with
THE and the Lucida font, create essentially perfect syntax diagrams.

But that doesn't solve the problem of doing it in html *without* having
to use a lot of <img> markup and having to package a lot of external
files. Plus, as someone else has noted, what you see on the web is
almost _entirely_ under your own control! Most browsers allow you to
select your own fonts, set font size, etc. which can destroy what was
intended to be presented (overriding a fixed width font with a variable
width font, for instance).

I suspect, but don't know, that character art is the only thing that can
be used that is acceptable for all the documentation target media.

I'm sure the ooRexx Developers would welcome your assistance in
improving what they have!

[Jennifer Murphy]

I doubt it. They won't even let me register.