Subject: [xml2rfc] Fwd: I-D Action: draft-reschke-xml2rfc-02.txt

From: Julian Reschke <[email-masked]>
Date: Tue, 26 Nov 2013 19:29:29 +0100

(FYI)

-------- Original Message --------
Subject: I-D Action: draft-reschke-xml2rfc-02.txt
Date: Tue, 26 Nov 2013 10:18:16 -0800
From: [email-masked]
Reply-To: [email-masked]
To: [email-masked]

A New Internet-Draft is available from the on-line Internet-Drafts 
directories.

	Title           : The 'XML2RFC' version 2 Vocabulary
	Author(s)       : Julian F. Reschke
	Filename        : draft-reschke-xml2rfc-02.txt
	Pages           : 78
	Date            : 2013-11-26

Abstract:
    This document defines the 'XML2RFC' version 2 vocabulary; an XML-
    based language used for writing Internet-Drafts and RFCs.  This
    vocabulary is used for current processing of XML into RFCs.  A future
    version of this vocabulary will be used as the canonical version of
    RFCs.

Editorial Note (To be removed by RFC Editor)

    Discussion of this draft takes place on the XML2RFC mailing list
    ([email-masked]), which has its home page at
    <https://www.ietf.org/mailman/listinfo/xml2rfc>.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-reschke-xml2rfc

There's also a htmlized version available at:
http://tools.ietf.org/html/draft-reschke-xml2rfc-02

A diff from the previous version is available at:
http://www.ietf.org/rfcdiff?url2=draft-reschke-xml2rfc-02

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org.

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

_______________________________________________
I-D-Announce mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/i-d-announce
Internet-Draft directories: http://www.ietf.org/shadow.html
or ftp://ftp.ietf.org/ietf/1shadow-sites.txt

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 26 Nov 2013 10:55:52 -0800

1.1.  Syntax Notation

   The XML vocabulary here is defined in prose, based on the Relax NG
   schema ([RNC]) contained in Appendix C (specified in Relax NG Compact
   Notation, "RNC").

   Each element description also contains the RNC fragment for that
   specific element in a slightly simplified form (for instance, leaving
   out defaults).  This is included as alternative for readers who
   prefer formal syntax over prose. [[anchor2: This information is
   redundant with the prose *and* repeated in the index; I'd like to
   hear feedback whether it's more useful than distracting.]]

   Note that the schema can be used for automated validity checks, but
   certain constraints are only described in prose (example: the
   conditionally required presence of the "abbrev" attribute).

It is great to have the RNC in the document. Concerning anchor2: the grammar fragments in each section are *mostly* useless because they are redundant with the prose and, worse, sometimes modified by the prose. Proposals:
- remove the fragments from the body of the draft
- add a bit of prose at the end of Appendix C that says which elements have prose-based modifications

--Paul Hoffman

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 26 Nov 2013 10:57:01 -0800

It is not at all clear why some contents are TEXT but others CTEXT, given that they both reduce to "text" in the RNG.

--Paul Hoffman

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 26 Nov 2013 11:02:44 -0800

3.  Special Unicode Code Points

   [[anchor29: Explain those code points where the processors implement
   something special, such as "nbsp".]]

Why is this here for *v2*? The output always has to be ASCII, yes?

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Tue, 26 Nov 2013 20:08:17 +0100

> It is not at all clear why some contents are TEXT but others CTEXT, given that they both reduce to "text" in the RNG.

Yup. I just checked and suspected some weirdness in the conversion from 
the original DTD. Turns out that the conversion faithfully transformed 
what the DTD says:

> <!ENTITY % NUMBER "CDATA">
>
> <!ENTITY % NUMBERS "CDATA">
>
> <!ENTITY % DAY "CDATA">
>
> <!ENTITY % MONTH "CDATA">
>
> <!ENTITY % YEAR "CDATA">
>
> <!ENTITY % URI "CDATA">
>
> <!ENTITY % ATEXT "CDATA">
>
> <!ENTITY % CTEXT "#PCDATA">
>
> <!ENTITY % TEXT "#PCDATA">

I believe it would be best to get rid of all of these definitions.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 26 Nov 2013 20:10:40 +0100

> - remove the fragments from the body of the draft

I'm leaning towards that as well, but wanted first to hear more feedback 
from others...

> - add a bit of prose at the end of Appendix C that says which elements have prose-based modifications

That's non-trivial, so it won't be done with a "bit of prose".

Appendix C essentially is there for people who like formal schemeta; 
isn't it sufficient that all additional constraints are given once in 
the main section?

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 26 Nov 2013 20:13:03 +0100

> Why is this here for *v2*? The output always has to be ASCII, yes?

a) no, the output already uses non-ASCII when it's not plain text, and

b) nbsp is used in practice for keeping things together with respect to 
line breaking (yes, even in plain text generation); there are other code 
points such as nbhy that xml2rfc already knows about.

Best regards, Julian

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 26 Nov 2013 12:22:16 -0800

On Nov 26, 2013, at 11:08 AM, Julian Reschke <[email-masked]> wrote:

> Yup. I just checked and suspected some weirdness in the conversion from the original DTD. Turns out that the conversion faithfully transformed what the DTD says:
> 

+1

--Paul Hoffman

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 26 Nov 2013 12:42:15 -0800

On Nov 26, 2013, at 11:10 AM, Julian Reschke <[email-masked]> wrote:

> I'm leaning towards that as well, but wanted first to hear more feedback from others...
> 

It could be added even if non-trivial.

> Appendix C essentially is there for people who like formal schemeta; isn't it sufficient that all additional constraints are given once in the main section?

I proposed listing the ones with modifications, not listing the modifications. That will help someone reading the schemata know what else they *need* to read.

--Paul Hoffman

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 26 Nov 2013 12:44:11 -0800

On Nov 26, 2013, at 11:13 AM, Julian Reschke <[email-masked]> wrote:

> b) nbsp is used in practice for keeping things together with respect to line breaking (yes, even in plain text generation); there are other code points such as nbhy that xml2rfc already knows about.

This indicates that you are thinking of "processors" other than those that output Internet-Drafts and RFCs. Those should be listed so that there is some scoping for the draft. For example, your XSLT probably doesn't follow all of the rules that the two main processors do.

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Tue, 26 Nov 2013 21:45:46 +0100

> This indicates that you are thinking of "processors" other than those that output Internet-Drafts and RFCs. Those should be listed so that there is some scoping for the draft. For example, your XSL…

No, I'm really talking about the "classic" xml2rfc.tcl (and it's "almost 
ready" successor).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 26 Nov 2013 21:47:44 +0100

> I proposed listing the ones with modifications, not listing the modifications. That will help someone reading the schemata know what else they *need* to read.

They really need to read the main body if the spec anyway. I think if 
you look closely, only a small subset of the elements really is fully 
defined by the schema.

Best regards, Julian

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 26 Nov 2013 12:57:08 -0800

On Nov 26, 2013, at 12:45 PM, Julian Reschke <[email-masked]> wrote:

> No, I'm really talking about the "classic" xml2rfc.tcl (and it's "almost ready" successor).

Then I'm still confused. The nbsp codepoint is not in the ASCII range. Do you mean "entities that are converted to ASCII"?

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Tue, 26 Nov 2013 22:12:04 +0100

> Then I'm still confused. The nbsp codepoint is not in the ASCII range. Do you mean "entities that are converted to ASCII"?

No.

What I'm saying is that there are non-ASCII characters, that, when they 
appear in the source, affect how the result document is formatted -- 
even if *that* is pure ASCII.

The most important example is NBSP. For instance, if your source 
document has

   "foo&nbsp;bar"

then xml2rfc will try to avoid to insert a line break between "foo" and 
"bar".

It's also slightly abused to suggest a good line break position in long 
titles (by nbsp-ing together those parts where no line break should happen).

For instance (taken straight from a published RFC):

   <title abbrev="Charset/Language Encoding in HTTP">Character Set and 
Language Encoding for Hypertext&nbsp;Transfer&nbsp;Protocol&nbsp;(HTTP) 
Header Field Parameters</title>

There's similar support for NBHY; not sure about other code points.

Best regards, Julian

---

From: Tony Hansen <[email-masked]>
Date: Tue, 26 Nov 2013 16:26:38 -0500

On 11/26/13, 2:08 PM, Julian Reschke wrote:
>> It is not at all clear why some contents are TEXT but others CTEXT, 
>> given that they both reduce to "text" in the RNG.
>>
>> --Paul Hoffman
>
> Yup. I just checked and suspected some weirdness in the conversion 
> from the original DTD. Turns out that the conversion faithfully 
> transformed what the DTD says:
>

I believe that these terms are all aliases indicating semantic checks 
that are done by the processor that could not be done by a DTD checker.

So while NUMBER really is a CDATA, it is still constrained further 
beyond CDATA to only contain digits.

Would it be possible to use something other than text in the RNG that 
recognizes their really semantic nature?

     Tony Hansen

---

From: Tony Hansen <[email-masked]>
Date: Tue, 26 Nov 2013 16:31:46 -0500

On 11/26/13, 4:12 PM, Julian Reschke wrote:
> No.
>
> What I'm saying is that there are non-ASCII characters, that, when 
> they appear in the source, affect how the result document is formatted 
> -- even if *that* is pure ASCII.
>
> then xml2rfc will try to avoid to insert a line break between "foo" 
> and "bar".
>
> It's also slightly abused to suggest a good line break position in 
> long titles (by nbsp-ing together those parts where no line break 
> should happen).
>
> Language Encoding for 
> Hypertext&nbsp;Transfer&nbsp;Protocol&nbsp;(HTTP) Header Field 
> Parameters</title>
>

There are a variety of these, including WJ (word join). These are most 
often used by the RFC editor staff.

As Julian says, they *affect* the output, but are not actually output in 
the text or html files.

     Tony Hansen

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 26 Nov 2013 15:32:35 -0800

On Nov 26, 2013, at 1:12 PM, Julian Reschke <[email-masked]> wrote:

> What I'm saying is that there are non-ASCII characters, that, when they appear in the source, affect how the result document is formatted -- even if *that* is pure ASCII.
> 
> The most important example is NBSP. For instance, if your source document has
> 
>  "foo&nbsp;bar"

Maybe I'm being dense, but "&nbsp;" looks like an entity to me. In that example, I suspect that the result would be "foo bar" with an ASCII space between. So what does your "No." mean? That the author can insert a U+00A0 character and it will be interpreted as a non-breaking space? Or...?

> then xml2rfc will try to avoid to insert a line break between "foo" and "bar".

Sure. But for the entity or for that character itself?

> There's similar support for NBHY; not sure about other code points.

It sounds like some listing is important, but it sounds like we need to be more careful in how we describe it.

On Nov 26, 2013, at 1:31 PM, Tony Hansen <[email-masked]> wrote:

> There are a variety of these, including WJ (word join). These are most often used by the RFC editor staff.

Same question as above: do they insert the entity or the character into the XML?

> As Julian says, they *affect* the output, but are not actually output in the text or html files.

That's good to hear.

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Wed, 27 Nov 2013 01:10:55 +0100

> Sure. But for the entity or for that character itself?

It doesn't matter. (If it did, the processor would be broken).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 27 Nov 2013 01:12:07 +0100

On 2013-11-26 22:26, Tony Hansen wrote:
> ...
> ...

It would, but I'd rather avoid that route.

In the end, the scheme may be useful for a few tools, but will never 
capture all constraints.

Best regards, Julian

---

From: Tony Hansen <[email-masked]>
Date: Tue, 26 Nov 2013 21:47:27 -0500

> Same question as above: do they insert the entity or the character into the XML?

I know the current xml2rfc *definitely* accepts the entity specification.
I *think* it accepts the corresponding unicode characters as well.

>> As Julian says, they *affect* the output, but are not actually output in the text or html files.

Tony