Stan Doherty comments disposition

[Michael Priestley <mpriestl@ca.ibm.com>]

FYI, comments from Stan Doherty and their disposition
(just getting them on the list for archiving):


> P01-L15: users -> users' 

sticking with users - "users guide" vs. "user's/users' guide"
differs from style guide to style guide 

> P03-L32: contents -> content 

sticking with contents - the singular is "table of contents",
so when pluralizing table, I wouldn't want to drop contents to singular
- eg "basket of oranges" -> baskets of oranges, not baskets
of orange. 

> P04-P05: Request for 1.2 - this section yearns for a containment
>          diagram for all the types defined
here 

logged 

> P07:     Here's a comment that might help readers. Is it
true?
>          "All specializations to the
base DITA DTDs require
>          DITA modules. Modules have no function
apart from
>          specializations." If DITA DTDs
are not really useful
>          constructs without the mod/speiclization
files, that
>          might be worth mentioning/commenting.
This gets stated
>          explicitly (I believe) in P10-L11.

added this clarification to DTD organization:
All element and attribute type declarations are made in modules, which
are 
then integrated into a document type using a document type shell.

And this to schema organization: 
All element and attribute type declarations are made in modules, which
are 
then integrated into a document type using a head schema.

Also added "head schema" as alternate term for "document
type shell" in terminology section 

> P08:     Request for 1.2 - A table (perhaps as an appendix)
>          specifying in columnar format which
DTDs (concept
>          etc) correlate to the .ent or .mod
files. The information
>          is all in the current table, but
is not optimal for
>          understanding.

Are you thinking one column per doctype, with checkmarks? Will log.

> P10:     Request for 1.2 - A table (perhaps as an appendix)
>          specifying in columnar format which
schema xsd files
>          correlate to which common module
xsd. The information
>          is all in the current table, but
is not optimal for
>          understanding.

Done as per previous. 

> P16:     So is the generic type a base topic type or an
>          exception/workaround to the 1.0
base topic types?
>          Is "generic" synonymous
with "unspecialized"? 

yes to both - adding clarification (for specializers, a base; for authors,
a workaround/exception) 

> P22:     Mentioning that glossary structure can be processed
>          for online or book output seems
harmless enough. 

added explanation that glossary topics go into glossaries, which may have
many forms. 

> P23-L23: contents -> content 

per previous, "tables of contents" is correct - I suspect it's
your editorial eye catching the pluralization of the second noun in a compound,
which would be wrong except in this case (where it's already pluralized
in the singular) 

> P23f:    Addition? "DITA maps are specific to particular
>          target output formats whereas topics
are (most
>          often) independent of output. To
process/publish
>          the same content to two output formats,
you need
>          two DITA maps." The current
language around
>          "scalable reuse of content
across multiple
>          contexts" is a bit sqooshy.
This gets stated more\
>          explicitly on P24-L21.

This is a stronger statement than I'm comfortable making. Most people I
know are actually using the same map to produce both print and online output,
with only minor variants controlled using attributes. So while the ability
to have two different maps for different output formats is valuable, it's
not defining. 

> P32-L14: / -> .
> P36-L25: on -> in ? 

done, and done 

> P43-L11: The sentence "Fragments of DITA ... " still throws
me.
>          It may well be a dummy thing on
my end, but some sort
>          of clarification or exemplification
would help. 

done - added clarification: 
Fragments of DITA content (such as a document containing only a single
paragraph) 
do not contain enough information on their own to allow the conref processor
to determine the validity of a reference to them.