Hi Erich,
On 31.03.2020 23:17, Erich Steinböck wrote:
> Rony, we're on Docbook 4.5.
> xref's within classname (or filename) are not allowed.
hmm, good to know (was not aware of this as it had worked without any errors)!
:)
I would appreciate if you could give some pointers where this gets documented.
Looking through the
DocBook 4.5 DTDs and modules [1] I could not see that exclusion, but then it
may have to do with
inferrals that I am not aware of (it has been far too long that I fiddled with
SGML/XML DTDs).
Thank you also for the snippet at the bottom for classname examples. The
current version had them
removed already, however these instances could still be found:
* classname:
provide.xml:<classname><xref linkend="clsMessage"
xrefstyle="template:Message"/></classname> class.
* filename:
samples.xml:class implemented in the package <filename><xref
linkend="complex" /></filename>.</para>
samples.xml:<listitem><para>Sample uses of the pipe implementation in
package <filename><xref
linkend="pipe" /></filename>. </para>
samples.xml:defined in package <filename><xref linkend="singleton"
/></filename>, which makes
sure that
Will remove the classname and filename tags later.
> You may want to check with the docs or our existing xml's before using any
> special xml tagging.
I have done that as I have explained already in another post.
The rexxpg book was almost devoid of semantic markup it just used emphasis at
places, which I
copied, short of knowing any better at that time. Later when learning more
about the elements I
replaced all emphasis markup with semantic markup where spotted, a *lot* of
additional work that I
could have saved, if I had known earlier, i.e. if it was explicitly documented
someplace! Looking
around the rexxpg book originally did not unveil how to use the available
markup in a more correct
manner.
So what you call "special xml tagging" was unintentional, short of knowing
better.
Also, I think it is very important to have a section about tagging the ooRexx
documentation with
examples of how to do it and also giving don'ts that may not be obvious. (This
is something I have
on my todo list, once the documentation processes has been established and once
having enough
insight and knowledge for doing that. My test.pdf book is a first start as it
also includes the
original DocBook sample markup.)
> Please revert this change.
Will do later.
> Also the rexxpg modification to the class hierarchy now fails to show Array
> being an
> OrderedCollection which in turn being a Collection which is the whole idea of
> this diagram. Just
> compare with the 4.2 version.
> This "Basics of Classes" diagram should give the oo beginner an overview and
> should be as simple
> as possible.
Do you have a pointer to the 4.2 pdf version for comparison?
The current hierarchy is as simple as possible using ooRexx subclasses and
superclasses methods
itself with the aim to have each class shown once in the diagram to make it "as
simple as possible"
indeed!
If you look at the Array class you immediately see that Array is not only a
subclass of Object, but
inherits the OrderableCollection behaviour, which via inheritance is also a
Collection. This follows
from multiple inheritance applied to this collection class. This the reason BTW
why I added the
information "(mixin)" and "(inherit x y)" next to the classes in the class
tree: to communicate e.g.
that the Array class is also an OrderableCollection, making it a Collection.
Adding classes that use multiple inheritance to all those mixin classes in the
class hierarchy they
inherit in addition will cause classes to be shown all over the place, which I
fear is making the
hierarchy "difficult" and truly confusing for beginners and newcomers (why is
this class showing up
more than one time, all over these places?). E.g. the classes Bag, DateTime,
File,
InputOutputStream, Message, Set and TimeSpan which actually are
subclassing/inheriting a total of
three classes each at the same time?
Maybe listing the inheriting classes in the brief description of Comparable,
MapCollection,
Orderable, etc. and at the same time listing the superclasses (immediate and
inherited) in the brief
description of the respective classes like for Array, Message, etc.?
---rony
[1] DocBook 4.5 XML, module and enttiy files (look for the zip-file for
downloading):
<http://www.oasis-open.org/docbook/xml/4.5/>.
>
>
> On Sun, Mar 29, 2020 at 8:40 PM orexx--- via Oorexx-svn
> <oorexx-...@lists.sourceforge.net
> <mailto:oorexx-...@lists.sourceforge.net>> wrote:
>
> Revision: 12022
> http://sourceforge.net/p/oorexx/code-0/12022
> Author: orexx
> Date: 2020-03-29 18:40:42 +0000 (Sun, 29 Mar 2020)
> Log Message:
> -----------
> Add missing classes, reorder, standardize id-link names, add links from
> the class tree to the
> individual brief class descriptions.
>
> Modified Paths:
> --------------
> docs/trunk/rexxpg/en-US/provide.xml
>
> Modified: docs/trunk/rexxpg/en-US/provide.xml
> ===================================================================
> --- docs/trunk/rexxpg/en-US/provide.xml 2020-03-29 18:39:56 UTC (rev
> 12021)
> +++ docs/trunk/rexxpg/en-US/provide.xml 2020-03-29 18:40:42 UTC (rev
> 12022)
> @@ -57,322 +57,166 @@
> classes.
> </para>
>
> -<!-- GENERATED by 'docs/trunk/tools/createClassHierarchy.rex' on
> [2020-03-10T13:27:36.162000] -->
> -<!--
> +
> +
> +<!-- GENERATED by 'docs/trunk/tools/rexxpg/createClassHierarchy.rex' on
> [2020-03-29T20:27:16.359000] -->
> <para>
>
> <itemizedlist mark="none" spacing="compact">
> - <listitem><para><classname>Object</classname> </para></listitem>
> + <listitem><para><classname><xref linkend="clsObject"
> xrefstyle="template:Object"
> /></classname></para></listitem>
>
> <listitem><itemizedlist mark="none" spacing="compact">
>
> - <listitem><para><classname>Alarm</classname> </para></listitem>
> + <listitem><para><classname><xref linkend="clsAlarm"
> xrefstyle="template:Alarm"
> /></classname></para></listitem>
>
> - <listitem><para><classname>AlarmNotification</classname>
> &added50; <emphasis
> role="italic"> (mixin)</emphasis></para></listitem>
> + <listitem><para><classname><xref linkend="clsAlarmNotification"
> xrefstyle="template:AlarmNotification" /></classname> &added50;<emphasis
> role="italic">
> (mixin)</emphasis></para></listitem>
>
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
