This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 3516 - Editorial comments on ITS from i18n core
Summary: Editorial comments on ITS from i18n core
Status: CLOSED FIXED
Alias: None
Product: ITS
Classification: Unclassified
Component: ITS tagset (show other bugs)
Version: LastCall
Hardware: PC Windows XP
: P2 normal
Target Milestone: AfterLC
Assignee: Felix Sasaki
QA Contact: Felix Sasaki
URL:
Whiteboard:
Keywords: proposalAccepted, reviewerSatisfied
Depends on:
Blocks:
 
Reported: 2006-07-20 08:18 UTC by Felix Sasaki
Modified: 2006-10-03 14:54 UTC (History)
0 users

See Also:


Attachments

Description Felix Sasaki 2006-07-20 08:18:35 UTC
This bug is about
http://lists.w3.org/Archives/Public/www-i18n-comments/2006Jul/0000.html
http://lists.w3.org/Archives/Public/www-i18n-comments/2006Jul/0001.html
http://lists.w3.org/Archives/Public/www-i18n-comments/2006Jul/0002.html
http://lists.w3.org/Archives/Member/member-i18n-core/2006Jul/0000.html

We took the following decision on these comments, see http://www.w3.org/2006/07/17-i18nits-minutes.html#item01 :

[[
Yves: everbody at the last call agreed in leaving them to the editors
... so we skip over them now, to gain some time
Richard: sounds good to me
Felix: me as well]]

The editors can now go on and implement these, until they don't see any further issues. In that case, they will open separate bugs for each such issue.
Comment 1 Felix Sasaki 2006-07-25 06:04:51 UTC
Resolution: the working group agreed with the proposals at http://www.w3.org/2006/07/17-i18nits-minutes.html#item01 and leaves it to the editors to make the change.
Action: editors to make the changes.
Comment 2 Christian Lieske 2006-08-16 08:53:08 UTC
I worked on 

http://lists.w3.org/Archives/Public/www-i18n-comments/2006Jul/0000.html
(see text repeated below) as follows:

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

THESE ARE COMMENTS FOR SECTION 1


1.1.1  Vendors of ...
This type of users encompasses...
This type of user includes...

CL> Comment has been implemented

1.1.1 Content producers
This type of users comprises...
This type of user comprises...


CL> Comment has been implemented

... other types of content authors.
... other types of content author.

CL> Comment has been implemented

The burden of inserting markup should be ...
The burden of inserting markup can be ...

CL> Comment has been implemented

1.1.2 Eg 1
I find the links such as [EX-ways-to-use-its-1.xml] very strange.  Why not just say "Link to source text" or some such thing.

CL> Comment needs further action: Modification of transformation/rendering stylesheet

"A content author or information architect uses markup at the top of the document to identify a particular type of element or context in which the content should not be translated."
I think you should add further commentary right here (briefly) on what the example shows.  For example:
"Example 2 shows how you could set a rule to say that no dt elements in a document should be translated."

CL> Comment needs further action: Where to hold explanations of the examples? Internal or external to the example file?

A processor may inject markup...
A processor may insert markup...


"A processor may inject markup at the top of the document which links to ITS information outside of the document."
I find myself wondering, How does this work?

CL> Comment has been implemented (mentioned external rules in #link-external-rules)

"A schema developer integrates ITS markup declarations in his schema to allow users to indicate that specific parts of the content should not be translated."
I really think you need a third example here to make this clear.  I think an example of the content would work fine.

CL> Comment needs further action: Create example file (and store in CVS) 

It's not immediately obvious which examples relate to which bullet points - you have to check.  It would be much better to do something like add "(Example X)" at the end of each line, to associate the point with the right example.
(Note that you can easily refer to examples by number using the i18n version of the xmlspec dtd, by pointing to the id of the example in a specref element.)

CL> Comment needs further action: Give example about the markup that has to be used; change requires ODD schema

1.2 Motivation for ITS

Having read this after a while away from the document, I really think that the first part of this section should come before the previous section (1.1).  It is very high level introductory stuff.

Examples
I think it would help to split this seemingly long section.  I think that would make it more likely for people to read it.  You could insert a title "Typical problems" before the para "The following examples sketch...".

CL> Comment needs further action: Change requires ODD schema

Examples
I think people will wonder what the problem is.  You say that the general issue is that there's a "lack of a standard, declarative mechanism which identifies which parts of an XML document need to be translated".  You also say "PhaseCode should not be translated; the title attribute sometimes has to be translated and sometimes must not be translated.". But you don't say why the approach in the example doesn't work, ie. why ITS is needed. Same for the following example. Example 6 is slightly better in this regard, but by then I'm beginning to wonder why there are 3 examples, all of documents with partially translatable content.  Are there systematic differences? I have to investigate that to come up with some ideas, but the text should spell this out for me.

CL> Comment needs further action: Where to hold explanations of the examples? Internal or external to the example file?

Example 3
"In the example below, there are no clear mechanisms allowing one to know which string element needs to be translated."
Well, actually I think the question is which ones should NOT be translated, given that the default is translate=yes

CL> Comment has been implemented

1.3


"These mechanisms and data formats, sometimes called Localization Properties, however, possibly may be implemented"

'these mechanisms' refers to "This standard does not exhaustively cover all mechanisms and data formats which might be needed for configuring localization workflows or tools to process a specific format."
Either you need to say:
"This standard does not cover mechanisms and data formats..."
or 
"Certain mechanisms and data formats, sometimes called Localization Properties,..."

If you go the first route, you should probably say something like:
"This standard does not cover the mechanisms and data formats sometimes called Localization Properties, however these may be implemented using the framework described in this standard."

CL> Comment has been implemented as follows:
CL>
CL> <p>This standard does not cover all mechanisms and data formats (sometimes called
CL> <term>Localization Properties</term>), which might be needed for configuring
CL> localization workflows or tools to process a specific format.  However, these
CL>  mechanisms and data formats may be implemented using the framework described in this standard.</p>

Note
...data formats that allows localization tools...
...data formats that allow localization tools...

CL> Comment has been implemented

...the "Trados DTD Settings" file, and the SDLX "Analysis" file.
should that be 
...the Trados "DTD Settings" file, and the SDLX "Analysis" file.

CL> Comment has been implemented

I think you can lose the : after 'are'

CL> Comment has been implemented

1.4

...need an efficient way for managing...
...need an efficient way of managing...

CL> Comment has been implemented

This specification responds to these requirements by introducing mechanisms for specifying ITS information in XML documents
is a bit complex - how about
To meet these requirements this specification introduces mechanisms that add ITS information to XML documents

CL> Comment has been implemented

" The ITS mechanisms for selection are:
  * as for XML documents, usable local (at the XML node to which it pertains) or globally (not at the XML node to which it pertains)
    * as for global usage: possibly in the target XML document or in a separate file"
This reads rather weird. At the very least local->locally or globally->global.
How about breaking the paragraph before "The ITS mechanisms for selection...", (since this is a slightly different topic, but sounds like a repetition if you arent' reading carefully), and rewording as:
"ITS selection mechanisms allows you to provide information about content locally (specified at the XML node to which it pertains) or globally (specified in another part of the document). Global selection mechanisms can be in the same document, or in a separate file."

CL> Comment has been implemented

Ease of integration
Only for some requirements additional child...
Only for some requirements do additional child...

CL> Comment has been implemented

1.5

literate programming language
meaning?

CL> Comment needs further action: Comment needs further action: Change requires ODD schema and reference to be used

...to extract documentation in HTML, XSL FO or LaTeX forms...
'in' means 'into' or 'from' (ie. ',which is in')?  not clear what you're saying here

CL> Comment has been implemented
Comment 3 Christian Lieske 2006-08-16 09:50:58 UTC
I worked on 

http://lists.w3.org/Archives/Public/www-i18n-comments/2006Jul/0001.html
(see text repeated below) as follows:

===

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..."

CL> Comment has been implemented: subheadings for "Selection", "Examples for Global and Local Selection",
CL> "Overriding and Inheritance", "Adding Information or Pointing to Existing Information"

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..."

CL> Comment needs further action: Change requires ODD schema

And I'd move this paragraph BEFORE the example.

CL> Comment has been implemented

"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.)

CL> Comment has been implemented

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

CL> Comment has been implemented

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

CL> Comment needs further action: Change requires ODD schema

"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?

CL> Comment needs further action: Modify example file (and store in CVS) 

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

CL> Comment has been implemented

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.

CL> Comment has been implemented: Moved to beginnging of section with examples for selection

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)."

CL> Comment has been implemented

"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."

CL> Comment has been implemented

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

CL> Comment has been implemented
Comment 4 Christian Lieske 2006-08-16 10:08:55 UTC
I worked on 

http://lists.w3.org/Archives/Public/www-i18n-comments/2006Jul/0002.html
(see text repeated below) as follows:

===

6.3.2

the information associate to the selection...
the information associated with the selection...

CL> Comment has been implemented

The selection is the textual content of element...
The selection is the textual content of the element...

CL> Comment has been implemented

As for...
This is slowly driving me nuts.  It's not good usage ('as for...' is typically used to mean, 'on the other hand, wrt...'), but apart from that, there appear to be clear divisions marked by this phrase that would be better highlighted by some kind of heading.  It doesn't need to be, eg., 6.4.2.3, but a bolded "Global rules: " at the beginning of the first para related to that would help a lot in scanning, as well as look cleaner.

This would also simplify the following text. Eg.
"As for global rules, identifying terminology information at selected nodes is realized with a termRule element with a mandatory selector attribute."
could be 
"Global rules: Terminology information is identified by a termRule element, which has a mandatory selector attribute."

Also, the following sentence could be cleaner without the "In addition,"

CL> Comment needs further action: Change requires ODD schema

As I try to understand the section on data categories, I keep wishing there was more standardization of the text. For instance, in one place we have "Directionality can be expressed with global rules or locally on an individual element." as the second sentence under implementation; elsewhere "Ruby can be expressed locally in a document or with global rules." as the first sentence; elsewhere "This data category can be expressed only in a set of rules. It cannot be expressed as local markup on an individual element."  And Language Information doesn't have an Implementation section at all.

It would be much easier to compare and contrast, but also pick up information if this was expressed in a standard form, eg. first sentence under "Implementation" is always
"XXX can be expressed with global rules, or locally on an individual element.", or, in the case like the third above "XXX can only be expressed locally on an individual element."

Several other similar standardisations could be applied to the data categories section.

CL> Comment needs further action: Modification of transformation/rendering
stylesheet

6.5.2
"The dir attribute is used for the implementation of the directionality data category. It has the four values "ltr", "rtl", "lro" or "rlo"."
-> 
"The dir attribute takes the values "ltr", "rtl", "lro" or "rlo"."

CL> Comment has been implemented

6.6
It makes it harder to assimilate the ruby information that the local implementation is described first (unlike any other section).  Also it is not immediately clear that the last para describes one set of global rules, and 6.6.3 another.


CL> Comment needs further action: Change requires ODD schema

6.6.2
"The functionality of pointing to existing ruby markup is realized with various pointer attributes for ruby."
"Various pointer attributes can be used to point to existing ruby markup."  Please list them here.


CL> Comment needs further action: Change requires ODD schema

5.3.1
s/all other possible attributes at rule elements/all other possible attributes on rule elements/

CL> Comment has been implemented

5.3 intro
s/which are attached to the selected element node/which are attached to an element node/
You can argue that the author selected the element node, but it's confusing to say it that way given the importance of selection through attributes in global rules.

CL> Comment has been implemented

5.4
s/Application processing global ITS markup/Applications processing global ITS markup/

CL> Comment has been implemented

Example 19
"<dd>ITS defines <term>data category</term> as an abstract concept for a particular 
    type of information for internationalization and localization of XML schemas
    and documents.</dd>"
->
<dd>ITS defines <term>data category</term> as an abstract concept for a particular 
    type of information related to internationalization and localization of XML schemas
    and documents.</dd>

CL> Comment needs further action: Modify example file (and store in CVS) 

Comment 5 Felix Sasaki 2006-09-06 21:59:07 UTC
Action: Yves and Felix to go through the changes, and implement as much as possible in the ODD file.
Comment 7 Felix Sasaki 2006-09-20 14:59:10 UTC
Closed. Reviewer satisfied. See http://lists.w3.org/Archives/Public/public-i18n-its/2006JulSep/0387.html .
Comment 8 Felix Sasaki 2006-09-28 07:01:01 UTC
Summary: The Working Group decided to accept the editorial comments and to implement many of them in the working draft, until the reviewer is satisfied.