RE: Comments on the usage scenarios doc, sections 1-3

Thanks for the comments. See below for resolutions. Made just about all of
the changes, plus a few extra things beating document into submission.

New version online now. AV: please check my changes.

Addison

Addison P. Phillips
Director, Globalization Architecture
webMethods | Delivering Global Business Visibility
http://www.webMethods.com
Chair, W3C Internationalization (I18N) Working Group
Chair, W3C-I18N-WG, Web Services Task Force
http://www.w3.org/International

Internationalization is an architecture.
It is not a feature.

> -----Original Message-----
> From: public-i18n-ws-request@w3.org
> [mailto:public-i18n-ws-request@w3.org]On Behalf Of A. Vine
> Sent: Tuesday, April 27, 2004 5:55 PM
> To: I18n WSTF
> Subject: Comments on the usage scenarios doc, sections 1-3
>
>
>
> Editors' copy $Date: 2004/04/14 11:17:19
>
> Here is my last review of sections 1-3 of the scenarios doc
> before a potential
> proofread when it really is done.
>
>
> 1 Introduction
> --------------
>
> "The goal of the Web Services Internationalization Task Force is
> to ..." -
> shouldn't that be Internationalization Web Services Task Force,
> as it's written
> on the linked page?

DONE.

>
>
> 2.1 Basic Framework: Anatomy of a Web Service Interaction
> ---------------------------------------------------------
>
> "The services is the function, ..." - remove final 's' from 'services'

DONE
>
> 2.1.2 Request
> -------------
>
> 5. "If the SOAP message was decoded successfully, ... (that is,
> it was not in
> error) ... the provider agent will now attempt to invoke the
> service itself."
>   - change of tense, would be better as -
>     "If the SOAP message is decoded successfully, ... (that is,
> it is not in
> error) ... the provider agent attempts to invoke the service itself."

DONE
>
>
> 3.1 What are Internationalization and Localization?
> ---------------------------------------------------
>
> subtitle "Do you even care?"  - just kidding
>
> noted "web services" - assume doc will be scanned for all
> occurrences of "web
> services in any capitalization configuration and adjusted to the
> prescribed "Web
> services"

This occurrence fixed.
>
> "Natural language text processing (parsing, spell checking,
> grammar checking are
> examples of these)" =>
> "Natural language text processing; for example, parsing, spell
> checking, grammar
> checking."

Actually a colon should be used to introduce lists. I note that this item
didn't quite make sense in its context (which is a list of items for which
there might be an international preference). I changed it to read:

<p>Natural language for text processing: parsing, spell checking, and
grammar checking are examples of this</p>

I also cleaned up the list so that all items omit an ending period and use
similar language, etc.

>
> "Alternate Calendars ... " => "Alternate calendars ... "

DONE. I used semi-colons in this list to make up for using a colon earlier.
>
> Add period after "Tax or regulatory regime", "Currency", "...and
> many more", or
> take the periods off the ends of the other bullet points.

Ah. Yes. Done.

>   Add a
> space after the
> ellipses in "...and many more".

DONE
>
> Is there a W3C convention for referring to keywords and constants in
> programming/markup languages?  I think we should set off "lang"
> and "xml:lang"
> in the following statement "HTML for example uses the lang
> attribute to indicate
> the language of segments of content. XML uses the xml:lang
> attribute for the
> same purpose."

Agreed. xml:lang is now marked up with the <code> tag throughout.
>
> More on setting off a term "In this document, we will use the
> term locale as the
> name for this shorthand indicator for a user's particular set of
> international
> preferences." => 'locale' should be set off in some way, via underline or
> italics or bold or quotes or something.  We should be consistent,
> though, about
> how we set off a type of term.  In " ... this shorthand indicator
> for a user's
> particular set of international preferences." change 'for' to 'of'.

I should make 'locale' a termref everywhere that it occurs. Actually, in
doing it, I find that this is sort of overkill. I'm trying to make the first
occurrence in each section a termref.
>
> In the definition of Localization, why is "Locale" capitalized?

It's consistent.

> I don't see a
> need for it.  And again in the 2nd paragraph of Language
> Negotiation definition.

Cleaned up other references to locale to be all lowercase, except when
referring to the Java class (which we do in a couple of examples). In these
cases I replaced with <code>java.util.Locale</code> to make the usage clear.
>
> 2nd paragraph of Language Negotiation definition - " ... the
> locale of "en-US"
> ... " - 2 things, should we leave the hyphen as opposed to the
> underscore even
> though that convention is not yet established or standardized,
> and whatever we
> use, should it be set off by double quote marks?  back to establishing
> conventions for setting off types of terms.

Replaced sentence with this text:

For example, a system might define a locale of "en-US" (English, United
States). This locale encompasses
several time zones, so the user's preferred time zone...

>
> Same paragraph "prefered" => "preferred", "infered" =>
> "inferred", "vs" => "vs."
> - assume doc will be spell-checked.

Will spell check when done. Fixed these. Replaced vs with "versus"
>
> 3.1 last paragraph, change "and so forth" to "and others" or "and other
> entities" or something like that

DONE.
>
> 3.1.1 Relationship of Locale to Natural Language
> -------------------------------------------------
>
> " ...  in the absence of other information, the language parameter can be
> helpful in guessing a relevant locale." - remove comma after 'information'

DONE. Some wordsmithing and formatting was also done on this paragraph,
inserting a cross-reference to RFC3066 as well.
>
> So, you _are_ deleting the old block, right?

DONE.
>
> 3.1.2 I-025: Specifying and Exchanging International Preferences
> in Web Services
> ------------------------------------------------------------------
> --------------
>
> "Web services, by contrast, must ... " =>
> "Web services, in contrast, must ..."

DONE
>
> Expand "RPC" the first time it's used, then use the acronym.

You know not what you ask. I rewrote the paragraph to accommodate this as
follows:

<p>Web services, in contrast, must allow disparate systems to interoperate
in a consistent, non-proprietary manner. This design allows systems to
invoke each other without regard to the internal architecture of any part of
the system. It is helpful to think of a Web service as an remote procedure
call ("RPC"), even though many Web services do not use the SOAP-RPC pattern.
Unlike Web applications that can store user preferences in a session-like
object hidden from the requester, Web service interoperability requires a
shared model, if processing is to produce consistency between expectations
and result.</p>

Formerly:

<p>Web services, by contrast, must interoperate between systems in an
RPC-like way (even though many Web services do not use the SOAP-RPC pattern,
it is helpful to think about it this way for a moment). Web applications can
store user preferences in a session-like object which is hidden from the
requester. Interoperability at an API level requires a shared model, if
processing is to produce consistency between expectations and result.</p>
>
> "There is no way to associate the string argument with locale
> functionality in
> the provider or available in the transport." =>
> "There is no way to associate the string argument with locale
> functionality
> available in the provider or in the transport." - hmm, locale
> functionality
> available in the transport, is that even possible?  Identification, yes,
> functionality?

Modified substantially:

<p><emph>Description Scenario B:</emph>The same method is implemented taking
a single string argument instead. The programmer creating the method writes
logic to translate the string into the appropriate internal locale object.
This logic may be substantial and  must be repeated or shared for each
locale-affected method. There is no way to associate the string argument
with locale functionality in the provider, locale or language identifiers
available in the transport, or to describe the parameter fully and
consistently in directories. A system invoking the service might not be able
to create a string in the expected format. The provider may not be able to
validate the information appropriately.</p>
>
> Need spaces after all the colons, e.g. "Description Scenario

DONE

> B:The ... " =>
> "Description Scenario B: The ... "
>
> "A legacy (existing) function ... " =>
> "An existing function ... "

DONE. Changed to: "A existing or "legacy" function or method which obtains
its locale information from the runtime environment is deployed as a Web
service. "
>
> in Description Scenario C, "Accept-Langauge" => "Accept-Language"

DONE

> "Existing locale negotiation mechanisms (such as Accept-Langauge in many
> application servers) rely on the container (formerly an
> Application server, but
> in this case the service provider) to populate this information. " =>
> "Existing locale negotiation mechanisms, such as Accept-Language in many
> application servers, rely on the container (formerly an
> Application server, but
> in this case the service provider) to populate this information. "

DONE.
>
> Can we do something about the double colons in the Scenario As?
> maybe replace
> the second colon with a dash or something.

Reformatted.
>
> "Scenario A: Different Locale Identifiers: Sender sends a request
> to a Provider
> and wants a specific locale and uses its identifier for that." =>
> "Scenario A: Different Locale Identifiers - Sender sends a
> request to a Provider
> wanting a specific locale and uses its identifier for that."

Sender sends a request to a Provider, expecting a result in a specific
locale.

>
> " ... but the specific operation is slightly different than the sender's
> implementation and ... "=>
> " ... but the specific operation is slightly different from the sender's
> implementation and ... "

DONE. Some more rewording in this para.

>
> " ... (zh-Hant -> zh which represents Simplified)" =>
> " ... , for example zh-Hant, which represents Traditional
> Chinese, becomes zh,
> which represents Simplified Chinese." - set off zh-Hant and zh

DONE. Reworded this as:

<code>zh-Hant</code>, the RFC3066 language tag for Chinese written in the
Traditional Han script might fall back to <code>zh</code> which represents
generic Chinese and, on many systems, implies the use of the Simplified Han
script
>
> "Scenario B: Senders sends a request to a Provider and wants a specific
> locale and uses its identifer for that." =>
> "Scenario B: Sender sends a request to a Provider wanting a specific
> locale and uses its identifer for that."

Reworked a bunch of the items in here, making changes as suggested, but also
making the parenthetical items into fully explanatory sentences.
>
> Same Scenario, is the parenthetical (LCID -> Java) clear to our
> audience?  My

Fixed that.

> guess is that it's pretty much Greek to anyone outside of i18n.
> I think we
> should clarify the example, e.g. "For example, Microsoft Windows'
> Locale C? ID

LCID is, I think, short for LoCale ID.... go figure.

> (LCID) is not the same as a Java locale identifier." or something
> like that
>
> I'd like to pull the examples out of parentheses and give them
> more clarity in
> general in this section.

Me too. DONE.
>
> Scenario D needs a cleanup, I'm not sure exactly what is the
> intention so I
> can't rewrite it.

Did that...
>
> "Scendario E" => "Scenario E"  (Addison needs more sleep)  also
> another cleanup
> needed.
>
> Scenario F needs cleanup.

Did more.
>
> Figure shows up in wrong spot, at least on Netscape 7.1 - it
> should be after
> Scenario A++ (the extra smart scenario)

Moved. Graphic needs fixing still.
>
> 3.2.1 Textual vs. Binary Representations
> ----------------------------------------
>
> " ... binary representations and textual represenations." =>
> " ... binary and textual representations."

DONE, and fixed the misspell of represenations, space in text ual.
>
>
> "As an example, a floating-point number is represented in some
> binary format
> internal to an application, and is converted to a text ual format, with
> appropriate localization formatting (e.g. using a decimal comma
> rather than a
> decimal point for many European locales), for output to the user." =>
> "As an example, a floating-point number is represented in some
> binary format
> internal to an application, and is converted to text with appropriate
> localization formatting for output to the user; for instance, the
> decimal in the
> formatted text may be represented by a comma, rather than a period."

Slightly different rewording was done.
>
> "Nevertheless, most of them were carefully designed to be
> locale-independent,
> and are intended to be used locale-independent." =>
> "Nevertheless, most of them were carefully designed to be
> locale-independent,
> and are intended to be used in a locale-independent manner."  or
> something
> similar which is not "Me Tarzan, you Jane" sounding

Unga-bunga. Reworded para as:

As an example, the XML Schema Datatype
<code>date</code>
   uses the format YYYY-MM-DD from ISO 8601. This format is similar
(and in some
   cases even identical)  to some actual formats used in some locales. The
format is unambiguous and can be
   understood by a human reading the XML file. Although it is the
appropriate format in some locales and not in others, it can be understood
to be a locale-independent format. By contrast, if XML Schema had chosen a
format
that is not
   used in any locale, such as just numbering days since a well-defined
day, it would
   have made the format much more difficult for humans to work with,
without any
   benefits.
>
> Note in the 2nd paragraph, the word "date" is set off via a
> change to a Courier
> type font - we could exploit this convention throughout the doc
> for keywords and
> constants.  Also note, the ISO standard here is written ISO 8601,
> that is, with
> a space after 'ISO'.  We should be consistent in the way we write the ISO
> standard names.  Same goes for RFCs, but RFCs don't have to be
> consistent with ISOs.

Noted and working on it, as you can see.
>
> 3.2.2 Locale-dependent XML Schema datatypes
> -------------------------------------------
>
> still need the Ethiopic example here
>
> also, we have to decide if we're sticking with titlecase rules
> for section heads
> and apply it to all of them.

Fixing as I go.
>
>
>
> I'll put the rest of the comments in a separate mail (or mails)
>
> Andrea
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

Received on Wednesday, 28 April 2004 14:01:59 UTC