draft-ietf-appsawg-text-markdown-06.txt   draft-ietf-appsawg-text-markdown-07.txt 
Applications Area Working Group S. Leonard Applications Area Working Group S. Leonard
Internet-Draft Penango, Inc. Internet-Draft Penango, Inc.
Intended Status: Informational February 23, 2015 Intended Status: Informational April 15, 2015
Expires: August 27, 2015 Expires: October 17, 2015
The text/markdown Media Type The text/markdown Media Type
draft-ietf-appsawg-text-markdown-06 draft-ietf-appsawg-text-markdown-07
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 16 skipping to change at page 2, line 16
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. This Is Markdown! Or: Markup and Its Discontents . . . . . 2 1.1. This Is Markdown! Or: Markup and Its Discontents . . . . . 2
1.2. Markdown Is About Writing and Editing . . . . . . . . . . . 3 1.2. Markdown Is About Writing and Editing . . . . . . . . . . . 3
1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Markdown Media Type Registration Application . . . . . . . . . 5 2. Markdown Media Type Registration Application . . . . . . . . . 5
3. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 7 3. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . . 7
3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8
4. Content Disposition and preview-type . . . . . . . . . . . . . 8 4. Content Disposition and preview-type . . . . . . . . . . . . . 8
5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10 6.1. Markdown Variants . . . . . . . . . . . . . . . . . . . . . 10
6.2. Reserved Identifiers . . . . . . . . . . . . . . . . . . . 11 6.2. Reserved Identifiers . . . . . . . . . . . . . . . . . . . 11
6.3. Standard of Review . . . . . . . . . . . . . . . . . . . . 11 6.3. Standard of Review . . . . . . . . . . . . . . . . . . . . 11
6.4. Provisional Registration . . . . . . . . . . . . . . . . . 11 6.4. Provisional Registration . . . . . . . . . . . . . . . . . 12
7. Security Considerations . . . . . . . . . . . . . . . . . . . . 11 6.5. Original Markdown . . . . . . . . . . . . . . . . . . . . . 12
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 12
8.1. Normative References . . . . . . . . . . . . . . . . . . . 11 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
8.2. Informative References . . . . . . . . . . . . . . . . . . 13 8.1. Normative References . . . . . . . . . . . . . . . . . . . 13
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 13 8.2. Informative References . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15
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 6, line 10 skipping to change at page 6, line 10
identifiers MAY be registered in the registry defined in Section identifiers MAY be registered in the registry defined in Section
6. If a receiver does not recognize the variant identifier, the 6. If a receiver does not recognize the variant identifier, the
receiver MAY present the identifier to a user to inform him or receiver MAY present the identifier to a user to inform him or
her of it. 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 parameters. Additionally, the
variant MAY be registered under another media type; this 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: Text. Encoding considerations:
Markdown content is plain text content; any octet sequence is valid
as long as it conforms to the character codes of the charset
parameter. See [RFC2046]. Markup characters in [MDSYNTAX] are
limited to printable US-ASCII; however, other variants can define
markup characters outside this range (including control characters
such as NUL and characters encoded in multiple bytes).
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.
skipping to change at page 7, line 7 skipping to change at page 7, line 15
Published specification: This specification; [MDSYNTAX]. Published specification: This specification; [MDSYNTAX].
Applications that use this media type: Applications that use this media type:
Markdown conversion tools, Markdown WYSIWYG editors, and plain text Markdown conversion tools, Markdown WYSIWYG editors, and plain text
editors and viewers; markup processor targets indirectly use editors and viewers; markup processor targets indirectly use
Markdown (e.g., web browsers for Markdown converted to HTML). Markdown (e.g., web browsers for Markdown converted to HTML).
Fragment identifier considerations: Fragment identifier considerations:
See Section 4. See Section 3.
Additional information: Additional information:
Magic number(s): None Magic number(s): None
File extension(s): .md, .markdown File extension(s): .md, .markdown
Macintosh file type code(s): Macintosh file type code(s):
TEXT. A uniform type identifier (UTI) of TEXT. A uniform type identifier (UTI) of
"net.daringfireball.markdown", which conforms to "public.plain- "net.daringfireball.markdown", which conforms to "public.plain-
text", is RECOMMENDED [MDUTI]. See [MDMTUSES] for other text", is RECOMMENDED [MDUTI]. See [MDMTUSES] for other
considerations. considerations.
skipping to change at page 10, line 22 skipping to change at page 10, line 30
6.1. Markdown Variants 6.1. Markdown Variants
IANA is also asked to establish a registry called "Markdown IANA is also asked to establish a registry called "Markdown
Variants". While the registry is being created in the context of the Variants". While the registry is being created in the context of the
text/markdown media type, the registry is intended for broad text/markdown media type, the registry is intended for broad
community use, so protocols and systems that do not rely on Internet community use, so protocols and systems that do not rely on Internet
media types can still tag Markdown content with a common variant media types can still tag Markdown content with a common variant
identifier. Each entry in this registry shall consist of basic identifier. Each entry in this registry shall consist of basic
information about the variant: information about the variant:
Identifier Identifier: unique identifier for the variant
Name Name: the commonly known name of the variant
Description Description: a prose description of the variant,
Additional Parameters (optional) including how it differs from other
Fragment Identifiers (optional) variants such as Original
References Additional Parameters*: additional Content-Type parameters
Contact Information Fragment Identifiers*: additional fragment identifier
Expiration Date (if provisional) syntaxes and semantics
References: URIs or other references to documentation
Contact Information: whom to contact (email, URI, phone,
address, etc.)
Expiration Date^: when this provisional
registration expires
* (optional)
^ (if provisional)
While the variant parameter is "plain US-ASCII" (see registration While the variant parameter is "plain US-ASCII" (see registration
template), the Identifier field (and by implication, all registered template), the Identifier field (and by implication, all registered
identifiers) SHALL conform to the ABNF [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:
skipping to change at page 11, line 9 skipping to change at page 11, line 24
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
(Original Markdown). [MDMTUSES] includes additional registrations.
6.2. Reserved Identifiers 6.2. Reserved Identifiers
The registry SHALL have the following identifiers RESERVED. No one is The registry SHALL have the following identifiers RESERVED. No one is
allowed to register them (or any case variations of them). allowed to register them (or any case variations of them).
Standard Standard
Common Common
Markdown Markdown
6.3. Standard of Review 6.3. Standard of Review
skipping to change at page 11, line 31 skipping to change at page 11, line 49
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 If a registration is being updated, the contact information MUST
either match the prior registration and be verified, or the prior either match the prior registration and be verified, or the prior
registrant MUST confirm that the updating registrant has authority to registrant MUST confirm that the updating registrant has authority to
update the registration. As a special "escape valve", registrations update the registration. IANA is to send an email to each old and new
can be updated with IETF Review [RFC5226]. All fields may be updated address confirming the change request. The emails are to contain a
except the variant identifier, which is permanent: not even case may nonce (which may be embedded in a URI) that, when return by email or
be changed. 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
Review [RFC5226]. All fields may be updated except the variant
identifier, which is permanent: not even case may be changed.
6.4. Provisional Registration 6.4. Provisional Registration
Any registrant may make a provisional registration to reserve a Any registrant may make a provisional registration to reserve a
variant identifier. Only the variant identifier and contact variant identifier. Only the variant identifier and contact
information fields are required; the rest are optional. Provisional information fields are required; the rest are optional. Provisional
registrations expire after three months, after which time the variant registrations expire after three months, after which time the variant
identifier may be reused. To make a registration permanent, a identifier may be reused. To make a registration permanent, a
registrant simply needs to complete a permanent registration with the registrant simply needs to complete a permanent registration with the
same identifier as the provisional registration. same identifier as the provisional registration.
6.5. Original Markdown
The registry SHALL be populated with this initial variant. A
conforming implementation that processes the variant parameter MUST
recognize this variant (although the processing behavior is not
defined here).
Identifier: Original
Name: Markdown
Description:
Gruber's original Markdown syntax.
References:
[MARKDOWN]
[MDSYNTAX]
Contact Information:
(individual) John Gruber <http://daringfireball.net/>
<comments@daringfireball.net>
7. Security Considerations 7. Security Considerations
See the Security considerations entry in Section 2. See the Security considerations entry in Section 2.
8. References 8. References
8.1. Normative References 8.1. Normative References
[MARKDOWN] Gruber, J., "Daring Fireball: Markdown", December 2004, [MARKDOWN] Gruber, J., "Daring Fireball: Markdown", December 2004,
<http://daringfireball.net/projects/markdown/>. <http://daringfireball.net/projects/markdown/>.
[MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax [MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax
Documentation", December 2004, Documentation", December 2004,
<http://daringfireball.net/projects/markdown/syntax>. <http://daringfireball.net/projects/markdown/syntax>.
[MDUTI] Gruber, J., "Daring Fireball: Uniform Type Identifier for [MDUTI] Gruber, J., "Daring Fireball: Uniform Type Identifier for
skipping to change at page 13, line 30 skipping to change at page 14, line 33
[PANDOC] MacFarlane, J., "Pandoc", 2014, [PANDOC] MacFarlane, J., "Pandoc", 2014,
<http://johnmacfarlane.net/pandoc/>. <http://johnmacfarlane.net/pandoc/>.
[RFC4263] Lilly, B., "Media Subtype Registration for Media Type [RFC4263] Lilly, B., "Media Subtype Registration for Media Type
text/troff", RFC 4263, January 2006. text/troff", RFC 4263, January 2006.
Appendix A. Change Log Appendix A. Change Log
This draft is a continuation from draft-ietf-appsawg-text-markdown- This draft is a continuation from draft-ietf-appsawg-text-markdown-
05.txt. These technical changes were made: 06.txt. These technical changes were made:
1. Removed TODO items for the time being. 1. Defined the IANA email confirmation process.
2. Added RFC 5234 reference. 2. Defined the fields for the variants registry.
3. Made minor changes. 3. Referred to use-cases draft.
4. Beefed up the encoding considerations.
5. Referred to the right section (Section 3) in fragment
identifier considerations.
6. Added Original Markdown registration.
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. 13 change blocks. 
30 lines changed or deleted 83 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/