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

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



http://dita.xml.org/blog/25





"SeicoDyne DITA"
<> 
10/18/2006 05:24 PM




To
<>


cc
Michael Priestley/Toronto/IBM@IBMCA,
"'W. Eliot Kimber'" <>


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:]


Gesendet: Dienstag, 17. Oktober 2006 18:08

An: W. Eliot Kimber

Cc: 

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



http://dita.xml.org/blog/25





"W. Eliot Kimber"
<> 
10/17/2006 10:50 AM






To




cc
 


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




 
 






Don Day wrote:

> -----Ursprüngliche Nachricht-----

> Von: Christian Kravogel [mailto:]

> Gesendet: Dienstag, 10. Oktober 2006 17:03

> An: ''

> 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




www.innodata-isogen.com