Subject: [apps-discuss] Ben Campbell's No Objection on draft-ietf-appsawg-text-markdown-08: (with COMMENT)

From: "Ben Campbell" <[email-masked]>
Date: Wed, 08 Jul 2015 12:50:47 -0700

Ben Campbell has entered the following ballot position for
draft-ietf-appsawg-text-markdown-08: No Objection

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-appsawg-text-markdown/

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

1.2, last paragraph:

Is this document attempting to place normative requirements on existing
markdown implementations? Or should the 2119 keywords in this section be
more statements of fact (and use descriptive language?)

6.1.2, first paragraph, last sentence:
Does this refer to section 6.1.2, or 6.1 and children? If the latter, and
if there is no expert reviewer, who is expected to perform those checks
(automatically or otherwise?)

Editorial:

IDNits reports a few missing or unused references, please check.

There is at least one occurrence of a word inclosed in slashes like /so/.
 I assume that's intended for emphasis--but whether it's for that or some
other reason it would be good to explicitly mention it.

section 1.1, last paragraph: Does "author's intent" refer to the author
of this draft, or of markdown?

Figure 1: The continuation characters and some markup, impinge on the
border.

---

From: Sean Leonard <[email-masked]>
Date: Fri, 10 Jul 2015 20:37:28 -0700

(See below.)

> https://datatracker.ietf.org/doc/draft-ietf-appsawg-text-markdown/

The paragraph includes hortative statements that encourage Markdown system implementations to include certain features. The hortative (encouraging) statements are intended to be normative for implementations in general, but in particular, for future implementations of Markdown systems that process multiple variants, because the point is that the systems interoperate.

Basically it is like saying (when motivated by security): “Server-side implementations SHOULD check the client’s input to avoid buffer overruns when allocating memory.” That would be a normative statement: it is not required (not MUST), but it is encouraged (SHOULD). In this case, the IETF goal is interoperability: the normative text supports this goal.

> IDNits reports a few missing or unused references, please check.

Not sure I saw those; I will look at the IDNits report.

> other reason it would be good to explicitly mention it.

Yes, it is intended for emphasis. It might have been an artifact of xml2rfc before I switched to nroff; not sure. In any event, is it true that published RFCs generally do not include those types of textual markers? If so, they can be removed (when not in quoted text) without significant loss of meaning.

> of this draft, or of markdown?

The “author's intent” refers to the author of the particular Markdown content. (Not the author of the draft, and not the author of Markdown, John Gruber.)

> Figure 1: The continuation characters and some markup, impinge on the

Yes, it was written to go right to the edge.

Sean

---

From: "Ben Campbell" <[email-masked]>
Date: Fri, 10 Jul 2015 23:59:01 -0500

> On Jul 8, 2015, at 12:50 PM, Ben Campbell <[email-masked]> wrote:

[...]
> The paragraph includes hortative statements that encourage Markdown 
> system implementations to include certain features. The hortative 
> (encouraging) statements are intended to be normative for 
> implementations in general, but in particular, for future 
> implementations of Markdown systems that process multiple variants, 
> because the point is that the systems interoperate.
>
> Basically it is like saying (when motivated by security): 
> “Server-side implementations SHOULD check the client’s input to 
> avoid buffer overruns when allocating memory.” That would be a 
> normative statement: it is not required (not MUST), but it is 
> encouraged (SHOULD). In this case, the IETF goal is interoperability: 
> the normative text supports this goal.

I guess the issue is that this draft does not specify markdown itself, 
and I did not get the impression it specified markdown implementations 
in general. Thus it seems like it's trying to put normative requirements 
on things that don't necessarily implement this draft (and implementers 
that may not even read this).

In any case, it's not a show stopper--I just wanted to make sure it was 
intentional.

>> (automatically or otherwise?)

I didn't see a response to this. (But again, I don't see it as a 
showstopper unless IANA does.)

[...]

> Yes, it is intended for emphasis. It might have been an artifact of 
> xml2rfc before I switched to nroff; not sure. In any event, is it true 
> that published RFCs generally do not include those types of textual 
> markers? If so, they can be removed (when not in quoted text) without 
> significant loss of meaning.
>

I don't know that it's forbidden, although the RFC editor may have an 
opinion. If you prefer to keep it, it might be worth a sentence 
mentioning the convention.

> The “author's intent” refers to the author of the particular 
> Markdown content. (Not the author of the draft, and not the author of 
> Markdown, John Gruber.)

Ah, that makes sense. Maybe "content author's intent" would be more 
obvious.

[...]