[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [no subject]
-----Original Message-----
From: Paul Prescod [mailto:paul.prescod@blastradius.com]
Sent: Monday, November 21, 2005 1:44 AM
To: dita@lists.oasis-open.org
Subject: [dita] Nested Sections Solution Proposal
IssueNumber00
I don't know what the official number is for this issue, so I'll send the first draft to the mailing list rather than uploading it.
DITA Proposed Feature # 00
A mechanism for allowing topics and specializations of topic to have lightweight nested structures.
IssueNumber00__section_4EAD791FB21A437BADBF62545BBFBBDB
Longer description
Many topics have an internal narrative structure that is analogous to sections within a book chapter or help topic. DITA has two mechanisms for dealing with this situation. One is to use sections. This mechanism breaks down if the required hierarchy is more than one level deep. The second mechanism is to use sub-topics. This mechanism is "heavy-weight" in a few different ways:
IssueNumber00__ol_CA2F4FAC6A094BEF87B951FD798AD23C
1. IssueNumber00__li_ADF9375D2EC14439B52219B56C214786Topics must have authored titles rather than specialization-specified ones ("spectitles").
2. IssueNumber00__li_B0365A64A7B54B8F830623AFBC13DF77Topics must always have titles: sometimes neither authored nor generated titles are required (see the "output-transparent grouping" use case below)
3. IssueNumber00__li_EFEC2C896EA44DCAA51B486D87E7E1D8Topics must always have IDs.
4. IssueNumber00__li_ADD13744663245FA929E50D15E954321Topics require an extra layer of "body" wrapping that differentiates between metadata and content: even when metadata is either not needed or explicitly disallowed through specialization.
5. IssueNumber00__li_C9F4EEBE93344324A09E1731E3185263Acccording to some definitions of "topic", making content into a sub-topic has certain unwanted semantic implications like: "This content is independently reusable" or "this content should be independently indexed by CMS search engines".
6. IssueNumber00__li_246FB0CCB02B4E23873A461CCBF9BB57Topics can only be grouped by other topics with all of the issues described above. Topics cannot be grouped by sections.
7. IssueNumber00__li_898DEE88BFAC4F1EB26B739F9676289CThe output behaviours for subtopics are typically quite different from those for sections. E.g. with respect to HTML chunking and locations of related-links elements.
This proposal defines mechanisms for lightweight, hierarchical, sectional grouping.
IssueNumber00__section_58408528B0E848F08FA1B8BC9371A12F
Scope
Intermediate
IssueNumber00__section_D50F4B7A0F614A90B46F44601A6F39A4
Use Cases
Complex Specialized Templates
Imagine if the document type for DITA Proposed Features were a specialization. It would likely have elements like "Longer Description", "Use Cases", "Technical Requirements" and so forth. For the sake of clarity, lets call these specialization-defined sections "schematic sections". In contrast, sections with titles and semantics totally under the control of authors will be called "author-defined sections". It seems quite possible that under many circumstances, these schematic sections will require author-defined subsections or schematic sub-sections. For example, the use case you are reading right now might be within a sub-section (perhaps a specialized "Use Case" section type) rather than a definition list if that were possible. Because the output-requirements for this document type are so lax, we can get away with using a definition list. But sometimes customers really do require "section behaviour" for sub-sections.
Output-transparent Grouping
Sometimes it is necessary to group multiple sections and other content into a single unit in order to "conref" them or filter than all together.
IssueNumber00__section_D1D72D757F124B24844817D1ED1A66FA
Anti-Use Cases
The proposal is not meant to address situations where authors wish to create deeply nested topics with many levels of titles. They should use nested topic features to do that.
IssueNumber00__section_545E6EE4ECFF47F5B44FB0E842A6306F
Technical Requirements
The proposal is the addition of two elements. One, "bodydiv" or "div" would be able to contain sections and other body-level elements. The other, "sectiondiv" would be contained by sections and contain body-level elements. Neither type would allow authors to write titles. Both types would have optional "spectitle" attributes that would behave the same as the equivalent attribute on sections.
Here is an example of the "bodydiv" element:
<body>
<p>Got some stuff to say</p>
<bodydiv>
<p>A logical grouping of content within a body - a
specializer could use this to generate a title, but there's no
facility for the author to define a topic-like or unique
title.</p>
<section>
<title>A</titke>
<p>etc.</p>
</section>
<section>
<title>B</titke>
<p>etc.</p>
</section>
<bodydiv>
<p>A nested bodydiv.</p>
</bodydiv>
</bodydiv>
<bodydiv>
<p>Another bodydiv</p>
</bodydiv>
</body>
Here is an eample fo the "sectiondiv" element:
<section>
<title>stuff</title>
<p>etc.</p>
<sectiongroup>
<p>A logical grouping of content within a section - a
specializer could use this to generate a title, but there's no
facility for the author to define a topic-like or unique
title.</p>
<p>etc.</p>
</sectiongroup>
IssueNumber00__section_DE9BFD6C450A4E839830CDA5E8F793A5
Costs
The DTD changes required to allow this are minor. Basically two new element definitions are required. They are not particularly complex elements and are almost the same as sections.
The implementation changes are relatively minor as these elements can be treated as a variant of section elements.
The largest long-term cost is the incremental bloat to the DITA language itself. DITA is already a large language, so the addition of new elements should be carefully considred.
IssueNumber00__section_EA5CAE7E231E4FAFA82449D324D0EBB8
Benefits
As per the introduction, the benefit is the ability to create section-nested content without the overhead and mismatched content model of nested topics. It is hard at this time to determine how many people are bothered by the issues with nested topics.
IssueNumber00__section_FB7AE186FE874A5EBF163482426732FE
Time Required
The technical time to implement is relatively small: on the order of a day. The submitter feels that there are still some open issues with respect to defining best practices for using this feature versus using nested topics. It may take a further few meetings to work through these issues.
------_=_NextPart_001_01C5EF76.96B7D89C
Content-Type: text/html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
<TITLE></TITLE>
<META content="MSHTML 6.00.2800.1523" name=GENERATOR></HEAD>
<BODY>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>To
continue the argument that we may not be able to anticipate all possible
applications of the DITA language, and that we should be careful to allow
sufficient flexibility, here is a scenario that arose today in our use of the
Lucent internal XML DTD.</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>We are
documenting a procedure that can be done in two control languages: a command
language and a GUI.</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>From
what I have seen so far, the presentation environment that is assumed by XML
markup languages often has the weakness that it assumes a single flow of
information. So there is already a tension between the assumptions that we make
about the presentation environment and the idea of presenting parallel
procedures in two languages. For example, in DITA, we don't have the ability to
designate two flows of output, one per language, and assign each procedure to a
particular flow.</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>So we
would like to indicate a correspondence between procedures in two different
control languages. If the steps line up precisely, we can do so by making one
combined procedure that lists, for each step, the actions to take in each
language. However, we are not currently assuming that the steps will line
up precisely. It's possible that there are setup steps that occur in one
language and not the other, and vice versa.</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>So our
design at the moment contains two procedures per task, one for each
language.</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>Within
each step, we need two titled subsections. One is the result, and that title is
a standard title that clearly can be autogenerated. The other is an alternate.
That is, our customer is emphatically requesting (we'll be checking this, but
this is our current understanding) that we provide the corresponding command in
the same procedure at the same point, precisely because the alternate command is
in a different language, and having the information on the same page at that
point enables one technician to support another. They can look at the same page
even though they are thinking about different languages, and they can tell each
other what the corresponding actions are.</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>For
this alternate, now that we know about it, we could architect a pre-defined
title: Alternate. However, we would not have known about it. Our information
developers would have had to ask for a change to the markup
language.</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>Fortunately, at this point, we have an optional
repeatable item with a user-definable title called additional-information that
occurs at the end of each step. The information developers decided to use a
standard title for this purpose: "Lang2 reference information", where Lang2 is
the name of the second language. Maybe "Alternate command" would be better, but
the point is that we had the flexibility and needed it.</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>To
give the full structure (omitting most end tags):</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005><LU-LiPP:step></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005> <LU-LiPP:action></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>
<LU-LiPP:para> what to do in Lang 1</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>
</LU-LiPP:action></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>
<LU-LiPP:additional-info></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>
<LU-LiPP:label>Result</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>
<LU-LiPP:para> what you have accomplished</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005> </LU-LiPP:additional-info></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>
<LU-LiPP:additional-info></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>
<LU-LiPP:label>Lang2 reference information</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>
<LU-LiPP:para> the corresponding Lang 2 command, in
brief</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005>
<LU-LiPP:xref> <!-- cross-reference to the full procedure in Lang 2
--></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005> </LU-LiPP:additional-info></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></LU-LiPP:step></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV></SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>Best
wishes,</SPAN></FONT></DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN
class=459064714-22112005></SPAN></FONT> </DIV>
<DIV><FONT face=Arial color=#0000ff size=2><SPAN class=459064714-22112005>Bruce
Esrig</SPAN></FONT></DIV>
<BLOCKQUOTE dir=ltr style="MARGIN-RIGHT: 0px">
<DIV class=OutlookMessageHeader dir=ltr align=left><FONT face=Tahoma
size=2>-----Original Message-----<BR><B>From:</B> Paul Prescod
[mailto:paul.prescod@blastradius.com]<BR><B>Sent:</B> Monday, November 21,
2005 1:44 AM<BR><B>To:</B> dita@lists.oasis-open.org<BR><B>Subject:</B> [dita]
Nested Sections Solution Proposal<BR><BR></FONT></DIV><A name=IssueNumber00><!-- --></A>
<DIV><FONT face=Arial size=2>I don't know what the official number is for this
issue, so I'll send the first draft to the mailing list rather than uploading
it.</FONT></DIV>
<H1 class=topictitle1>DITA Proposed Feature # 00</H1>
<DIV>
<P>A mechanism for allowing topics and specializations of topic to have
lightweight nested structures.</P>
<DIV class=section
id=IssueNumber00__section_4EAD791FB21A437BADBF62545BBFBBDB><A
name=IssueNumber00__section_4EAD791FB21A437BADBF62545BBFBBDB><!-- --></A>
<H2 class=topictitle2>Longer description</H2>
<P>Many topics have an internal narrative structure that is analogous to
sections within a book chapter or help topic. DITA has two mechanisms for
dealing with this situation. One is to use sections. This mechanism breaks
down if the required hierarchy is more than one level deep. The second
mechanism is to use sub-topics. This mechanism is "heavy-weight" in a few
different ways:</P><A name=IssueNumber00__ol_CA2F4FAC6A094BEF87B951FD798AD23C><!-- --></A>
<OL id=IssueNumber00__ol_CA2F4FAC6A094BEF87B951FD798AD23C>
<LI id=IssueNumber00__li_ADF9375D2EC14439B52219B56C214786><A
name=IssueNumber00__li_ADF9375D2EC14439B52219B56C214786><!-- --></A>Topics
must have authored titles rather than specialization-specified ones
("spectitles").
<LI id=IssueNumber00__li_B0365A64A7B54B8F830623AFBC13DF77><A
name=IssueNumber00__li_B0365A64A7B54B8F830623AFBC13DF77><!-- --></A>Topics
must always have titles: sometimes neither authored nor generated titles are
required (see the "output-transparent grouping" use case below)
<LI id=IssueNumber00__li_EFEC2C896EA44DCAA51B486D87E7E1D8><A
name=IssueNumber00__li_EFEC2C896EA44DCAA51B486D87E7E1D8><!-- --></A>Topics
must always have IDs.
<LI id=IssueNumber00__li_ADD13744663245FA929E50D15E954321><A
name=IssueNumber00__li_ADD13744663245FA929E50D15E954321><!-- --></A>Topics
require an extra layer of "body" wrapping that differentiates between
metadata and content: even when metadata is either not needed or explicitly
disallowed through specialization.
<LI id=IssueNumber00__li_C9F4EEBE93344324A09E1731E3185263><A
name=IssueNumber00__li_C9F4EEBE93344324A09E1731E3185263><!-- --></A>Acccording
to some definitions of "topic", making content into a sub-topic has certain
unwanted semantic implications like: "This content is independently
reusable" or "this content should be independently indexed by CMS search
engines".
<LI id=IssueNumber00__li_246FB0CCB02B4E23873A461CCBF9BB57><A
name=IssueNumber00__li_246FB0CCB02B4E23873A461CCBF9BB57><!-- --></A>Topics
can only be grouped by other topics with all of the issues described above.
Topics cannot be grouped by sections.
<LI id=IssueNumber00__li_898DEE88BFAC4F1EB26B739F9676289C><A
name=IssueNumber00__li_898DEE88BFAC4F1EB26B739F9676289C><!-- --></A>The
output behaviours for subtopics are typically quite different from those for
sections. E.g. with respect to HTML chunking and locations of related-links
elements. </LI></OL>
<P>This proposal defines mechanisms for lightweight, hierarchical, sectional
grouping.</P></DIV>
<DIV class=section
id=IssueNumber00__section_58408528B0E848F08FA1B8BC9371A12F><A
name=IssueNumber00__section_58408528B0E848F08FA1B8BC9371A12F><!-- --></A>
<H2 class=topictitle2>Scope</H2>
<P>Intermediate</P></DIV>
<DIV class=section
id=IssueNumber00__section_D50F4B7A0F614A90B46F44601A6F39A4><A
name=IssueNumber00__section_D50F4B7A0F614A90B46F44601A6F39A4><!-- --></A>
<H2 class=topictitle2>Use Cases</H2>
<DL>
<DT class=dlterm>Complex Specialized Templates
<DD>Imagine if the document type for DITA Proposed Features were a
specialization. It would likely have elements like "Longer Description",
"Use Cases", "Technical Requirements" and so forth. For the sake of clarity,
lets call these specialization-defined sections "schematic sections". In
contrast, sections with titles and semantics totally under the control of
authors will be called "author-defined sections". It seems quite possible
that under many circumstances, these schematic sections will require
author-defined subsections or schematic sub-sections. For example, the use
case you are reading right now might be within a sub-section (perhaps a
specialized "Use Case" section type) rather than a definition list if that
were possible. Because the output-requirements for this document type are so
lax, we can get away with using a definition list. But sometimes customers
really do require "section behaviour" for sub-sections.
<DT class=dlterm>Output-transparent Grouping
<DD>Sometimes it is necessary to group multiple sections and other content
into a single unit in order to "conref" them or filter than all together.
</DD></DL></DIV>
<DIV class=section
id=IssueNumber00__section_D1D72D757F124B24844817D1ED1A66FA><A
name=IssueNumber00__section_D1D72D757F124B24844817D1ED1A66FA><!-- --></A>
<H2 class=topictitle2>Anti-Use Cases</H2>
<P>The proposal is <STRONG>not</STRONG> meant to address situations where
authors wish to create deeply nested topics with many levels of titles. They
should use nested topic features to do that.</P></DIV>
<DIV class=section
id=IssueNumber00__section_545E6EE4ECFF47F5B44FB0E842A6306F><A
name=IssueNumber00__section_545E6EE4ECFF47F5B44FB0E842A6306F><!-- --></A>
<H2 class=topictitle2>Technical Requirements</H2>
<P>The proposal is the addition of two elements. One, "bodydiv" or "div" would
be able to contain sections and other body-level elements. The other,
"sectiondiv" would be contained by sections and contain body-level elements.
Neither type would allow authors to write titles. Both types would have
optional "spectitle" attributes that would behave the same as the equivalent
attribute on sections. </P>
<DIV class=p>Here is an example of the "bodydiv" element:<PRE><body>
<p>Got some stuff to say</p>
<bodydiv>
<p>A logical grouping of content within a body - a
specializer could use this to generate a title, but there's no
facility for the author to define a topic-like or unique
title.</p>
<section>
<title>A</titke>
<p>etc.</p>
</section>
<section>
<title>B</titke>
<p>etc.</p>
</section>
<bodydiv>
<p>A nested bodydiv.</p>
</bodydiv>
</bodydiv>
<bodydiv>
<p>Another bodydiv</p>
</bodydiv>
</body> </PRE></DIV>Here is an eample fo the "sectiondiv" element:<PRE><section>
<title>stuff</title>
<p>etc.</p>
<sectiongroup>
<p>A logical grouping of content within a section - a
specializer could use this to generate a title, but there's no
facility for the author to define a topic-like or unique
title.</p>
<p>etc.</p>
</sectiongroup> </PRE></DIV>
<DIV class=section
id=IssueNumber00__section_DE9BFD6C450A4E839830CDA5E8F793A5><A
name=IssueNumber00__section_DE9BFD6C450A4E839830CDA5E8F793A5><!-- --></A>
<H2 class=topictitle2>Costs</H2>
<P>The DTD changes required to allow this are minor. Basically two new element
definitions are required. They are not particularly complex elements and are
almost the same as sections.</P>
<P>The implementation changes are relatively minor as these elements can be
treated as a variant of section elements.</P>
<P>The largest long-term cost is the incremental bloat to the DITA language
itself. DITA is already a large language, so the addition of new elements
should be carefully considred.</P></DIV>
<DIV class=section
id=IssueNumber00__section_EA5CAE7E231E4FAFA82449D324D0EBB8><A
name=IssueNumber00__section_EA5CAE7E231E4FAFA82449D324D0EBB8><!-- --></A>
<H2 class=topictitle2>Benefits</H2>
<P>As per the introduction, the benefit is the ability to create
section-nested content without the overhead and mismatched content model of
nested topics. It is hard at this time to determine how many people are
bothered by the issues with nested topics. </P></DIV>
<DIV class=section
id=IssueNumber00__section_FB7AE186FE874A5EBF163482426732FE><A
name=IssueNumber00__section_FB7AE186FE874A5EBF163482426732FE><!-- --></A>
<H2 class=topictitle2>Time Required</H2>
<P>The technical time to implement is relatively small: on the order of a day.
The submitter feels that there are still some open issues with respect to
defining best practices for using this feature versus using nested topics. It
may take a further few meetings to work through these
issues.</P></DIV></DIV></BLOCKQUOTE><!-- Converted from text/plain format --><FONT
face=Arial size=2></FONT></BODY></HTML>
------_=_NextPart_001_01C5EF76.96B7D89C--
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]