[Comment on ITS WD] Editorial comments from RI, Section 2

These are non-weighty editorial comments or suggestions.  I will send more important comments via separate emails.

THESE ARE COMMENTS FOR SECTION 2



First, this section is awfully long for a single heading, and needs to be broken up.  eg. add subheadings before
- example 7
- example 8
- "The global, rule based approach..."
- "The ITS selector attribute allows..."



There was a certain amount of deja vu going on in this section, eg. the first bulleted list repeats things said a short while ago, and is repeated later in this section.


"The example above shows..."
"Example 7 shows..."
And I'd move this paragraph BEFORE the example.

"how a content author may use the ITS translate attribute to indicate what text should be translated and what text should be protected from translation."
be more specific, eg.
"how a content author may use the ITS translate attribute to indicate that all content inside the author element should be protected from translation."
(Note that the default is translate=yes, but the example looks like a complete document, so the use fo translate=yes may give the wrong idea.)


For this to work, the schema developer...
For this approach to work, the schema developer



"The example above shows..."
"Example 8 shows..."


"Information for the handling of namespaces in these path expressions is contained in the ITS element ns which is a child of rules."
Why isn't it in the example?


Para starting: "For this to work, the schema developer needs to add the rules element and associated markup to the schema."
I would break the para at
- In some cases this may allow the schema developer to avoid adding other ITS markup
- For specification of the translatability information, the contents of the rules element


I think the "To summarize" paragraph repeats info we've heard before, so I didn't appreciate it in this location.  However, I thought it might be useful to set this out near the beginning of section 2, rather than here - especially since this isn't the end of the section.


The last part of section 2 feels quite long-winded, I'm afraid.  For example, I suggest:
"Depending on the data category and its usage, there are additional attributes for adding information to the selected nodes, or for pointing to existing information in the document. For example, the data category for localization information can be used to add information to selected nodes, or to point at existing information in the document. For the former purpose, a locInfo element can be used. For the latter purpose, a locInfoPointer attribute can be used."
 ->
"For some data categories, special attributes add or point to information about the selected nodes. For example, the data category for localization information can add information to selected nodes (using a locInfo element), or point at existing information elsewhere in the document(using a locInfoPointer attribute)."

"The functionality of adding information to the selected nodes is available for each data category except language information."
"Each data category allow you to add information to the selected nodes except for language information."


...must not appear at the same rule element
...must not appear in the same rule element



============
Richard Ishida
Internationalization Lead
W3C (World Wide Web Consortium)

http://www.w3.org/People/Ishida/
http://www.w3.org/International/
http://people.w3.org/rishida/blog/
http://www.flickr.com/photos/ishida/

Received on Tuesday, 4 July 2006 17:09:59 UTC