Bjoern Hoehrmann | 2 Dec 14:08 2004
Picon
Picon

Re: Second Edition or (Second Edition)


* Martin Duerst wrote:
>I just had a look at some second/third editions. There seems some
>variation in how this information is integrated into the title.
>In particular, I found:
>	Extensible Markup Language (XML) 1.0 (Third Edition)
>but
>	XML Schema Part 2: Datatypes Second Edition
>
>I think that the former (with parentheses) is much clearer, and
>would recommend to use that form in the future.

I agree, I think this should be a requirement in the Pubrules document,
the upcoming revision of section 7 would be a perfect opportunity to do
that (it needs revision as both document you cite do not comply with the
requirement that "If a technical report with changes that affect
conformance to previous Recommendation but no new features, then there
MUST be a change to the minor revision number (e.g., "Version 1.1")").

>P.S.: This brings up another point. In both of the above cases,
>       only the latest date is noted, e.g.
>		W3C Recommendation 28 October 2004
>       for the later. I think it would be much better to use
>       the same wording in the actual document as on the TR
>       page (in this case:
>		First published 2 May 2001, revised 28 October 2004). 

I disagree here, it is adding noise that would only be useful to few
readers which can already find this information quite easily. It would
certainly look ugly (either overlong heading lines or changes in the
(Continue reading)

Bjoern Hoehrmann | 2 Dec 14:31 2004
Picon
Picon

Improper XHTML syntax when using text/html


Dear Editors,

  An unfortunate side-effect of using XML tools to generate Technical
Reports in the XHTML format is that most tools are not suited for this
task when it is desired that the document is delivered using the text/
html MIME Type, it is for example common that empty a elements like

  <a name="foo" id="bar"></a>

are generated using the empty-element syntax, i.e.

  <a name="foo" id="bar" />

which is not well-supported among text/html processors, it is for
example common that 

  <a name="foo" id="bar" /><span>...</span>

is considered to be

  <a name="foo" id="bar"><span>...</span></a>

which might not affect the visual representation of the document but
causes problems for a11y tools that attempt to post-process the DOM
generated for the document. This is one of the reasons why the XHTML
Recommendation advises against using such syntax. Recent documents
that are affected by such problems would be

  http://www.w3.org/TR/2004/PR-charmod-20041122/
(Continue reading)

Roy T. Fielding | 6 Dec 22:24 2004

Square-bracket output of Definition in specs is bogus


The output chosen for definitions in W3C specs is easily the worst 
example
of spec language abuse that I have ever seen.  Definitions are supposed 
to
highlighted to the reader, not placed in obscurity through the addition 
of
[Definition: ...].  Mark-up should never obscure CONTENT.

Under normal English, anything inside square brackets can be removed.
In technical specifications, anything inside parentheses or square 
brackets
is non-normative or indicative of an editorial addition in order to
clarify a quote taken from some other source.  Obviously, neither is
the case for definitions.

I suggest that the W3C ask a literature department (like Harvard or 
Chicago)
what they think such a style document says to a typical reader, and 
perhaps
suggest a more useful signage for definitions that actually calls them 
out
in a normative way that doesn't cause experienced technical writers to 
go
into fits of perplexity.  For example, here is the style for IEEE specs:

   http://standards.ieee.org/guides/style/section4.html#527

Cheers,

(Continue reading)

François Yergeau | 7 Dec 02:38 2004

Re: Square-bracket output of Definition in specs is bogus


Roy T. Fielding a écrit :
> The output chosen for definitions in W3C specs is easily the worst example
> of spec language abuse that I have ever seen.  Definitions are supposed to
> highlighted to the reader, not placed in obscurity through the addition of
> [Definition: ...].  Mark-up should never obscure CONTENT.

+1

--

-- 
François Yergeau

Karl Dubost | 7 Dec 22:12 2004
Picon

Re: Square-bracket output of Definition in specs is bogus


Le 06 déc. 2004, à 16:24, Roy T. Fielding a écrit :
> I suggest that the W3C ask a literature department (like Harvard or 
> Chicago)
> what they think such a style document says to a typical reader, and 
> perhaps
> suggest a more useful signage for definitions that actually calls them 
> out
> in a normative way that doesn't cause experienced technical writers to 
> go
> into fits of perplexity.  For example, here is the style for IEEE 
> specs:

That's a good suggestion.

They are a few details to clarify.

* What is a definition?
	We define a lot of things in a specification and one would consider 
that everything which is normative is a definition. Another one would 
say that it's only testable assertions which are true definitions. And 
I believe for most of the editors and WGs now is to define terms which 
might belong to a glossary. And I assume it's what we intend here.

* The XMLSpec markup to create definition.

For example from:
http://www.w3.org/TR/2004/REC-xml-20040204/REC-xml-20040204.xml
http://www.w3.org/TR/2004/REC-xml-20040204/Overview.html

(Continue reading)

Karl Dubost | 8 Dec 18:06 2004
Picon

Status of XMLSpec and related materials


Hi,

I would like to know what is the status of XMLSpec materials. I have 
seen on the page the XML Spec Schema and stylesheets [1] page that the 
last version of the material is numbered 2.8 on Feb 2004 [2]

I see also that it seems Norman Walsh is in charge of this document. I 
was wondering if the development too?

It seems there's no recent tutorial for XMLSPec [3] and there's no 
"fake" document as a test suite to show the input markup and the output 
markup.

My questions/comments:
	- I am inclined to help on the XHTML output of XMLSpec (I'm not a 
top-gun XSLT creator but I have notions and at least for XHTML markup 
semantics I have very good knowledge)
	- I proposed to rewrite the tutorial if it seems necessary or at least 
to update it.
	- I proposed to create a fake document covering all cases of XMLSpec, 
and that will constitute a kind of test suite for the style sheet.

Does it seem reasonable or am I putting my feet in the plate of someone 
else?

[1] http://www.w3.org/2002/xmlspec/
[2] http://www.w3.org/2002/xmlspec/#spec28
[3] http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm

(Continue reading)

Bjoern Hoehrmann | 8 Dec 19:07 2004
Picon
Picon

Re: Square-bracket output of Definition in specs is bogus


* Roy T. Fielding wrote:
>The output chosen for definitions in W3C specs is easily the worst 
>example
>of spec language abuse that I have ever seen.  Definitions are supposed 
>to
>highlighted to the reader, not placed in obscurity through the addition 
>of
>[Definition: ...].  Mark-up should never obscure CONTENT.

The "Definition:" clearly highlights the definition and the square
brackets clearly delimit the definition from other text in the same
paragraph. This style is widely used in W3C Technical Reports and
well-understood by the target audience; you are the first one who
complains about it as far as I can tell; I do not agree that the
style is "obscure" in a meaningful way. If there are going to be
such changes, the new style should be much more usable than the old
style. You have unfortunately not proposed a style that would.
--

-- 
Björn Höhrmann · mailto:bjoern <at> hoehrmann.de · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: +49(0)621/4309674 · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/ 

Roy T. Fielding | 9 Dec 00:06 2004

Re: Square-bracket output of Definition in specs is bogus


On Dec 8, 2004, at 10:07 AM, Bjoern Hoehrmann wrote:
>> [Definition: ...].  Mark-up should never obscure CONTENT.
>
> The "Definition:" clearly highlights the definition and the square
> brackets clearly delimit the definition from other text in the same
> paragraph.

So does any other mark-up, such as boxes or glossaries or sections
(as in the IEEE example I sent), but the others leave the in-line text
as-is (making just the term bold) so that they do not interfere with
the text surrounding the definition -- the definitions are then 
collected
and repeated automatically in a box, glossary, or Definitions section.

If you don't trust my opinion, then take it to any English writing group
and ask them what the current style means.  I say it means the contents
are editorial and can be skipped.

> This style is widely used in W3C Technical Reports and
> well-understood by the target audience; you are the first one who
> complains about it as far as I can tell; I do not agree that the
> style is "obscure" in a meaningful way. If there are going to be
> such changes, the new style should be much more usable than the old
> style. You have unfortunately not proposed a style that would.

Any style commonly used in technical writing would be better. I gave
you an example from the IEEE standards.  And, no, it is neither 
understood
nor appreciated by the target audience -- why don't you ask them?
(Continue reading)

Tim Bray | 9 Dec 00:20 2004

Re: Square-bracket output of Definition in specs is bogus


On Dec 8, 2004, at 3:06 PM, Roy T. Fielding wrote:

> So does any other mark-up, such as boxes or glossaries or sections
> (as in the IEEE example I sent), but the others leave the in-line text
> as-is (making just the term bold) so that they do not interfere with
> the text surrounding the definition -- the definitions are then 
> collected
> and repeated automatically in a box, glossary, or Definitions section.

Speaking as the <blush> inventor of the current typographical usage, I 
think Roy's right. -Tim

Bjoern Hoehrmann | 9 Dec 00:35 2004
Picon
Picon

Re: Square-bracket output of Definition in specs is bogus


* Roy T. Fielding wrote:
>Any style commonly used in technical writing would be better. I gave
>you an example from the IEEE standards.  And, no, it is neither 
>understood nor appreciated by the target audience -- why don't you
>ask them?

I am afraid I would not find anyone who would claim that the XML 1.0
Recommendation does not define what a "well-formed XML document" is,
which is however a consequence of not understanding that [Definition:]
is a normative part of the document. So it seems you are overstating
the problem. I agree that this style is not perfect, but it does not
actually hinder anyone accessing the technical content.

>I did and only one of the ten people I asked said it was better than
>no highlighting at all.  The only reason they go along with it is 
>because they want to be consistent with W3C spec production.

How many of these people were people who just do some programming in
their spare time or hobbyists who do some web page authoring in their
spare time? It would seem you've only asked people editing W3C specs,
that's not a very representative group for the target audience for
most W3C Technical Reports and proper markup and style is much more
important to people who are not experienced readers of technical
writings.

Maybe you could modify a sample specification (e.g. by modifying the
XMLSpec transformation to generate the desired markup) with the best
alternate markup and style you can come up with? I think this would
greatly ease reviewing your change proposal. It would be a pity if
(Continue reading)


Gmane