dita message

Subject: Re: AW: Fw: WG: [dita] Status of Nested Sections Issue

From: Michael Priestley <mpriestl@ca.ibm.com>
To: "SeicoDyne DITA" <dita@seicodyne.ch>
Date: Wed, 18 Oct 2006 17:45:41 -0400

Wouldn't having a nested, titled element inside topic have the same effect as allowing section to nest?

In the case below, it seems like the markup could be done with topic and section:

<topic id="x">
<title>Lorem Ipsum</title>
<body>
<p id=”para1”>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Suspendisse tincidunt, lacus in faucibus fermentum, nisl mi dapibus tellus, vitae aliquam velit lacus sed velit..</p>
<section><title>Donec convallis faucibus lorem. </title>
<p>Nunc volutpat commodo mi. Praesent tortor. Nullam rutrum metus et magna. Sed mi augue, suscipit vitae, lacinia et, vestibulum vel, justo.</p>
</section>
<p id=”para2”> Donec id mauris. Maecenas venenatis tortor feugiat enim. Nunc elit. Donec sapien sem, cursus ac, posuere non, consectetuer eget, purus.</p>
</body>
</topic>

It's not great practice to mix titled blocks/sections with untitled ones, since the output will likely make it look like the titled block contains the untitled ones following it. But it is still possible within the current definition of topic.

If the requirement is to keep some headings out of the table of contents, it seems to me there should be other ways to accomplish that effect besides using sections - for example, using the toc attribute in a map, or creating a general rule (like TOC entries for top two levels only), or using outputclass, or specializing topic...

For examples of complex nested structures using specialized topics, check out the API specialization in the toolkit.

I'm hoping you can post some more examples, even if the actual content is substitued. I've seen a lot of legacy material get migrated to DITA, and so far there's always been a way to make it work using topics and sections - if this really is something new and different, I'd like to understand how, otherwise I'm hoping I can offer some suggestions on how it might be made to fit.

Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

"SeicoDyne DITA" <dita@seicodyne.ch>

10/18/2006 05:24 PM

To	<dita@lists.oasis-open.org>
cc	Michael Priestley/Toronto/IBM@IBMCA, "'W. Eliot Kimber'" <ekimber@innodata-isogen.com>
Subject	AW: Fw: WG: [dita] Status of Nested Sections Issue

Michael

I do not ask for the ability to nest sections. But I would welcome to have a block level element that can be nested. That would help for some specialization needs.

In my mind I have e.g. to transfer legacy data who might run into a too complex topic structure. Something like

<div>
<title>Lorem Ipsum</title>
<p id=”para1”>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Suspendisse tincidunt, lacus in faucibus fermentum, nisl mi dapibus tellus, vitae aliquam velit lacus sed velit..</p>
<div><title>Donec convallis faucibus lorem. </title>
<p>Nunc volutpat commodo mi. Praesent tortor. Nullam rutrum metus et magna. Sed mi augue, suscipit vitae, lacinia et, vestibulum vel, justo.</p>
</div>
<p id=”para2”> Donec id mauris. Maecenas venenatis tortor feugiat enim. Nunc elit. Donec sapien sem, cursus ac, posuere non, consectetuer eget, purus.</p>
</div>

would be imaginable.

While para1 and para2 belong to the same topic. To the same unit of information that belongs together.

Of course I would not place div titles into a toc, that may look strange. It is something on a lower level.

I absolutely understand your point and I am in favour of our modular content architecture. But I also understand the needs of our customers who are delighted by DITA and the DITA specialization concept but who face an unconquerable company internal barrier while not having the availability to nest on a block level. This can be a mission critical question, and – if we can not offer a solution - lead companies (managers, decision makers, prima ballerinas) to stupid decisions like staying at word instead of going into the XML world. We know such things are driving XML project leaders mad.

That’s my package behind this proposal.

Best regards

Chris

Von: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Gesendet: Dienstag, 17. Oktober 2006 18:08
An: W. Eliot Kimber
Cc: dita@lists.oasis-open.org
Betreff: Re: Fw: WG: [dita] Status of Nested Sections Issue

Chris, can you clarify why nesting topics wouldn't do the trick? It's not clear to me why nesting topics would be substantially different from nesting sections, except that nesting topics preserves the definition of modular content for DITA, whereas nesting sections allows topics the size and complexity of entire books, which would mean that being in DITA has nothing to do with being modular.

In other words, right now a lot of DITA's messaging is about content modularity and topic orientation. All of that messaging is based on topics having some kind of common size or complexity. The only limit we have on a topic's size or complexity is the enforcement on non-nesting of sections (effectively, if you have more than one level of section, then experience tells us you have more than one topic).

So if we allow sections to nest, we are undermining one of our core DITA messages, and one of our main differentiators from other standards. On the plus side, we would be able to say that we can now handle any content, regardless of topic orientation; on the minus side, we would not be able to say that DITA is a modular content architecture with any special claim to enabling reuse.

That said, it also makes sense that content goes through stages, and whether it's new content being jammed into a big readme or migration of existing content that hasn't been chunked yet, there's always cases where you need a single document with multiple levels of heading, which you intend later to break apart for more effective reuse etc.

But my understanding was that we allowed complex documents (eg through the ditabase doctype) to support this continuum - you can create a big complex nested document using ditabase, then rechunk it later into smaller documents with an accompanying map. That's all do-able today, and has the virtue of protecting the identity and integrity of individual topics through the content lifecycle.

What is it about this use case that makes nesting topics inappropriate? To me, it looks like exactly the use case that drove us to allow nesting topics to begin with, and I don't understand why we need to nest sections as well, at such a high cost to DITA's core focus.

From our charter:

>The work of this TC will differ from similar efforts such as DocBook because of
> - broader scope, inasmuch as DITA applies to more areas than just technical manuals
> - more specific scope, inasmuch as DITA applies to topic-oriented information rather than all technical manuals
...
>DITA topics
> - can be assembled in different combinations for many deliverables or output formats
> - are optimized for navigation and search
> - are well suited for concurrent authoring and content management
> Through use of a common specification, DITA content owners can benefit from industry support, interoperability, and reuse of community contributions.

Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25

"W. Eliot Kimber" <ekimber@innodata-isogen.com>
10/17/2006 10:50 AM

To
dita@lists.oasis-open.org

cc

Subject
Re: Fw: WG: [dita] Status of Nested Sections Issue

Don Day wrote:
> -----Urspr�ngliche Nachricht-----
> Von: Christian Kravogel [mailto:christian.kravogel@seicodyne.ch]
> Gesendet: Dienstag, 10. Oktober 2006 17:03
> An: 'dita@lists.oasis-open.org'
> Betreff: RE: [dita] Status of Nested Sections Issue
>
> Eliot
>
> The issue of nested sections looks to me of something of high importance
> and
> the source for controversial discussions. I am working in technical
> authoring since 12 years, most time in the machine industry (elevators,
> escalators, etc.) and I noticed that if you give an author the ability to
> nest topics and to nest sections it will become a mess indeed and some will
> screw-up most structured content.
>
> On the other hand, there are companies with special requirements and they
> absolutely need the ability to nest sections. The example of implementing
> legacy data is a very good approach. Different industries and different
> departments have different requirements. And when we think of DITA users,
> we
> should not limit that to the view of a technical author writing an
> installation instruction of a mechanical device or writing an API user
> manual.
>
> Maybe we should not able section to nest, but we may add a separate block
> element that can be used for specializations to enable block nesting. E.g.
> the <div> element known from HTML (like you already mentioned).

I don't see that it makes that much difference whether you allow section
to nest or add a new element type that is equivalent to section but that
can nest.

In either case specializers can impose whatever local constraints they
want, either disallowing nesting or creating a limited nesting level (by
having unique specializations at each level) or by defining more
semantic section types.

The question of what authors will do with the ability to nest and having
two different ways to do things has always been a problem and will
always be a problem. That's because it's an *editorial* problem, not a
technology problem. Even if you disallow it (as the current DITA
specification does) authors will just do something different if they
have to.

That is, there is and can be no substitute for well-trained writers,
appropriate editorial oversight, and clearly-defined editorial policies.

In addition, no matter what the DITA schemas say (or what any other
schema designed for document authoring says), you *ALWAYS* need some
sort of "validation application" that validates rules that cannot be
expressed in a DTD or schema. This is either a separate application or a
side effect of the error checking or failure behavior your processors
provide. In either case, since you have to do this checking you can
always add checks for editorial rules for things like section nesting, a
requirement that there be at least two subsections under a section, that
sort of thing.

In 1.1 I think that simply allowing section elements to nest is the
simplest solution that meets the requirement, requiring no additional
design, no additional element types, or anything.

Adding a new element type would involve more changes to the
specification and open up more debate about exactly what the rules for
that new elemen type should be. That level of design does need to be
pushed off to a later version.

Cheers,

Eliot

--
W. Eliot Kimber
Professional Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX 78759
(214) 954-5198

ekimber@innodata-isogen.com
www.innodata-isogen.com