See comments in-line:
On 4/6/2020 9:16 AM, Rony G. Flatscher wrote:
Erich,
On 05.04.2020 17:47, Erich Steinböck wrote:
I don't think fonts and emphasis should be used within a heading (classname tag
etc.) - none of
our books do.
hmm, maybe I was not communicating that this is just a draft a work-in-progress
(WIP) that
concentrates on your remark about Array and the 4.2 rexxpg class hierarchy.
Removing markup from the title elements would be done later in a separate step
such that it can be
re-instated later, should such a desire ever arise in the future (adding markup
is quite cumbersome
and time-consuming, removing it is not so, could be even done with a simple
script).
First let me say that I agree with Erich that the tags in the headings
do not, IMO, add any value. Some DocBook elements are best treated as if
they are "atomic", i.e. self-contained. I think that headings and
program listings fall into that category. I would not foresee that
re-instating the tags in the headings would ever be desired so do not
make extra work for yourself by trying to make them easy to put back.
Sometimes the results of our efforts are not what we expected and I feel
that this is one of them.
The class hierarchy still doesn't show (e. g.) Array indented below
OrderedCollection - as said,
compare this with the easy to understand 4.2 layout.
The "easy to understand 4.2 layout" has the problem that it is not correct. The
class hierarchy in
4.2 has the fundamental problem that it ignores multiple inheritance [2].
Array is a direct subclass of Object and inherits from OrderedCollection but is
only shown in 4.2 as
a direct subclass of OrderedCollection which it is not.
I think the problem here is that we are all used to thinking of the
Array class, for example, as a sub-class of the Ordered Collection
class, even though it technically is not. This is probably due to the
way the classes are described in the Reference book. So, the question
then becomes "Is it more important to be consistent between the two
books or to be technically correct?".
Fundamentally, the problem stems from the fact that we are trying to
represent what is essentially a "graph" as a "tree" and there is no easy
answer to how to accomplish that.
Just my thoughts, FWIW. Gil
Or, take the Bag class in 4.2: it is only shown as a direct subclass of the
SetCollection which it
is not. In 4.2 Bag is neither shown as a MapCollection class, nor that its a
direct subclass of
Object, nor is there any hint to that effect anywhere in that version.
Looking at the class hierarchy in the 4.2 version [2] it is clear that the
author attempted to show
each class only once, which inhibits redundancy, it is therefore a "compact class
hierarchy".
However, the way It is done causes a wrong and an incomplete documentation of
those classes that
inherit more than a single class.
The class hierarchy in draft/WIP version [1] is also a compact class hierarchy,
one that - with the
help of ooRexx itself - correctly shows each class underneath its direct
superclass and in addition
supplies the relevant and important inherit information to completely document
the class.
---
It seems that you have missed the second class hierarchy at the end of chapter
4 which I pointed at
in my e-mail.
In [1] look-up "4.6. Class Tree Depicting Mixin with the Classes that Inherit". This
"exploded"
class tree documents the mixin classes with the classes that inherit it. This
way the reader gets -
what you were seeking in your first feedback - a listing of all classes
underneath OrderedCollection
such that Array will be listed there.
The Bag class will be shown as a direct subclass of Object and gets listed in
addition as an
inheriting subclass of MapCollection *and* of SetCollection.
All classes in the class hierarchy of [1] (both versions, the compact and the
exploed one) are
hyperlinked to the respective brief class descriptions in section 4.1.x. So
there will be links to
"4.1.3 The Array Class", "4.1.4 The Bag Class", ..., "4.1.33 The OrderedCollection
Class", ...
All the brief description of the classes in 4.1.x in [1] got additional brief
information that will
document which class they immediately subclass. In case of a class that
inherits other mixin classes
a list of those inherited classes (documenting the order too) is given. In case
of a mixin class all
classes that use it via inheritance are listed alphabetically. Note, all these
classes are linked to
their respective brief class descriptions given in section 4.1.x.
---
So these two changes, the supplemented brief class descriptions (subsections
4.1.x), and the
exploded class hierarchy (4.6), were at the heart of this draft/WIP version as
I tried to point out
in my e-mail.
This way one can take a look at how this information looks like and whether the
compact class tree
together with the supplemented brief class descriptions would give all
information in a complete and
easy to understand manner.
Also one can study the exploded class hierarchy which correctly depicts all
classes at all their
subclass positions (due to multiple inheritance), making the hierarchy grow
larger and adding some
redundancy.
And the hierarchy refers to the "mixin" term which is only discussed at a much
later chapter.
This can be fixed easily by using a link to the chapter that discusses the term.
As a matter of fact I just updated the current draft/WIP accordingly so you may
want to check the
updated rexxpg.pdf from [1].
---rony
[1] Current draft/WIP "rexxpg.pdf":
<https://www.dropbox.com/sh/gxvvgskb04gdsqf/AACRo_ZLeFOdoBXUHroPY_-Ca?dl=0>
[2] ooRexx "4.2 rexxpg.pdf":
<https://sourceforge.net/projects/oorexx/files/oorexx-docs/4.2.0/rexxpg.pdf/download>
_______________________________________________
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
