I have found the following links useful re. DocBook tags:
https://tdg.docbook.org/tdg/4.5/docbook.html - this is a good reference
for tags and attributes
www.sagehill.net/docbookxsl/ - more explanations on things like
"chunking" or "xref"; NB this is DocBook 5!
Gil
On 4/1/2020 10:08 AM, Rony G. Flatscher wrote:
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
--
Gil Barmwater
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
