Hi Bruce,
I have some questions and a few comments based on my
understanding of your email.
I'm not sure I get what you want to add below the map level?
You may have more then 1 level in a map. Moreover, it's
much easier to use submaps or use a map per catalog to reuse content
in multiple deliverables, then to create a huge topic and break it down. By
what mechanic would you break it down?
It is important not to mix up topic title with heading level.
The nesting in DITA is based on semantics, not presentation. You manage
meaningful information chunks, and only then apply presentation and decide
what expressions should be shown as headings.
In my
experience, if a title is recurrent (same wording at a similar position), like
"questions" in the previous example, it is a structural part of a topic, not a
topic and therefore, should be handled as such. If you type that title
manually and want the question headings "questions" to become
"exercises", semantic tagging will save you a lot of time.
One
thing I didn't get: how do you put content into DITA without architecturing
it? You can't put semantic elements around content segments if they
are not semantically accurate. Otherwise, you might as well use
XHTML: XML that will give you heading levels and will not lead you into
believing that the tag content is something that it is
not.
I hope
this brings some light, unless I'm beside the point you wanted to
make?
France
France
Baril
Documentation
Architect/Architecte documentaire
IXIASOFT
tel.:
+ 1 514 279-4942
fax:
+ 1 514 279-3947
toll
free: + 1 877
279-IXIA
[ www.ixiasoft.com ]
Let's Talk XML
From: Esrig, Bruce (Bruce)
[mailto:]
Sent: 8 novembre 2005 10:37
To:
France Baril
Cc: ; Michael Priestley; David
Brainard; Indi Liepa
Subject: RE: [dita] example of catalog of small
topics
France, your approach makes work for information
architects! (That's a good thing provided that all information that is published
is architected. We don't have that situation yet at our
organization.) If you're willing to specialize <ol> to
provide a new title, you can definitely reduce your need for nested
structure.
Here's
an excerpt from the Lucent in-house style guide, showing our use of subsections
(what we call LiPP subblocks). (Please don't
assume that this quotation accurately reflects the formatting of our style
guide!)
This
is a catalog within a single "rich topic" of various inline elements that we
support. In the excerpt, <abbrev> and <command-syntax> are shown.
Each inline element could be documented by a topic. The sections would contain
the Attributes and Example.
Alternatively, the entire "rich topic" could be a topic
with nested substructure. In that case, the default would be that the entire
rich topic would be one chunk. But it would be possible for an author to break
out the substructure as separate chunks if desired.
Michael would probably view the documentation on each
inline element as one reusable topic. If that view is generally accepted, then
the question (that this example raises) would be whether to provide something
below the map level that permits aggregation of such topics into a small
catalog.
Best
wishes,
Bruce
============
Inline element descriptions
................................................................................................................................................................................................................................
abbrev
Indicates an abbreviation....
Attributes
expand contains the abbreviation’s expansion
text.
command-syntax
Contains an inline
command. It will be formatted in an ASCII-like constant-width typeface. command-syntax is one of the
elements that can be used either as typical
inline element or on the paragraph level, for example in an action
element.
Attributes
The command-syntax
element has a pgwide attribute that allows you to specify whether the ASCII text will fit to the text
column or the page if command-syntax is
being used on the paragraph level. For more information on the pgwide
attribute, see “Using the pgwide
attribute”.
Example
The ping
command can be used to check TCP/IP
connectivity.
-----Original Message-----
From: France Baril
[mailto:]
Sent: Tuesday, November 08, 2005
9:26 AM
To: Michael Priestley; David Brainard; Indi
Liepa
Cc:
Subject: RE: [dita]
Two proposals for nested sections
I have not followed the whole thread, I just tried
to find the source of the discussion before coming up with an answer. My
conclusion is that I don't see why sections are needed to specialize the
example that triggered this whole thread (see my proposed solution below
- one of many).
I have met some cases where I was tempted to add
extra section levels. After looking at these issues with a big question
mark over my head for a while, I always found solutions that were,
in the end, more satisfying. My own point of vue for now is that the
current model should stay as is, because it works semantically and it helps to
reinforce some minimal usability rules.
Reusable Learning Object (topic/topic
RLO/topic)
Information (topic/p - or topic/section if many p
per info)
Information (topic/p - or topic/section
if many p per info)
Questions (topic/ul RLO/questions) -->
XSL or CSS adds "Questions" as the
title!!!
Question title (topic/li
RLO/question) followed by (topic/ph
RLO/questiontitle)
Para
(topic/p)
Para
(topic/p)
List (topic/ol
RLO/ol) followed by li+
Para (topic/p)
Question title (topic/li
RLO/question) followed by (topic/ph
RLO/questiontitle)
Para
(topic/p)
Para
(topic/p)
List (topic/ol)
followed by li+
Para
(topic/p)
Question title
(topic/li RLO/question)followed by (topic/ph
RLO/questiontitle)
Para
(topic/p)
Para
(topic/p)
Table
(topic/table RLO/questiontable) followed by table
elements
Para
(topic/p)
From: Michael Priestley
[mailto:]
Sent: 7 novembre 2005
22:56
To: France Baril; David Brainard; Indi
Liepa
Subject: Fw: [dita] Two proposals for nested
sections
I'm getting the
sense that Paul and I are deadlocked, and I'd welcome some additional input on
the thread, even if it's to tell me I'm crazy. If you haven't been following
the thread, Paul wants to add at least one level of subsections to topic; my
original suggestion was to rechunk his design (ie treat them as nested topics
rather than nested sections); my fallback proposal was to create an entirely
new base type, same level as topic, that allows nesting divisions (and can
even embed topics if necessary).
Michael Priestley
IBM DITA Architect
SWG Classification Schema
PDT Lead
----- Forwarded by Michael Priestley/Toronto/IBM on 11/07/2005 10:45 PM
-----
Michael
Priestley/Toronto/IBM@IBMCA
11/07/2005 10:38 PM
To
"Paul Prescod"
<>
cc
Subject
RE: [dita] Two
proposals for nested sections
"Paul Prescod" <> wrote on
11/07/2005 07:14:02 PM:
> But it will make your life as spec editor
much harder (as well as
> making the lives of readers harder).
According to my understanding
> of the proposal, we would have to go
through the entire DITA spec
> and everywhere it says "topic" (as in
maps point to topics through
> "topicref" elements), we would have to
say: "topic or thingee"
> (depending on what we call the thingees).
We went through a
similar change earlier changing "topic type or map type" to "structural type".
>The topicref
attribute
> would be a misnomer because it could point to topics or
thingees.
It can
already point to maps, PDFs, and websites, so it's arguably already a
misnomer. If necessary we can introduce a domain specialization for
<articleref>
> We'll have to add "thingee" to the "type" attribute.
I'm suggesting it
will be a base type, same as map and topic. And same as map and topic, when an
element already exists in topic, we could just keep the topic class
attribute.
>What
module
> will the shared elements be in? That seems like a lot of
painful
> reworking to me.
Since <article> would contain all the same elements as
topic plus some additional ones, the shared elements would be in the topic
module files (topic.mod etc.).
>It also implies that things with a certain
>
organization are "topics" (even if they nest deeply!) whereas things
>
with a slightly different organization (even if they have only one
>
level of nesting) are not topics! They aren't articles. So I don't
>
know what to call them.
This is the crux of our problem. I can propose all the
compromises I want, but you and I seem to fundamentally disagree on the nature
of a topic in DITA. So regardless of whether my proposal addresses your
immediate issue, I suspect you will not be satisfied with anything short of
changing the current definition of topic.
For me it comes down to how much control we
put in the hands of the map author versus the content author. On the one hand,
I want the content author to have considerable freedom in how they author
content: one per file or multiple per file, nested or flat, etc. On the other
hand I want the map author to have considerable freedom in how they reuse and
integrate content: whether it's in one file or many, nested or flat etc. The
topic is a handshake between the two formats: no matter how complex the
content gets, it will be consumable in topic-sized chunks that have a maximum
complexity determined by the limited nesting depth of topic.
The topic is also the unit of reuse in
design and processing, allowing for shared design elements and processing
modules at the topic level, across multiple complex document types and
applications.
Changing the size of the basic unit of reuse - on both the
content, design, and processing dimensions - is not trivial. Adding even one
level of nesting increases the potential complexity of a topic exponentially,
with a corresponding decrease in the potential for reuse across document type
and system boundaries. Allowing unlimited nesting destroys the entire idea of
a topic, in the DITA architecture - the unit of reuse becomes essentially
unlimited in its complexity.
I would rather simply preserve the existing architecture; my
compromise proposal is article as a peer of topic. You would rather allow
unlimited nesting of sections in topic; your compromise proposal is to add one
level of nesting. It sounds like neither of our compromises is acceptable to
the other. Perhaps the only thing we agree on is that we disagree. I suspect
we need input from others, and ultimately a decision from the TC.
Michael
Priestley
