OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] Nested sections proposed compromise and call for use cases



We agree on the compromise but not on the example:

>Michael felt it was very important that we strongly discourage
>structures where you have many nested sections with titles authored by
>writers. In his opinion, this puts too much control in the hands of
>writers to write in an old-fashioned, non-topic-oriented fashion. For
>example:
>
> * http://support.microsoft.com/kb/834489


I see the example as being already pretty topic-oriented. I just think it contains multiple topics. The content of "More information", for example, is clearly a task.

The issue is not about putting too much control in the hands of authors - clearly they can already author nested documents using topics, and don't need sections to do so. The issue is about the degree to which internal document structures are exposed to control by both the original author and by reusers, using maps.

If the internal document structures are all in sections, then that is an expression by the original author that there is nothing below the top level that requires topic-level management: no need for managing links, search metadata, or anything else that differentiates a topic from a section. But in the example you provide, each "section" actually does contain links, which means that the document as a whole has bunches of dependencies on other content. If new resources become available, or existing ones become obsolete, then in your model the original author would have to go in and update the document because those links are embedded content of the document. But in my model, the links would be relationships between the nested topics and other resources; those relationships could be managed via maps, and a reuser could simply use a different map, or apply additional maps, to replace or enhance the related links in each nested topic.

So the decision to use nested topics rather than sections actually puts more control in the hands of both author and reuser.

I'm okay with the compromise because it allows more flexibility for specializers, as well as for authors who want to use the div-like elements for creating element groupings for conref or conditional processing, without changing the architecture's focus on creating user-titled structures using nested topics rather than nested sections.

Michael Priestley
IBM DITA Architect
SWG Classification Schema PDT Lead
mpriestl@ca.ibm.com



"Paul Prescod" <paul.prescod@blastradius.com>

11/14/2005 08:02 AM

To
<dita@lists.oasis-open.org>
cc
Subject
[dita] Nested sections proposed compromise and call for use cases





Michael Priestly and I discussed this nested sections issue further last
week. We still don't agree on all of the design issues but we came up
with a compromise that both of us are tentatively happy with. Now we
would like to validate the compromise against other use cases to see
whether it holds up.

Michael felt it was very important that we strongly discourage
structures where you have many nested sections with titles authored by
writers. In his opinion, this puts too much control in the hands of
writers to write in an old-fashioned, non-topic-oriented fashion. For
example:

* http://support.microsoft.com/kb/834489

Allowing this was never of interest to me (though, given my druthers, I
would not explicitly disallow it). My goal was not to put extra control
in the hands of the author, but in the hands of the specializer. For
example, one could imagine a specialization like this:

<kbarticle>
                <symptoms>...</symptoms>
                <resolutions><resolution><title>Hack your
registry</title>...</resolution>
                                 <resolution><title>Re-install
software</title>...</resolution>
                                 ...
                </resolutions>
</kbarticle>

Each <resolution> would be a specialization of section. <resolutions>
itself would be a specialization of section (with a generated title).
The output might look like this (using this as a use case because it is
public -- not because I am working with support.microsoft on DITA):

                http://support.microsoft.com/kb/906294

(note that my variant of it is a bit more structured than this article
is)

The intersection between what I need and what Michael can stand is a
restriction that only one level should have authored (as opposed to
generated) titles.

The core of our proposal is an element called "bodydiv" (or perhaps just
"div"). This element will not allow an authored title. Specializations
may supply a generated title. (probably with a spectitle attribute?)
Bodydiv elements may contain sections. So <resolutions> could be a
bodydiv and <resolution> could be a section. Bodydiv elements may also
nest, so both could be bodydivs. (my thinking is that bodydivs should be
used when you don't want authors to supply titles and sections should be
used when you do: Michael probably does not agree and might prefer
people continue to use sections with or without titles as they do today)

When used without specialization, bodydiv is a pure grouping element:
the body-level equivalent of the "ph" element. It has no semantics other
than that it groups stuff. Authors could use that to conref or filter a
bunch of body-level things all at once.

If you need the grouping function within a section, then we propose
another element called <sectiondiv>. I find it harder to envision the
specialization-based use case for this element but for semantic-less
grouping within sections it could also be useful. For consistency,
sectiondivs would also be able to nest. Sectiondivs cannot contain
bodydivs so there is no way to achieve arbitrary authored-title nesting.

If someone did want to achieve arbitrary authored-title nesting (perhaps
for dealing with legacy content) then one could "hack" DITA to
specialize a paragraph into a bodydiv title. (you can hack DITA in
similar ways today)

Please compare this compromise to your use cases and report back on
whether it meets your needs.

Paul Prescod



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]