draft-ietf-appsawg-text-markdown-07.txt   draft-ietf-appsawg-text-markdown-08.txt 
Applications Area Working Group S. Leonard Applications Area Working Group S. Leonard
Internet-Draft Penango, Inc. Internet-Draft Penango, Inc.
Intended Status: Informational April 15, 2015 Intended Status: Informational June 18, 2015
Expires: October 17, 2015 Expires: December 20, 2015
The text/markdown Media Type The text/markdown Media Type
draft-ietf-appsawg-text-markdown-07 draft-ietf-appsawg-text-markdown-08
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 12 skipping to change at page 2, line 12
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. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Markdown Media Type Registration Application . . . . . . . . . 5 2. Markdown Media Type Registration Application . . . . . . . . . 5
3. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 7 3. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 8
3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8
4. Content Disposition and preview-type . . . . . . . . . . . . . 8 4. Content Disposition and preview-type . . . . . . . . . . . . . 8
5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10 6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10
6.2. Reserved Identifiers . . . . . . . . . . . . . . . . . . . 11
6.3. Standard of Review . . . . . . . . . . . . . . . . . . . . 11
6.4. Provisional Registration . . . . . . . . . . . . . . . . . 12
6.5. Original Markdown . . . . . . . . . . . . . . . . . . . . . 12
7. Security Considerations . . . . . . . . . . . . . . . . . . . . 12 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 12
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
8.1. Normative References . . . . . . . . . . . . . . . . . . . 13 8.1. Normative References . . . . . . . . . . . . . . . . . . . 12
8.2. Informative References . . . . . . . . . . . . . . . . . . 14 8.2. Informative References . . . . . . . . . . . . . . . . . . 13
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 14 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14
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 4, line 44 skipping to change at page 4, line 42
/net/projects/markdown/syntax#html || Markdown editor: an application | /net/projects/markdown/syntax#html || Markdown editor: an application |
|"Markdown: Syntax: HTML" || that presents Markdown content | |"Markdown: Syntax: HTML" || that presents Markdown content |
| || ...</p> | | || ...</p> |
+----------------------------------++----------------------------------+ +----------------------------------++----------------------------------+
LEGEND: "/" embedded in a vertical line represents a line-continuation LEGEND: "/" embedded in a vertical line represents a line-continuation
marker, since a line break is not supposed to occur in that content. marker, since a line break is not supposed to occur in that content.
Figure 1: Markdown Split-Screen/Live Preview Editor Figure 1: Markdown Split-Screen/Live Preview Editor
Users on diverse platforms SHOULD be able to collaborate with their Implementations SHOULD produce and consume mutually intelligible and
tools of choice, whether those tools are desktop-based (MarkdownPad, identifiable bits of Markdown, so that users on diverse platforms can
MultiMarkdown Composer), browser-based (Dillinger, Markable), integrated collaborate with their tools of choice. Those tools MAY be desktop-based
widgets (Discourse, GitHub), general-purpose editors (emacs, vi), or (MarkdownPad, MultiMarkdown Composer), browser-based (Dillinger,
plain old "Notepad". Additionally, users SHOULD be able to identify Markable), integrated widgets (Discourse, GitHub), general-purpose
particular areas of Markdown content when the Markdown becomes editors (emacs, vi), or plain old "Notepad". Additionally,
appreciably large (e.g., book chapters and Internet-Drafts--not just implementations SHOULD have common ways to identify particular areas of
blog posts). Users SHOULD be able to use text/markdown to convey their Markdown content when the Markdown becomes appreciably large (e.g., book
works in progress, not just their finished products (for which full- chapters and Internet-Drafts--not just blog posts). So that users have
blown markups ranging from text/html to application/pdf are the option to use Markdown in MIME-capable systems to convey their works
appropriate). This registration facilitates interoperability between in progress, not just their finished products (for which full-blown
these Markdown editors by conveying the syntax of the particular markups ranging from text/html to application/pdf are appropriate),
implementations SHOULD label such Markdown content with a common media
type: text/markdown. This registration facilitates interoperability
between 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. Definitions 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 Since Markdown signifies a family of related formats with varying
degrees of formal documentation and implementation, this degrees of formal documentation and implementation, this
skipping to change at page 5, line 33 skipping to change at page 5, line 33
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:
charset: Per Section 4.2.1 of [RFC6838], charset is REQUIRED. There charset: Per Section 4.2.1 of [RFC6838], charset is REQUIRED. There
is no default value. [MDSYNTAX] clearly describes Markdown as a is no default value. [MDSYNTAX] clearly describes Markdown as a
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. This
[MDSYNTAX] nor many popular implementations at the time of this registration does not require or assume any particular character
registration actually require or assume any particular character set because neither [MDSYNTAX] nor many popular implementations
set. Many Markdown processors will get along just fine by at the time of this registration do either. Many Markdown
operating on character codes that lie in printable US-ASCII, processors will get along just fine by operating on character
blissfully oblivious to coded values outside of that range. codes that lie in printable US-ASCII, blissfully oblivious to
coded values outside of that range.
Optional parameters: Optional parameters:
variant: An optional identifier that serves as a "hint" to the variant: An optional identifier of the specific Markdown variant
recipient of the specific Markdown variant that the author that the author intended. The value serves as a "hint" to the
intended. When omitted, there is no hint; the interpretation is recipient, meaning that the recipient MAY interpret the Markdown
entirely up to the receiver and context. This identifier is plain as that variant, but is under no obligation to do so. When
US-ASCII and case-insensitive. To promote interoperability, omitted, there is no hint; the interpretation is entirely up to
identifiers MAY be registered in the registry defined in Section the receiver and context. This identifier is plain US-ASCII and
6. If a receiver does not recognize the variant identifier, the case-insensitive. To promote interoperability, identifiers can be
receiver MAY present the identifier to a user to inform him or registered in the registry defined in Section 6. If a receiver
her of it. does not recognize the variant identifier, the receiver MAY
present the identifier to a user to inform him or her of it.
Other parameters MAY be included with the media type. The variant Other parameters MAY be included with the media type. The variant
SHOULD define the semantics of such parameters. Additionally, the SHOULD define the semantics of such other parameters. Additionally,
variant MAY be registered under another media type; this the variant MAY be registered under another media type; this
text/markdown registration does not preclude other registrations. text/markdown registration does not preclude other registrations.
Encoding considerations: Encoding considerations:
Markdown content is plain text content; any octet sequence is valid Markdown content is plain text content; any octet sequence is valid
as long as it conforms to the character codes of the charset as long as it conforms to the character codes of the charset
parameter. See [RFC2046]. Markup characters in [MDSYNTAX] are parameter. See [RFC2046]. Markup characters in [MDSYNTAX] are
limited to printable US-ASCII; however, other variants can define limited to printable US-ASCII; however, other variants can define
markup characters outside this range (including control characters markup characters outside this range (including control characters
such as NUL and characters encoded in multiple bytes). such as NUL and characters encoded in multiple bytes).
skipping to change at page 6, line 48 skipping to change at page 6, line 50
interpretations depending on the tool and the environment, a better interpretations depending on the tool and the environment, a better
approach is to analyze (and sanitize or block) the output markup, approach is to analyze (and sanitize or block) the output markup,
rather than attempting to analyze the Markdown. rather than attempting to analyze the Markdown.
Interoperability considerations: Interoperability considerations:
Markdown variations (some might say "innovations") are designed to Markdown variations (some might say "innovations") are designed to
be broadly compatible with humans ("humane"), but not necessarily be broadly compatible with humans ("humane"), but not necessarily
with each other. Therefore, syntax in one Markdown derivative may with each other. Therefore, syntax in one Markdown derivative may
be ignored or treated differently in another derivative. The be ignored or treated differently in another derivative. The
overall effect is a general degradation of the output, proportional overall effect is a general degradation of the output that
to the quantity of variant-specific Markdown used in the text. When increases with the quantity of variant-specific Markdown used in
it is desirable to reflect the author's intent in the output, stick the text. When it is desirable to reflect the author's intent in
with the variant identified in the variant parameter. the output, stick with the variant identified in the variant
parameter, i.e., receivers SHOULD only accept Markdown variants
that they explicitly know about, and senders SHOULD avoid use of
variants that intended recipients are not known to understand.
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:
skipping to change at page 7, line 44 skipping to change at page 7, line 49
Intended usage: COMMON Intended usage: COMMON
Provisional registration? No Provisional registration? No
Implementations SHOULD record the value of the variant parameter (and Implementations SHOULD record the value of the variant parameter (and
other parameters if defined by the variant) along with the Markdown other parameters if defined by the variant) along with the Markdown
content when the content leaves the domain of Internet media type- content when the content leaves the domain of Internet media type-
capable formats. Strategies for doing so are discussed in [MDMTUSES]. capable formats. Strategies for doing so are discussed in [MDMTUSES].
The Content-Disposition header (particulalry the preview-type The Content-Disposition header (particularly the preview-type
parameter) can be used with Markdown content. See Section 4. parameter) can be used with Markdown content. See Section 4.
3. Fragment Identifiers 3. Fragment Identifiers
[MARKDOWN] does not define any fragment identifiers, but some [MARKDOWN] does not define any fragment identifiers, but some
variants do, and many types of Markdown processor output (e.g., HTML variants do, and many types of Markdown processor output (e.g., HTML
or PDF) will have well-defined fragment identifiers. Which fragment or PDF) will have well-defined fragment identifiers. Which fragment
identifiers are available for a given document are variant-defined. identifiers are available for a given document are variant-defined.
When encoded in a URI, characters that are outside of the fragment When encoded in a URI, characters that are outside of the fragment
skipping to change at page 11, line 8 skipping to change at page 11, line 14
While the variant parameter is "plain US-ASCII" (see registration While the variant parameter is "plain US-ASCII" (see registration
template), the Identifier field (and by implication, all registered template), the Identifier field (and by implication, all registered
identifiers) SHALL conform to the ABNF [RFC5234]: identifiers) SHALL conform to the ABNF [RFC5234]:
ALPHA [*VCHAR (ALPHA / DIGIT)] ALPHA [*VCHAR (ALPHA / DIGIT)]
For style and compatibility reasons, the Identifier field SHOULD For style and compatibility reasons, the Identifier field SHOULD
conform to the ABNF: conform to the ABNF:
ALPHA 1*( ["-" / "." / "_" / "~"] 1*(ALPHA / DIGIT) ) ALPHA *( ["-" / "." / "_" / "~"] 1*(ALPHA / DIGIT) )
I.e., the identifier MUST start with a letter and MAY contain I.e., the identifier MUST start with a letter and MAY contain
punctuation in the middle, but not at the end: the last character punctuation in the middle, but not at the end: the last character
MUST be alphanumeric. The second production uses the same characters MUST be alphanumeric. The second production uses the same characters
as the "unreserved" rule of [RFC3986], and is designed to be as the "unreserved" rule of [RFC3986], and is designed to be
compatible with characters in other identification systems, e.g., compatible with characters in other identification systems, e.g.,
filenames. Since the identifier MAY be displayed to a user-- filenames. Since the identifier MAY be displayed to a user--
particularly in cases where the receiver does not recognize the particularly in cases where the receiver does not recognize the
identifier--the identifier SHOULD be rationally related to the identifier--the identifier SHOULD be rationally related to the
vernacular name of the variant. vernacular name of the variant.
The Name, Description, Additional Parameters, Fragment Identifiers, The Name, Description, Additional Parameters, Fragment Identifiers,
References, and Contact Information fields SHALL be in a Unicode References, and Contact Information fields SHALL be in a Unicode
character set (e.g., UTF-8). character set (e.g., UTF-8).
The registry SHALL be populated with the registration in Section 6.5 The registry includes the registration in Section 6.1.4 (Original
(Original Markdown). [MDMTUSES] includes additional registrations. Markdown). [MDMTUSES] includes additional registrations.
6.2. Reserved Identifiers 6.1.1. Reserved Identifiers
The registry SHALL have the following identifiers RESERVED. No one is The registry has the following identifiers RESERVED, as they have
engendered some controversy in the Markdown community. 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.3. Standard of Review 6.1.2. 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.
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 IANA should confirm the authenticity of the senders of requests for
either match the prior registration and be verified, or the prior this registry.
registrant MUST confirm that the updating registrant has authority to
update the registration. IANA is to send an email to each old and new
address confirming the change request. The emails are to contain a
nonce (which may be embedded in a URI) that, when return by email or
another mechanism (e.g., HTTP), serve to verify the request. An
affirmative response from any of the addresses (old or new) is
sufficient. If neither the old nor the new registrations contain any
email addresses, then the update MAY succeed without email
confirmation. Therefore, registrants are encouraged to list at least
one email address for registration protection.
As a special "escape valve", registrations can be updated with IETF As a special "escape valve", registrations can be updated with IETF
Review [RFC5226]. All fields may be updated except the variant Review [RFC5226]. All fields may be updated except the variant
identifier, which is permanent: not even case may be changed. identifier, which is permanent: not even case may be changed.
6.4. Provisional Registration 6.1.3. Provisional Registration
Any registrant may make a provisional registration to reserve a Any registrant may make a provisional registration to reserve a
variant identifier. Only the variant identifier and contact variant identifier. Only the variant identifier and contact
information fields are required; the rest are optional. Provisional information fields are required; the rest are optional. Provisional
registrations expire after three months, after which time the variant registrations expire after three months, after which time the variant
identifier may be reused. To make a registration permanent, a identifier may be reused. To make a registration permanent, a
registrant simply needs to complete a permanent registration with the registrant simply needs to complete a permanent registration with the
same identifier as the provisional registration. same identifier as the provisional registration.
6.5. Original Markdown 6.1.4. Original Markdown
The registry SHALL be populated with this initial variant. A The registry includes this initial variant. A conforming
conforming implementation that processes the variant parameter MUST implementation that processes the variant parameter MUST recognize
recognize this variant (although the processing behavior is not this variant (although the processing behavior is not defined here).
defined here).
Identifier: Original Identifier: Original
Name: Markdown Name: Markdown
Description: Description:
Gruber's original Markdown syntax. Gruber's original Markdown syntax.
References: References:
[MARKDOWN] [MARKDOWN]
 End of changes. 21 change blocks. 
70 lines changed or deleted 64 lines changed or added

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