draft-ietf-appsawg-text-markdown-03.txt   draft-ietf-appsawg-text-markdown-04.txt 
Applications Area Working Group S. Leonard Applications Area Working Group S. Leonard
Internet-Draft Penango, Inc. Internet-Draft Penango, Inc.
Intended Status: Informational October 17, 2014 Intended Status: Informational December 16, 2014
Expires: April 20, 2015 Expires: June 19, 2015
The text/markdown Media Type The text/markdown Media Type
draft-ietf-appsawg-text-markdown-03 draft-ietf-appsawg-text-markdown-04
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 2, line 10 skipping to change at page 2, line 10
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
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
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. RFC 2119 . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Markdown Media Type Registration Application . . . . . . . . . 5 2. Markdown Media Type Registration Application . . . . . . . . . 5
3. Optional Parameters . . . . . . . . . . . . . . . . . . . . . 7 3. Optional Parameters . . . . . . . . . . . . . . . . . . . . . 7
3.1. syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 7
3.2. output-type . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1. General-Purpose Fragment Identifiers . . . . . . . . . . . 8
4. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 13 4.2. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8
4.1. #t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2. #o . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
4.3. #l and #ldef . . . . . . . . . . . . . . . . . . . . . . . 13 6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10
4.4. Other Fragment Identifiers . . . . . . . . . . . . . . . . 14 6.2. Reserved Identifiers . . . . . . . . . . . . . . . . . . . 10
5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.3. Standard of Review . . . . . . . . . . . . . . . . . . . . 11
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 6.4. Provisional Registration . . . . . . . . . . . . . . . . . 11
6.1. Syntax Template . . . . . . . . . . . . . . . . . . . . . . 15 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 11
6.2. Initial Registration . . . . . . . . . . . . . . . . . . . 17 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.3. Reserved Identifiers . . . . . . . . . . . . . . . . . . . 18 8.1. Normative References . . . . . . . . . . . . . . . . . . . 11
6.4. Standard of Review . . . . . . . . . . . . . . . . . . . . 18 8.2. Informative References . . . . . . . . . . . . . . . . . . 12
6.5. Provisional Registration . . . . . . . . . . . . . . . . . 19 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 13
7. Security Considerations . . . . . . . . . . . . . . . . . . . . 19 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
8.1. Normative References . . . . . . . . . . . . . . . . . . . 19
8.2. Informative References . . . . . . . . . . . . . . . . . . 20
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 21
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22
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 3, line 32 skipping to change at page 3, line 27
rules), the expectation is that the author should continue rules), the expectation is that the author should continue
experimenting by changing the content or the processor to achieve the experimenting by changing the content or the processor to achieve the
desired output. desired output.
Since its development in 2004 [MARKDOWN], a number of web- and Since its development in 2004 [MARKDOWN], a number of web- and
Internet-facing applications have incorporated Markdown into their Internet-facing applications have incorporated Markdown into their
text entry systems, frequently with custom extensions. Markdown has text entry systems, frequently with custom extensions. Markdown has
thus evolved into a kind of Internet meme [INETMEME] as different thus evolved into a kind of Internet meme [INETMEME] as different
communities encounter it and adapt the syntax for their specific use communities encounter it and adapt the syntax for their specific use
cases. Markdown now represents a family of related plain text cases. Markdown now represents a family of related plain text
formatting syntaxes that, while broadly compatible with humans formatting syntaxes and implementations that, while broadly
[HUMANE], are intended to produce different kinds of outputs that compatible with humans [HUMANE], are intended to produce different
push the boundaries of mutual intelligibility between software kinds of outputs that push the boundaries of mutual intelligibility
systems. between software systems.
To support identifying and conveying Markdown, this document defines To support identifying and conveying Markdown, this document defines
a media type and parameters that indicate the author's intent on how a media type and parameters that indicate the author's intent on how
to interpret the Markdown. This registration draws particular to interpret the Markdown. This registration draws particular
inspiration from text/troff [RFC4263], which is a plain text inspiration from text/troff [RFC4263], which is a plain text
formatting syntax for typesetting based on tools from the 1960s formatting syntax for typesetting based on tools from the 1960s
("RUNOFF") and 1970s ("nroff", et. al.). In that sense, Markdown is a ("RUNOFF") and 1970s ("nroff", et. al.). In that sense, Markdown is a
kind of troff for modern computing. A companion document [MDMTUSES] kind of troff for modern computing. A companion document [MDMTUSES]
provides additional Markdown background and philosophy. provides additional Markdown background and philosophy.
skipping to change at page 5, line 15 skipping to change at page 5, line 10
plain old "Notepad". Additionally, users SHOULD be able to identify plain old "Notepad". Additionally, users SHOULD be able to identify
particular areas of Markdown content when the Markdown becomes particular areas of Markdown content when the Markdown becomes
appreciably large (e.g., book chapters and Internet-Drafts--not just appreciably large (e.g., book chapters and Internet-Drafts--not just
blog posts). Users SHOULD be able to use text/markdown to convey their blog posts). Users SHOULD be able to use text/markdown to convey their
works in progress, not just their finished products (for which full- works in progress, not just their finished products (for which full-
blown markups ranging from text/html to application/pdf are blown markups ranging from text/html to application/pdf are
appropriate). This registration facilitates interoperability between appropriate). This registration facilitates interoperability between
these Markdown editors by conveying the syntax of the particular these Markdown editors by conveying the syntax of the particular
Markdown variant and the desired output format. Markdown variant and the desired output format.
1.3. RFC 2119 1.3. Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
Since Markdown signifies a family of related formats with varying
degrees of formal documentation and implementation, this
specification uses the term "variant" to identify such formats.
2. Markdown Media Type Registration Application 2. Markdown Media Type Registration Application
This section provides the media type registration application for the This section provides the media type registration application for the
text/markdown media type (see [RFC6838], Section 5.6). text/markdown media type (see [RFC6838], Section 5.6).
Type name: text Type name: text
Subtype name: markdown Subtype name: markdown
Required parameters: Required parameters:
skipping to change at page 5, line 44 skipping to change at page 5, line 43
writing format; its syntax rules operate on characters writing format; its syntax rules operate on characters
(specifically, on punctuation) rather than code points. Neither (specifically, on punctuation) rather than code points. Neither
[MDSYNTAX] nor many popular implementations at the time of this [MDSYNTAX] nor many popular implementations at the time of this
registration actually require or assume any particular encoding. registration actually require or assume any particular encoding.
Many Markdown processors will get along just fine by operating on Many Markdown processors will get along just fine by operating on
character codes that lie in printable US-ASCII, blissfully character codes that lie in printable US-ASCII, blissfully
oblivious to coded values outside of that range. oblivious to coded values outside of that range.
Optional parameters: Optional parameters:
The following parameters reflect the author's intent regarding the variant: An optional identifier that serves as a "hint" to the
content. A detailed specification can be found in Section 3. recipient of the specific Markdown variant that the author
intended. When omitted, there is no hint; the interpretation is
syntax: The Markdown-derivative syntax of the content, with entirely up to the receiver and context. This identifier is plain
optional version and named extensions. Default value: none US-ASCII and case-insensitive. To promote interoperability,
(receiver's choice). identifiers MAY be registered in the registry defined in Section
6. If a receiver does not recognize the variant identifier, the
receiver MAY present the identifier to a user to inform him or
her of it.
output-type: The Content-Type (Internet media type) of the output, Other parameters MAY be included with the media type. The variant
with optional parameters. Default value: "text/html". SHOULD define the semantics of such parameters. Additionally, the
variant MAY be registered under another media type; this
text/markdown registration does not preclude other registrations.
Encoding considerations: Text. Encoding considerations: Text.
Security considerations: Security considerations:
Markdown interpreted as plain text is relatively harmless. A text Markdown interpreted as plain text is relatively harmless. A text
editor need only display the text. The editor SHOULD take care to editor need only display the text. The editor SHOULD take care to
handle control characters appropriately, and to limit the effect of handle control characters appropriately, and to limit the effect of
the Markdown to the text editing area itself; malicious Unicode- the Markdown to the text editing area itself; malicious Unicode-
based Markdown could, for example, surreptitiously change the based Markdown could, for example, surreptitiously change the
skipping to change at page 7, line 13 skipping to change at page 7, line 15
Published specification: This specification; [MDSYNTAX]. Published specification: This specification; [MDSYNTAX].
Applications that use this media type: Applications that use this media type:
Markdown conversion tools, Markdown WYSIWYG editors, and plain text Markdown conversion tools, Markdown WYSIWYG editors, and plain text
editors and viewers; markup processor targets indirectly use editors and viewers; markup processor targets indirectly use
Markdown (e.g., web browsers for Markdown converted to HTML). Markdown (e.g., web browsers for Markdown converted to HTML).
Fragment identifier considerations: Fragment identifier considerations:
Markdown content acts as a "bridge" between plain text and formal See Section 4.
markup, so this specification permits fragment identifiers [[NB:
used to be #i]] #t for the [[NB: used to be input]] source text and
#o for the output content. The #l and #ldef fragment identifiers
identify link references. A detailed specification can be found in
Section 4.
Additional information: Additional information:
Magic number(s): None Magic number(s): None
File extension(s): .md, .markdown File extension(s): .md, .markdown
Macintosh file type code(s): Macintosh file type code(s):
TEXT. A uniform type identifier (UTI) of TEXT. A uniform type identifier (UTI) of
"net.daringfireball.markdown", which conforms to "public.plain- "net.daringfireball.markdown", which conforms to "public.plain-
text", is RECOMMENDED [MDUTI]. Additionally, implementations text", is RECOMMENDED [MDUTI]. Additionally, implementations
SHOULD record syntax and output-type parameters along with the SHOULD record syntax and output-type parameters along with the
skipping to change at page 7, line 46 skipping to change at page 7, line 43
Restrictions on usage: None. Restrictions on usage: None.
Author/Change controller: Sean Leonard <dev+ietf@seantek.com> Author/Change controller: Sean Leonard <dev+ietf@seantek.com>
Intended usage: COMMON Intended usage: COMMON
Provisional registration? No Provisional registration? No
3. Optional Parameters 3. Optional Parameters
The optional parameters "syntax" and "output-type" can be used by an [[NB: OMITTED from this draft. This section may be replaced with
author to indicate the author's intent regarding how the Markdown Content-Disposition: ... preview-type=...]]
ought to be processed.
All identifiers are case-sensitive; receivers MUST compare for exact
equality. At the same time, identifiers MUST NOT be registered in the
IANA registry (see Section 6) if another registration differs only in
the casing, as these registrations may cause confusion.
The following ABNF definitions are used in this section:
EXTCHAR = <any character outside the printable US-ASCII
range, essentially amounting to Unicode code
points less than U+0020 or greater than U+007E
without requiring Unicode or any particular
encoding>
REXTCHAR = <EXTCHAR without separators (Z category) or
control characters (C category)>
Figure X: ABNF Used in This Section
The discussion in this section presumes that the parameter values are
discrete strings. When encoded in protocols such as MIME [RFC2045],
however, the value strings MUST be escaped properly. [MDMTUSES]
provides some strategies to preserve this information when it leaves
the domain of IETF protocols.
3.1. syntax
The syntax parameter indicates the Markdown-derivative syntax in
which the author composed the content, without regard to any
particular implementation. With reference to the "paradigmatic use
case" (i.e., collaborative Markdown editing) in Section 1.3, the
syntax parameter primarily affects the "left-hand" side of a Markdown
editor. The entire parameter is case-sensitive.
Syntaxes other than [MDSYNTAX] extend the original rules in some way.
These extensions fall into broad categories: clarifying ambiguities
in [MDSYNTAX], adding brand new features, repurposing [MDSYNTAX] for
completely new use cases, and adding metadata or other structured
data blocks. Occasionally new syntaxes directly contradict [MDSYNTAX]
based on seasoned experience.
A syntax identifier is composed of two or more characters excluding
(Unicode) separators, control characters, the hyphen-minus "-",
quotation marks """, and angle brackets "<" and ">"; however, ASCII
characters alone SHOULD be used. To promote interoperability, only
registered syntaxes are permissible. An IANA registry of syntaxes
will be created as discussed in Section 6.
When omitted, the default value is unspecified, which means that the
syntax interpretation is up to the receiver. However, the receiver
SHOULD NOT "guess" based on content-sniffing, as this methodology is
error-prone. Generators SHOULD always specify a syntax, whether
explicitly or by context in embedding protocols or formats. All
implementations MUST support the syntax value "Original", with the
meaning covered in Section 6. Generators MUST omit the syntax
parameter rather than transmitting an empty string (""); the empty
string is a syntax error per the ABNF below. The full ABNF of the
syntax parameter is:
syntax-param = syntax-id [ "-" version ]
*( 1*WSP extension ) *WSP
syntax-id = 2*sid-char
version = 1*sid-char
sid-char = %d33 / %d35-44 / %d46-59 / %d61 /
%d63-126 / REXTCHAR
extension = ext-name [ ":" ( ext-string / ext-uri ) ]
ext-name = 1*( %d33 / %d35-57 / %d59 / %d61 /
%d63-126 / REXTCHAR )
ext-string = ext-quoted [ ext-string ] /
( ext-safe-char / ">" )
*( ext-safe-char / "<" / ">" / ext-quoted )
ext-safe-char = %d33 / %d35-59 / %d61 / %d63-126 / REXTCHAR
; [[NB: Could be EXTCHAR ? depends on how we feel about Unicode
; high-order separators]]
ext-quoted = DQUOTE *eqcontent DQUOTE
ext-uri = "<" URI-reference ">" ; from [RFC3986]
eqcontent = %d0-33 / %d35-127 / EXTCHAR / DQUOTE DQUOTE
Figure X: ABNF of the syntax parameter
3.1.1. syntax version
For better precision, an author MAY include the syntax version. The
version is delimited from the syntax identifier with a hyphen-minus
"-" and has the same repertoire as the syntax identifier. The version
string itself is an opaque string of at least one character. Version
strings (e.g., "2.0", "3.0.5") are registered and updated along with
the syntax registration. Updates to syntax registrations SHOULD only
add new versions when those new versions have a material difference
on the interpretation of the Markdown content. If a syntax has a
version "2014.10" and a version "2014.11", for example, but "2014.11"
only fixes typos in the specification, the registration SHOULD NOT
separately register the "2014.11" version. The repertoire of the
version string is the same as the syntax identifier (and like the
processor identifier, ASCII characters alone SHOULD be used).
A receiver that recognizes the syntax but not the version MAY use any
version of the syntax, preferably the latest version.
3.1.2. syntax extensions
Some Markdown syntaxes are self-contained, with no options. However,
others have optional rules or features that may be applied with
discretion. For those syntax systems where optional rules are an
integral feature, the author MAY indicate that those named extensions
be applied in a whitespace-separated list. The syntax for extensions
derives in significant part from pandoc [PANDOC].
All extensions for a particular syntax are to be registered as part
of the syntax registration in Section 7.
An extension identifier is composed of any sequence of characters
excluding (Unicode) separators, control characters, the colon ":",
quotation marks """, and angle brackets "<" and ">"; however,
lowercase ASCII letters and the underscore "_" alone SHOULD be used,
where the underscore SHOULD NOT be at the beginning or end.
When present, an extension is "enabled", "enabled, with string", or
"enabled, with URI". When absent, an extension is "disabled". An
extension can have different semantics depending on whether a string
or URI is supplied. For example, an extension "bullet" could specify
whether and how to render bulleted lists. "Disabled" could mean
"bulleted" lists do not have bullets; "enabled" could mean that the
bullet is some default character; "enabled, with string" could mean
that the string is used as the bullet; finally, "enabled, with URI"
could mean that the image identified by URI is used as the bullet.
3.1.2.1. Enabled, with String
According to the ABNF above, extensions are delimited by whitespace.
Quotation marks are used to support zero-length strings, whitespace
or quotation marks in a single string, or strings where the first
character is "<". If a quotation mark appears anywhere in the string,
the following text is considered quoted; two successive quotation
marks "" within quoted text mean one quotation mark in the string. A
single quotation mark ends the quoting. Generators MUST NOT generate
unterminated quoted strings; however, parsers SHOULD treat an
unterminated quoted string as if it were terminated. Because of this
rule, quotation marks do not have to appear at the termini of a
string; embedded quotation marks start (and end) quoting within a
single argument. For example:
a""b
means:
ab
for the actual argument. In spite of this relaxed positioning rule,
for human readability generators SHOULD quote the entire string in
lieu of embedding quoted sub-strings.
3.1.2.2. Enabled, with URI
Certain syntaxes can take supplementary content, such as metadata,
from other resources. To support these workflows, an extension can
use the URI delimiters "<" and ">" to signal a URI, such as a cid: or
mid: URL [RFC2392] in the context of MIME messages. The URI MUST
comply with [RFC3986], and MAY be a relative reference if the subject
Markdown content has a base URI. The charset parameter specifies the
character encoding that is relevant to the URI's semantics (to the
extent that the URI needs it).
3.2. output-type
The output-type parameter indicates the Internet media type (and
parameters) of the output from the processor. With reference to the
"paradigmatic use case" (i.e., collaborative Markdown editing) in
Section 1.3, the outout-type parameter primarily affects the "right-
hand" side of a Markdown editor.
When omitted, the default value is "text/html". Implementations
SHOULD anticipate and support HTML (text/html) and XHTML
(application/xhtml+xml) output, to the extent that a syntax targets
those markup languages.
The default value of text/html ought to be suitable for the majority
of current purposes. However, Markdown is increasingly becoming
integral to workflows where HTML is not the target output; examples
range from TeX, to PDF, to OPML, and even to entire e-books (e.g.,
[PANDOC]). Anticipated output types for a particular syntax are to be
registered as part of the syntax registration in Section 7.
3.2.1. Value Format and Semantics
The value of output-type is an Internet media type with optional
parameters. The syntax (including case sensitivity considerations) is
the same as specified in [RFC2045] for the Content-Type header (with
updates over time), namely:
type "/" subtype *(";" parameter)
; Matching of media type and subtype
; is ALWAYS case-insensitive.
Figure X: Content-Type ABNF (from [RFC2045])
The Internet media type in the output-type parameter MUST be
observed.
Although arbitrary parameters may be passed along with the Internet
media type, receivers are under no obligation to honor or interpret
them in any particular way. For example, the parameter value
"text/plain; format=flowed; charset=ISO-2022-JP" obligates the
receiver to output text/plain (and to treat the output as plain text:
no sneaking in or labeling the output as HTML!). In contrast, such a
parameter value neither obligates the receiver to follow [RFC3676]
(for flowed output) nor to output ISO-2022-JP Japanese character
encoding (see [RFC1468]).
The output-type parameter does not distinguish between fragment
content and whole-document content. A Markdown processor MAY (and
typically will) output HTML or XHTML fragment content, without
preambles or postambles such as <!DOCTYPE>, <html>, <head>, </head>,
<body>, </body>, or </html> elements. Receivers MUST be aware of this
behavior and take appropriate precautions. Fragment vs. whole-
document output considerations are appropriate for addressing in
syntax specifications, either as part of the syntax or by a syntax
extension.
3.2.2. text/markdown Special Value
The author may specify the output-type "text/markdown", which has a
special meaning. "text/markdown" means that the author does not want
to invoke Markdown processing at all: the receiver SHOULD view the
Markdown source as-is.
This output-type is not the default because one generally assumes
that Markdown is meant for composing rather than reading: readers
expect to see the output format (or dual-display of the output and
the Markdown). However, if authors are collaboratively editing a
document or are discussing Markdown, "text/markdown" may make sense.
Furthermore, "text/markdown" differs from "text/plain" in that
"text/plain" encompasses a wide range of characters and formatting
techniques (in Unicode, examples include bullet points, roman
numerals, unambiguous line and paragraph separators, and interlinear
annotation). While the optional parameter output-type may be used
recursively (as a sneaky way to stash the author's follow-on or
secondary intent), receivers are not obligated to recognize it;
optional parameters internal to output-type MAY be ignored.
4. Fragment Identifiers 4. Fragment Identifiers
4.1. #t Many types of content (such as HTML or PDF) that is output from a
Markdown processor will have well-defined fragment identifier
[[NB: This section used to say: The fragment #i refers to the content semantics associated with the content (such as named anchors or page
input into a Markdown processor, which for purposes of this fragment numbers, respectively). However, the original [MDSYNTAX] neither
identifier, MUST be treated as plain text (text/plain).]] defines a syntax for naming such content parts, nor associates such
parts with fragment identifiers. Several variants have since defined
The fragment #t refers to the Markdown content treated as plain text such content parts, making them suitable for use with fragment
(text/plain). A specific area of the text can be identified with a identifiers.
text/plain sub-fragment identifier (e.g., [RFC5147] or its
successors) delimited by a second "#" character. For example:
#t#line=10 identifies the eleventh line of Markdown input.
Implementers should take heed that the "char" scheme counts by
characters rather than octets (or, for that matter, code points);
thus proper interpretation of the charset parameter is REQUIRED for
interoperability of the "char" scheme. For example, "character" and
"code point" are NOT synonymous in the Unicode Standard.
4.2. #o 4.1. General-Purpose Fragment Identifiers
The fragment #o refers to the content output from a Markdown A Markdown fragment identifier is a sequence of characters that
processor, which is governed by the output-type parameter. A specific identifies some area of the Markdown content. Each Markdown variant
area of the output can be identified with a sub-fragment identifier can formally define a syntax for such fragment identifiers. (In
delimited by a second "#" character. The encoding and semantics of practice, identifiers that are similar to HTML's anchors are used by
sub-fragment identifiers are also governed by the output-type many variants, usually by surrounding the identifier with "{#" and
parameter. Examples: when the output-type is text/html [RFC2854], "}" and placing the production at the end of a line that comprises
#o#section6 identifies the named anchor "section6" specified by the particular kinds of content, such as a header, table, or image.)
input that the Markdown processor converts to <a [[NB: citation necessary to PHP Markdown Extra as an exemplary
name=section6>...</a>. When the output-type is application/pdf syntax?]]
[RFC3778], #o#page=6 causes the sixth page to open.
When the output-type is "text/markdown" (regardless of parameters), When encoded in a URI, the production SHALL conform to the fragment
the #o fragment identifier has no semantics; generators MUST use #t production of [RFC3986] (specifically: pchar, "/", and "?"
in lieu of #o. characters). Characters that are outside of that production SHALL be
percent-encoded. 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. Variants are free to specify
how fragment identifiers are compared. In the absence of a variant-
specific rule, fragment identifiers SHOULD be considered case-
sensitive, which maintains consistency with HTML. [[NB: citation
necessary to HTML4/HTML5?]]
4.3. #l and #ldef At least the first equals sign "=" SHOULD be percent-encoded to
prevent ambiguity as described in the following section.
The fragment prefix #l refers to links by their link identifiers. The 4.2. Parameters
sub-component of this identifier is delimited by a second "#"
character, followed by the encoded link identifier, optionally
followed by a 1-based index number. Without the index number, the
fragment refers to all such identified links. Example: #l#eS matches
links such as "The rain in [Spain][ES]" and "The word [es][] means
'is' in Spanish." #l#es#2 only matches the second instance of the
"es" link identifier.
The fragment prefix #ldef refers to link reference definitions. The Similar to application/pdf [RFC3778] and text/plain [RFC5147], this
sub-component of this identifier is delimited by a second "#" registration permits a parameter syntax for fragment identifiers. The
character, followed by the encoded link identifier. There is no index syntax is a parameter name, the equals sign "=" (which MUST NOT be
number; in the case of multiple link reference definitions, the last percent-encoded), and a parameter value. To the extent that multiple
definition wins. parameters can appear in a fragment production, the parameters SHALL
be separated by the ampersand "&" (which MUST NOT be percent-
encoded).
Both the #l and #ldef REQUIRE that "#" characters be percent-encoded The only parameter defined in this registration is "line", which has
if they are part of the link identifier. The percent-encoding of the same meaning as [RFC5147] (i.e., counting is zero-based). For
other characters follow the regular rules of [RFC3986]. [MDSYNTAX] example: "#line=10" identifies the eleventh line of Markdown input.
states that identifiers (or names) "may consist of letters, numbers, Implementers should take heed that different environments and
spaces, and punctuation--but they are NOT case sensitive." Characters character sets may have a wide range of code sequences to divide
outside of the URI character set SHALL be percent-encoded with the lines.
same encoding as the Markdown content. For maximum compatibility and
readability, authors who intend to reference links in fragment
identifiers SHOULD limit themselves to URI characters that do not
require percent-encoding.
4.4. Other Fragment Identifiers Markdown variants are free to define additional parameters.
Specific syntaxes may define additional fragment identifiers specific [[NB: This draft does not import all of text/plain's fragment
to the syntax. For example, a syntax that incorporates "header" identifier schemes, mainly because the utility of the other schemes
information might consider #h to refer to the "header" part, and #b is far from obvious. Implementing line= is not difficult but char= is
to refer to the "body" part. 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.]]
5. Example 5. Example
The following is an example of Markdown as an e-mail attachment: The following is an example of Markdown as an e-mail attachment:
MIME-Version: 1.0 MIME-Version: 1.0
Content-Type: text/markdown; charset=UTF-8; syntax=Original; Content-Type: text/markdown; charset=UTF-8; syntax=Original;
output-type="application/xhtml+xml" output-type="application/xhtml+xml"
Content-Disposition: attachment; filename=readme.md Content-Disposition: attachment; filename=readme.md
skipping to change at page 15, line 22 skipping to change at page 10, line 6
has more information. has more information.
[fOo]: http://example.com/loc 'Will Not Work with Markdown.pl-1.0.1' [fOo]: http://example.com/loc 'Will Not Work with Markdown.pl-1.0.1'
6. IANA Considerations 6. IANA Considerations
IANA is asked to register the media type text/markdown in the IANA is asked to register the media type text/markdown in the
Standards tree using the application provided in Section 2 of this Standards tree using the application provided in Section 2 of this
document. document.
IANA is also asked to establish a subtype registry called "Markdown 6.1. Markdown Variants
Syntaxes". Each entry in this registry shall consist of a syntax
identifier and information about the syntax, as follows:
6.1. Syntax Template
{if provisional}
PROVISIONAL REGISTRATION EXPIRES [YYYY-MM-DD date format]
Identifier: [Identifier]
Description: [Concise, prose description of the syntax, with
emphasis on its purpose and notable variations
from [MDSYNTAX] or another syntax. If the syntax
permits structured data, this fact ought to be
included. Other Markdown syntaxes may be referenced
by quoting their registered identifiers.]
Documentation: [References to documentation.]
Community of Use: [Concise, prose description of the
community of use, such as
"scholarly publications" or "screenwriting".
"General" may be entered if the community
encompasses general users of the Internet.]
[[TODO: Users (screenwriters) or use cases
(screenwriting)?]]
[[NB: Should Versions: and Extensions: be {optional} and
therefore omittable, or should they have "None." to
indicate that no versions or extensions apply?]]
Versions:
{for each version}
Identifier: [Identifier]
Description: [Optional, concise, prose description of the
version. "N/A" SHALL be used to indicate no description.]
Extensions:
{for each extension}
Identifier: [Identifier]
Syntax:
{if Enabled}
Enabled
{if Enabled, with String}
Enabled, with String: [prose description of what the
string is (not what it does)]
{if Enabled, with URI}
Enabled, with URI: [prose description of what the URI
is (not what it does)]
Description: [Concise, prose description of the extension,
i.e., what it does.]
Documentation: [References to documentation.]
Anticipated Output Types:
{for each output-type}
[media type]
{optional} [prose description of parameter considerations]
{optional}
Additional Fragment Identifiers:
[Prose description of additional fragment identifiers,
sufficient for interoperability.]
Responsible Parties:
{for each party}
([type: individual, corporate, representative])
[Name] <contact info 1>...<contact info n>
Currently Maintained? [Yes/No]
{optional}
Implementations:
{for each implementation}
Name: [Name]
Version(s): [Significant version or versions that
implement the syntax]
Type: ["Processor" or some other type]
References: <contact info 1>...<contact info n>
Purpose: [Concise, prose description of the implementation.]
A responsible party can be an individual author or maintainer, a
corporate author or maintainer (plus an individual contact), or a
representative of a community of interest dedicated to the Markdown
syntax.
The Versions, Extensions, Additional Fragment Identifiers, and
Implementations sections are optional.
6.2. Initial Registration
The registry shall have the following initial registration;
implementations conforming to this document MUST handle this syntax.
[MDMTUSES] provides additional exemplary syntaxes.
Identifier: Original
Description: Gruber's original Markdown syntax.
Documentation:
[MDSYNTAX]. For the "2004" version, the documentation is
provided in HTML and in Markdown, as follows:
syntax: Content-Type: text/html; charset=UTF-8
Accessed at October 12, 2014 8:27 PM (-0700)
38570 bytes
SHA-256 hash: B2EC2A62 3257F164 FBC88AE8 C7E76F3F
80F16845 105D9F3E 3E8CE25B 6F0CB33B
syntax.text: Content-Type: text/plain; charset=UTF-8 IANA is also asked to establish a registry called "Markdown
(actually text/markdown; Variants". While the registry is being created in the context of the
syntax=Original; text/markdown media type, the registry is intended for broad
output-type="text/markdown") community use, so protocols and systems that do not rely on Internet
Accessed at October 12, 2014 8:27 PM (-0700) media types can still tag Markdown content with a common variant
27784 bytes identifier. Each entry in this registry shall consist of basic
SHA-256 hash: 01A6A07A F51838E1 8749454B 06D716BC information about the variant:
B1BC0EAA A21B67B7 D6FB5A6B 4FFB5D5B
Community of Use: General. Identifier
Name
Description
References
Contact Information
Expiration Date (if provisional)
Versions: Variants that have additional media type parameters or fragment
Identifier: 2004 identifier considerations SHOULD describe them in detail in the
Description: [MDSYNTAX] as it (is rumored to have) existed Description field.
since December 14, 2004, corresponding to
Markdown.pl 1.0.1. The version "2004" SHOULD NOT
be specified until further notice; is is only
documented for completeness (in case Gruber
revises the syntax with material contradictions).
Anticipated Output Types: While the variant parameter is "plain US-ASCII" (see registration
text/html template), the Identifier field (and by implication, all registered
application/xhtml+xml identifiers) SHALL conform to the ABNF:
Responsible Parties: ALPHA [*(ALPHA / DIGIT / "-" / "." / "_" / "~") (ALPHA / DIGIT)]
(individual) John Gruber <http://daringfireball.net/> [[NB: Be less restrictive, maybe reuse some other common ABNF]]
<comments@daringfireball.net>
Currently Maintained? No I.e., the identifier MUST start with a letter and MAY contain
punctuation in the middle, but not at the end: the last character
MUST be alphanumeric. Since the identifier MAY be displayed to a
user--particularly in cases where the receiver does not recognize the
identifier--the identifier SHOULD be rationally related to the
vernacular name of the variant.
Implementations: The Name, Description, References, and Contact Information fields
Name: Markdown.pl SHALL be in a Unicode character set (e.g., UTF-8).
Version(s): 1.0.1, 1.0.2b8
Type: Processor
References: [MARKDOWN]
Purpose: Converts Markdown to HTML or XHTML circa 2004.
The argument "--html4tags" causes HTML output.
6.3. Reserved Identifiers 6.2. Reserved Identifiers
The registry SHALL have the following identifiers RESERVED. No one is The registry SHALL have the following identifiers RESERVED. No one is
allowed to register them (or any case variations of them). allowed to register them (or any case variations of them).
Standard Standard
Common Common
Markdown Markdown
6.4. Standard of Review 6.3. Standard of Review
Registrations are made on a First-Come, First-Served [RFC5226] basis Registrations are made on a First-Come, First-Served [RFC5226] basis
by anyone with a need to interoperate. While documentation is by anyone with a need to interoperate. While documentation is
required, any level of documentation is sufficient; thus, neither required, any level of documentation is sufficient; thus, neither
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.
Syntax, version, and extension identifiers MUST comply with the
syntaxes specified in this document. Additionally, the identifier
MUST NOT differ from other registered identifiers merely by case.
Identifiers MUST conform to [[TODO: PRECIS? STRINGPREP?]]. The
purpose of this requirement is to eliminate confusingly similar
identifiers, placing the burden on the registration process rather
than on syntax parameter parsers.
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]. [[NB: Two purposes: 1) to
deal with "harmful" registrations (stale references are not a deal with "harmful" registrations (stale references are not a
sufficient justification); 2) to deal with registrations that are sufficient justification); 2) to deal with registrations that are
IETF registrations, like RFC-related Markdown (but this could be IETF registrations, like RFC-related Markdown (but this could be
handled by listing the IETF as the contact organization, right?).]] handled by listing the IETF as the contact organization, right?).]]
All fields may be updated except the syntax identifier, which is All fields may be updated except the variant identifier, which is
permanent: not even case may be changed. permanent: not even case may be changed.
6.5. 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
syntax identifier. Provisional registrations include the ALL-CAPS variant identifier. Only the variant identifier and contact
legend as shown in Section 6.1. All fields are optional except for information fields are required; the rest are optional. Provisional
the syntax identifier and contact information. Provisional registrations expire after three months, after which time the variant
registrations expire after three months, after which time the syntax
identifier may be reused. identifier may be reused.
7. Security Considerations 7. Security Considerations
See the Security considerations entry in Section 2. See the Security considerations entry in Section 2.
8. References 8. References
8.1. Normative References 8.1. Normative References
skipping to change at page 21, line 29 skipping to change at page 13, line 34
[FOUNTAIN] Maschwitz, S. and J. August, "Fountain | A markup language [FOUNTAIN] Maschwitz, S. and J. August, "Fountain | A markup language
for screenwriting.", 2014, <http://fountain.io/>. for screenwriting.", 2014, <http://fountain.io/>.
[FTSYNTAX] Maschwitz, S. and J. August, "Syntax - Fountain | A markup [FTSYNTAX] Maschwitz, S. and J. August, "Syntax - Fountain | A markup
language for screenwriting.", 1.1, March 2014, language for screenwriting.", 1.1, March 2014,
<http://fountain.io/syntax>. <http://fountain.io/syntax>.
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-
02.txt. These technical changes were made: 03.txt. These technical changes were made:
1. Proposed that the document be split into two documents: the 1. Removed output-type optional parameter.
main document (which is normative), and a second document. The 2. Renamed syntax optional parameter to variant.
second document (draft-seantek-text-markdown-use-cases-00) 3. Defined variant optional parameter as discussed on mailing
[MDMTUSES] provides additional background information, list.
suggestions for preserving metadata, registration templates 4. Removed Section 3 (which may be replaced with Content-
for common Markdown syntaxes, and examples for common Markdown Disposition/preview-type in the future).
syntaxes. RFC 2119 key words are not included in draft- 5. Redid the fragment identifier considerations, simplifying the
seantek-text-markdown-use-cases because this content is not specification considerably.
normative (at least, not as normative) compared with the main 6. Discussed the meaning of "variant" in the context of Markdown.
document. 7. Redefined the IANA registry as "Markdown Variants" and
2. De-emphasized Unicode (and UTF-8 encoding) after close expanded its applicability outside of this particular media
consideration of the original [MDSYNTAX], and the various type.
proposed extensions to Markdown in the intervening time. 8. Drastically simplified the registration template.
"CommonMark", for example, places stronger emphasizes on
Unicode (and UTF-8).
3. Deleted processor parameter.
4. Renamed flavor parameter to syntax parameter.
5. Renamed "rules" to "extensions" in the syntax parameter.
6. Parameterized "extensions" so that it can have a string or a
URI.
7. Simplified the syntax parameter (compared to draft-02, in any
event) with fewer exceptional cases in the ABNF.
8. Rewrote significant parts of the output-type parameter, and
gave text/markdown additional explanation.
9. Rewrote the introduction so that it is much shorter.
10. Moved the example towards the end.
11. Added Fragment Identifier Considerations.
12. Consolidated the Security Considerations into the registration
template.
13. Rewrote the IANA Considerations section so that it only
creates one new registry.
14. Redefined the flavors registry (now called the Markdown
Syntaxes registry).
15. Rewrote the "Original" syntax registration to conform to the
new registration template.
16. Added a discussion and example of the Paradigmatic Use Case
(Markdown Editors).
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. 37 change blocks. 
542 lines changed or deleted 147 lines changed or added

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