Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations
draft-ietf-appsawg-text-markdown-use-cases-07

[Ballot comment]

(Sorry I included this in my comments for the other markdown doc
but it relates to this one. I'll take this out of my ballot comment for
that but not re-tx the mail.)

- 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 agree with others that mixing the IANA Registrations in the use cases draft is odd -- specially when the draft-ietf-appsawg-text-markdown document also exists.  Without the IANA Considerations I would also think that use cases would be better off in a Wiki.  [No need to reply to this, as it has been talked about elsewhere..]

I do have one nit:

Section 2 reads: " [MDMTREG] (draft-05) only defines two parameters: the charset parameter (required for all text/* media types) and the variant parameter."  I think that is still true in the latest version of that draft; the "draft-05" reference should be taken out.

[Ballot discuss]
Thanks for writing this document. This is a really small thing, but the Gen-ART reviewer (Tom Taylor) noted a couple of things. The one that I would raise as a discuss so that we do not forget to fix is first:

Section 4.2: ~~Oops this is some mistaken text.~~

Please make sure your text is complete here. It was unclear if this was intended as actual example text, or if there was a problem in the draft on this point.

And, please remove or specify the "[CITE]" references.

These are indeed minor things and I'm only raising them (as an easily clearable) Discuss because with them, the draft seems incomplete, and I worry that we have forgotten something.

[Ballot comment]
Like others have commented, I find it a bit odd to mix the IANA registrations with the rest of the material in this draft.

Some of the editorial comments (from myself below, from others, and from IDNits) makes me wonder if this draft was quite finished?

While I don't think it makes sense to change course this late in the process for this draft, I am skeptical that the material in sections 1 and 2 will benefit from being in an RFC.  I think that it might have made more sense to capture it in a working group wiki, or similar repository. (But again, no point in changing now.)

-- 3.3, additional parameters:
I’m not sure I understand why the list is broken in to “stuff to turn off” and “new stuff”.

Editorial:

IDNits has quite a bit to say, some of which might even be relevant. Please check.

There are a number of words enclosed in /slashes/ or *asterisks*. I assume this is intended for emphasis. (Or perhaps as performance art when discussing methods for formatting text :-)  ) But it seems odd for an RFC. If it stays, I suggest picking one method and sticking with it. (If it means something different, please mention that in the text.)

-- section 4 refers to Appendix C, but the draft has no appendices.

[Ballot discuss]
This does not strike me as a 'use cases' document when you make IANA requests to register identifiers with IANA. These seem more appropriate in draft-ietf-appsawg-text-markdown-08.

[Ballot comment]
- I was surprised by the RFC2119 keywords in a use cases document (which I first thought of as an applicability document")
But, actually, according to the abstract, it's way more than a use cases document: "Background information, local storage strategies, and additional syntax registrations are supplied.",
It's really the companion document of draft-ietf-appsawg-text-markdown. Maybe the title is wrong, and should be something such as text/markdown strategies and registrations?

" [MDMTREG] (draft-05) only defines two parameters:"
I guess there is nothing special about version 5. The latest version is v8

Editorial:
- section 1, para 4. That confused me until I saw figure 1
OLD: On the formal end of the spectrum is markup
NEW: On the formal end of the formatted text spectrum is markup

- There are a couple of [CITE] reference, including this one: Character set interoperability is well-studied territory [NB: CITE?]
To be completed I guess.

[Ballot discuss]
Easy to fix DISCUSS: The RFC 2119 boilerplate is missing:

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
      "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
      document are to be interpreted as described in [RFC2119].

[Ballot comment]
- I was surprised by the RFC2119 keywords in a use cases document (which I first thought of as an applicability document")
But, actually, according to the abstract, it's way more than a use cases document: "Background information, local storage strategies, and additional syntax registrations are supplied.",
It's really the companion document of draft-ietf-appsawg-text-markdown. Maybe the title is wrong, and should be something such as text/markdown strategies and registrations?

Editorial:
- section 1, para 4. That confused me until I saw figure 1
OLD: On the formal end of the spectrum is markup
NEW: On the formal end of the formatted text spectrum is markup

- There are a couple of [CITE] reference, including this one: Character set interoperability is well-studied territory [NB: CITE?]
To be completed I guess.

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

IANA has reviewed draft-ietf-appsawg-text-markdown-use-cases-02.  Please report any inaccuracies and respond to any questions as soon as possible.

IANA's reviewer has the following comments/questions:

IANA understands that some of the actions requested in the IANA Considerations section of this document are dependent upon the approval of and completion of IANA Actions in another document: draft-ietf-appsawg-text-markdown.

We understand that the draft-ietf-appsawg-text-markdown registry should include columns for all of the fields described below. If this is not the case (if, for example, the registry should include only a few fields, or should include a few fields and a link to the template), please reply to our review of draft-ietf-appsawg-text-markdown. 

IANA understands that, upon approval of this document, there is a single action which IANA must complete.

In the Markdown Variants registry to be created by the approval of draft-ietf-appsawg-text-markdown, eight new Markdown Variants will be registered as follows:

Identifier: MultiMarkdown
Name: MultiMarkdown
Description: MultiMarkdown (MMD) is a superset of "Original". It adds multiple syntax features (tables, footnotes, and citations, to name a few), and is intended to output to various formats. Additionally, it builds in "smart" typography for various languages (proper left- and right- sided quotes, for example).
Additional Parameters: options: String with zero or more of the following WSP-delimited tokens:
"memoir" / "beamer"
"full" / "snippet"
"process-html"
"random-footnote-identifiers"
"accept"
"reject"
"nosmart"
"nonotes"
"nolabels"
"nomask"
The meanings of these tokens are defined in the MultiMarkdown documentation.
Fragment Identifiers:
References:
Contact Information: (individual) Fletcher T. Penney ,
Expiration Date:

Identifier: GFM
Name: GitHub Flavored Markdown
Description: "Original" with the following differences:
1. Multiple underscores in words
2. URL (URI) autolinking
3. Strikethrough
4. Fenced code blocks
5. Syntax highlighting
6. Tables (- for rows; | for columns; : for alignment)
7. Only some HTML allowed; sanitization is integral
to the format
Additional Parameters: extensions: String with an optional starting syntax token, followed by a "+" and "-" delimited list of extension tokens. "+" preceding an extension token turns the extension on; "-" turns the extension off. The starting syntax tokens are "markdown", "markdown_strict", "markdown_phpextra", and "markdown_github". If no starting syntax token is given, "markdown" is assumed. The extension tokens include:

[[Stuff to turn off:]]

escaped_line_breaks
blank_before_header
header_attributes
auto_identifiers
implicit_header_references
blank_before_blockquote
fenced_code_blocks
fenced_code_attributes
line_blocks
fancy_lists
startnum
definition_lists
example_lists
table_captions
simple_tables
multiline_tables
grid_tables
pipe_tables
pandoc_title_block
yaml_metadata_block
all_symbols_escapable
intraword_underscores
strikeout
superscript
subscript
inline_code_attributes
tex_math_dollars
raw_html
markdown_in_html_blocks
native_divs
native_spans
raw_tex
latex_macros
implicit_figures
footnotes
inline_notes
citations

[[New stuff:]]

lists_without_preceding_blankline
hard_line_breaks
ignore_line_breaks
tex_math_single_backslash
tex_match_double_backslash
markdown_attribute
mmd_title_block
abbreviations
autolink_bare_uris
ascii_identifiers
link_attributes
mmd_header_identifiers
compact_definition_lists
Fragment Identifiers:
References: ,
Contact Information: (corporate) GitHub, Inc.
Expiration Date:

Identifier: pandoc
Name: Pandoc
Description: Markdown is designed to be easy to write and to read: the content should be publishable as-is, as plain text, without looking like it has been marked up with tags or formatting instructions. Yet whereas "Original" has HTML generation in mind, pandoc is designed for multiple output formats. Thus, while pandoc allows the embedding of raw HTML, it discourages it, and provides other, non-HTMLish ways of representing important document elements like definition lists, tables, mathematics, and footnotes.
Additional Parameters:
Fragment Identifiers: Pandoc defines fragment identifiers using the  in the {# .class ...} production (PHP Markdown Extra attribute block). This syntax works for Header Identifiers and Code Block Identifiers.
References:
Contact Information: (individual) Prof. John MacFarlane ,
Expiration Date:

Identifier: Fountain
Name: Fountain
Description: Fountain is a simple markup syntax for writing, editing and sharing screenplays in plain, human-readable text. Fountain allows you to work on your screenplay anywhere, on any computer or tablet, using any software that edits text files.
Additional Parameters:
Fragment Identifiers: See  and . In the following fragment identifiers, the  and  productions MUST have "/" characters percent-encoded.

#/ Title Page (acts as metadata).
#/ Title Page;  is the key string.
# *("/" )
Section or subsection. The ..
productions are the text of the Section line,
with whitespace trimmed from both ends.
Sub-sections (sections with multiple # at
at the beginning of the line in the source)
are addressed hierarchically by preceding
the sub-section with higher-order
sections. If the section hierarchy "skips",
e.g., # to ###, use a blank section name,
e.g., #Section/ACT%20I//PATIO%20SCENE.
References:
Contact Information: (individual) Stu Maschwitz , (individual) John August
Expiration Date:

Identifier: CommonMark
Name: CommonMark
Description: CommonMark is a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate Markdown implementations against this specification. The maintainers believe that CommonMark is necessary, even essential, for the future of Markdown.

Compared to "Original", CommonMark is much longer and in a few instances contradicts "Original" based on seasoned experience. Although CommonMark specifically does not mandate any particular encoding for the input content, CommonMark draws in more of Unicode, UTF-8, and HTML (including HTML5) than "Original".

This registration always refers to the latest version or an unspecified version (receiver's choice). Version 0.13 of the CommonMark specification was released 2014-12-10.
Additional Parameters:
Fragment Identifiers:
References:
Contact Information: (individual) John MacFarlane , (individual) David Greenspan , (individual) Vicent Marti , (individual) Neil Williams , (individual) Benjamin Dumke-von der Ehe , (individual) Jeff Atwood
Expiration Date:

Identifier: kramdown-rfc2629
Name: Markdown for RFCs
Description: kramdown is a markdown parser by Thomas Leitner, which has a number of backends for generating HTML, Latex, and Markdown again. kramdown-rfc2629 is an additional backend to that: It allows the generation of XML2RFC XML markup (also known as RFC 2629 compliant markup).
Additional Parameters:
Fragment Identifiers:
References:
Contact Information: (individual) Carsten Bormann
Expiration Date:

Identifier: rfc7328
Name: Pandoc2rfc
Description: Pandoc2rfc allows authors to write in "pandoc" that is then transformed to XML and given to xml2rfc. The conversions are, in a way, amusing, as we start off with (almost) plain text, use elaborate XML, and end up with plain text again.
Additional Parameters:
Fragment Identifiers:
References: [RFC 7328],
Contact Information: (individual) R. (Miek) Gieben
Expiration Date:

Identifier: Extra
Name: Markdown Extra
Description: Markdown Extra is an extension to PHP Markdown implementing some features currently not available with the plain Markdown syntax. Markdown Extra is available as a separate parser class in PHP Markdown Lib. Other implementations include Maruku (Ruby) and Python Markdown. Markdown Extra is supported in several content management systems, including Drupal, TYPO3, and MediaWiki.
Additional Parameters:
Fragment Identifiers: Markdown Extra defines fragment identifiers using the  in the {# .class ...} production (attribute block). This syntax works for headers, fenced code blocks, links, and images.
References:
Contact Information: (individual) Michel Fortin
Expiration Date:

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:  (text/markdown Use Cases) to Informational RFC


The IESG has received a request from the Applications Area Working Group
WG (appsawg) to consider the following document:
- 'text/markdown Use Cases'
  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-03. 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 elaborates upon 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.
  Background information, local storage strategies, and additional
  syntax registrations are supplied.




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

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-appsawg-text-markdown-use-cases/ballot/


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

1. Summary

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

This document elaborates upon 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.
Background information, local storage strategies, and additional
syntax registrations are supplied.

The WG is requesting Informational status for this document.  The
main work of specifying Markdown syntax variants is done outside of the
IETF.  This document, which was split off from
draft-ietf-appsawg-text-markdown, consists mainly of brief descriptions
and references for several Markdown variants, and presents IANA registrations
for them.

2. Review and Consensus

This document was spun off from the above-named draft to try to keep
the other one shorter.  They each received the same amount of attention
and criticism.

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.

The IANA Considerations seem to be fine for this document, though there
are some formatting oddities that would be nice to resolve.

Nothing else of note.