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:
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
