On 10.03.2020 14:24, Rick McGuire wrote:
>
> On Tue, Mar 10, 2020 at 9:12 AM Rony G. Flatscher <rony.flatsc...@wu.ac.at
> <mailto:rony.flatsc...@wu.ac.at>> wrote:
>
> Thank you for your feedback, Rick. As a result the current rexxpg book at
>
> <https://www.dropbox.com/sh/gxvvgskb04gdsqf/AACRo_ZLeFOdoBXUHroPY_-Ca?dl=0>
>
> <https://www.dropbox.com/sh/gxvvgskb04gdsqf/AACRo_ZLeFOdoBXUHroPY_-Ca?dl=0>
> reflects the
> changed hierarchy tree (created from a script).
>
> There would be two questions still:
>
> * the original book documents the "RegularExpression" (4.1.26) class,
> but it is not
> available by default, therefore I would leave it out, if that is o.k.,
>
> Yes, that is ok, but it might also be nice to have a section that lists
> classes that come from
> packages included with the interpreter (and how to get them).
There are these packages, which partly have documentation in a proper book
(like RxFtp) or are
documented in the rexxref book (like RegularExpression):
Directory of C:\Program Files (x86)\ooRexx
23.12.2019 17:28 25 447 csvStream.cls
23.12.2019 17:28 45 265 dateparser.cls
23.12.2019 17:28 13 955 json.cls
04.03.2020 20:23 11 680 mime.cls
09.03.2020 15:08 407 614 ooDialog.cls
09.03.2020 15:08 3 063 oodPlain.cls
09.03.2020 15:08 3 063 oodWin32.cls
04.03.2020 20:23 5 865 ooShapes.cls
23.12.2019 17:28 67 463 rxftp.cls
23.12.2019 17:28 3 582 rxregexp.cls
23.12.2019 17:28 19 078 smtp.cls
23.12.2019 17:28 32 389 socket.cls
04.03.2020 20:23 18 869 streamsocket.cls
23.12.2019 17:28 37 307 winsystm.cls
So what I would propose then is to have a proper (sub) section pointing at
those packages, briefly
describing their purpose (like with the individual, built-in classes) and the
need to require them.
This way the reader is made aware of them and also, that she has to require
these packages in order
to get at the classes there.
>
> * there is a subchapter "4.1.7 Collection Classes" which lists all
> collection classes; this
> goes back to the previous listing of the classes which was not
> correct. As the rexxref
> book explains the collection classes I would plan to reorder the
> brief description of the
> classes by alphabet only (e.g. also correcting the position of the
> "NumericComparator" and
> "Orderable" classes etc.) in section 4.1
>
> I think the classes should be organized first by category (i.e., All the
> Orderable classes
> together, all of the MapCollections together). Comparators should also be
> their own section.
Researched and looked at this from different angles. Found out among other
things that currently
classes like Object (!) but also mixin classes like MapCollection,
OrderedCollection or
SetCollection are not documented at all. Creating a scheme that is intuitive
for the reader and at
the same time containing all those classes that share common behaviour is not
quite easy.
So this is what I would suggest which also incorporates the category
organizations, but hopefully
remains intuitive for the reader. Now that we have the class hierarchy with the
mixin and inherits
some categorizations can be deduced directly from it.
Now, if there was a complete, alphabetically ordererd list of all the classes
in the class
hierarchy, the reader will intuitively understand the ordering principle. Those
classes that
represent categories (mixins like Comparator and Collection) will keep their
descriptions and would
get a listing of all of its subclassing classes which thereby get categorized
accordingly. E.g.
Collection will get MapCollection, OrderedCollection and SetCollection listed;
MapCollection then
would get Bag, Directory with its subclass Property, IdentityTable, Relation,
Set, Stem,
StringTable and Table listed; and so forth.
This way finding a specific class and its general purpose would be easy going
by its alphabetic
name. Learning about the categories would be implicit when e.g. studying the
Collection or
MapCollection class, and so forth. However, if using the term "category" in the
brief description of
these categorial classes, the reader should become aware of this important
alternative ordering
property. Then, if consulting the class tree with the information going with
those categorial
classes and the inherit lists should implicitly make them aware of the
interconnections.
So in the end the class listings would be complete and each class gets a brief
description and how
it is interrelated with other classes via multiple inheritance. The reader then
can consult the
detailed documentation of the built-in classes by consulting the rexxref book.
What I would suggest then is to create such a version, such that one can see
whether and how that
works out. If it is still felt that the categorizations are not sufficiently
visible, then we would
need to create a separate section (separate from the alphabetically ordered
classes), one for each
category and removing the listed classes per category class from the
alphabetical listing.
Would that be sensible?
> ---
>
> Another question: I wrote a little Rexx script to create the class
> hierarchy and optionally
> create the Docbook XML rendering that can be directly copied into the
> "provide.xml" chapter of
> the rexxpg book.
>
> How about creating a "tools" directory in "doc/trunk" and place the
> script there, such that
> everybody can use it, should an update of the class hierarchy become
> necessary in the future?
>
> Excellent idea. When you first posted that there were bits that appeared to
> be automatically
> generated, I was surprised when didn't appear to have the tool that generated
> these under source
> control. I suspect Gil's tooling should also be placed there. Not sure how to
> handle the binaries
> needed to generate the pubs, though I suspect having them in the svn repo
> might be a good idea too.
Committed.
---rony
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
