> 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?
Another question that has come up reading your statement:
* why would one mark up Rexx method name symbols thereby emphasizing them in
the resulting typeset book, but none of the other Rexx symbols (instruction
names etc) in the text, what is the reasoning?
—-rony
Rony G. Flatscher (mobil/e)
>> Am 09.04.2020 um 19:46 schrieb Gil Barmwater <gbarmwa...@alum.rpi.edu>:
>
> There is so much in this note that I decided to comment only on the questions
> regarding SAY. I see no need to do any typographical marking for keywords or
> sub-keywords other than making them all capitals. This is the "convention"
> used in the Reference and it seems to be enough. This also applies to
> functions and routines. (I also notice that sometimes a keyword is rendered
> as CALL but also as Call. I do not find that confusing.) FWIW
>
> Gil
>
> On 4/9/2020 11:21 AM, Rony G. Flatscher wrote:
>> 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"
>> ... 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"
>> ... 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>
>>> 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
> --
> Gil Barmwater
> _______________________________________________
> Oorexx-devel mailing list
> Oorexx-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/oorexx-devel
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
