The text/markdown Media Type
draft-ietf-appsawg-text-markdown-12

[Ballot comment]

- 1.1: Who says that there's only a 1-dimensional continuum:-)
And what's on the other end? You don't say.

- The 2119 terms in the para after Figure 1 are bogus, except
for the last SHOULD (on p5).

[Ballot comment]

- 1.1: Who says that there's only a 1-dimensional continuum:-)
And what's on the other end? You don't say.

- The 2119 terms in the para after Figure 1 are bogus, except
for the last SHOULD (on p5).

- Please respond to the secdir review [1] which raised a couple
of questions that deserve answers. (Apologies if I missed your
answer to that.)

  [1] https://www.ietf.org/mail-archive/web/secdir/current/msg05830.html

[Ballot comment]
I'm not making this a DISCUSS because I think I've raised a similar issue before (with this same AD and doc shepherd, no less, I think) and lost the argument, but I don't get why this document is informational. It specifies a parameter syntax for fragment identifiers. If one implementation follows the syntax specified here and another implementation uses some other syntax defined somewhere else, how is this spec helping the two implementations interoperate?

[Ballot discuss]
This is a small issue but there's something wrong with the references. Noted in Suresh Krishnan's Gen-ART review. Please look at this, so that we are not missing something important:

- RFC 2046 and 2183 are referenced in the text but not defined as
references. Please add them as either normative or informative references.

- RFC5322 is never referenced in the text. Is some intended text missing?

[Ballot 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.

[Ballot comment]
1.  From Nevil's OPS DIR feedback:
> 2. The markdown Example (Section 5) is helpful, but it doesn't seem
>  to have an obvious end marker - it just runs on into section 6.
>  Does markdown have something like an end-of-file marker you could
>  use to make that obvious?
And answered by Alexey:
>
> Not really, it is a textual format with no special end marker.
>
> I suppose the whole example can be surrounded by some markers and a note added that they are not a part of the example?

could we use the and ?

2. "A companion document [MDMTUSES] provides additional Markdown background and philosophy."

There is more than that. See the draft-ietf-appsawg-text-markdown-use-cases abstract: "Background information, local storage strategies, and additional syntax registrations are supplied"

3. Editorial
OLD: [fOo]
NEW: [foo]

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

IANA has reviewed draft-ietf-appsawg-text-markdown-07.  Authors should review the comments and/or questions below.  Please report any inaccuracies and respond to any questions as soon as possible.

IANA has questions about the actions requested in the IANA Considerations section of this document.

We received the following comments/questions from the IANA's reviewer:

IANA understands that, upon approval of this document, there are three actions which IANA must complete.

First, in the Media Types registry located at:

http://www.iana.org/assignments/media-types/

a new Media Type in the text subregistry will be created as follows:

Name: markdown
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

Second, in the Content Disposition Parameters subregistry of the Content Disposition Values and Parameters registry located at:

http://www.iana.org/assignments/cont-disp/

a new disposition parameter will be registered as follows:

Name: preview-type
Description: [ See-Question ]
Reference: [ RFC-to-be ]

QUESTION --> What description should be used for this new Content Disposition Parameter?

Third, a new registry is to be created called the Markdown Variants registry. The new registry will be maintained on a First Come, First Served basis as defined in RFC 5226. IANA notes that the authors request that IANA should confirm the authenticity of the senders of requests for this registry.

QUESTION -> Where should this new registry be located? Is it a néw registry on the IANA Matrix or is it a subregistry of an existing registry? If it is a subregistry of an existing registry, in which registry will it be contained?

IANA understands that the registry contains the following fields: Identifier, Name, Description, Additional Parameters, Fragment Identifiers, References, Contact Information, Expiration Date.

Three variants are to be marked as reserved in the new registry.

QUESTION -> Section 6.1.1 of the current draft provides the three variants to be reserved but none of the other fields to be displayed in the registry. What are the Name, Description, Additional Parameters, Fragment Identifiers, References, Contact Information, and Expiration Date to be used for each of the three reserved variants?

The new registry contains a single, initial registration as follows:

Identifier: Original
Name: Markdown
Description: Gruber's original Markdown syntax
Additional Parameters:
Fragment Identifiers:
References: ,
Contact Information: (individual) John Gruber 
Expiration Date:

IANA understands these three actions as the only ones that need completion upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is only to confirm what actions will be performed.

The following Last Call announcement was sent out:

From: The IESG
To: IETF-Announce
CC:
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (The text/markdown Media Type) to Informational RFC


The IESG has received a request from the Applications Area Working Group
WG (appsawg) to consider the following document:
- 'The text/markdown Media Type'
  as Informational RFC

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2015-07-02. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract
  This document registers the text/markdown media type for use with
  Markdown, a family of plain text formatting syntaxes that optionally
  can be converted to formal markup languages such as HTML.

The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-appsawg-text-markdown/

Once IESG discussion begins, it can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-appsawg-text-markdown/ballot/

No IPR declarations have been submitted directly on this I-D.

The IANA Considerations section has the following change already noted:

OLD
  All references (including contact information) MUST be verified as
  functional at the time of the registration.

  If a registration is being updated, the contact information MUST
  either match the prior registration and be verified, or the prior
  registrant MUST confirm that the updating registrant has authority to
  update the registration. IANA is to send an email to each old and new
  address confirming the change request. The emails are to contain a
  nonce (which may be embedded in a URI) that, when return by email or
  another mechanism (e.g., HTTP), serve to verify the request. An
  affirmative response from any of the addresses (old or new) is
  sufficient. If neither the old nor the new registrations contain any
  email addresses, then the update MAY succeed without email
  confirmation. Therefore, registrants are encouraged to list at least
  one email address for registration protection.

  As a special "escape valve", registrations can be updated with IETF
  Review [RFC5226]. All fields may be updated except the variant
  identifier, which is permanent: not even case may be changed.

NEW
  All references (including contact information) are expected to be
  valid at the time of the registration.

  All fields may be updated except the variant
  identifier, which is permanent: not even case may be changed.

END

1. Summary

Murray Kucherawy is the document shepherd.
Barry Leiba is the responsible Area Director.

This document registers the text/markdown media type for use with
Markdown, a family of plain text formatting syntaxes that optionally
can be converted to formal markup languages such as HTML.

The working group has selected Informational status since the markdown
syntax was specified outside of the IETF, and RFC6838 does not require
Standards Track status for a document from the IETF stream registering
a media type.

2. Review and Consensus

The document had fairly active review within APPSAWG at first, but
suffered from some attrition along the way.  Feedback ranged from
"Why does the IETF need to do this?" to whether the entire work
(this plus the use-cases document) should appear in a single document
or in separate documents.  For the latter question, the split was done;
for the former, there are still one or two participants who are unclear
whether this media type or the registries created here will ever be used
by someone other than the author.

Still, there was enough critical mass to get it through a Call For Adoption
and enough reviewers, including both the usual suspects and some outside
participants, that the chairs chose to proceed.

The document evolved over time, being whittled down quite a bit from the
earliest proposals.  The version being sent to the IESG appears to be
minimalist, which is what the WG wanted.

The author and chairs were implored to be sensitive to the markdown community,
which is external to the IETF.  I'm satisfied that this was done as much
as practical.

No particular directorate review is critical here, though the usual ones
should still be done.  The media type reviewer is aware of the work and
has not voiced any objection to the working group, though no specific
request was made for early review either.

The author asserts that he and others have already begun to use the
media type in prototype form within open source and commercial products.

3. Intellectual Property

The author has confirmed that he knows of no outstanding IPR claims, and
thus submits the draft in full compliance with BCPs 78 and 79.

4. Other Points

There are three references to non-IETF URLs in the Normative References.
There is also a normative reference to RFC3778, which is Informational, and
not currently in the DOWNREF Registry.

The IANA Considerations section was checked and needs the following change:

OLD
  All references (including contact information) MUST be verified as
  functional at the time of the registration.

  If a registration is being updated, the contact information MUST
  either match the prior registration and be verified, or the prior
  registrant MUST confirm that the updating registrant has authority to
  update the registration. IANA is to send an email to each old and new
  address confirming the change request. The emails are to contain a
  nonce (which may be embedded in a URI) that, when return by email or
  another mechanism (e.g., HTTP), serve to verify the request. An
  affirmative response from any of the addresses (old or new) is
  sufficient. If neither the old nor the new registrations contain any
  email addresses, then the update MAY succeed without email
  confirmation. Therefore, registrants are encouraged to list at least
  one email address for registration protection.

  As a special "escape valve", registrations can be updated with IETF
  Review [RFC5226]. All fields may be updated except the variant
  identifier, which is permanent: not even case may be changed.

NEW
  All references (including contact information) are expected to be
  valid at the time of the registration.

  All fields may be updated except the variant
  identifier, which is permanent: not even case may be changed.

Nothing else of note.