draft-ietf-appsawg-text-markdown-05.txt   draft-ietf-appsawg-text-markdown-06.txt 
Applications Area Working Group S. Leonard Applications Area Working Group S. Leonard
Internet-Draft Penango, Inc. Internet-Draft Penango, Inc.
Intended Status: Informational December 22, 2014 Intended Status: Informational February 23, 2015
Expires: June 25, 2015 Expires: August 27, 2015
The text/markdown Media Type The text/markdown Media Type
draft-ietf-appsawg-text-markdown-05 draft-ietf-appsawg-text-markdown-06
Abstract Abstract
This document registers the text/markdown media type for use with This document registers the text/markdown media type for use with
Markdown, a family of plain text formatting syntaxes that optionally Markdown, a family of plain text formatting syntaxes that optionally
can be converted to formal markup languages such as HTML. can be converted to formal markup languages such as HTML.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 34 skipping to change at page 1, line 34
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 16 skipping to change at page 2, line 16
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. This Is Markdown! Or: Markup and Its Discontents . . . . . 2 1.1. This Is Markdown! Or: Markup and Its Discontents . . . . . 2
1.2. Markdown Is About Writing and Editing . . . . . . . . . . . 3 1.2. Markdown Is About Writing and Editing . . . . . . . . . . . 3
1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Markdown Media Type Registration Application . . . . . . . . . 5 2. Markdown Media Type Registration Application . . . . . . . . . 5
3. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 7 3. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 7
3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8
4. Content Disposition and preview-type . . . . . . . . . . . . . 8 4. Content Disposition and preview-type . . . . . . . . . . . . . 8
5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10 6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10
6.2. Reserved Identifiers . . . . . . . . . . . . . . . . . . . 11 6.2. Reserved Identifiers . . . . . . . . . . . . . . . . . . . 11
6.3. Standard of Review . . . . . . . . . . . . . . . . . . . . 11 6.3. Standard of Review . . . . . . . . . . . . . . . . . . . . 11
6.4. Provisional Registration . . . . . . . . . . . . . . . . . 11 6.4. Provisional Registration . . . . . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . . 12 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 11
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
8.1. Normative References . . . . . . . . . . . . . . . . . . . 12 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11
8.2. Informative References . . . . . . . . . . . . . . . . . . 13 8.2. Informative References . . . . . . . . . . . . . . . . . . 13
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 13 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
1. Introduction 1. Introduction
1.1. This Is Markdown! Or: Markup and Its Discontents 1.1. This Is Markdown! Or: Markup and Its Discontents
In computer systems, textual data is stored and processed using a In computer systems, textual data is stored and processed using a
continuum of techniques. On the one end is plain text: a linear continuum of techniques. On the one end is plain text: a linear
sequence of characters in some character set (code), possibly sequence of characters in some character set (code), possibly
interrupted by line breaks, page breaks, or other control characters. interrupted by line breaks, page breaks, or other control characters.
The repertoire of these control characters (a form of in-band The repertoire of these control characters (a form of in-band
skipping to change at page 8, line 4 skipping to change at page 8, line 4
variants do, and many types of Markdown processor output (e.g., HTML variants do, and many types of Markdown processor output (e.g., HTML
or PDF) will have well-defined fragment identifiers. Which fragment or PDF) will have well-defined fragment identifiers. Which fragment
identifiers are available for a given document are variant-defined. identifiers are available for a given document are variant-defined.
When encoded in a URI, characters that are outside of the fragment When encoded in a URI, characters that are outside of the fragment
production of [RFC3986] are percent-encoded. The default encoding production of [RFC3986] are percent-encoded. The default encoding
(character set) of percent-encoded octets in URIs is the same as the (character set) of percent-encoded octets in URIs is the same as the
Markdown content, which is identified by the charset parameter or by Markdown content, which is identified by the charset parameter or by
other contextual means. Fragment identifiers SHOULD be considered other contextual means. Fragment identifiers SHOULD be considered
case-sensitive, which maintains consistency with HTML. Variants MAY case-sensitive, which maintains consistency with HTML. Variants MAY
override the guidance in this paragraph. [[NB: citation necessary to override the guidance in this paragraph.
HTML4/HTML5?]]
At least the first equals sign "=" SHOULD be percent-encoded to At least the first equals sign "=" SHOULD be percent-encoded to
prevent ambiguity as described in the following section. prevent ambiguity as described in the following section.
3.1. Parameters 3.1. Parameters
Similar to application/pdf [RFC3778] and text/plain [RFC5147], this Similar to application/pdf [RFC3778] and text/plain [RFC5147], this
registration permits a parameter syntax for fragment identifiers. The registration permits a parameter syntax for fragment identifiers. The
syntax is a parameter name, the equals sign "=" (which MUST NOT be syntax is a parameter name, the equals sign "=" (which MUST NOT be
percent-encoded), and a parameter value. To the extent that multiple percent-encoded), and a parameter value. To the extent that multiple
skipping to change at page 8, line 29 skipping to change at page 8, line 28
The only parameter defined in this registration is "line", which has The only parameter defined in this registration is "line", which has
the same meaning as [RFC5147] (i.e., counting is zero-based). For the same meaning as [RFC5147] (i.e., counting is zero-based). For
example: "#line=10" identifies the eleventh line of Markdown input. example: "#line=10" identifies the eleventh line of Markdown input.
Implementers should take heed that different environments and Implementers should take heed that different environments and
character sets may have a wide range of code sequences to divide character sets may have a wide range of code sequences to divide
lines. lines.
Markdown variants are free to define additional parameters. Markdown variants are free to define additional parameters.
[[NB: This draft does not import all of text/plain's fragment
identifier schemes, mainly because the utility of the other schemes
is far from obvious. Implementing line= is not difficult but char= is
more difficult since "character" has various meanings that will skew
the numbering significantly as the content grows in length; the other
integrity check things simply do not seem to be particularly
useful.]]
4. Content Disposition and preview-type 4. Content Disposition and preview-type
The Content-Disposition header [RFC2183] conveys presentational The Content-Disposition header [RFC2183] conveys presentational
information about a MIME entity, using a type and set of parameters. information about a MIME entity, using a type and set of parameters.
The parameter "preview-type" is defined here for Markdown content. The parameter "preview-type" is defined here for Markdown content.
When present, "preview-type" indicates the Internet media type (and When present, "preview-type" indicates the Internet media type (and
parameters) of the preview output desired from the processor by the parameters) of the preview output desired from the processor by the
author. With reference to the "paradigmatic use case" (i.e., author. With reference to the "paradigmatic use case" (i.e.,
collaborative Markdown editing) in Section 1.3, the output-type collaborative Markdown editing) in Section 1.3, the output-type
skipping to change at page 10, line 42 skipping to change at page 10, line 33
Name Name
Description Description
Additional Parameters (optional) Additional Parameters (optional)
Fragment Identifiers (optional) Fragment Identifiers (optional)
References References
Contact Information Contact Information
Expiration Date (if provisional) Expiration Date (if provisional)
While the variant parameter is "plain US-ASCII" (see registration While the variant parameter is "plain US-ASCII" (see registration
template), the Identifier field (and by implication, all registered template), the Identifier field (and by implication, all registered
identifiers) SHALL conform to the ABNF: identifiers) SHALL conform to the ABNF [RFC5234]:
ALPHA [*(%d33-126) (ALPHA / DIGIT)] ALPHA [*VCHAR (ALPHA / DIGIT)]
For style and compatibility reasons, the Identifier field SHOULD For style and compatibility reasons, the Identifier field SHOULD
conform to the ABNF: conform to the ABNF:
ALPHA 1*( ["-" / "." / "_" / "~"] 1*(ALPHA / DIGIT) ) ALPHA 1*( ["-" / "." / "_" / "~"] 1*(ALPHA / DIGIT) )
I.e., the identifier MUST start with a letter and MAY contain I.e., the identifier MUST start with a letter and MAY contain
punctuation in the middle, but not at the end: the last character punctuation in the middle, but not at the end: the last character
MUST be alphanumeric. The second production uses the same characters MUST be alphanumeric. The second production uses the same characters
as the "unreserved" rule of [RFC3986], and is designed to be as the "unreserved" rule of [RFC3986], and is designed to be
skipping to change at page 11, line 40 skipping to change at page 11, line 32
Specification Required nor Expert Review are warranted. The checks Specification Required nor Expert Review are warranted. The checks
prescribed by this section can be performed automatically. prescribed by this section can be performed automatically.
All references (including contact information) MUST be verified as All references (including contact information) MUST be verified as
functional at the time of the registration. functional at the time of the registration.
If a registration is being updated, the contact information MUST If a registration is being updated, the contact information MUST
either match the prior registration and be verified, or the prior either match the prior registration and be verified, or the prior
registrant MUST confirm that the updating registrant has authority to registrant MUST confirm that the updating registrant has authority to
update the registration. As a special "escape valve", registrations update the registration. As a special "escape valve", registrations
can be updated with IETF Review [RFC5226]. [[NB: Two purposes: 1) to can be updated with IETF Review [RFC5226]. All fields may be updated
deal with "harmful" registrations (stale references are not a except the variant identifier, which is permanent: not even case may
sufficient justification); 2) to deal with registrations that are be changed.
IETF registrations, like RFC-related Markdown (but this could be
handled by listing the IETF as the contact organization, right?).]]
All fields may be updated except the variant identifier, which is
permanent: not even case may be changed.
6.4. Provisional Registration 6.4. Provisional Registration
Any registrant may make a provisional registration to reserve a Any registrant may make a provisional registration to reserve a
variant identifier. Only the variant identifier and contact variant identifier. Only the variant identifier and contact
information fields are required; the rest are optional. Provisional information fields are required; the rest are optional. Provisional
registrations expire after three months, after which time the variant registrations expire after three months, after which time the variant
identifier may be reused. To make a registration permanent, a identifier may be reused. To make a registration permanent, a
registrant simply needs to complete a permanent registration with the registrant simply needs to complete a permanent registration with the
same identifier as the provisional registration. same identifier as the provisional registration.
skipping to change at page 12, line 41 skipping to change at page 12, line 28
Extensions (MIME) Part One: Format of Internet Message Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996. Bodies", RFC 2045, November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded
Word Extensions: Character Sets, Languages, and Word Extensions: Character Sets, Languages, and
Continuations", RFC 2231, November 1997. Continuations", RFC 2231, November 1997.
[RFC2854] Connolly, D. and L. Masinter, "The 'text/html' Media
Type", RFC 2854, June 2000.
[RFC3778] Taft, E., Pravetz, J., Zilles, S., and L. Masinter, "The [RFC3778] Taft, E., Pravetz, J., Zilles, S., and L. Masinter, "The
application/pdf Media Type", RFC 3778, May 2004. application/pdf Media Type", RFC 3778, May 2004.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005. 3986, January 2005.
[RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the
text/plain Media Type", RFC 5147, April 2008. text/plain Media Type", RFC 5147, April 2008.
[RFC5226] Narten, T., and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T., and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", RFC 5226, May 2008. IANA Considerations Section in RFCs", RFC 5226, May 2008.
[RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234, January
2008.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
October 2008. October 2008.
[RFC6532] Yang, A., Steele, S., and N. Freed, "Internationalized [RFC6532] Yang, A., Steele, S., and N. Freed, "Internationalized
Email Headers", RFC 6532, February 2012. Email Headers", RFC 6532, February 2012.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13, RFC Specifications and Registration Procedures", BCP 13, RFC
6838, January 2013. 6838, January 2013.
skipping to change at page 13, line 30 skipping to change at page 13, line 17
[HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", May 2008, [HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", May 2008,
<http://blog.codinghorror.com/is-html-a-humane-markup- <http://blog.codinghorror.com/is-html-a-humane-markup-
language/>. language/>.
[INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of [INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of
the word 'meme'", June 2013, the word 'meme'", June 2013,
<http://www.wired.co.uk/news/archive/2013-06/20/richard- <http://www.wired.co.uk/news/archive/2013-06/20/richard-
dawkins-memes>, <http://www.webcitation.org/6HzDGE9Go>. dawkins-memes>, <http://www.webcitation.org/6HzDGE9Go>.
[MDMTUSES] Leonard, S., "text/markdown Use Cases", draft-seantek- [MDMTUSES] Leonard, S., "text/markdown Use Cases", draft-ietf-
text-markdown-use-cases-00 (work in progress), October appsawg-text-markdown-use-cases-01 (work in progress),
2014. February 2015.
[PANDOC] MacFarlane, J., "Pandoc", 2014, [PANDOC] MacFarlane, J., "Pandoc", 2014,
<http://johnmacfarlane.net/pandoc/>. <http://johnmacfarlane.net/pandoc/>.
[RFC4263] Lilly, B., "Media Subtype Registration for Media Type [RFC4263] Lilly, B., "Media Subtype Registration for Media Type
text/troff", RFC 4263, January 2006. text/troff", RFC 4263, January 2006.
Appendix A. Change Log Appendix A. Change Log
This draft is a continuation from draft-ietf-appsawg-text-markdown- This draft is a continuation from draft-ietf-appsawg-text-markdown-
04.txt. These technical changes were made: 05.txt. These technical changes were made:
1. Added preview-type Content Disposition parameter. 1. Removed TODO items for the time being.
2. Updated example. 2. Added RFC 5234 reference.
3. Fleshed out more of the registration procedures. 3. Made minor changes.
4. Simplified the text of the fragment identifiers.
5. Removed vestiges of the old syntax and output-type parameters.
6. Discussed the meaning of "variant" in the context of Markdown.
Author's Address Author's Address
Sean Leonard Sean Leonard
Penango, Inc. Penango, Inc.
5900 Wilshire Boulevard 5900 Wilshire Boulevard
21st Floor 21st Floor
Los Angeles, CA 90036 Los Angeles, CA 90036
USA USA
 End of changes. 16 change blocks. 
41 lines changed or deleted 26 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/