draft-ietf-appsawg-text-markdown-01.txt   draft-ietf-appsawg-text-markdown-02.txt 
Applications Area Working Group S. Leonard Applications Area Working Group S. Leonard
Internet-Draft Penango, Inc. Internet-Draft Penango, Inc.
Intended Status: Informational September 9, 2014 Intended Status: Informational September 22, 2014
Expires: March 13, 2015 Expires: March 26, 2015
The text/markdown Media Type The text/markdown Media Type
draft-ietf-appsawg-text-markdown-01.txt draft-ietf-appsawg-text-markdown-02.txt
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 5 skipping to change at page 1, line 47
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
described in the Simplified BSD License. described in the Simplified BSD License.
[[TODO: add table of contents.]]
1. Introduction 1. Introduction
1.1. On Formats
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.
Plain text provides /some/ fixed facilities for formatting Plain text provides /some/ fixed facilities for formatting
instructions, namely codes in the character set that have meanings instructions, namely codes in the character set that have meanings
other than "represent this character on the output medium"; however, other than "represent this character on the output medium"; however,
these facilities are not particularly extensible. Compare with these facilities are not particularly extensible. Compare with
[RFC6838] Section 4.2.1. (Applications may neuter the effects of [RFC6838] Section 4.2.1. Applications may neuter the effects of these
these special characters by prohibiting them or by ignoring their special characters by prohibiting them or by ignoring their dictated
dictated meanings, as is the case with how modern applications treat meanings, as is the case with how modern applications treat most
most control characters in US-ASCII.) On this end, any text reader or control characters in US-ASCII. On this end, any text reader or
editor that interprets the character set can be used to see or editor that interprets the character set can be used to see or
manipulate the text. If some characters are corrupted, the corruption manipulate the text. If some characters are corrupted, the corruption
is unlikely to affect the ability of a computer system to process the is unlikely to affect the ability of a computer system to process the
text (even if the human meaning is changed). text (even if the human meaning is changed).
On the other end is binary format: a sequence of instructions On the other end is binary format: a sequence of instructions
intended for some computer application to interpret and act upon. intended for some computer application to interpret and act upon.
Binary formats are flexible in that they can store non-textual data Binary formats are flexible in that they can store non-textual data
efficiently (perhaps storing no text at all, or only storing certain efficiently (perhaps storing no text at all, or only storing certain
kinds of text for very specialized purposes). Binary formats require kinds of text for very specialized purposes). Binary formats require
skipping to change at page 2, line 51 skipping to change at page 3, line 4
input mechanism), a user can enter these textual characters to input mechanism), a user can enter these textual characters to
express the non-textual meanings. For example, a character like "<" express the non-textual meanings. For example, a character like "<"
no longer means "LESS-THAN SIGN"; it means the start of a tag or no longer means "LESS-THAN SIGN"; it means the start of a tag or
element that affects the document in some way. element that affects the document in some way.
On the formal end of the spectrum is markup, a family of languages On the formal end of the spectrum is markup, a family of languages
for annotating a document in such a way that the annotations are for annotating a document in such a way that the annotations are
syntactically distinguishable from the text. Markup languages are syntactically distinguishable from the text. Markup languages are
(reasonably) well-specified and tend to follow (mostly) standardized (reasonably) well-specified and tend to follow (mostly) standardized
syntax rules. Examples of markup languages include SGML, HTML, XML, syntax rules. Examples of markup languages include SGML, HTML, XML,
and LaTeX. Standardized rules lead to interoperability between markup and LaTeX. [[TODO: CITE.]] Standardized rules lead to
processors, but a skill requirement for new (human) users of the interoperability between markup processors, but a skill requirement
language that they learn these rules in order to do useful work. This for new (human) users of the language that they learn these rules in
imposition makes markup less accessible for non-technical users order to do useful work. This imposition makes markup less accessible
(i.e., users who are unwilling or unable to invest in the requisite for non-technical users (i.e., users who are unwilling or unable to
skill development). invest in the requisite skill development).
informal /---------formatted text----------\ formal informal /---------formatted text----------\ formal
<------v-------------v-------------v-----------------------v----> <------v-------------v-------------v-----------------------v---->
plain text informal markup formal markup binary format plain text informal markup formal markup binary format
(Markdown) (HTML, XML, etc.) (Markdown) (HTML, XML, etc.)
Figure 1: Degrees of Formality in Data Storage Formats for Text Figure 1: Degrees of Formality in Data Storage Formats for Text
On the informal end of the spectrum are lightweight markup languages. On the informal end of the spectrum are lightweight markup languages.
In comparison with formal markup like XML, lightweight markup uses In comparison with formal markup like XML, lightweight markup uses
simple syntax, and is designed to be easy for humans to enter with simple syntax, and is designed to be easy for humans to enter with
basic text editors. Markdown, the subject of this document, is an basic text editors. Markdown, the subject of this document, is an
/informal/ plain text formatting syntax that is intentionally /informal/ plain text formatting syntax that is intentionally
targeted at non-technical users (i.e., users upon whom little to no targeted at non-technical users (i.e., users upon whom little to no
skill development is imposed) using unspecialized tools (i.e., text skill development is imposed) using unspecialized tools (i.e., text
boxes). Jeff Atwood once described these informal markup languages as boxes). Jeff Atwood once described these informal markup languages as
"humane" [HUMANE]. "humane" [HUMANE].
1.2. Markdown Design Philosophy
Markdown specifically is a family of syntaxes that are based on the Markdown specifically is a family of syntaxes that are based on the
original work of John Gruber with substantial contributions from original work of John Gruber with substantial contributions from
Aaron Swartz, released in 2004 [MARKDOWN]. Since its release a number Aaron Swartz, released in 2004 [MARKDOWN]. Since its release a number
of web or web-facing applications have incorporated Markdown into of web or web-facing applications have incorporated Markdown into
their text entry systems, frequently with proprietary extensions. Fed their text entry systems, frequently with custom extensions. Fed up
up with the complexity and security pitfalls of formal markup with the complexity and security pitfalls of formal markup languages
languages (e.g., HTML5) and proprietary binary formats (e.g., (e.g., HTML5) and proprietary binary formats (e.g., commercial word
commercial word processing software), yet unwilling to be confined to processing software), yet unwilling to be confined to the
the restrictions of plain text, many users have turned to Markdown restrictions of plain text, many users have turned to Markdown for
for document processing. Whole toolchains now exist to support document processing. Whole toolchains now exist to support Markdown
Markdown for online and offline projects. for online and offline projects.
Due to Markdown's intentional informality, there is no standard Informality is a bedrock premise of Gruber's design. Gruber created
specifying the Markdown syntax, and no governing body that guides or Markdown after disastrous experiences with strict XML and XHTML
impedes its development. Markdown works for users for two key processing of syndicated feeds. In Mark Pilgrim's "thought
reasons. First, the markup instructions (in text) look similar to the experiment", several websites went down because one site included
markup that they represent; therefore the cognitive burden to learn invalid XHTML in a blog post, which was automatically copied via
the syntax is very low. Second, the primary arbiter of the syntax's trackbacks across other sites [DIN2MD]. These scenarios led Gruber to
success is *running code*. The tool that converts the Markdown to a believe that clients (e.g., web browsers) SHOULD try to make sense of
presentable format, and not a series of formal pronouncements by a data that they receive, rather than rejecting data simply because it
standards body, is the basis for whether syntactic elements matter. fails to adhere to strict, unforgiving standards. (In [DIN2MD],
Gruber compared Postel's Law [RFC0793] with the XML standard, which
says: "Once a fatal error is detected [...] the processor MUST NOT
continue normal processing" [XML1.0-3].) As a result, there is no
such thing as "invalid" Markdown; there is no standard demanding
adherence to the Markdown syntax; there is no governing body that
guides or impedes its development. If the Markdown syntax does not
result in the "right" output (defined as output that the author
wants, not output that adheres to some dictated system of rules),
Gruber's view is that the author either should keep on experimenting,
or should change the processor to address the author's particular
needs (see [MARKDOWN] Readme and [MD102b8] perldoc; see also
[CATPICS]).
1.3. Uses of Markdown
Since its introduction in 2004, Markdown has enjoyed remarkable
success. Markdown works for users for three key reasons. First, the
markup instructions (in text) look similar to the markup that they
represent; therefore the cognitive burden to learn the syntax is low.
Second, the primary arbiter of the syntax's success is *running
code*. The tool that converts the Markdown to a presentable format,
and not a series of formal pronouncements by a standards body, is the
basis for whether syntactic elements matter. Third, Markdown has
become something of an Internet meme [INETMEME], in that Markdown
gets received, reinterpreted, and reworked as additional communities
encounter it. There are communities that are using Markdown for
scholarly writing [CITE], for screenplays [CITE], for mathematical
formulae [CITE], and even for music annotation [CITE]. Clearly, a
screenwriter has no use for specialized Markdown syntax for
mathematicians; likewise, mathematicians do not need to identify
characters or props in common ways. The overall gist is that all of
these communities can take the common elements of Markdown (which are
rooted in the common elements of HTML circa 2004) and build on them
in ways that best fit their needs.
1.4. Uses of Labeling Markdown Content as text/markdown
To support identifying and conveying Markdown (as distinguished from To support identifying and conveying Markdown (as distinguished from
plain text), this document defines a media type and parameters that plain text), this document defines a media type and parameters that
indicate, in broad strokes, the author's intent on how to interpret indicate, in broad strokes, the author's intent on how to interpret
the Markdown. the Markdown. This registration draws particular inspiration from the
text/troff registration [RFC4263]; troff is an informal plain text
formatting syntax primarily intended for output to monospace line-
oriented printers and screen devices. In that sense, Markdown is a
kind of troff for modern computing.
1.1. Requirements Terminology The primary purpose of an Internet media type is to label "content"
on the Internet, as distinct from "files". Content is any computer-
readable format that can be represented as a primary sequence of
octets, along with type-specific metadata (parameters) and type-
agnostic metadata (protocol dependent). From this description, it is
apparent that appending ".markdown" to the end of a filename is not a
sufficient means to identify Markdown. Filenames are properties of
files in file systems, but Markdown frequently exists in databases or
content management systems (CMSes) where the file metaphor does not
apply. One CMS [RAILFROG] uses media types to select appropriate
processing, so a media type is necessary for the safe and
interoperable use of Markdown.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", Unlike complete HTML documents, [MDSYNTAX] provides no means to
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this include metadata into the content stream. Several derivative flavors
document are to be interpreted as described in [RFC2119]. have invented metadata incorporation schemes (e.g., [MULTIMD]), but
these schemes only address specific use cases. In general, the
metadata must be supplied via supplementary means in an encapsulating
protocol, format, or convention. The relationship between the content
and the metadata is not directly addressed by this specification;
however, by identifying Markdown with a media type, Markdown content
can participate as a first-class citizen with a wide spectrum of
metadata schemes.
2. Markdown Media Type Registration Applications Finally, registering a media type through the IETF process is not
trivial. Markdown can no longer be considered a "vendor"-specific
innovation, but the registration requirements even in the vendor tree
have proven to be overly burdensome for most Markdown implementers.
Moreover, registering hundreds of Markdown variants with distinct
media types would impede interoperability: virtually all Markdown
content can be processed by virtually any Markdown processor, with
varying degrees of success. The goal of this specification is to
reduce all of these burdens by having one media type that
accommodates diversity and eases registration.
This section provides the media type registration application for the 1.3. Requirements Terminology
text/markdown media type (see [RFC6838], Section 5.6).
Type name: text 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].
Subtype name: markdown 2. Example
Required parameters: charset. Per Section 4.2.1 of [RFC6838], charset The following is an example of Markdown as an e-mail attachment:
is REQUIRED. There is no default value. UTF-8 is RECOMMENDED;
however, neither [MDSYNTAX] nor popular implementations at the time
of this registration actually require or assume any particular
encoding. In fact, many Markdown processors can get along just fine
by operating on character codes that lie in the Portable Character
Set (i.e., printable US-ASCII), blissfully oblivious to coded values
outside of that range.
Optional parameters: MIME-Version: 1.0
Content-Type: text/markdown; charset=UTF-8; flavor=Original;
processor="Markdown.pl-1.0.2b8 --html4tags"
Content-Disposition: attachment; filename=readme.md
The following parameters reflect how the author intends the Sample HTML 4 Markdown
content to be processed. If rules and processor parameters are =============
both supplied, the processor parameters take precedence.
rules: A whitespace-delimited list of Markdown processing rules This is some sample Markdown. [Hooray!][foo]
that apply to this content. This parameter represents the intent (Remember that link names are not case-sensitive.)
of the author, namely, that the Markdown will be interpreted
"best" (i.e., as the author intended) when processed with the
rules as specified and ordered in this list. Identifiers MUST
match the <token> production of [RFC2045]; whitespace MUST match
the <FWS> production of [RFC5322].
Each identifier specifies a set of processing rules that are to Bulleted Lists
be applied to the content during a processing operation. Rules -------
are prioritized in order--later rules override earlier rules. For
example, if this parameter is "Example1 Example2", and both
Example1 and Example2 have specific rules to process { }-
delimited content in conflicting ways, then the author's intent
is to apply Example2's rules, not Example1's rules. However, the
author intends for Example1's other rules (for example, to
process "fenced code blocks") that are not overridden by Example2
to be applied to the content.
Rule identifiers are drawn from and registered in the IANA Here are some bulleted lists...
registry discussed below. Rule identifiers that represent
significant variations of Markdown SHOULD begin with a capital
letter, e.g., "GitHub", "Original", "Multi". Rule identifiers
that represent single or small collections of rules SHOULD begin
with a lowercase letter, e.g., "fenced-code-blocks", "fancy-
lists", "strikeout".
When this parameter conveyed (even if empty), the implicit first * One Potato
rule is "Original", namely, the original Markdown rules provided * Two Potato
in John Gruber's Markdown Syntax from 2004 [MDSYNTAX]. When this * Three Potato
parameter is not conveyed, the author does not express any intent
about which rules apply: [MDSYNTAX] may not necessarily be the
author's intent.
In practice, Markdown implementations that are aware of this - One Tomato
parameter will only be able to process a limited list of rules in - Two Tomato
an automated fashion. Therefore, when composing this parameter, - Three Tomato
it is RECOMMENDED that the composing process limit itself to
small lists of broadly recognizable rules, namely lists with just
one item (specifically, some major variation of Markdown).
processor: An identifier for the specific Markdown implementation More Information
that processes the Markdown into another format, such as HTML. If -----------
conveyed, this value cannot be empty. If not conveyed, the author
does not express any intent about which processor should be used.
Processor identifiers are registered in the IANA registry [.markdown, .md](http://daringfireball.net/projects/markdown/)
discussed below. Each processor registration (which is expected has more information.
to be updated over time) also defines the versions and arguments
that are considered valid. The repertoire of this string is any
number of characters (e.g., any Unicode character); however,
registrations SHOULD stick to US-ASCII-based strings unless there
is a compelling reason to do otherwise.
processor-ver: An identifier for the version of the processor [fOo]: http://example.com/some/foo/location
identified in the processor parameter. If conveyed, this value 'This Title Will Not Work with Markdown.pl-1.0.1'
cannot be empty. If not conveyed, the author does not express any
intent regarding a particular version to be used. This parameter
has no meaning if it is conveyed without a sibling processor
parameter.
For purposes of this specification, the version is a string; the 3. Markdown Media Type Registration Application
set of valid strings are registered and updated as a part of the
processor registration. A version "2.0" does not necessarily
imply that version 2.0 of an executable should be used instead of
2.0.1, 2.1, or even 3.0. If the processor has a way to be invoked
"as if" it is a different version (e.g., version 3.0 of a
processor can process some content "as if" it were 2.0), then the
receiver is free to use that invocation method. Updates to
processor registrations SHOULD only add new versions when those
new versions have a material difference on the interpretation of
the Markdown content. If a processor has a version 2014.10 and a
version 2014.11, for example, but 2014.11 only provides security
updates, then the processor registration SHOULD NOT have a
separate registration for the 2014.11 version.
The repertoire of this string is any number of characters (e.g., This section provides the media type registration application for the
any Unicode character); however, registrations SHOULD stick to text/markdown media type (see [RFC6838], Section 5.6).
US-ASCII-based strings unless there is a compelling reason to do
otherwise.
processor-args: A string conforming to a subset of the POSIX Shell Type name: text
Command Language in Volume 3, Chapter 2 of [POSIX.1-2008] for
arguments that are to be passed in an invocation to the
processor. The format of this parameter also has a facility to
reference resources by URI. [[TODO: Put in a separate section?
[[Section X]] discusses the details of this parameter.]]
If conveyed but empty, the author's intent is to turn off any Subtype name: markdown
optional arguments that the receiver would typically pass to the
processor. If not conveyed, the author does not express any
intent regarding particular arguments to be used. This parameter
has no meaning if it is conveyed without a sibling processor
parameter.
If conveyed and not empty, the string MUST be parseable to the Required parameters: charset. Per Section 4.2.1 of [RFC6838],
<cmd_suffix> item in Volume 3, Section 2.10.2 of [POSIX.1-2008] charset is REQUIRED. There is no default value. UTF-8 is
with accommodations for embedded URIs as specified below; RECOMMENDED; however, neither [MDSYNTAX] nor popular
however, <io_redirect> items MUST NOT appear. Effectively, the implementations at the time of this registration actually require
string is a sequence of <WORD> tokens. The string MUST NOT or assume any particular encoding. In fact, many Markdown
contain any sequences that would cause any shell processing other processors can get along just fine by operating on character codes
than newline and quote removal. For example, the string MUST NOT that lie in the Portable Character Set (i.e., printable US-ASCII),
contain redirects, pipelines, or comments. Section 2.6 Word blissfully oblivious to coded values outside of that range.
Expansions (Section 2.6.7 Quote Removal notwithstanding) are
right out!
A processor-args string MUST NOT include arguments regarding the Optional parameters:
input content or the output markup. For example, if a processor
normally reads Markdown input using the arguments "-i filename"
or "< filename" (i.e., from standard input), those arguments MUST
be omitted. A processor-args string MUST NOT include arguments
that have no bearing on the output, such as arguments that
control verbosity of the processor (-v) or that cause side-
effects (such as writing diagnostic messages to some other file).
Of course, if warnings or errors are signaled within the output,
arguments enabling that output MAY be used.
Some authors may wish to combine inputs from multiple resources. The following parameters reflect the author's intent regarding the
For security reasons, file references MUST NOT be included in content. A detailed specification can be found in Section 4.
processor-args. Instead, references to resources are encoded in
strictly-conforming URIs [RFC3986] delimited with angle brackets
<>, which MUST NOT be escaped according to [POSIX.1-2008] (i.e.,
the brackets cannot be escaped with preceding backslash
characters). A receiver may retrieve the resource specified by
the URI, and then pass it to the processor in an appropriate way,
such as via a temporary file. The intent of this option is to
provide a means to include additional data that might accompany
the Markdown content, for example, using cid: or mid: URLs
[RFC2392] in the context of MIME messages.
Prior to invoking a Markdown processor, the preprocess routine flavor: The variant, or "flavor" of the Markdown content, with
MUST first analyze the processor-args string for URIs. Depending optional rules (qualifiers). Default value: "Original".
on privacy and security considerations, the routine either
dereferences the URIs--retrieving the contents--or rejects the
string. The URIs (including <> delimiters) shall then be replaced
with appropriate, complete file paths or descriptors, and the
resulting string shall be checked for conformance with a sequence
of arguments as defined by the POSIX Shell Command Language in
Volume 3, Chapter 2 of [POSIX.1-2008].
Not all processors are literally invoked from an operating processor: A specific Markdown implementation, with optional
system's command facility; some may be invoked from within arguments. Default value: none (receiver's choice).
another process as a library call. In such cases, the processor
SHOULD be invoked in such a way to communicate the semantics of
the arguments. One strategy might be to provide a library call
with one or more explicit argument parameters; for example,
either a string type of parameter (if the library does the
parsing), or an "argc" plus "argv" pair of parameters (if the
caller does the parsing). Another strategy might be to provide
several different library calls, which the caller would choose to
invoke depending on the directions of the arguments. In the
registration for the processor, argument handling MUST be
discussed.
The repertoire of this string is any number of characters that output-type: The Content-Type (Internet media type) of the output,
conform to a [POSIX.1-2008] implementation. (Note that the NULL with optional parameters. Default value: "text/html".
character is excluded, because POSIX uses it to terminate
strings.) When characters in the arguments lie outside of the
Portable Character Set (i.e., outside of US-ASCII), this
parameter MUST be encoded to preserve those characters and to
signal the required encoding to the receiver. Then, the processor
MUST be invoked in such a way that it properly understands these
characters in the required encoding (or a superset thereof). When
encoded in a MIME Content-Type header, use of [RFC2231] is
RECOMMENDED. The rationale for this (convoluted) requirement is
because POSIX defines command lines and arguments with the C
language char * data type, but leaves the character set dependent
on locale environment variables (see Volume 1, Chapter 7 of
[POSIX.1-2008]). Therefore, it is not sufficient to pass
arguments from the processor-args parameter "as is" to the
processor: the routine MUST change the locale or transform the
arguments to an appropriate character encoding so that there is
no ambiguity.
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
directionality of the text. An editor for normal text would already directionality of the text. An editor for normal text would already
take these control characters into consideration, however. take these control characters into consideration, however.
Markdown interpreted as a precursor to other formats, such as HTML, Markdown interpreted as a precursor to other formats, such as HTML,
skipping to change at page 8, line 41 skipping to change at page 7, line 51
personally identifiable information. Markdown also can contain personally identifiable information. Markdown also can contain
islands of formal markup, such as HTML. These islands of formal islands of formal markup, such as HTML. These islands of formal
markup may be passed as-is, transformed, or ignored (perhaps markup may be passed as-is, transformed, or ignored (perhaps
because the islands are conditional or incompatible) when the because the islands are conditional or incompatible) when the
Markdown is interpreted into the target format. Since Markdown may Markdown is interpreted into the target format. Since Markdown may
have different interpretations depending on the tool and the have different interpretations depending on the tool and the
environment, a better approach is to analyze (and sanitize or environment, a better approach is to analyze (and sanitize or
block) the output markup, rather than attempting to analyze the block) the output markup, rather than attempting to analyze the
Markdown. Markdown.
[[TODO: discuss the implications of processor-args, and Specific security considerations apply to the optional parameters;
safeguards.]] [[TODO: discuss the security implications of for details, consult Section 4.
combining supplementary resources in processor-args...the
supplementary resources could be config files or scripts.]] [[TODO:
discuss the privacy implications of dereferencing URIs.]]
Interoperability considerations: Interoperability considerations:
Markdown flavors are designed to be broadly compatible with humans Markdown flavors are designed to be broadly compatible with humans
("humane"), but not necessarily with each other. Therefore, syntax ("humane"), but not necessarily with each other. Therefore, syntax
in one Markdown flavor may be ignored or treated differently in in one Markdown flavor may be ignored or treated differently in
another flavor. The overall effect is a general degradation of the another flavor. The overall effect is a general degradation of the
output, proportional to the quantity of flavor-specific Markdown output, proportional to the quantity of flavor-specific Markdown
used in the text. When it is desirable to reflect the author's used in the text. When it is desirable to reflect the author's
intent in the output, stick with the flavor identified in the intent in the output, stick with the flavor identified in the
skipping to change at page 10, line 5 skipping to change at page 8, line 43
Sean Leonard <dev+ietf@seantek.com> Sean Leonard <dev+ietf@seantek.com>
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? Yes Provisional registration? Yes
3. Example 4. Optional Parameters
The following is an example of Markdown as an e-mail attachment: The following optional parameters can be used by an author to
indicate the author's intent regarding how the Markdown ought to be
processed. For security and accuracy, IANA registries will be
created. However, authors who wish to use custom values by private
agreement may do so via an extension mechanism; all unregistered
identifiers MUST start with an exclamation mark "!".
MIME-Version: 1.0 All identifiers are case-sensitive; receivers MUST compare for exact
Content-Type: text/markdown; charset=UTF-8; rules=GitHub equality. Identifiers MUST NOT be registered if another registration
Content-Disposition: attachment; filename=readme.md differs only in the casing, as these registrations may cause
confusion.
Sample GitHub Markdown The following ABNF definitions are used in this section:
=============
This is some sample GitHub Flavored Markdown (*GFM*). EXTCHAR = <any character outside the US-ASCII range,
The generated HTML is then run through filters in the essentially amounting to any Unicode
[html-pipeline](https://github.com/jch/html-pipeline) code point beyond U+007F without requiring
to perform things like [sanitization](#html-sanitization) and Unicode or any particular encoding>
[syntax highlighting](#syntax-highlighting).
Bulleted Lists REXTCHAR = <EXTCHAR without spaces (Zs category) or
------- control characters>
Here are some bulleted lists... Figure X: ABNF Used in This Section
* One Potato The discussion in this section presumes that the parameter values are
* Two Potato discrete strings. When encoded in protocols such as MIME [RFC2045],
* Three Potato however, the value strings MUST be escaped properly.
- One Tomato 4.1. flavor
- Two Tomato
- Three Tomato
More Information The flavor parameter indicates the Markdown variant in which the
----------- author composed the content. The overall intent of this parameter is
to provide a facility for Markdown tools, such as graphical editors,
to be able to broadly categorize the content and perform useful
services such as syntax highlighting without resorting to executing
the Markdown processor. Of course, actual recipients may use this
information for any useful purpose, including picking and configuring
an appropriate Markdown processor. The entire parameter is case-
sensitive.
[.markdown, .md](http://daringfireball.net/projects/markdown/) An IANA registry of flavors will be created as discussed in Section
has more information. 5. A flavor identifier is composed of two or more Unicode characters
excluding spaces (Zs category), control characters, the hyphen-minus
"-", quotation marks """, and the plus sign "+"; however, ASCII
characters alone SHOULD be used. Additionally, registered flavor
identifiers MUST NOT begin with "!", the exclamation mark. By
convention, flavor identifiers start with a capital letter (when
using Roman characters), but this is not a requirement. Unregistered
flavor identifiers MUST begin with "!" (plus two additional
characters).
4. IANA Considerations When omitted, the default value is "Original". Its meaning is covered
in Section 5. Generators MUST NOT emit empty flavor parameters, but
parsers MUST treat empty flavor parameters the same as if omitted.
The full ABNF of the flavor parameter is:
flavor-param = flavor *( *WSP rule ) *WSP
flavor = registered-fid / unregistered-fid
registered-fid = fid-char 1*("!" / fid-char)
unregistered-fid = "!" 2*fid-char
fid-char = %d35-%d42 / %d44 / %d46-%d126 / REXTCHAR
rule = "+" (should-rule / any-rule)
should-rule = should-rule-char [ *(should-rule-char / "_")
should-rule-char ]
any-rule = 1*rule-char
rule-char = %d35-%d42 / %d44-%d126 / REXTCHAR
Figure X: ABNF of the flavor parameter
4.1.1. flavor rules
[[TODO: consider. This section is mainly inspired from pandoc.]]
Most flavors are self-contained, with no options. However, some
flavors have optional rules that may be applied with discretion. For
those flavors where optional rules are an integral feature, the
author MAY indicate that those extra rules be applied in a plus sign-
delimited list.
Because Markdown has no inherent concept of validity, authors SHOULD
be aware that receivers are not required to honor these optional
rules--the special characters in the Markdown content may well be
interpreted as plain text, rather than Markdown markup. Generally
speaking, defining a new (simple) flavor is preferable to defining a
complex flavor with multiple optional rules.
A flavor rule identifier is composed of any sequence of Unicode
characters excluding spaces (Zs category), control characters,
quotation marks """, exclamation marks "!", and the plus sign "+";
however, lowercase ASCII letters and the underscore "_" alone SHOULD
be used, where the underscore SHOULD NOT be at the beginning or end.
The syntax for flavor rules derives in significant part from pandoc
[PANDOC].
[[TODO: There are no requirements about exclamation marks for
unregistered rules...flavor rules SHOULD be registered along with the
flavor, but a receiver does not need to reject the flavor parameter
simply because it does not recognize a rule...it can just ignore the
rule.]]
4.2. processor
The processor parameter indicates the specific Markdown
implementation that the author intends be used. The purpose of this
parameter is to control the automatic processing of Markdown into
some output format, but of course actual recipients may use this
information for any useful purpose. The entire parameter is case-
sensitive.
An IANA registry of processors will be created as discussed in
Section 5. A processor identifier is composed of two or more Unicode
characters excluding spaces (Zs category), control characters, the
hyphen-minus "-", quotation marks """, the less-than sign "<", and
the greater-than sign ">"; however, ASCII characters alone SHOULD be
used. Additionally, registered processor identifiers MUST NOT begin
with "!", the exclamation mark. Unregistered processor identifiers
MUST begin with "!" (plus two additional characters).
When omitted, the default value is to use whatever processor the
receiver prefers. Generators MUST NOT emit empty processor
parameters, but parsers MUST treat empty processor parameters the
same as if omitted.
The full ABNF of the processor parameter is:
processor-param = processor [ "-" version ]
*( 1*WSP argument ) *WSP
processor = registered-pid / unregistered-pid
registered-pid = pid-char 1*("!" / pid-char)
unregistered-pid = "!" 2*pid-char
version = pid-char *("!" / pid-char)
argument = regular-argument / uri-argument
regular-argument = 1*(regular-char / quoted-chars)
pid-char = %d35-%d44 / %d46-%d59 / %d61 /
%d63-126 / REXTCHAR
regular-char = %d33 / %d35-%d59 / %d61 / %d63-126 / REXTCHAR
quoted-chars = DQUOTE *pqcontent DQUOTE
pqcontent = %d1-%d33 / %d35-127 / EXTCHAR / DQUOTE DQUOTE
uri-argument = "<" URI-reference ">" ; from [RFC3986]
Figure X: processor parameter ABNF
4.2.1. processor version
For better precision, an author MAY include the processor version.
The version is delimited from the processor identifier with a hyphen-
minus "-"; the version string itself is an opaque string. Version
strings (e.g., "2.0", "3.0.5") are registered and updated along with
the processor registration. Updates to processor registrations SHOULD
only add new versions when those new versions have a material
difference on the interpretation of the Markdown content. If a
processor has a version "2014.10" and a version "2014.11", for
example, but "2014.11" only provides performance updates, then the
processor registration SHOULD NOT separately register the "2014.11"
version. The repertoire of the version string is the same as the
processor identifier (and like the processor identifier, ASCII
characters alone SHOULD be used).
A receiver that recognizes the processor but not the processor
version MAY use any version of the processor, preferably the latest
version.
4.2.2. processor arguments
Processor arguments MAY be supplied for finer-grained control over
how the processor behaves. Multiple arguments and URI references are
supported.
4.2.2.1. Quoted Arguments
According to the ABNF above, arguments are delimited by whitespace.
Quotation marks are used to support zero-length arguments, as well as
whitespace or quotation marks in a single argument. If a quotation
mark appears anywhere in the argument, the following text is
considered quoted; two successive quotation marks "" mean one
quotation mark. A single quotation mark ends the quoting. Because of
this rule, quotation marks do not have to appear at the termini of an
argument; embedded quotation marks start (and end) quoting within a
single argument. For example:
a""b
means:
ab
for the actual argument.
4.2.2.2. URI Reference Arguments
Certain processors can take supplementary content, such as metadata,
from other resources. To support these workflows, an author MAY use
the URI delimiters <> to signal a URI, such as cid: or mid: URLs
[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 receiver is to interpret this as a
request to retrieve the resource, and to supply that resource in a
local reference form that the processor can use (e.g., via a
temporary file). The URI MUST be entire argument; the URI cannot be
combined with other text to constitute the argument (and the ABNF
above supports this restriction). The reason for this restriction is
security, so that a maliciously constructed argument string cannot
resolve to some other file reference (such as parent directories like
../ or special files such as /dev/hd0). If the processor accepts URI
strings directly, the string is to be supplied as a regular string
without <> delimiters. For security reasons, direct file references
MUST NOT be included in the processor arguments.
The prior paragraph notwithstanding, certain workflows may require
file references. In such cases, file: URLs [RFC1738] (including
relative references) are appropriate. The receiver SHOULD apply the
same security and privacy analyses to file: URLs as it would to any
other URI.
4.2.2.3. Appropriate Arguments and Security Considerations
Not all arguments are appropriate for inclusion in the processor
parameter. Appropriate arguments are basically limited to those that
affect the output markup, without side-effects. Arguments MUST NOT
identify input sources or output destinations. For example, if a
processor normally reads Markdown input using the arguments "-i
filename" or "< filename" (i.e., from standard input), those
arguments MUST be omitted. Arguments that have no bearing on the
output MUST be omitted as well, such as arguments that control
verbosity of the processor (-v) or that cause side-effects (such as
writing diagnostic messages to some other file). Of course, if
warnings or errors are signaled within the output, arguments enabling
that output MAY be used.
When in doubt, a receiver SHOULD omit arguments with unknown or
undocumented effects, and MAY ignore author-supplied arguments
entirely, but SHALL NOT reorder arguments. An author has very little
assurance that a receiver will honor unregistered arguments.
Consequently, the burden is squarely on processor registrants
(Section 5.2) to document their arguments properly.
For security reasons, the parsed argument array (or a string
unambiguously representing the delimited argument array) MUST be
passed directly to the processor. Emitting the argument array as-is
in a batch script (for example) may cause risky side effects, such as
automatic substitutions, alias activation, or macro execution. The
arguments in this parameter MUST be encoded to preserve characters
outside of US-ASCII, and to signal the required encoding to the
receiver. When going between (system) processes, some implementations
may interpret character codes based on locale environment variables.
Therefore, it is not sufficient to pass arguments from this parameter
"as-is" to the processor: the routine MUST change the locale or
transform the arguments to an appropriate character encoding so that
there is no ambiguity. Furthermore, the NUL character (%d0, U+0000)
is not permitted because most common operating systems use that code
point as a delimiter.
4.2.3. Examples of processor parameters
[[TODO: provide examples.]]
4.3. output-type
The output-type parameter indicates the Internet media type (and
parameters) of the output from the processor.
When omitted, the default value is "text/html". Generators MUST NOT
emit empty output-type parameters, but parsers MUST treat empty
output-type parameters the same as if omitted.
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 [CITE], to PDF [CITE], to OPML [CITE], and even to
entire e-books [CITE].
Security provides a significant motivator for this parameter. Most
Markdown processors emit byte (octet) streams; without a well-defined
means for a Markdown processor to pass metadata onwards, it is
perilous for post-processing to assume that the content is always
HTML. A processor might emit PostScript (application/postscript)
content, for example, in which case an HTML sanitizer would fail to
excise dangerous instructions.
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. Processors or processor arguments that conflict with the
output-type parameter MUST be re-chosen, ignored, or rejected.
Although arbitrary optional 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]).
Markdown implementations for all kinds of formats already exist,
including formats that are not registered Internet media types, or
that are inexpressible as Internet media types. For example, one
Markdown processor for the mass media industry outputs formatted
screenplays [CITE to fountain.io]: none of applicable media types
application/pdf, text/html, or text/plain adequately distinguish this
kind of output. Such distinctions SHOULD be made in the processor
parameter (and to a lesser extent, the flavor parameter),
underscoring that the primary concern of the output-type parameter is
making technical and security-related decisions.
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.
[[TODO: consider.]]
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. In this case, the processor choice has little
practical effect because the Markdown is not actually processed, but
other tools can use the flavor parameter (and secondarily if so
inclined, the processor parameter) to perform useful services such as
syntax highlighting. 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. 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.
5. 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 IANA is also asked to establish a subtype registry called "Markdown
Parameters". Entries in these registries is by Expert Review Parameters". The registry has two sub-registries: a registry of
[RFC5226]. The registry has two sub-registries: a registry of rules flavors and a registry of processors.
and a registry of processors.
4.1 Registry of Rules 5.1. Registry of Flavors
Each entry in this registry shall consist of a) a rule identifier and Each entry in this registry shall consist of a flavor identifier and
b) whether the rule is defined in the registry entry, or in some information about the flavor, as follows:
external document.
If the rule is defined in the registry entry, then the entry must 5.1.1. Flavor Template
also include: i) a list of rules in prose text, and ii) for each
rule, an example illustrating the rule. Additionally, each registry
entry shall describe in prose text iii) which rules take precedence
over other rules, or how conflicts between rules may be resolved. The
Expert will review the rule to determine whether the rule is
plausible and whether the rule can be implemented.
If the rule is defined in some external document, the Expert will Identifier: [Identifier]
determine whether the registration represents a bona-fide variation
of the Markdown syntax (i.e., neither a duplicate of an existing Description: [Concise, prose description of the syntax,
registration nor a syntax that is something other than Markdown; with emphasis on its purpose, the community
[MDSYNTAX] SHALL be used as a normative basis), a brief description, that it addresses, and notable variations
one or more responsible parties, whether the document is being from [MDSYNTAX] or another flavor.]
maintained at the time of registration, and the existence of at least
one complete tool (with or without documentation) that processes the Documentation: [References to documentation.]
Markdown syntax into a formal document language.
Rules:
{for each rule}
Identifier: [Identifier]
Description: [Concise, prose description of the rule.]
Documentation: [References to documentation.]
Responsible Parties:
{for each party}
([type: individual, corporate, representative])
[Name] <contact info 1>...<contact info n>
Currently Maintained? [Yes/No]
Tools:
{for each tool}
Name: [Name]
Version(s): [Significant version or versions that
implement the flavor]
Type: ["Processor" or some other type]
Reference(s): <contact info 1>...<contact info n>
Purpose: [Concise, prose description of the tool.]
A responsible party can be an individual author or maintainer, a A responsible party can be an individual author or maintainer, a
corporate author or maintainer (plus an individual contact), or a corporate author or maintainer (plus an individual contact), or a
representative of a community of interest dedicated to the Markdown representative of a community of interest dedicated to the Markdown
syntax. syntax.
The registry shall have the following initial value: Multiple tools MAY be listed, but only one is necessary for a
successful registration. If a tool is a Markdown processor, it MUST
be registered; however, any Markdown-related tool (for example,
graphical editors, emacs "major modes", web apps) is acceptable. The
purpose of the tool requirement is to ensure that the flavor is
actually used in practice.
Identifier: Original 5.1.2. Initial Registration
Description: The registry shall have the following initial registration:
The Markdown syntax as it exists in the Markdown 1.0.1 Perl script
at [MARKDOWN], with accompanying documentation at [MDSYNTAX].
Responsible Parties: Identifier: Original
(individual)
John Gruber <http://daringfireball.net/>
<comments@daringfireball.net>
Currently Maintained? No Description: Gruber's original Markdown syntax.
Tool: Documentation: [MDSYNTAX]
Name: Markdown 1.0.1
Reference: <http://daringfireball.net/projects/markdown/>
Purpose: Converts to HTML or XHTML circa 2004.
Additionally, the registry shall have the following identifiers Rules: None.
reserved for future versions of this draft:
Responsible Parties:
(individual) John Gruber <http://daringfireball.net/>
<comments@daringfireball.net>
Currently Maintained? No
Tools:
Name: Markdown.pl
Version(s): 1.0.1, 1.0.2b8
Type: Processor
Reference(s): <http://daringfireball.net/projects/markdown/>
Purpose: Converts Markdown to HTML or XHTML circa 2004.
5.1.3. Reserved Identifiers
The flavors registry SHALL have the following identifiers RESERVED.
No one is allowed to register them (or any case variations of them).
Standard Standard
Common Common
Regular Markdown
Community
Uniform
Vanilla
Compatible
Gruber
GitHub
Multi
PageDown
4.2 Registry of Processors 5.1.4. Standard of Review
Each entry in this registry shall consist of a) a processor Registrations are made by a highly constrained Expert Review
identifier, b) a concise description of the processor, c) one or more [RFC5226] that amounts more-or-less to First-Come, First-Served with
responsible parties, d) whether the processor is being maintained at sanity checking.
the time of the registration (or registration update), (optionally)
e) a list of version strings, and (optionally) f) documentation about
the arguments.
If arguments are to be used, documentation MUST be provided as a part The designated expert SHALL review the flavor registration. The
of the registry entry. However, the documentation MAY merely refer to identifier MUST comply with the syntax specified in this document.
external documentation, such as a manpage, webpage, or user manual. Additionally, the identifier MUST NOT differ from other registered
identifiers merely by case. The description and documentation SHOULD
provide sufficient guidance to an implementer to implement a tool to
handle the flavor. The designated expert SHOULD warn the registrant
if the description and documentation are inadequate; however,
inadequacy (in the opinion of the designated expert) will not bar a
registration.
[[TODO: figure out if the list should be more formal, so a receiver All references (including contact information) MUST be verified as
can validate the safety/correctness of the arguments before passing functional at the time of the registration.
them along.]]
5. Security Considerations If rules are included in the registration, the rule identifiers MUST
comply with the syntax specified in this document. The description
and documentation of each rule SHOULD provide sufficient guidance to
an implementer to implement a tool to handle the rule. The designated
expert SHOULD warn the registrant if the description and
documentation are inadequate; however, inadequacy (in the opinion of
the designated expert) will not bar a registration.
The designated expert MUST determine that all tools listed in the
registration are real implementations. If a tool is a Markdown
processor, the processor MUST be registered in the Registry of
Flavors in Section 5.2. The designated expert MAY request that the
registrant provide evidence that a tool actually works (for example,
that it passes certain test suites); however, the failure of a tool
to work according to the flavor registration will not bar a
registration. (For example, not even Gruber's own Markdown.pl
implementation complies with [MDSYNTAX]. C'est la vie!)
If a registration is being updated, the designated expert SHOULD
verify that the updating registrant matches the contact information
on the prior registration, and if not, that the updating registrant
has authority from the prior registrant to update it. All fields may
be updated except the Identifier, which is permanent: not even case
may be changed.
5.2. Registry of Processors
Each entry in this registry SHALL consist of a processor identifier
and information about the processor, as follows:
5.2.1. Processor Template
Identifier: [Identifier]
Description: [Concise, prose description of the processor,
with emphasis on its purpose, the community
that it addresses, and notable variations
from [MDSYNTAX] or another flavor.]
Documentation: [References to documentation.]
Versions:
{for each version}
Identifier: [Identifier]
Description: [Optional, concise, prose description of the
version. "N/A" SHALL be used to indicate no description.]
Arguments:
{in general}
Argument Ordering: [Concise, prose description of how
arguments need to be ordered.]
{for each argument}
Argument Syntax: [Syntax here; multiple consecutive argument
positions are allowed, separated by a single space. Use
braces for variable information (add : for example input),
<URI> for URI references, and .. for sequences of arguments
with # as a placeholder for the number of arguments or
..-.. to indicate the first character of the subsequent
argument that ends the sequence, e.g.:
-c
--title {title: "The Rain in Spain"}
--metadata <URI>
--bullet-chars:{#} {char 1}..{char #}
--verbs {verb: walk, run, sleep}..-..
]
Description: [Concise, prose description of the argument.]
Documentation: [References to documentation.]
Output Type(s): [Internet media types, comma-separated
(with optional LWSP)]
Security Considerations: [Sufficient description of risks and
other considerations; "N/A" or
"None" responses are insufficient.]
Responsible Parties:
{for each party}
([type: individual, corporate, representative])
[Name] <contact info 1>...<contact info n>
Currently Maintained? [Yes/No]
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
processor.
5.2.2. Initial Registration
The registry shall have the following initial registration:
Identifier: Markdown.pl
Description: Gruber's original Markdown processor, written in
Perl. Requires Perl 5.6.0 or later. "Welcome to
the 21st Century." Works with Movable Type 2.6+,
Blosxom 2.0+, BBEdit 6.1+, and the command-line.
Documentation: [MARKDOWN]
Versions:
Identifier: 1.0.1
Description: The 2004-12-17 version.
Identifier: 1.0.2b8
Description: The 2007-05-09 version. Fixes many bugs
and adds several new features; see
VERSION HISTORY in Markdown.pl.
Arguments:
Argument Syntax: --html4tags
Description:
"Use the --html4tags command-line switch to produce HTML
output from a Unix-style command line."
Without this argument, Markdown.pl outputs XHTML style
tags by default, e.g.: <br />. Even though XHTML style
is the default, the output SHOULD be analyzed as
text/html; the processor makes no attempt to make
its output well-formed application/html+xml
(not surprising--see the design philosophy).
Documentation: [MARKDOWN]
Output Type: text/html
Security Considerations: The security of this implementation
has not been fully analyzed.
Responsible Parties:
(individual) John Gruber <http://daringfireball.net/>
<comments@daringfireball.net>
Currently Maintained? No [[TODO: maybe?]]
5.2.3. Reserved Identifiers
The processors registry SHALL have the following identifiers
RESERVED. No one is allowed to register them (or any case variations
of them).
Standard
Markdown
md
5.2.4. Standard of Review
Registrations are First-Come, First-Served [RFC5226]. The checks
prescribed by this section can be performed automatically.
The identifier MUST comply with the syntax specified in this
document. Additionally, the identifier MUST NOT differ from other
registered identifiers merely by case. The description and
documentation SHOULD provide sufficient guidance to an implementer to
know how to invoke the processor and handle the output.
All references (including contact information) MUST be verified as
functional at the time of the registration.
If arguments are included in the registration, the Argument Syntax
MUST comply with the template instructions in Section 5.2.1. Each
description and documentation field SHOULD provide sufficient
guidance to an implementer to know how to invoke the processor and
handle the output.
The Security Considerations field is not optional; it MUST be
provided.
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. All fields may be updated except the
Identifier, which is permanent: not even case may be changed.
6. Security Considerations
See the answer to the Security Considerations template questions in See the answer to the Security Considerations template questions in
Section 2. Section 2.
6. References Security considerations for the optional parameters are integrated
throughout Section 4.
6.1. Normative References 7. References
[MARKDOWN] Gruber, J., "Daring Fireball: Markdown", WWW 7.1. Normative References
http://daringfireball.net/projects/markdown/, December
2004. [MARKDOWN] Gruber, J., "Daring Fireball: Markdown", December 2004,
<http://daringfireball.net/projects/markdown/>.
[MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax [MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax
Documentation", WWW Documentation", December 2004,
<http://daringfireball.net/projects/markdown/syntax>, <http://daringfireball.net/projects/markdown/syntax>.
December 2004.
[POSIX.1-2008] IEEE Std 1003.1, 2013 Edition (incorporates IEEE Std [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
1003.1-2008 and IEEE Std 1003.1-2008/Cor 1-2013, "Standard Resource Locators (URL)", RFC 1738, December 1994.
for Information Technology - Portable Operating System
Interface (POSIX(R)) Base Specifications, Issue 7"
(incorporating Technical Corrigendum 1), April 2013.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
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.
[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
skipping to change at page 13, line 32 skipping to change at page 23, line 13
[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.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
October 2008. October 2008.
[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.
6.2. Informative References 7.2. Informative References
[HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", WWW [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/, May 2008. language/>.
[DIN2MD] Gruber, J., "Dive Into Markdown", March 2004,
<http://daringfireball.net/2004/03/dive_into_markdown>.
[MD102b8] Gruber, J., "[ANN] Markdown.pl 1.0.2b8", May 2007,
<http://six.pairlist.net/pipermail/markdown-discuss/2007-
May/000615.html>, <http://daringfireball.net/projects/
downloads/Markdown_1.0.2b8.tbz>.
[CATPICS] Gruber, J. and M. Arment, "The Talk Show: Ep. 88: 'Cat
Pictures' (Side 1)", July 2014,
<http://daringfireball.net/thetalkshow/2014/07/19/ep-088>.
[INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of
the word 'meme'", June 2013,
<http://www.wired.co.uk/news/archive/2013-06/20/richard-
dawkins-memes>, <http://www.webcitation.org/6HzDGE9Go>.
[MULTIMD] Penney, F., "MultiMarkdown", April 2014,
<http://fletcherpenney.net/multimarkdown/>.
[PANDOC] MacFarlane, J., "Pandoc", 2014,
<http://johnmacfarlane.net/pandoc/>.
[RAILFROG] Railfrog Team, "Railfrog", April 2009,
<http://railfrog.com/>.
[RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC
793, September 1981.
[RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource
Locators", RFC 2392, August 1998. Locators", RFC 2392, August 1998.
[RFC4263] Lilly, B., "Media Subtype Registration for Media Type
text/troff", RFC 4263, January 2006.
[XML1.0-3] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
F. Yergeau, "Extensible Markup Language (XML) 1.0 (Third
Edition)", World Wide Web Consortium Recommendation REC-
xml-20040204, February 2004,
<http://www.w3.org/TR/2004/REC-xml-20040204#dt-fatal>.
[TODO] [[Add remaining references.]]
Appendix A. Change Log Appendix A. Change Log
This draft is a continuation from draft-seantek-text-markdown-media- This draft is a continuation from draft-ietf-appsawg-text-markdown-
type-00.txt (since renamed). These technical changes were made: 01.txt. These technical changes were made:
1. The flavor parameter was replaced with the rules, processor, 1. The entire document was reorganized: optional parameters now
processor-ver, and processor-args parameters. have their own section, and the Introduction section is
2. The IANA Considerations now covers the rules and processors. divided into four subsections.
3. The charset parameter was modified. 2. The Introduction section provides substantial background
4. The example was updated to reflect the current specification. information, along with goals and use cases for both Markdown
and the Internet media type registration.
3. The rules parameter was reverted back to flavor, and flavor
was beefed up.
4. The processor parameters were consolidated and simplified.
5. Dependencies on POSIX were removed.
6. The output-type parameter was added.
7. Unregistered identifiers can be used with their own ! syntax.
8. The IANA Considerations section was fleshed out in great
detail, with emphasis on easing the registration process.
9. Security considerations were weaved throughout the
specification. Overall, most of the complexity in this
specification comes directly from the security considerations.
Those considerations are necessary since a lot of bad things
can and will happen when HTML, URIs, and executable code get
together.
10. Changed the example in Section 2 to use initially registered
identifiers.
11. Added output-type="text/markdown" for recursive handling
(i.e., don't process this Markdown, just show it like it is).
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. 80 change blocks. 
326 lines changed or deleted 841 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/