On 09.04.2020 15:24, Erich Steinböck wrote:
Rony, I'd rather avoid introducing new terminology like
"specializes", "constructor" or "destructor" - none of our ooRexx
docs use it.
You may have noted that "specializes" is given in parentheses
"(specializes)" like in:
4.1.4. The Bag Class
A collection where the index is equal to the value. Bag indexes
can be any object (as with the Table class) and each index can
appear more than once.
The class Bag subclasses (specializes) Object and inherits
(specializes) in addition in the following order:
• MapCollection
• SetCollection
The purpose of this addition of the term "(specializes)" is to
communicate to the reader that in this case the Bag class due to
multiple inheritance specializes all three superclasses, the
immediate one (using the ooRexx term "subclass") and the two
inherited ones (using the ooRexx term "inherits"). So the intention
is to communicate to the reader that in effect the "Bag" class
specializes conceptually three superclasses at the same time which
he may not be aware of.
However, if this is seen to be not helpful or superfluous or
distracting then it would not serve its intended purpose.
How does this bode to other readers: is this helpful, not helpful,
even distracting?
---
Ad explicitly denoting which Rexx methods are the Rexx constructor
method and Rexx destructor method has two intentions, one to point
newcomers with oo-expertise to them (they may be seeking them and it
would be hard to guess that the methods named init and uninit are
these important life-cycle related methods), and one to just teach
all-newbies that the generic technical oo-term for the init and
uninit methods are constructor and destructor method (fundamental
terms like "object", "method" that oo-programmers should know).
The way this information got added to the programmer's guide was
attempted in a non-distracting manner by inserting a short sentence
to point out that fact:
* "5.2.1. Initializing Instances Using INIT"
o ... As the INIT method gets invoked automatically at object
creation time it is also known as the Rexx constructor
method. ...
* "5.2.3. Uninitializing and Deleting Instances Using UNINIT"
o ... Because this method runs at destruction time only it is
called the Rexx desctructor method. ...
---
The same intention using the opportunity of updating the
documentation is true for adding the term "attribute" wherever
"variables", "object variables", "instance variables", "variable
pools" that relate to "object variable pools" are mentioned to help
the reader to learn that all these terms denote the same,
attributes, hoping to clarify and reduce confusion that otherwise
occurs when expecting that different terms denote different concepts.
It is hoped that by this it is becomes possible for the reader to
relate the ::attribute directive with all those terms ("object
variable", "instance variable", ...) and explanations in the context
of chapter 5.
Using hard-coded cross-book references like below doesn't seem to
be a good idea (and rexxref really isn't called "Open Object
Reference Documentation" either).
Open Object Reference Documentation, section "4.2.11 Required
String Values"
Yes, this is currently stated in the draft. I noticed when searching
on the Internet DocBook related information in the past that in some
hits there were pointers about linking to external DocBooks from
another one, such that somehow external DocBook references are
supported, although I did not take the time to research that while
trying to update this "Programmer Guide" book. (This was planned at
a later time, once my work is concluded on rexxpg.)
What I think important for the reader is that he learns about the
concept of the "required string values" in ooRexx and the exact
mechanism if interested, and where to find the documentation of it.
(The programming guide is not the place to explain that in all
detail like defaultname and string, but give the most important
information from a bird's eye view.) Personally I think that the
original author who thought that the SAY instruction would send the
STRING message was not aware of that fundamental "required string
value" concept and how it works (and that it gets triggered for BIFs
as well), so such a pointer would have been helpful for him as well,
if it existed.
As the programming guide should help a newcomer (oo-educated or not)
to get acquainted with the most important concepts of ooRexx quickly
and to learn where to look for more details, if interested, that
such references are important to them.
And yes, you are of course right, the title ought to match exactly
with the rexxref.pdf one (e.g. in my case "ooRexx Documentation
5.0.0.r11986, Open Object Rexx, Reference")!
I noticed instances where the SAY instruction is marked with
<methodname> tags.
Yes, because there are no <instruction> tags that could be used
e.g. for the SAY instruction, the same is unfortunately also true
for routine names as there are no <routine> or <function> tags.
(This was the reason for my questions a couple of weeks ago that
went unanswered.)
As with method names that get set apart in the text with a
mono-spaced normal font, instructions, keywords, routine/function
names should be set apart as well with a mono-spaced normal font,
IMHO. Except, there are no such specific tags available!
Here is what the common typographic hints of the ooRexx books tell
the reader (the reader does not get to see the tag names at all) at
the beginning of each ooRexx book:
<ljinmmmjohecjlbl.png>
Here is the XML text for the above renderings:
... cut ...
<section>
<title>Document Conventions</title>
<para>
This manual uses several conventions to highlight certain words
and phrases and draw attention to specific pieces of information.
</para>
<section>
<title>Typographic Conventions</title>
<para>
Typographic conventions are used to call attention to specific
words and phrases. These conventions, and the circumstances they apply to, are
as follows.
</para>
<para>
<literal>Mono-spaced Bold</literal> is used to highlight
literal strings, class names, or inline code examples. For example:
</para>
<blockquote>
<para>
The <classname>Class</classname> class comparison methods return
<literal>.true</literal> or <literal>.false</literal>, the result of performing the
comparison operation.
</para>
<para>
This method is exactly equivalent to <code>subWord(</code><emphasis
role="italic">n</emphasis><code>, 1)</code>.
</para>
</blockquote>
<para>
<methodname>Mono-spaced Normal</methodname> denotes method
names or source code in program listings set off as separate examples.
</para>
<blockquote>
<para>
This method has no effect on the action of any <methodname>hasEntry</methodname>,
<methodname>hasIndex</methodname>, <methodname>items</methodname>, <methodname>remove</methodname>, or
<methodname>supplier</methodname> message sent to the collection.
</para>
<para>
<programlisting>-- reverse an array
a = .Array~of("one", "two", "three", "four", "five")
-- five, four, three, two, one
aReverse =
.CircularQueue~new(a~size)~appendAll(a)~makeArray("lifo")</programlisting>
</para>
</blockquote>
<para>
<emphasis role="italic">Proportional Italic</emphasis> is used
for method and function variables and arguments.
</para>
<blockquote>
<para>
A supplier loop specifies one or two control variables, <emphasis
role="italic">index</emphasis>, and <emphasis role="italic">item</emphasis>, which
receive a different value on each repetition of the loop.
</para>
<para>
Returns a string of length <emphasis role="italic">length</emphasis> with <emphasis
role="italic">string</emphasis> centered in it and with <emphasis role="italic">pad</emphasis>
characters added as necessary to make up length.
</para>
</blockquote>
</section>
<section>
<title>Notes and Warnings</title>
<para>
Finally, we use three visual styles to draw attention to
information that might otherwise be overlooked.
</para>
... cut ...
So "Mono-spaced Normal" is not marked-up with some
monospacednormal-tag, but with the methodname-tag:
"<methodname>Mono-spaced Normal</methodname>", because that tag
causes the marked up text to be rendered as "mono-spaced normal"
text shown to the reader. This works without any problem as the
reader does not get to see the tag, only the result of being
rendered as a mono-spaced normal text!
Short of tag names for instructions (keywords, subkeywords), the
names of routines and functions I have used the methodname-tag in
order to achieve the same rendering while marking them up .
I agree that it would be better if the tag name would indicate the
type that gets marked up, but unfortunately such tag names do not exist!
If you know of a version of the emphasis (or any other neutral) tag
that would cause the marked up text to be rendered as "mono-spaced
normal", then please let me know, I will then change those
occurrences of instructions (keywords, subkeywords), the names of
routines and functions accordingly. (Although for all practical
reasons it would make no difference.)
---
The ooRexx stripped down version of "Conventions.xml" does not use
all tag names that are available in DocBook. This is the reason why
I pointed that out some time ago and created the "test.pdf" book
that got placed in the same directory where the current "rexxpg.pdf"
draft resides for others to inspect.
In it I also gave examples of other existing DocBook tag names (cf.
"1.4. Some Markup in DocBook ...") that could be used for the ooRexx
books, as a result also demonstrating their typographic rendering
such that one becomes able to judge how it would look (and allowing
to decide whether to use those tags or not).
In addition the full original "Conventions.xml" is given in
"test.pdf" as well, just look up all "1.5 Document Conventions ..."
there.
---
Because it is important to agree upon how instructions (keywords,
subkeywords), the names of routines and functions get typeset, I
have asked that a couple of weeks ago without getting an answer.
In the current draft I used the methodname tag such that
instructions (keywords, subkeywords), the names of routines and
functions get typeset exactly as method names, namely in mono-spaced
normal text, such that they are set apart from the proportional
normal text in order for the reader to notice that this is an exact
ooRexx name for an instruction/keyword/subkeyword/routine/function.
Adding the markup is the quite a laborious task as everyone knows.
When I started out with rexxpg almost none of such markup was
present in the entire programmers' guide, rather the emphasis-tag
was used here and there (which I used in the beginning before
learning about the tag names that got used in other books and
finally what DocBook makes available).
Maybe the questions that I have in this context are as follows:
* Why would one mark up up the names of methods but not the names
of instructions, keywords, subkeywords, routines and functions
as mono-spaced normal text?
* The reader is only presented with how some kind of terms get
typographically rendered (see screenshot above) and in it the
author even uses the methodname tag to demonstrate mono-spaced,
normal font, short of any other tag that does that. Should the
methodname tag be used for method names only?
* Should the names of Rexx instructions, keywords, subkeywords,
routines and functions be marked up in the text? And if so, how,
if one is not supposed to use the methodname tag that causes the
typesetting in a mono-spaced, normal font?
---rony
On Thu, Apr 9, 2020 at 12:55 AM Rony G. Flatscher
<rony.flatsc...@wu.ac.at <mailto:rony.flatsc...@wu.ac.at>> wrote:
At [1] you will find two versions of "rexxpg.pdf":
* "rexxpg-before-changing-chapter-5.pdf"
* and the latest draft "rexxpg.pdf"
There has been a *lot* of work in correcting, completing,
updating, enhancing this chapter which among other things
contained outright wrong information like:
say myarray /* SAY sends STRING message to Myarray */
Results:
an Array
Whenever a method
The SAY instruction does *not* send the string message,
rather the required string mechanism gets triggered for
such instructions or classic Rexx built-in functions, the
output has changed as Array's makestring method employs its
tostring method which turnes the array object to a string
where each stored item's string value is listed in its own
line (items are separated by CR-LF).
There are many places where a reader, especially a newcomer
cannot realize what the term "variable" denotes in which
context. Now that we have an attribute directive I added in
parentheses that term to make it a) clear that an
object/instance variable a.k.a. attribute is meant and b) that
the relationship to the attribute directive becomes clear.
Many little things got tackled as well, like wrong examples or
new examples to demonstrate the environment object .syscargs,
markup at wrong places, ...
As this was more than a day's work and I am not a native
English speaker I would really appreciate if some native
speakers would proof-read that chapter 5, A Closer Look at
Objects. If something is unclear or the English needs
corrections or brush ups, please let me know. Chances are that
you learn something new as a price! ;-)
---rony
[1] Temporary Dropbox link to the above books:
<https://www.dropbox.com/sh/gxvvgskb04gdsqf/AACRo_ZLeFOdoBXUHroPY_-Ca?dl=0>
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
