OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  Data types and default values

    Posted 02-02-2009 18:29 
    Hi,

A couple of reviewers have commented on the data types and default values
in the language specification.

Comments from a couple of reviewers include:
* What do CDATA and NMTOKEN mean?
* What does #IMPLIED mean?
* Why does it say the default is #IMPLIED when my processor always does XYZ
with it?
* Why does it use DTD syntax (#IMPLIED) instead of Schema syntax, or
something more general?

My question is now - what should these values say? Considerations are:
* CDATA, NMTOKEN, etc do have external definitions.
* How can I explain these in words without overloading the attribute tables
with definitions? That is, we do not want each attribute to define NMTOKEN
or CDATA
* I know many look to the default column to see what DITA defines as a
default - but processor defaults are distinct from DTD/Schema enforced
defaults

My preference is:
* For data type, stick to CDATA/NMTOKEN, because these are common XML
terms ... unless somebody can suggest something better. Maybe "Character
data" or "String" for CDATA, but NMTOKEN?
* If needed, we can define those terms at the start of the spec (or
reference definitions elsewhere)
* If there is no DTD/Schema default, list "No default" or leave the column
empty instead of listing #IMPLIED or #REQUIRED
* I think that the "default" column should stick to listing only DTD/Schema
defaults (not processor defaults), otherwise we run in to trouble with
vendors / processors

Other thoughts?

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit


  • 2.  Re: [dita] Data types and default values

    Posted 02-03-2009 13:34 
    Hi Robert,
We could provide a very brief introductory section that explains the layout
of the tables in the lang spec. I do that in my DITA workshop, explaining
how to read the lang spec. That would be helpful for new users. However, I'd
keep the explanation brief and suggest references for common terms like
CDATA and NMTOKEN.

JoAnn


On 2/2/09 11:29 AM, "Anderson Robert"


  • 3.  RE: [dita] Data types and default values

    Posted 02-04-2009 15:10 
    In all my standards writing experience, we have made
a distinction between the standard and tutorials about
the standard.

The standard is not written for the end user with no
background.  Rather, it is written "on the shoulders"
of other standards (e.g., the XML standard) as much
as possible so as to avoid redefining technical terms
that are defined elsewhere.  Whenever one standard
starts trying to paraphrase another, it usually does
a poorer job than the original, and confusion can ensue.

I think we should stick with the XML terms and simply
include a reference to the XML spec (if one isn't 
already there).  For those who know XML, the terms
CDATA, NMTOKEN, and #IMPLIED are perfect; for those
who don't know XML, there will hopefully be DITA 
tutorials--we should not be writing the official 
DITA standard as a tutorial.

Since DTDs are the only schema language built into
the XML standard, it is completely reasonable to
use that syntax.  We can certain say that DITA is
compatible with--and can be used with--XML Schemas
and other schema languages, but it makes perfect sense 
to use DTD syntax in the standard that defines DITA.

paul

> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


Related Content