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
