Applications Area Working Group                               S. Leonard
Internet-Draft                                             Penango, Inc.
Intended Status: Informational                        September 9, 22, 2014
Expires: March 13, 26, 2015

                      The text/markdown Media Type
                draft-ietf-appsawg-text-markdown-01.txt
                draft-ietf-appsawg-text-markdown-02.txt

Abstract

   This document registers the text/markdown media type for use with
   Markdown, a family of plain text formatting syntaxes that optionally
   can be converted to formal markup languages such as HTML.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

Copyright Notice

   Copyright (c) 2014 IETF Trust and the persons identified as the
   document authors. All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document. Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document. Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

[[TODO: add table of contents.]]
1. Introduction

1.1. On Formats

   In computer systems, textual data is stored and processed using a
   continuum of techniques. On the one end is plain text: a linear
   sequence of characters in some character set (code), possibly
   interrupted by line breaks, page breaks, or other control characters.
   Plain text provides /some/ fixed facilities for formatting
   instructions, namely codes in the character set that have meanings
   other than "represent this character on the output medium"; however,
   these facilities are not particularly extensible. Compare with
   [RFC6838] Section 4.2.1. (Applications Applications may neuter the effects of these
   special characters by prohibiting them or by ignoring their dictated
   meanings, as is the case with how modern applications treat most
   control characters in US-ASCII.) US-ASCII. On this end, any text reader or
   editor that interprets the character set can be used to see or
   manipulate the text. If some characters are corrupted, the corruption
   is unlikely to affect the ability of a computer system to process the
   text (even if the human meaning is changed).

   On the other end is binary format: a sequence of instructions
   intended for some computer application to interpret and act upon.
   Binary formats are flexible in that they can store non-textual data
   efficiently (perhaps storing no text at all, or only storing certain
   kinds of text for very specialized purposes). Binary formats require
   an application to be coded specifically to handle the format; no
   partial interoperability is possible. Furthermore, if even one byte
   or bit are corrupted in a binary format, it may prevent an
   application from processing any of the data correctly.

   Between these two extremes lies formatted text, i.e., text that
   includes non-textual information coded in a particular way, that
   affects the interpretation of the text by computer programs.
   Formatted text is distinct from plain text and binary format in that
   the non-textual information is encoded into textual characters, which
   are assigned specialized meanings /not/ defined by the character set.
   With a regular text editor and a standard keyboard (or other standard
   input mechanism), a user can enter these textual characters to
   express the non-textual meanings. For example, a character like "<"
   no longer means "LESS-THAN SIGN"; it means the start of a tag or
   element that affects the document in some way.

   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
   syntactically distinguishable from the text. Markup languages are
   (reasonably) well-specified and tend to follow (mostly) standardized
   syntax rules. Examples of markup languages include SGML, HTML, XML,
   and LaTeX. [[TODO: CITE.]] Standardized rules lead to
   interoperability between markup processors, but a skill requirement
   for new (human) users of the language that they learn these rules in
   order to do useful work. This imposition makes markup less accessible
   for non-technical users (i.e., users who are unwilling or unable to
   invest in the requisite skill development).

     informal        /---------formatted text----------\        formal
     <------v-------------v-------------v-----------------------v---->
      plain text     informal markup   formal markup    binary format
                     (Markdown)        (HTML, XML, etc.)

    Figure 1: Degrees of Formality in Data Storage Formats for Text

   On the informal end of the spectrum are lightweight markup languages.
   In comparison with formal markup like XML, lightweight markup uses
   simple syntax, and is designed to be easy for humans to enter with
   basic text editors. Markdown, the subject of this document, is an
   /informal/ plain text formatting syntax that is intentionally
   targeted at non-technical users (i.e., users upon whom little to no
   skill development is imposed) using unspecialized tools (i.e., text
   boxes). Jeff Atwood once described these informal markup languages as
   "humane" [HUMANE].

1.2. Markdown Design Philosophy

   Markdown specifically is a family of syntaxes that are based on the
   original work of John Gruber with substantial contributions from
   Aaron Swartz, released in 2004 [MARKDOWN]. Since its release a number
   of web or web-facing applications have incorporated Markdown into
   their text entry systems, frequently with proprietary custom extensions. Fed up
   with the complexity and security pitfalls of formal markup languages
   (e.g., HTML5) and proprietary binary formats (e.g., commercial word
   processing software), yet unwilling to be confined to the
   restrictions of plain text, many users have turned to Markdown for
   document processing. Whole toolchains now exist to support Markdown
   for online and offline projects.

   Due

   Informality is a bedrock premise of Gruber's design. Gruber created
   Markdown after disastrous experiences with strict XML and XHTML
   processing of syndicated feeds. In Mark Pilgrim's "thought
   experiment", several websites went down because one site included
   invalid XHTML in a blog post, which was automatically copied via
   trackbacks across other sites [DIN2MD]. These scenarios led Gruber to
   believe that clients (e.g., web browsers) SHOULD try to make sense of
   data that they receive, rather than rejecting data simply because it
   fails to adhere to Markdown's intentional informality, 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
   specifying demanding
   adherence to the Markdown syntax, and 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 two 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 very 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
   plain text), this document defines a media type and parameters that
   indicate, in broad strokes, the author's intent on how to interpret
   the Markdown.

1.1. Requirements Terminology

   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].

2. Markdown Media Type Registration Applications This section provides registration draws particular inspiration from the media type
   text/troff registration application [RFC4263]; troff is an informal plain text
   formatting syntax primarily intended for the
   text/markdown output to monospace line-
   oriented printers and screen devices. In that sense, Markdown is a
   kind of troff for modern computing.

   The primary purpose of an Internet media type (see [RFC6838], Section 5.6).

   Type name: text

   Subtype name: markdown

   Required parameters: charset. Per Section 4.2.1 of [RFC6838], charset
   is REQUIRED. There is no default value. UTF-8 is RECOMMENDED;
   however, neither [MDSYNTAX] nor popular implementations at to label "content"
   on the time
   of this registration actually require or assume Internet, as distinct from "files". Content is any particular
   encoding. In fact, many Markdown processors computer-
   readable format that can get be represented as a primary sequence of
   octets, along just fine
   by operating on character codes with type-specific metadata (parameters) and type-
   agnostic metadata (protocol dependent). From this description, it is
   apparent that lie in the Portable Character
   Set (i.e., printable US-ASCII), blissfully oblivious appending ".markdown" to coded values
   outside of that range.

   Optional parameters:

       The following parameters reflect how the author intends the
       content end of a filename is not a
   sufficient means to be processed. If rules and processor parameters identify Markdown. Filenames are
       both supplied, the processor parameters take precedence.

     rules: A whitespace-delimited list properties of
   files in file systems, but Markdown processing rules
       that apply frequently exists in databases or
   content management systems (CMSes) where the file metaphor does not
   apply. One CMS [RAILFROG] uses media types to this content. This parameter represents select appropriate
   processing, so a media type is necessary for the intent safe and
   interoperable use of Markdown.

   Unlike complete HTML documents, [MDSYNTAX] provides no means to
   include metadata into the author, namely, that content stream. Several derivative flavors
   have invented metadata incorporation schemes (e.g., [MULTIMD]), but
   these schemes only address specific use cases. In general, the Markdown will
   metadata must be interpreted
       "best" (i.e., as the author intended) when processed with the
       rules as specified and ordered supplied via supplementary means in this list. Identifiers MUST
       match an encapsulating
   protocol, format, or convention. The relationship between the <token> production of [RFC2045]; whitespace MUST match content
   and the <FWS> production of [RFC5322].

       Each identifier specifies metadata is not directly addressed by this specification;
   however, by identifying Markdown with a set of processing rules that are to
       be applied to the media type, Markdown content during
   can participate as 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, first-class citizen with a wide spectrum of
   metadata schemes.

   Finally, registering a media type through the
       author intends for Example1's other rules (for example, to IETF process "fenced code blocks") that are is not overridden by Example2
       to
   trivial. Markdown can no longer be applied to considered a "vendor"-specific
   innovation, but the content.

       Rule identifiers are drawn from and registered registration requirements even in the IANA
       registry discussed below. Rule identifiers that represent
       significant variations of vendor tree
   have proven to be overly burdensome for most Markdown SHOULD begin with a capital
       letter, e.g., "GitHub", "Original", "Multi". Rule identifiers
       that represent single or small collections implementers.
   Moreover, registering hundreds 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
       rule is "Original", namely, the original Markdown rules provided
       in John Gruber's variants with distinct
   media types would impede interoperability: virtually all Markdown Syntax from 2004 [MDSYNTAX]. When this
       parameter is not conveyed, the author does not express any intent
       about which rules apply: [MDSYNTAX] may not necessarily
   content can be the
       author's intent.

       In practice, processed by virtually any Markdown implementations that are aware processor, with
   varying degrees of this
       parameter will only be able to process a limited list success. The goal of rules in
       an automated fashion. Therefore, when composing this parameter,
       it specification is RECOMMENDED that the composing process limit itself to
       small lists
   reduce all of broadly recognizable rules, namely lists with just these burdens by having one item (specifically, some major variation of Markdown).

     processor: An identifier for the specific Markdown implementation media type that processes the Markdown into another format, such as HTML. If
       conveyed,
   accommodates diversity and eases registration.

1.3. Requirements Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this value cannot
   document are to be empty. If not conveyed, the author
       does not express any interpreted as described in [RFC2119].

2.  Example

   The following is an example of Markdown as an e-mail attachment:

      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

      Sample HTML 4 Markdown
      =============

      This is some sample Markdown. [Hooray!][foo]
      (Remember that link names are not case-sensitive.)

      Bulleted Lists
      -------

      Here are some bulleted lists...

      * One Potato
      * Two Potato
      * Three Potato

      - One Tomato
      - Two Tomato
      - Three Tomato

      More Information
      -----------

      [.markdown, .md](http://daringfireball.net/projects/markdown/)
      has more information.

      [fOo]: http://example.com/some/foo/location
        'This Title Will Not Work with Markdown.pl-1.0.1'

3. Markdown Media Type Registration Application

   This section provides the media type registration application for the
   text/markdown media type (see [RFC6838], Section 5.6).

    Type name: text

    Subtype name: markdown

    Required parameters: charset. Per Section 4.2.1 of [RFC6838],
     charset 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:

     The following parameters reflect the author's intent regarding the
     content. A detailed specification can be found in Section 4.

     flavor: The variant, or "flavor" of the Markdown content, with
       optional rules (qualifiers). Default value: "Original".

     processor: A specific Markdown implementation, with optional
       arguments. Default value: none (receiver's choice).

     output-type: The Content-Type (Internet media type) of the output,
       with optional parameters. Default value: "text/html".

    Encoding considerations: Text.

    Security considerations:

     Markdown interpreted as plain text is relatively harmless. A text
     editor need only display the text. The editor SHOULD take care to
     handle control characters appropriately, and to limit the effect of
     the Markdown to the text editing area itself; malicious Unicode-
     based Markdown could, for example, surreptitiously change the
     directionality of the text. An editor for normal text would already
     take these control characters into consideration, however.

     Markdown interpreted as a precursor to other formats, such as HTML,
     carry all of the security considerations as the target formats. For
     example, HTML can contain instructions to execute scripts, redirect
     the user to other webpages, download remote content, and upload
     personally identifiable information. Markdown also can contain
     islands of formal markup, such as HTML. These islands of formal
     markup may be passed as-is, transformed, or ignored (perhaps
     because the islands are conditional or incompatible) when the
     Markdown is interpreted into the target format. Since Markdown may
     have different interpretations depending on the tool and the
     environment, a better approach is to analyze (and sanitize or
     block) the output markup, rather than attempting to analyze the
     Markdown.

     Specific security considerations apply to the optional parameters;
     for details, consult Section 4.

   Interoperability considerations:

     Markdown flavors are designed to be broadly compatible with humans
     ("humane"), but not necessarily with each other. Therefore, syntax
     in one Markdown flavor may be ignored or treated differently in
     another flavor. The overall effect is a general degradation of the
     output, proportional to the quantity of flavor-specific Markdown
     used in the text. When it is desirable to reflect the author's
     intent in the output, stick with the flavor identified in the
     flavor parameter.

   Published specification: This specification.

   Applications that use this media type:

     Markdown conversion tools, Markdown WYSIWYG editors, and plain text
     editors and viewers; target markup processors indirectly use
     Markdown (e.g., web browsers for Markdown converted to HTML).

   Additional information:

     Magic number(s): None
     File extension(s): .md, .markdown
     Macintosh file type code(s): TEXT

   Person & email address to contact for further information:

     Sean Leonard <dev+ietf@seantek.com>

   Restrictions on usage: None.

   Author/Change controller: Sean Leonard <dev+ietf@seantek.com>

   Intended usage: COMMON

   Provisional registration? Yes

4.  Optional Parameters

   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 "!".

   All identifiers are case-sensitive; receivers MUST compare for exact
   equality. Identifiers MUST NOT be registered if another registration
   differs only in the casing, as these registrations may cause
   confusion.

   The following ABNF definitions are used in this section:

          EXTCHAR  = <any character outside the US-ASCII range,
                      essentially amounting to any Unicode
                      code point beyond U+007F without requiring
                      Unicode or any particular encoding>

          REXTCHAR = <EXTCHAR without spaces (Zs category) or
                      control characters>

                  Figure X: ABNF Used in This Section

   The discussion in this section presumes that the parameter values are
   discrete strings. When encoded in protocols such as MIME [RFC2045],
   however, the value strings MUST be escaped properly.

4.1. flavor

   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.

   An IANA registry of flavors will be created as discussed in Section
   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).

   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 which 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 should identifier (and like the processor identifier, ASCII
   characters alone SHOULD be used. 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 identifiers arguments MAY be supplied for finer-grained control over
   how the processor behaves. Multiple arguments and URI references are registered
   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 IANA registry
       discussed below. Each processor registration (which argument, the following text is expected
   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 updated over time) also defines a relative reference if the versions subject Markdown
   content has a base URI. The receiver is to interpret this as a
   request to retrieve the resource, and arguments 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 considered valid. appropriate. The repertoire of this string is any
       number of characters (e.g., any Unicode character); however,
       registrations receiver SHOULD stick apply the
   same security and privacy analyses to US-ASCII-based strings unless there
       is a compelling reason file: URLs as it would to do otherwise.

     processor-ver: An identifier any
   other URI.

4.2.2.3. Appropriate Arguments and Security Considerations

   Not all arguments are appropriate for the version of the processor
       identified inclusion in the processor
   parameter. If conveyed, this value
       cannot be empty. If not conveyed, the author does not express any
       intent regarding a particular version Appropriate arguments are basically limited to be used. This parameter
       has no meaning if it is conveyed those that
   affect the output markup, without side-effects. Arguments MUST NOT
   identify input sources or output destinations. For example, if a sibling
   processor
       parameter.

       For purposes of this specification, normally reads Markdown input using the version is a string; arguments "-i
   filename" or "< filename" (i.e., from standard input), those
   arguments MUST be omitted. Arguments that have no bearing on the
       set of valid strings are registered and updated
   output MUST be omitted as a part well, such as arguments that control
   verbosity of the processor registration. A version "2.0" does not necessarily
       imply (-v) or that version 2.0 of an executable should be used instead of
       2.0.1, 2.1, cause side-effects (such as
   writing diagnostic messages to some other file). Of course, if
   warnings or even 3.0. If errors are signaled within the processor has a way to output, arguments enabling
   that output MAY be invoked
       "as if" it is a different version (e.g., version 3.0 of used.

   When in doubt, 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 omit arguments with unknown or
   undocumented effects, and a
       version 2014.11, for example, MAY ignore author-supplied arguments
   entirely, but 2014.11 only provides security
       updates, then the processor registration SHOULD SHALL NOT have reorder arguments. An author has very little
   assurance that a
       separate registration for receiver will honor unregistered arguments.
   Consequently, the 2014.11 version.

       The repertoire of this string burden is any number of characters (e.g.,
       any Unicode character); however, registrations SHOULD stick squarely on processor registrants
   (Section 5.2) to
       US-ASCII-based strings unless there is document their arguments properly.

   For security reasons, the parsed argument array (or a compelling reason to do
       otherwise.

     processor-args: A string conforming to a subset of
   unambiguously representing the POSIX Shell
       Command Language in Volume 3, Chapter 2 of [POSIX.1-2008] for
       arguments that are to delimited argument array) MUST be
   passed in an invocation 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 format of
   arguments in this parameter also has a facility MUST be encoded to
       reference resources by URI. [[TODO: Put in a separate section?
       [[Section X]] discusses the details preserve characters
   outside of this parameter.]]

       If conveyed but empty, US-ASCII, and to signal the author's intent is required encoding to turn off any
       optional arguments that the receiver would typically
   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. If not conveyed, processor: the routine MUST change the locale or
   transform the author does not express any
       intent regarding particular arguments to be used. This parameter
       has an appropriate character encoding so that
   there is no meaning 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 it 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 conveyed 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 sibling well-defined
   means for a Markdown processor
       parameter.

       If conveyed and not empty, the string MUST be parseable to pass metadata onwards, it is
   perilous for post-processing to assume that the
       <cmd_suffix> item content is always
   HTML. A processor might emit PostScript (application/postscript)
   content, for example, in Volume 3, Section 2.10.2 which case an HTML sanitizer would fail to
   excise dangerous instructions.

   The value of [POSIX.1-2008] output-type is an Internet media type with accommodations for embedded URIs optional
   parameters. The syntax (including case sensitivity considerations) is
   the same as specified below;
       however, <io_redirect> items MUST NOT appear. Effectively, in [RFC2045] for the
       string is a sequence Content-Type header (with
   updates over time), namely:

          type "/" subtype *(";" parameter)
                          ; Matching of <WORD> tokens. The string MUST NOT
       contain any sequences that would cause any shell processing other
       than newline media type and quote removal. For example, subtype
                          ; is ALWAYS case-insensitive.

              Figure X: Content-Type ABNF (from [RFC2045])

   The Internet media type in the string MUST NOT
       contain redirects, pipelines, or comments. Section 2.6 Word
       Expansions (Section 2.6.7 Quote Removal notwithstanding) are
       right out!

       A processor-args string output-type parameter MUST NOT include arguments regarding the
       input content be
   observed. Processors 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 conflict with the output,
       arguments enabling that output MAY
   output-type parameter MUST be used.

       Some authors re-chosen, ignored, or rejected.

   Although arbitrary optional parameters may wish to combine inputs from multiple resources.
       For security reasons, file references MUST NOT be included in
       processor-args. Instead, references to resources are encoded in
       strictly-conforming URIs [RFC3986] delimited passed along 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
   Internet media type, receivers are under no obligation to honor or
   interpret them in any particular way. For example, the resource specified by parameter
   value "text/plain; format=flowed; charset=ISO-2022-JP" obligates the URI, and then pass it
   receiver to output text/plain (and to treat the processor output as plain text-
   -no sneaking in an appropriate way,
       such or labeling the output as via HTML!). In contrast, such a temporary file. The intent of this option is
   parameter value neither obligates the receiver to
       provide a means follow [RFC3676]
   (for flowed output) nor to include additional data that might accompany
       the output ISO-2022-JP Japanese character
   encoding (see [RFC1468]).

   Markdown content, 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, using cid: 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 mid: URLs
       [RFC2392] text/plain adequately distinguish this
   kind of output. Such distinctions SHOULD be made in the context of MIME messages.

       Prior processor
   parameter (and to invoking a Markdown processor, the preprocess routine
       MUST first analyze the processor-args string for URIs. Depending
       on privacy and security considerations, lesser extent, the routine either
       dereferences the URIs--retrieving flavor parameter),
   underscoring that the contents--or rejects primary concern of the
       string. output-type parameter is
   making technical and security-related decisions.

   The URIs (including <> delimiters) shall then be replaced
       with appropriate, complete file paths or descriptors, output-type parameter does not distinguish between fragment
   content and the
       resulting string shall be checked for conformance with a sequence
       of arguments whole-document content. A Markdown processor MAY (and
   typically will) output HTML or XHTML fragment content, without
   preambles or postambles such as defined by the POSIX Shell Command Language in
       Volume 3, Chapter 2 <!DOCTYPE>, <html>, <head>, </head>,
   <body>, </body>, or </html> elements. Receivers MUST be aware of [POSIX.1-2008].

       Not all processors are literally invoked from an operating
       system's command facility; some this
   behavior and take appropriate precautions.

   [[TODO: consider.]]
   The author may be invoked from within
       another process as specify the output-type "text/markdown", which has a library call.
   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 such cases, 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
       SHOULD be invoked in such a way parameter) to communicate the semantics of perform useful services such as
   syntax highlighting. This output-type is not the arguments. One strategy might be to provide a library call
       with default because one or more explicit argument parameters;
   generally assumes that Markdown is meant for example,
       either a string type composing rather than
   reading: readers expect to see the output format (or dual-display of parameter (if
   the library does output and the
       parsing), Markdown). However, if authors are collaboratively
   editing a document or an "argc" plus "argv" pair of parameters (if the
       caller does are discussing Markdown, "text/markdown" may
   make sense. While the parsing). Another strategy might optional parameter output-type may be used
   recursively (as a sneaky way to provide
       several different library calls, which stash the caller would choose author's follow-on or
   secondary intent), receivers are not obligated to
       invoke depending on the directions of recognize it;
   optional parameters internal to output-type MAY be ignored.

5.  IANA Considerations

   IANA is asked to register the arguments. In media type text/markdown in the
       registration for
   Standards tree using the processor, argument handling MUST be
       discussed.

       The repertoire application provided in Section 2 of this string
   document.

   IANA is any number of characters that
       conform also asked to establish a [POSIX.1-2008] implementation. (Note that subtype registry called "Markdown
   Parameters". The registry has two sub-registries: a registry of
   flavors and a registry of processors.

5.1. Registry of Flavors

   Each entry in this registry shall consist of a flavor identifier and
   information about the NULL
       character is excluded, because POSIX uses flavor, as follows:

5.1.1. Flavor Template

      Identifier: [Identifier]

      Description: [Concise, prose description of the syntax,
                    with emphasis on its purpose, the community
                    that it addresses, and notable variations
                    from [MDSYNTAX] or another flavor.]

      Documentation: [References to documentation.]

      Rules:
       {for each rule}
        Identifier: [Identifier]
        Description: [Concise, prose description of the rule.]
        Documentation: [References to terminate
       strings.) When characters in 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 arguments lie outside 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
   corporate author or maintainer (plus an individual contact), or a
   representative of the
       Portable Character Set (i.e., outside a community of US-ASCII), this
       parameter MUST be encoded to preserve those characters and to
       signal the required encoding interest dedicated to the receiver. Then, the processor
       MUST Markdown
   syntax.

   Multiple tools MAY be invoked in such listed, but only one is necessary for a way that it properly understands these
       characters in the required encoding (or
   successful registration. If a superset thereof). When
       encoded in tool is a MIME Content-Type header, use of [RFC2231] Markdown processor, it MUST
   be registered; however, any Markdown-related tool (for example,
   graphical editors, emacs "major modes", web apps) is
       RECOMMENDED. acceptable. The rationale for this (convoluted)
   purpose of the tool requirement is
       because POSIX defines command lines and arguments with the C
       language char * data type, but leaves to ensure that the character set dependent
       on locale environment variables (see Volume 1, Chapter 7 of
       [POSIX.1-2008]). Therefore, it flavor is not sufficient to pass
       arguments from
   actually used in practice.

5.1.2. Initial Registration

   The registry shall have the processor-args parameter "as is" following initial registration:

      Identifier: Original

      Description: Gruber's original Markdown syntax.

      Documentation: [MDSYNTAX]

      Rules: None.

      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 the
       processor: the routine MUST change the locale HTML or transform XHTML circa 2004.

5.1.3. Reserved Identifiers
   The flavors registry SHALL have the
       arguments to an appropriate character encoding so that there following identifiers RESERVED.
   No one is
       no ambiguity.

   Encoding considerations: Text.

   Security considerations: allowed to register them (or any case variations of them).
      Standard
      Common
      Markdown interpreted as plain text is relatively harmless. A text
     editor need only display

5.1.4. Standard of Review

   Registrations are made by a highly constrained Expert Review
   [RFC5226] that amounts more-or-less to First-Come, First-Served with
   sanity checking.

   The designated expert SHALL review the text. flavor registration. The editor SHOULD take care to
     handle control characters appropriately,
   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 limit the effect of
     the Markdown an implementer to the text editing area itself; malicious Unicode-
     based Markdown could, for example, surreptitiously change the
     directionality of the text. An editor for normal text would already
     take these control characters into consideration, however.

     Markdown interpreted as implement a precursor tool to other formats, such as HTML,
     carry all of
   handle the security considerations as flavor. The designated expert SHOULD warn the target formats. For
     example, HTML can contain instructions to execute scripts, redirect registrant
   if the user to other webpages, download remote content, description and upload
     personally identifiable information. Markdown also can contain
     islands documentation are inadequate; however,
   inadequacy (in the opinion of formal markup, such the designated expert) will not bar a
   registration.

   All references (including contact information) MUST be verified as HTML. These islands
   functional at the time of formal
     markup may be passed as-is, transformed, or ignored (perhaps
     because the islands registration.

   If rules are conditional or incompatible) when included in the
     Markdown is interpreted into registration, the target format. Since Markdown may
     have different interpretations depending on rule identifiers MUST
   comply with the tool syntax specified in this document. The description
   and the
     environment, documentation of each rule SHOULD provide sufficient guidance to
   an implementer to implement a better approach is tool to analyze (and sanitize or
     block) handle the output markup, rather than attempting to analyze rule. The designated
   expert SHOULD warn the
     Markdown.

     [[TODO: discuss registrant if the implications of processor-args, description and
     safeguards.]] [[TODO: discuss
   documentation are inadequate; however, inadequacy (in the security implications opinion of
     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:

     Markdown flavors are designed to be broadly compatible with humans
     ("humane"), but designated expert) will not necessarily with each other. Therefore, syntax
     in one Markdown flavor may be ignored or treated differently in
     another flavor. bar a registration.

   The overall effect designated expert MUST determine that all tools listed in the
   registration are real implementations. If a tool is a general degradation of Markdown
   processor, the
     output, proportional to processor MUST be registered in the quantity Registry of flavor-specific Markdown
     used
   Flavors in Section 5.2. The designated expert MAY request that the text. When
   registrant provide evidence that a tool actually works (for example,
   that it is desirable to reflect the author's
     intent in passes certain test suites); however, the output, stick with failure of a tool
   to work according to the flavor identified in 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
     flavor parameter.

   Published specification: This specification.

   Applications designated expert SHOULD
   verify that use this media type:

     Markdown conversion tools, Markdown WYSIWYG editors, and plain text
     editors and viewers; target markup processors indirectly use
     Markdown (e.g., web browsers for Markdown converted to HTML).

   Additional information:

     Magic number(s): None
     File extension(s): .md, .markdown
     Macintosh file type code(s): TEXT

   Person & email address to the updating registrant matches the contact for further information:

     Sean Leonard <dev+ietf@seantek.com>

   Restrictions information
   on usage: None.

   Author/Change controller: Sean Leonard <dev+ietf@seantek.com>

   Intended usage: COMMON

   Provisional registration? Yes

3.  Example

   The following is an example of Markdown as an e-mail attachment:

      MIME-Version: 1.0
      Content-Type: text/markdown; charset=UTF-8; rules=GitHub
      Content-Disposition: attachment; filename=readme.md

      Sample GitHub Markdown
      =============

      This is some sample GitHub Flavored Markdown (*GFM*).
      The generated HTML is then run through filters in the
      [html-pipeline](https://github.com/jch/html-pipeline)
      to perform things like [sanitization](#html-sanitization) prior registration, and
      [syntax highlighting](#syntax-highlighting).

      Bulleted Lists
      -------

      Here are some bulleted lists...

      * One Potato
      * Two Potato
      * Three Potato

      - One Tomato
      - Two Tomato
      - Three Tomato

      More Information
      -----------

      [.markdown, .md](http://daringfireball.net/projects/markdown/)
      has more information.

4.  IANA Considerations

   IANA is asked to register the media type text/markdown in if not, that the
   Standards tree using updating registrant
   has authority from the application provided in Section 2 of this
   document.

   IANA is also asked prior registrant to establish a subtype registry called "Markdown
   Parameters". Entries in these registries update it. All fields may
   be updated except the Identifier, which is by Expert Review
   [RFC5226].  The registry has two sub-registries: a registry of rules
   and a registry of processors.

4.1 permanent: not even case
   may be changed.

5.2. Registry of Rules Processors

   Each entry in this registry shall SHALL consist of a) a rule processor identifier
   and
   b) whether the rule is defined in the registry entry, or in some
   external document.

   If information about the rule is defined in processor, as follows:

5.2.1. Processor Template

      Identifier: [Identifier]

      Description: [Concise, prose description of the registry entry, then processor,
                    with emphasis on its purpose, the entry must
   also include: i) a list of rules in prose text, community
                    that it addresses, and ii) for notable variations
                    from [MDSYNTAX] or another flavor.]

      Documentation: [References to documentation.]

      Versions:
       {for each
   rule, an example illustrating version}
        Identifier: [Identifier]
        Description: [Optional, concise, prose description of the rule. Additionally, each registry
   entry shall describe in
          version. "N/A" SHALL be used to indicate no description.]

      Arguments:
       {in general}
        Argument Ordering: [Concise, prose text iii) which rules take precedence
   over other rules, or description of how conflicts between rules may be resolved. The
   Expert will review the rule
                            arguments need 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
   determine whether the registration represents a bona-fide variation
   of the Markdown syntax (i.e., neither ordered.]
       {for each argument}
        Argument Syntax: [Syntax here; multiple consecutive argument
          positions are allowed, separated by a duplicate single space. Use
          braces for variable information (add : for example input),
          <URI> for URI references, and .. for sequences of an existing
   registration nor a syntax that is something other than Markdown;
   [MDSYNTAX] SHALL be used arguments
          with # as a normative basis), a brief description,
   one or more responsible parties, whether placeholder for the document is being
   maintained at number of arguments or
          ..-.. to indicate the time first character of registration, and the existence 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 at least
   one complete tool 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 without documentation) that processes the
   Markdown syntax into a formal document language.
                                "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
   syntax.
   processor.

5.2.2. Initial Registration

   The registry shall have the following initial value: registration:

      Identifier: Original Markdown.pl

      Description:
    The Gruber's original Markdown syntax as it exists processor, written in the Markdown 1.0.1
                   Perl. Requires Perl script
    at [MARKDOWN], 5.6.0 or later. "Welcome to
                   the 21st Century." Works with accompanying documentation at [MDSYNTAX]. 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

   Tool:
    Name: Markdown 1.0.1
    Reference: <http://daringfireball.net/projects/markdown/>
    Purpose: Converts to HTML or XHTML circa 2004.

   Additionally, the [[TODO: maybe?]]

5.2.3. Reserved Identifiers

   The processors registry shall SHALL have the following identifiers
   reserved for future versions
   RESERVED. No one is allowed to register them (or any case variations
   of this draft: them).
      Standard
      Markdown
      md

5.2.4. Standard
      Common
      Regular
      Community
      Uniform
      Vanilla
      Compatible
      Gruber
      GitHub
      Multi
      PageDown

4.2 Registry of Processors

   Each entry 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 registry shall consist of a) a processor
   identifier, b) a concise
   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 processor, c) one or more
   responsible parties, d) whether 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 maintained at updated, the time of contact information MUST
   either match the prior 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
   of verified, or the registry entry. However, prior
   registrant MUST confirm that the documentation MAY merely refer updating registrant has authority to
   external documentation, such as a manpage, webpage, or user manual.

   [[TODO: figure out if
   update the list should registration. All fields may be more formal, so a receiver
   can validate the safety/correctness of updated except the arguments before passing
   them along.]]

5.
   Identifier, which is permanent: not even case may be changed.

6. Security Considerations

   See the answer to the Security Considerations template questions in
   Section 2.

6.

   Security considerations for the optional parameters are integrated
   throughout Section 4.

7. References

6.1.

7.1. Normative References

   [MARKDOWN] Gruber, J., "Daring Fireball: Markdown", WWW
              http://daringfireball.net/projects/markdown/, December
              2004. 2004,
              <http://daringfireball.net/projects/markdown/>.

   [MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax
              Documentation", WWW
              <http://daringfireball.net/projects/markdown/syntax>, December 2004.

   [POSIX.1-2008] IEEE Std 1003.1, 2013 Edition (incorporates IEEE Std
              1003.1-2008 and IEEE Std 1003.1-2008/Cor 1-2013, "Standard
              for Information Technology - Portable Operating System
              Interface (POSIX(R)) Base Specifications, Issue 7"
              (incorporating Technical Corrigendum 1), April 2013. 2004,
              <http://daringfireball.net/projects/markdown/syntax>.

   [RFC1738]  Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
              Resource Locators (URL)", RFC 1738, December 1994.

   [RFC2045]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part One: Format of Internet Message
              Bodies", RFC 2045, November 1996.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66, RFC
              3986, January 2005.

   [RFC5226]  Narten, T., and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", RFC 5226, May 2008.

   [RFC5322]  Resnick, P., Ed., "Internet Message Format", RFC 5322,
              October 2008.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13, RFC
              6838, January 2013.

6.2.

7.2. Informative References

   [HUMANE]   Atwood, J., "Is HTML a Humane Markup Language?", WWW
              http://blog.codinghorror.com/is-html-a-humane-markup-
              language/, May 2008. 2008,
              <http://blog.codinghorror.com/is-html-a-humane-markup-
              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
              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

   This draft is a continuation from draft-seantek-text-markdown-media-
   type-00.txt (since renamed). draft-ietf-appsawg-text-markdown-
   01.txt. These technical changes were made:

      1.  The flavor parameter entire document was replaced with the rules, processor,
         processor-ver, reorganized: optional parameters now
          have their own section, and processor-args parameters. the Introduction section is
          divided into four subsections.
      2.  The IANA Considerations now covers the rules Introduction section provides substantial background
          information, along with goals and processors. use cases for both Markdown
          and the Internet media type registration.
      3.  The charset rules parameter was modified. reverted back to flavor, and flavor
          was beefed up.
      4.  The example processor parameters were consolidated and simplified.
      5.  Dependencies on POSIX were removed.
      6.  The output-type parameter was updated to reflect 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 current
          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

   Sean Leonard
   Penango, Inc.
   5900 Wilshire Boulevard
   21st Floor
   Los Angeles, CA  90036
   USA

   EMail: dev+ietf@seantek.com
   URI:   http://www.penango.com/