RE: [dita] Two proposals for nested sections

Indi: I don't agree that it is best to force your structure 
into DITA by just using elements that have the same structure but different 
semantics. For example, a title is not just a kind of phrase. It is a title and 
DITA already has an element for titles. Similarly, a section is not a kind of 
list item. It is a kind of section and DITA already has an element for section. 
The \problem with just using tags that "kind of fit" the structure is that you 
must do a bunch of processing overrides telling various tools not to treat your 
section/list item like a list but rather like a section and your 
phrase/title as a phrase but actually as a title. Over times as you may change 
tools you must continually update your tools to remind them of your proprietary 
overrides of DITA semantics. Specialization is about saving work by getting 
processing for free: not making work by turning some processing off and other 
processing on.

 

As per another email, I don't believe that usability is an 
issue at all. DITA allows arbitrary nesting of content  Here's an example 
output from the DITA toolkit: 

 

http://www-128.ibm.com/developerworks/xml/library/x-dita2/

 

That's one long, deeply nested document authored in DITA. 
DITA does not really enforce or even strictly encourage writers to avoid nesting 
or narrative content. Michael and I aren't even really disagreeing on 
appropriate output. We're asking what the authoring process should be to get to 
that output.

  

  
  From: France Baril 
  [mailto:] 
Sent: Tuesday, November 08, 2005 
  6: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