BP comments

Hi,

yesterday I read whole BP document. Please find below some of my comments.

Summary table in section 2:
Third row about avoiding translateable attributes has wrong text in 3rd
column -- it talks about @xml:lang which is not related to BP.

BP9: Defining markup for unique identifier:
There is sentence: "Make sure that elements with translatable content
are associated with a unique identifier."

I think that "are" should be replaced by "can be". It is not always
necessary to assign unique ids. Moreover this BP9 is for schema authors
-- and schema can only provide means for associating IDs but IDs
themselves are present in instance which is being localized not in schema.

Example 22:
XPath expression //img/@alt[../@role='ui'] can be written as
//img[@role='ui']/@alt which is easier to read. I already made this
change in CVS.

Example 24:
Ed. note: Shouldn't the ==> be ==> ? Otherwise, what's the point of
the example?

It is not necessary to escape > in XML (except when it is preceded by
]]). There is still ampersand to be escaped.
I think that example is OK and I have removed editorial note.

Example 27:
I have slightly improved identation for better readability.

General issue with quotes. We are currently using typewriter quotes like
"quote" in prose. Shouldn't we use proper English “quotes”? Is this
covered by W3C style guide?

Section 5.1.1: Integration of ITS into XHTML
Example is labeled as "non-conformant XHTML". Document is really
non-conformant as defined in XHTML spec. But XHTML conformance
definition is really silly. As this BP is for normal people and not
standard wonks who knows oddities of spec what about removing
"non-conformant" adjective completely? I think that current wording can
scare people little bit.

Then sentence "There are three ways to use ITS with XHTML and keep the
XHTML document conformant:" can be changed to "There are three ways to
use ITS with XHTML and keep the XHTML document valid:"

Section 5.1.2.1: There is * (asterisks) after word "description" in
attribute definition. Does * has some purpose here or is this just a typo?

Example 42:
I would suggest removing xsi:schemaLocation attribute as it is usually
bad practice to tightly bing document to particular schema.

Section 5.3:
There are only links to schemas, but source listings of schemas are not
present. In other section we usually show schema listing. Shouldn't we
unify this?

Example 58:
I have removed CVS $Id:$ tag from source code

Example 60:
I have added new terminology elements as suggested by comments from Kara.

Overall, I think you have done great work on BP doc. Have a nice holidays,

   Jirka

-- 
------------------------------------------------------------------
  Jirka Kosek      e-mail: jirka@kosek.cz      http://xmlguru.cz
------------------------------------------------------------------
       Professional XML consulting and training services
  DocBook customization, custom XSLT/XSL-FO document processing
------------------------------------------------------------------
 OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
------------------------------------------------------------------

Received on Thursday, 20 December 2007 09:31:32 UTC