comments on language specification

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

Did a fairly complete review over the
weekend - here's my list. Some of the usability suggestions are debatable
(eg deleting attribute descriptions from specialized elements, and just
linking to the parent element). I'd welcome feedback.

This list may be easiest to read with
the language reference in front of you. I haven't attempted to reproduce
the entire context of the change in every case primarily because I'm a
lazy typer.

general:
- reorg by module (topic type or domain)
- punt to index for alphabetical org
- generate index for pdf
- eliminate attribute lists of specialized
elements when duplicate of ancestor, and just link to ancestor element
- link to attribute definitions when
the attributes are common, rather than repeating the definitions in every
attribute list
        (e.g.
class, outputclass, xml:lang)
- add "Example" section titles

- in examples, bold the element being
illustrated 
- when same example used for whole branch
of elements, include example at root element level only, link there from
others (eg reltable)
- change references to "DTDs"
to "document types"
- change domain descriptions that talk
about the domain's use in concept, task, and reference to be topic-type-neutral
- in descriptions of importance attribute,
remove assertion that it is for conditional processing
- change "syntax definition"
to "syntax diagram" everywhere (make it easier to understand
that we mean the syntaxdiagram element)
- when examples show both source and
output, shd be standard for which comes first (I'll suggest source)


anchor:
- rewrite id description (currently
using wrong description)
- provide contrast with conref on a
map element

area
- delete ref to imagemap - will be covered
by standard links

author
- in href description, change "typically"
to "for example"

b
- change "tag" to "element"

category:
- rewrite example (currently showing
empty category element with use of select-atts)


choicetable:
- delete substeps from example (obscures
choicetable, and also most steps would not include both)


chrow:
- delete extra lines from example

conbody:
- create new example. current example
talks about sgml entities, which is likely to cause confusion since dita
deprecates entity use

concept (or topic, and then refer to
topic):
- correct conref attribute description
- filename without id points to first topic; file name with id points to
specific topic
- change id description to say "target
for href and conref atts" rather than listing linking elements
- ditaarchversion: chg dtd to architecture
- delete <example> section in
the example - it doesn't actually contain an example.


coords
- delete ref to imagemap (can get there
indirectly via contained by links)

copyryear
- in year descrip, delete citation -
YYYY as format is self-explanatory


dl
- say "presented flush left"
rather than "is"
- update formatting in example to start
new elemens on new line

draft-comment
- delete exclamation mark, turn note
into normal paragraph


dt
- shorten example and fix typo (extention)

example
- remove reference to IBMIDDOC
- delete example, since it's primarily
talking about things other than examples.

featnum
- change document to topic


groupchoice
- fix spacing in example

image
- main desc, change ref to alt attribute
to alt element (alt attribute deprecated)
- alt attribute, deprecate and recommend
alt element
- longdescref, add syntax example

imagemap
- change "examples" to singular

indexterm
- make description specific to indexterm
(not keyword as well)
- update keyref description to describe
intended use (adds current indexterm under referenced target)

indextermref
- delete note (none of the indexing
is supported under the current public processing, and the functionality
of indextermref is not in fact equivalent to keyref on indexterm - may
be equiv to conref)
- do we want to say this is deprecated
in favour of indexterm with conref?

keyword
- make description specific to keyword
(delete indexterm discussion)


link
- remove reference to sort orders (no
attributes for determining sort keys)
- expand href description to cover full
syntax (same file, first in different file, specific in different file)
- change format description to say allowable
values "include" rather than "are"
- chg format description from saying
"mapref" to "ditamap" as a value
- chg format description final bullet
to be a suggestion rather than a rule
- chg scope description to use bullets
- chg query description to remove references
to topicref
- chg example to use linkgroup rather
than linklist (the current example shows the kind of structure that is
currently generated from linkgroup)

linkinfo
- chg example to set collection-type="sequence"
and give a more descriptive title

linklist
- chg description to remove ambiguity
(currently reads as if linkpool is used by the processor as a sorting mechanism)
- collection-type: remove list of allowable
values, which is duplicated in the data type column
- duplicates: defaults to yes for linklist.
update descrip and value fields
- format and scope as per link
- delete example, which currently shows
manual tags for what gets generated for free

linkpool
- clarify descrip - links are sorted
together if they aren't in a linklist
- clarify descrip per linklist
- collection-type per linklist
- duplicates: defaults to no for linkpool,
can't be changed. update descrip.
- mapkeyref: chg refs to linklist to
linkpool
- example: delete collection-type, delete
linktext from example

lq
- delete future dita considerations
- href: delete "see keyref"
reference, delete example which is wrong
- type: doc as-is, but add to issues
for 1.1 - use of type is inconsistent with linking elsewhere
- reftitle: doc as-is, but should allow
text in an element instead for translation purposes. consider making a
specialized xref element inside lq instead of atts on the elem itself

map
- update descrip to make clear that
it can organize other resources besides topics, using tables/hierarchies/groups
- correct caps on att name "Title"
- clarify description of Eclipse behavior
(title always required for eclipse output, used as toc label)
- id: chg "is only used" to
"may be used"
- anchorref: clarify - used for runtime
integration only
- ditaarchversion: version of architecture,
not dtd

menucascade
- delete "or to show any choice..."
- chg "may show" to "shows"
(the output processor must provide the connecting chars)

msgblock
- example: add closing tag

navref
- contrast with conref for build-time
integration, per anchor above
- example: delete the topicref

navtitle
- delete "or needs stated..."

option
- make clear it's only in use by syntax
diagrams
- delete example

othermeta
- name: correct descrip (shd be name
of the metadata property)
- translate-content: doc as-is, but
add to issues for 1.1 - why not just @translate?

param
- name: shd be name of the parameter
- id: shd be id of the parameter
- doc as-is, but why no conref?
- value-type: add bullets

parml
- chg "computer parameters"
to "command or interface parameters"

parmname
- chg example to show env as a param
of config, rather than an object operated on by config

pd
- update example to use synph rather
than codeblock, and use standard format for output and input

ph
- delete "future"
- say "create semantic markup"
rather than "apply specific processing"

plentry
- same as for pd

pre
- add warning to use more semantic elems
when avail (eg codeblock)

prereq
- clarify processing of prereq links,
or link to explanation in "related-links"

prophead
- delete "more about this element"
- example: delete plural, delete extraneous
" in headings, add source

propdeschd, proptypehd, propvaluehd
- say same as stentry rather than property

refbody
- example: remove doctype, <?xml

reference
- same as refbody
- chg atts per concept

refsyn
- same as refbody

related-links
- processing notes: chg "pdf output
ignores" to "typically ignores" and add note that it may
include child links to create chapter summaries
- processing notes: get rid of italics
on att names
- format, scope: chg per link

relcell, relrow, relcolspec, reltable
- example: consolidate in reltable only,
add description of links added for output

repsep
- make clear it only applies within
syntaxdiagram

resourceid
- in last sentence of descrip, chg "or"
to "and"
- remove italics from att names
- id: correct descrip - shd be "a
value used by an app to identify the topic"
- appname: correct descrip - shd be
"the app that requires the id"
- example: switch id and appname values,
make the appname "dbaccess"

screen
- example: correct formatting 

sep
- make clear it's part of syntaxdiagram

shape
- example: delete extraneous first line,
delete ref to imagemap

simpletable
- delete "DITA insight" label,
turn content into normal paragraph, 


sl
- define as simple list, describe output
per descrip in sli

source
- href: correct descrip and examples

state
name: correct to "the name of the
property whose state is being described"
value: the state of the property identified
by name

steps-unordered
- delete "for example" since
forms typically do have a tab sequence

strow
- delete "like a row..." since
it is a row

substeps
- example: delete "Note:"
text since typically that would be provided by a note element if needed

sup
- delete "for example.. uicontrol"
- example works for bold but not others

synblk
- example: fix formatting

synnoteref
- chg "elsewhere in the topic"
to "elsewhere in the document"
- href: current descrip is wrong, need
confirmation of correct syntax. 
- example: shd show correct syntax,
needs confirmation

synph
- example: fix formatting

table
- where it mentions expanse in the descrip,
spell out as "the expanse attribute available on other dita elements"
- fix ref to display-atts - doesn't
use expanse, uses pgwide

task
- chg atts per concept

term
- chg "represent" to "may
have or require"

tfoot
- valign: chg "table entry (cell)"
to "table footer (tfoot)"


title
- chg document to topic, rewrite as
necessary

titlealts
- add that when titlealts absent, title
gets used for everything
- example: swap values of title and
navtitle (navtitle typically shorter)

tm
- delete first sentence of "Remember",
change remainder into normal para, chg "must be" to "may
be"
- tmclass: delete ibmisms

topic 
- chg id, other atts per concept


topicmeta
- chg "topic's children" to
"topic's children within the map"

topicref
- chg "designates" to "identifies"
- make clear topicrefs can point to
other resources besides topics
- id: currently wrong, chg to talk about
eg conref use
- href: rewrite, provide examples
- query: chg "topicref" to
"the target"
- conref: add descrip
- scope: att and descrip are missing,
shd probably be in topicref-atts
- copy-to: recommend providing title
and shortdesc for copies using topicmeta

topichead
- navtitle is required
- update other atts per topicref

topicgroup
- update atts per topicref

tt
- in descrip, use appropriate example,
eg codeph rather than uicontrol

tutorialinfo
- ok to use outside of tutorials, but
processor should suppress outside of tutorials (not currently doing so,
but that's a bug, not according to spec)

uicontrol
- chg "represents" to "identifies
text that is the name of"
- clarify for example to describe cascade
of menu choices

varname
- delete "possibly within a message
or API...". we do not have markup for environment variable names,
using varname would be inappropriate

wintitle
- chg "represents" to "identifies
text that is the title of a window" etc.

xref
- add descrip of desc usage (shd be
turned into flyover help, like desc for link)
- rewrite to provide enumeration of
potential scopes and formats
- chg descrip of href to say "provides
the location of the target"
- clarify warning against using xref,
also mention map-based linking
- href: rewrite to provide appropriate
list of href syntaxes
- type: chg "allowed values are"
to "possible values include"
- delete "other" as type value
- chg note for href to talk about what
other values can be used for, and when override processing will be required

- update format per previous edits
- update examples to use .dita for consistency
(makes it clear when the target is actually dita)

%global-atts
- xmlns shdn't be here

%id-atts
- conref: update examples - delete last
one, add elementid to second one
- consolidate descrip before atts
- delete "not all these capabilities.."

%rel-atts
- type: ensure type list is appropriate
wherever referenced, update per xref or link as appropriate
- role: getting rid of deprecated values
shd be priority for 1.1
- scope shd probably be part of this
list

%select-atts
- importance: delete property att info
- it is not used for conditional processing. also delete listed values,
since dup of data type cell
- status: delete list of values, and
property att info, same reasons as importance
- status: add list of allowed values
to data type cell
- delete "not all these capabilities..."

%topicref-atts
- collection-type: delete value list
from descrip field
- type: list is wrong, create appropriate
list for topicref
- format: update per link
- linking: chg "topic" to
"topic's current location in the map"
- chunk: add descrip

%topicref-atts-no-toc
- update per topicref-atts

appendix
- delete appendix; is either forecasting
future functionality, or duplicating content in arch spec or in other specs

Michael Priestley
mpriestl@ca.ibm.com
Dept PRG IBM Canada  phone: 416-915-8262
Toronto Information Development