That's interesting, Erik.
Are these specializations available for download from IBM? I don't see
them in the toolkit.
If I may inquire, what prompted the decision to use nested topics,
instead of nested sections, in programming class topics to handle
methods of that class?
As you indicate, they don't really make sense as separate topics.
--Dana
Erik Hennum wrote:
Hi, Esteemed TC:
If we deprecate nested topics, that's going to force a rewrite of the
API Reference and Java API Reference specializations, which use nested
topics to model descriptions of methods of classes (among other
things). We'd be forced to move the descriptions of methods into
separate files, which would be counterintuitive for an API writer.
Because a Java method always resides within one and only one class, it
makes sense to nest the description of the method within the
description of the class.
More generally, there are probably other cases in which the subject
matter dictates a primary hierarchy and primary reuse as a unit (so
that it makes sense to author the topics as a single bundle). Shouldn't
DITA be able to handle those exception cases as well as strongly
encourage the best practice of reusable individual topics for the more
common case?
On the general point of section nesting, I wonder if it would be useful
to compare an abstract example of nesting via section
<topic id="a1">
.... <title>A1 title</title>
.... <body>
........ <p>A1 content</p>
........ <section id="b1">
............ <title>B1 title</title>
............ <p>B1 content</p>
............ <section id="c1">
................ <title>C1 title</title>
................ <p>C1 content</p>
............ </section>
........ </section>
........ <section id="b2">
............ <title>B2 title</title>
............ <p>B2 content</p>
........ </section>
.... </body>
</topic>
with the equivalent nesting via topic
<topic id="a1">
.... <title>A1 title</title>
.... <body>
........ <p>A1 content</p>
.... </body>
.... <topic id="b1">
........ <title>B1 title</title>
........ <body>
............ <p>B1 content</p>
........ </body>
........ <topic id="c1">
............ <title>C1 title</title>
............ <body>
................ <p>C1 content</p>
............ </body>
........ </topic>
.... </topic>
.... <topic id="b2">
........ <title>B2 title</title>
........ <body>
............ <p>B2 content</p>
........ </body>
.... </topic>
</topic>
The content can fit into either markup without loss of structure or
processing capability.
The first markup, however, encourages the writer to view the structure
as subdivisions within a continuous flow for a single unit of content.
The second markup fights against that, encouraging the writer to view
the substructure as distinct units of content.
The question is whether that's the optimal blend of purist and
pragmatist -- encouraging the best practice but allowing compromises
because we live in the real world.
Finally, a particular comment:
"W. Eliot Kimber" <ekimber@innodata-isogen.com> wrote on
12/21/2006 08:57:04 AM:
>
> I ask because topic does not allow topicref where it allows
nested
> topics (I originally expected them to be allowed) so I'm assuming
that
> related links is the intended way to create explicit hierarchical
> relationships from within a topic to other topics. But then that
raises
> the issue of there being three distinct ways to do it (with a map
using
> topicrefs, with links, and with nested topics)--which approach do
you
> choose when?
FWIW, there is an existing proposal to introduce <topicref> as an
alternative to <link> (deprecating the latter) so we get down to
two:
http://www.oasis-open.org/apps/org/workgroup/dita/download.php/14060/Issue37.html
The existing proposal provides an account for handling topics with
multiple hierarchy contexts but needs a bit more for reltables (maybe
just a list of <relrow> in addition to <relcontext>).
The primary concern raised in prior discussions of that proposal was
revision to existing processing in the DITA Open Toolkit.
Hoping that's useful (and that the New Year is very good to you),
Erik Hennum
ehennum@us.ibm.com
|