Subject: [apps-discuss] Comments on draft-ietf-appsawg-text-markdown-04

From: Graham Klyne <[email-masked]>
Date: Fri, 19 Dec 2014 18:41:52 +0000

Sean,
All,

[These are comments I sent initially to Sean, but not in time for the I-D 
publication, so I'm re-posting here]

1. I think you should update the example before publication - as it stands I 
think it's confusing (see later).

2. I think section 3 should be renamed and a TODO-style comment added -- see 
below ... or actually deleted.

More detailed comments follow.

...

Sect 1.2: "The paradigmatic use case for text/markdown..." doesn't make sense to 
me.  I'm not sure what you mean by "paradigmatic" here.

Sect 2, 'charset' parameter.  I think some of the commentary (after the first 
sentence) here belongs under "encoding considerations"

Sect 2: Optional parameters.  I think the balance here is about right.  I have 
niggle about possible clashes between "other parameters" and other media-type 
defined parameters (e.g. 'charset') - but I suspect it's a non-problem and I'd 
wait to see what other feedback you get before worrying too much about that.

Sect 2: security considerations: mentions an "output-type" parameter that I 
don't see described.  I think we agreed to drop this as it wasn't really part of 
the markdown content format.  I think the rest of the commentary is still 
relevant: suggest drop the first sentence: "Security provides a significant 
motivator for the output-type parameter."

Sect 2: Interoperability considerations: mentions "syntax" parameter.  Shouldn't 
this now be "variant"?  Maybe also "associated with" rather than "identifier in"?

Sect 3: clearly still work to do here (or drop the section) - but that's OK for 
a draft.

Suggest adding a TODO-style note saying that output type is not part of the 
input format, and may be indicated by some other MIME header in a vein similar 
to content-disposition.  And change the section title.

...

Section 4.1, 4.2:

I think the discussion here is useful, but I'm not sure if it really belongs, 
especially with normative content.

There's a real danger here of getting in to too much detail.  The easy choice is 
to not introduce named parameters in fragments, and just leave it to the 
markdown variant.  But that's somewhat at odds with the web principle that a 
MIME type indicates for the fragment identifier should be interpreted.  In this 
case, I'm, not sure how best to square these.  I'd probably be OK with a general 
overarching syntax for fragments, with all details of interpretation left to the 
Markdown variant used (but being aware that the fate of a lot of Markdown is to 
be rendered as HTML.).

What follow are some more detailed thoughts which should be treated as 
subservient to this high-order consideration.  If the fragment issue becomes 
contentious, I'd suggest being prepared to simply drop it from the specification 
(at least in this incarnation).

...

Section 4.1:

"When encoded in a URI, the production..."  I'm not sure what you mean by 
"production" here, and the term is likely to be confused with the syntax 
production mentioned subsequently. Maybe just say "the fragment identifier 
SHALL..." here?  (Does this need saying at all?  It's already a requirement of 
RFC3986, but I'm OK if you think the emphasis is useful)

I'm wary of "The character set for percent-encoded octets SHALL be the same as 
the Markdown content, i.e., identified by the charset parameter or by other 
contextual means."  I'm not even sure that it always makes sense.  The current 
tendency is to %-encode URIs via UTF-8 encoding of the underlying characters. In 
this case, I think it's sufficient that interpretation of the fragment 
identifier is dependent on the Markdown variant used, which I think is pretty 
much what you already say.

(Example: consider a variant that is presented to a converter as, say 
"Windows-1252", but which is emitted by a converter as UTF-8-encoded HTML.  You 
have already emphasized Markdown as consisting of characters not codepoints, so 
having a URI fragment that is expressed with respect to code points in the 
source seems odd to me.)

...

Sections 4.1, 4.2:

I think the relationship between these sections is potentially confusing, and 
could use some work.

I'd be inclined to start with a general reference to fragment identifiers 
containing named parameters (which, BTW, conflicts with what you say about 
character encoding, as the encoding of the '=' must be independent of the 
content encoding -- I know it's contrived, but suppose the Markdown is 
EBCDIC-encoded).

Having introduced the general fragment syntax, you can go on to say that its 
interpretation is dependent on the markdown variant or processor used.

I'm uneasy about the choice of "&" as a parameter separator, as it would 
introduce escaping complications if one just wants to copy the fragment into an 
XML/HTML-based format (which I suggest may be a common scenario).  I'd be 
inclined to use ';' as proposed in 
http://w3ctag.github.io/packaging-on-the-web/#fragment-identifiers (you could 
also exploit the syntax described there).  (I note that 
http://tools.ietf.org/html/rfc5147 doesn't allow multiple parameters.)

If you introduce this style of fragment identifier, I think something like "id=" 
could be defined to refer to whatever maps to HTML id= values in the variant used.

I not sure about including line= from the RFC5147 spec, as I think it has the 
same problems as a character-based specification.

...

Section 5:

Your example includes parameters not described in the text.  I think this is 
confusing and unhelpful.  Update to be in line with text.

...

Section 6:

I'm not sure that an expiration date serves any useful purpose, and potentially 
adds administrative overhead.  [Later] I see what you're doing.  A problem here 
is that it's not clear how a provisional registration becomes permanent.  I 
think it would be simpler to just avoid provisional registration, but provide an 
"escape hatch" to allow registrations to be revoked by (e.g.) the IESG

I'd be interested to know why you want to include "~" in the registered 
identifiers.  My inclination would be to keep the variant names very restricted 
(e.g. letters, digits, "_" only) to maximize compatibility with other systems, 
OR to impose very few restrictions; i.e. exclude just those characters needed 
for other syntactic purposes similar to the way URI syntax is defined.

I think the character set for the other fields should be checked with IANA if 
they are to maintain the registry.  Usually, in my experience, as registration 
templates often appear in RFCs, just ASCII characters are used.

...

That's all!

#g
--

On 17/12/2014 00:32, Sean Leonard wrote:
> Hello Reviewers:
>
> I worked on draft-ietf-appsawg-text-markdown-04.
>
> This is a prelim notice before I post it to the IETF Internet-Drafts repository for public comment (probably will happen late tonight or sometime tomorrow). Let me know if you see any glaring problems.
>
> I tried to stick mostly with what has been discussed publicly. I also took another crack at fragment identifiers but otherwise tried to remain conservative.
>
> Thanks,
>
> Sean
>

---

From: Sean Leonard <[email-masked]>
Date: Sun, 21 Dec 2014 00:47:01 -0800

Hello—

(Only commenting on things that I did not change in the upcoming draft-05; all other things were accepted or mostly accepted.)

On Dec 19, 2014, at 10:41 AM, Graham Klyne <[email-masked]> wrote:

> 
> Sect 1.2: "The paradigmatic use case for text/markdown..." doesn't make sense to me.  I'm not sure what you mean by "paradigmatic" here.

I mean the model or pattern that is being followed, especially the conceptual framework from which basic assumptions, ways of thinking, and methodology can be gleaned. (Which is the definition of paradigm/paradigmatic.)

> 
> Sect 2, 'charset' parameter.  I think some of the commentary (after the first sentence) here belongs under "encoding considerations”

I changed “encoding” to “character set” to clarify, but kept it in the charset parameter.

“Character set” technically refers to an abstract set of characters; a character encoding is the mapping between abstract characters and bits on the wire. Unicode is (among other things) a character set; UTF-8, UTF-16LE, and UTF-16BE are some of several encodings to encode characters in that character set. (It is possible to have a single encoding usable with multiple character sets, although it’s a bit confusing and usually is not what one wants.) Unfortunately the “charset” parameter conflates the two terms; maybe it should have been called “charsetandencoding” or some such.

Usually in media type registrations, the “Encoding Considerations” just says something generic like “text” or “binary”. I suppose it could say something like “gzip works best” or “you will get better results with quoted-printable than base64 in most cases”, but I have never seen character encoding issues discussed in that section.

> Section 4.1, 4.2:

(As discussed in my response to Michel Fortin, I pared this section down.)

> I'm wary of "The character set for percent-encoded octets SHALL be the same as the Markdown content, i.e., identified by the charset parameter or by other contextual means."  I'm not even sure that it always makes sense.  The current tendency is to %-encode URIs via UTF-8 encoding of the underlying characters. In this case, I think it's sufficient that interpretation of the fragment identifier is dependent on the Markdown variant used, which I think is pretty much what you already say.
> 
> (Example: consider a variant that is presented to a converter as, say "Windows-1252", but which is emitted by a converter as UTF-8-encoded HTML.  You have already emphasized Markdown as consisting of characters not codepoints, so having a URI fragment that is expressed with respect to code points in the source seems odd to me.)

(Take a look at draft-05; I suspect we will revisit this issue.)

The key thing here is that the input is marked as Windows-1252, so without needing to invoke any particular Markdown processor, the MIME parser can use the input information to understand the fragment. The fragment is “addressed” to the text/markdown content, not the text/html content or any other such thing that might have gone through a Markdown processor.

In draft-03, I proposed #o#blahblah (output) and #i#blahblah (input), which were seen as too complicated (and wrong since # can’t be used—I suppose it should have been = instead). This simplified formulation only looks at input content, and drops the #i# (or #i= ) prefix.

> 
> ...
> 
> Sections 4.1, 4.2:
> 
> I think the relationship between these sections is potentially confusing, and could use some work.
> 
> I'd be inclined to start with a general reference to fragment identifiers containing named parameters

I did—application/pdf [RFC3778]. :) application/pdf uses & as a parameter separator.

> (which, BTW, conflicts with what you say about character encoding, as the encoding of the '=' must be independent of the content encoding -- I know it's contrived, but suppose the Markdown is EBCDIC-encoded).

It’s a little complicated…RFC 3986 actually says that US-ASCII codes are to be used for the US-ASCII range. If anything, the conflict is a broader problem with URIs than with this particular proposal. Anyway, we could go into this in detail for cases where the character set/encoding is not strictly aligned with US-ASCII in 00h-7Fh, but for the text/markdown spec I just tried to say that = and %?? (representing = ) have distinct reserved and unreserved meanings—the precise value for %?? is not this spec’s job to say. (It’s RFC 3986’s job.)

> If you introduce this style of fragment identifier, I think something like "id=" could be defined to refer to whatever maps to HTML id= values in the variant used.

As discussed above, that was the original idea behind things like #o#blahblah, #l#blahblah, and #ldef#blahblah in draft-03. Compared to that syntax, I think it makes more sense to align Markdown-to-HTML anchors with the same syntax that text/html itself uses…which is no prefix.

Overall draft-04 and forthcoming -05 exploit the property that certain characters have different meanings when percent-encoded, which I think is perfectly reasonable (and nifty).

> 
> 
> I think the character set for the other fields should be checked with IANA if they are to maintain the registry.  Usually, in my experience, as registration templates often appear in RFCs, just ASCII characters are used.

I checked. RFC 5226 Section 4.2:
   Documents that create a new namespace (or modify the definition of an
   existing space) and that expect IANA to play a role in maintaining
   that space (e.g., serving as a repository for registered values) MUST
   provide clear instructions on details of the namespace.  In
   particular, instructions MUST include:

…
      4) The size, format, and syntax of registry entries.  When
         creating a new name/number space, authors must describe any
         technical requirements on registry (and sub-registry) values
         (e.g., valid ranges for integers, length limitations on
         strings, etc.) as well as the exact format in which registry
         values should be displayed.  For number assignments, one should
         specify whether values are to be recorded in decimal,
         hexadecimal, or some other format.  For strings, the encoding
         format should be specified (e.g., ASCII, UTF8, etc.).  Authors
         should also clearly specify what fields to record in the
         registry.

So, that’s that…UTF-8 is okay.

Sean