Re: [cgmo-webcgm] REVIEW: Chapter 2

[Lofton Henderson <lofton@rockynet.com>]

Rob --

Thanks for a great, careful review.  See my responses to a few of your 
comments.

All --

I have started making an editors draft of the next CD text.  Below, I have 
responded to every one of Rob's comments with one of two things:  "Done" (I 
put it into the editors draft); or a comment beginning "[**LH**]".

You should have a look.  E.g., the one about compositing equations.

If you wish to respond to any "[**LH**]", you only need to include the item 
that you are addressing.  (For that matter, you can reply to a "Done." if 
you think it's wrong.)

At 05:40 PM 5/13/2008 -0600, Robert Orosz wrote:
>First, I used WinMerge (a visual diff tool) to compare the XHTML file with
>the 2.0 version. I saw no evidence for unintended changes or that an earlier
>2.0 version of the file was used as the starting point for the 2.1 work. In
>fact, there were a few editorial improvements. I did find some
>(intentionally) added paragraphs that aren't mentioned in the Change Log in
>Appendix D. I'll mention those paragraphs specifically when I get to the
>section they are in.
>
>The entire chapter is informative. I assume that makes my comments editorial
>by definition.

Yes, formally.  But things like the compositing equations are "important 
informative".


>2.1
>No changes.
>
>
>2.2
>
>2.2.1
>Change CCITT to ITU-T.

Done.


>Group 4 should be capitalized, i.e. "Group 4", not "group 4".

Done.


>The last sentence doesn't seem to belong in the same paragraph as the
>previous sentences. The paragraph abruptly jumps from discussing raster
>content to scaling WebCGM pictures in Web documents. I checked WebCGM 1.0,
>and these were separate paragraphs.

Done (separated).


>2.2.2
>I'm not sure if the alpha blending equations are correct. In the equations
>that calculate Cr', Cg', and Cb', Pa is used but Ca is not used. That
>doesn't seem quite right to me, however, I don't have time right now to look
>into this further.

[**LH**] I don't think there is a problem.  But if you can come up with a 
specific error and fix -- PLEASE DO -- these equations are formally 
informative, but probably have the impact of being normative.


>In the last paragraph, change "canvas are created." to "canvas is created."

Done.


>2.2.3
>No changes, but note that the last paragraph discusses the background param
>element within the HTML object element. There is a proposal to deprecate
>that element.
>
>http://lists.oasis-open.org/archives/cgmo-webcgm/200802/msg00082.html

Once we agree, then we can drop the paragraph.  (I don't see any problem 
with deprecating 'background', but we ought to formally close the issue -- 
it's on the telecon Agenda.)



>2.3
>
>2.3.1
>The first sentence of the last paragraph mentions "XML fragment" in Chapter
>3 in connection with the normative content model for version 4 elements. The
>only normative specification of content in Chapter 3 uses EBNF notation. So,
>the sentence should read something like this:
>
>Chapter 3 normatively defines the detailed content model for version 4
>elements in WebCGM using EBNF notation.

Done.

[**LH**] ...and I added "using XML DTD notation" to the end of the second 
sentence.


>2.3.2
>I don't like the start of the second to last paragraph. How about this
>instead?
>
>Note that 'grnode' was not present in WebCGM 1.0, but was added to WebCGM
>2.0 to allow for better hierarchical structure in WebCGM documents.

Done.

[**LH**]  And I changed the second sentence to:  "The 'grnode' ("graphical 
node") APS allows illustration authoring tools to preserve in the WebCGM 
metafile instance the graphical groupings that are often used by such tools."


>2.3.3
>No changes.
>
>2.3.4
>In the name list item, replace "object" with "an object."
>
>In the visibility list item, delete "potentially."

Done (both).


>2.3.5
>In the second sentence, replace "intelligence" with "intelligent."

Done.


>In the Figure 2 captions, I would prefer to see all of the type names lower
>case. For example,
>
>Figure 2a. WebCGM File Structure - PICBODY
>Figure 2b. WebCGM File Structure - LAYER
>
>The reason is twofold, 1) the APS type names, grobject, para, etc. are
>case-sensitive as far as I know, and 2) in the actual PNG graphic the names
>are all lower case.

Done.


>2.3.6
>The last anchor in the third paragraph targets 3.1.1.4. Shouldn't it go to
>3.1.1 instead? In other words, target the entire "IRI fragment
>specification" instead of a specific subsection of it.

Done (for now).

[**LH**]  The original intent (in 1.0) may have been to link specifically, 
from sentence talking about linkuri, to this subsection that describes 
URI/IRI representation within the fragment?  Do you think that's useful, or 
is 3.1.1 the better target?


>The term "base-URL" is used once in the seventh paragraph and twice in the
>10th paragraph. I think all three occurrences should be replaced with
>"base-IRI" in order to be consistent with the rest of the document.

Done.

[**LH**]  When I did the conversion, URL-to-IRI, I considered every 
instance.  For example in 3.1.1.4, some URL occurrences should remain.  I 
can't think why I might have exempted "base-URL" here.



>2.4
>In the second paragraph, replace the two occurrences of "CGM" with "WebCGM".

Done.



>2.5
>
>2.5.1
>In the raster list item, change "CCITT" to "ITU-T."

Done.


>The placement of the polysymbol list item implies that it was never allowed
>in WebCGM, when in fact it was allowed in WebCGM 1.0 and removed in WebCGM
>2.0. Maybe this should be broken out into a third category, "Allowed in
>WebCGM 1.0, but now excluded from WebCGM."

[**LH**]  Rather than category-of-one, I did this:

a.) changed the list introducer from "still excluded from WebCGM" to 
"excluded from the present version of WebCGM"
b.) reworded the Polysymbol bullet:  "Polysymbol - the Polysymbol element 
allows the sizing and placement into CGM pictures of "symbols". Symbols are 
defined in an external Symbol Library, which itself is a CGM. (Polysymbol 
was in WebCGM 1.0, but removed due to non-use.)"


>2.5.2
>In the fourth list item, the two anchor elements target
>"http://www.w3.org/TR/charmod/"; directly. This runs counter to most of the
>rest of the references which add an extra level of indirection, i.e. they
>target the appropriate anchor in section 1.2 or 1.3 instead.

[**LH**]  Reason:  the first anchor targets a specific section, 
".../#sec-Digital .  The second one *could* reference indirectly via an 
entry in 1.2 or 1.3, and this is the typical W3C "Style Rule".  But then 
the question comes up:  normative (1.2) or informative (1.3).  I would say 
informative.  But in W3C I can hear the question, "why is CHARMOD 
informative instead of normative?"  (Answer:  legacy terminology, CHARMOD 
is just presented for equivalent contemporary terminology, see T.16.14 in 
section 6.5)

For now, I just put a highlighted editors note in-line.


>In the fourth list item, change "... attribute actually give control ..." to
>"... attribute actually gives control ...".

Done.


>The last two paragraphs are new paragraphs, and their addition is not noted
>in the Change log in Appendix D. I'm not sure how accurate the Change Log is
>supposed to be.

[**LH**]  General rule of thumb:  it should reference specific changes 
which would change an implementation, or which have normative impact, or 
which are a major contribution of explanatory text.

This might have qualified, but I didn't do the editing that added the 2 
pgphs.  I did put the placeholder Ch.9 entry in there.  I just now updated 
the old change log entry to mention it.


>In the second to last paragraph, second occurrence of the word "definition"
>is misspelled "defintion".

Done.


>In the last paragraph, the word "found" is misspelled "fouund".

Done.


>2.5.3
>No changes.
>
>2.5.4
>Here again, the first two anchor elements target
>"http://www.w3.org/TR/charmod/"; directly. As I mentioned previously in
>2.5.2, the general style used throughout the document for references seems
>to be targeting the appropriate anchor in section 1.2 or 1.3.

[**LH**]  I'll tag it for further consideration.


>The last two paragraphs are new paragraphs that are not mentioned in the
>Change log. Again, I'm not sure if this is important or not, but I thought
>I'd mention it.

[**LH**] Same comment.  Marginal case.  But I did update the old change log 
entry for Ch.9.



>2.6
>No changes.
>
>
>2.7
>
>2.7.2
>The first two anchor elements directly target "http://www.w3.org/";.

[**LH**]  I think that's okay, since it is not a spec reference.


>The last paragraph has two anchor elements with href attributes that target
>non-existent anchors. I think the values of the href attributes were meant
>to be "webcgm21-Intro.html#webcgm-20-rqts" and
>"webcgm21-Intro.html#webcgm-21-rqts" respectively.

Done.

THANKS!!!

-Lofton.