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

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

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

Table of contents.]] Contents

   1. Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .  2
     1.1. On Formats This Is Markdown! Or: Markup and Its Discontents  . . . . .  2
     1.2. Markdown Is About Writing and Editing . . . . . . . . . . .  3
     1.3. RFC 2119  . . . . . . . . . . . . . . . . . . . . . . . . .  5
   2. Markdown Media Type Registration Application  . . . . . . . . .  5
   3.  Optional Parameters  . . . . . . . . . . . . . . . . . . . . .  7
     3.1. syntax  . . . . . . . . . . . . . . . . . . . . . . . . . .  8
     3.2. output-type . . . . . . . . . . . . . . . . . . . . . . . . 11
   4. Fragment Identifiers  . . . . . . . . . . . . . . . . . . . . . 13
     4.1. #t  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
     4.2. #o  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
     4.3. #l and #ldef  . . . . . . . . . . . . . . . . . . . . . . . 13
     4.4. Other Fragment Identifiers  . . . . . . . . . . . . . . . . 14
   5.  Example  . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 15
     6.1. Syntax Template . . . . . . . . . . . . . . . . . . . . . . 15
     6.2. Initial Registration  . . . . . . . . . . . . . . . . . . . 17
     6.3. Reserved Identifiers  . . . . . . . . . . . . . . . . . . . 18
     6.4. Standard of Review  . . . . . . . . . . . . . . . . . . . . 18
     6.5. Provisional Registration  . . . . . . . . . . . . . . . . . 19
   7. Security Considerations . . . . . . . . . . . . . . . . . . . . 19
   8. References  . . . . . . . . . . . . . . . . . . . . . . . . . . 19
     8.1. Normative References  . . . . . . . . . . . . . . . . . . . 19
     8.2. Informative References  . . . . . . . . . . . . . . . . . . 20
   Appendix A.  Change Log  . . . . . . . . . . . . . . . . . . . . . 21
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 22

1. Introduction

1.1. This Is Markdown! Or: Markup and Its Discontents

   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,
   The repertoire of these facilities are control characters (a form of in-band
   signaling) is necessarily limited, and not particularly extensible. Compare with
   [RFC6838] Section 4.2.1. Applications may neuter the effects of
   Because they are non-printing, these
   special characters by prohibiting them or by ignoring their dictated
   meanings, as is the case are also hard to
   enter with how modern applications treat most
   control standard keyboards.

   Markup offers an alternative means to encode this signaling
   information by overloading certain characters with additional
   meanings. Therefore, markup languages allow for annotating a document
   in US-ASCII. On this end, any text reader or
   editor such a way that interprets the character set can be used to see or
   manipulate the text. If some characters annotations are corrupted, syntactically distinguishable from
   the corruption
   is unlikely printing information. Markup languages are (reasonably) well-
   specified and tend to affect the ability follow (mostly) standardized syntax rules.
   Examples of a computer system formal markup languages include SGML, HTML, XML, and
   LaTeX. Standardized rules lead to interoperability between markup
   processors, but impose skill requirements on new users that lead to
   markup languages becoming less accessible to beginners. These rules
   also reify "validity": content that does not conform to process the
   text (even if the human meaning rules is changed).

   On the other end
   treated differently (i.e., is binary format: a sequence of instructions
   intended for some computer application to interpret and act upon.
   Binary formats are flexible in rejected) than content that conforms.

   In contrast to formal markup languages, lightweight markup languages
   use simple syntaxes; 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 are designed to be coded specifically easy for humans to handle enter
   and understand with basic text editors. Markdown, the format; no
   partial interoperability is possible. Furthermore, if even one byte
   or bit are corrupted in a binary format, it may prevent subject of this
   document, began as an
   application from processing any /informal/ plain text formatting syntax
   [MDSYNTAX] and Perl script HTML/XHTML processor [MARKDOWN] targeted
   at non-technical users using unspecialized tools, such as plain text
   e-mail clients. [MDSYNTAX] explicitly rejects the notion of validity:
   there is no such thing as "invalid" Markdown. If the data correctly.

   Between these two extremes lies formatted text, i.e., text that
   includes non-textual information coded Markdown content
   does not result in a particular way, the "right" output (defined as output that
   affects the interpretation
   author wants, not output that adheres to some dictated system of
   rules), the text by computer programs.
   Formatted text expectation 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 author should continue
   experimenting by changing the character set.
   With a regular text editor and a standard keyboard (or other standard
   input mechanism), a user can enter these textual characters content or the processor to
   express achieve the non-textual meanings. For example,
   desired output.

   Since its development in 2004 [MARKDOWN], a character like "<"
   no longer means "LESS-THAN SIGN"; it means the start number of web- and
   Internet-facing applications have incorporated Markdown into their
   text entry systems, frequently with custom extensions. Markdown has
   thus evolved into a tag or
   element that affects the document in some way.

   On the formal end kind of Internet meme [INETMEME] as different
   communities encounter it and adapt the spectrum is markup, syntax for their specific use
   cases. Markdown now represents a family of languages
   for annotating a document in such a way that the annotations are
   syntactically distinguishable from the text. Markup languages related plain text
   formatting syntaxes that, while broadly compatible with humans
   [HUMANE], 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 intended to
   interoperability between markup processors, but a skill requirement
   for new (human) users produce different kinds of the language outputs 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
   push the informal end boundaries of the spectrum are lightweight markup languages.
   In comparison with formal markup like XML, lightweight markup uses
   simple syntax, mutual intelligibility between software
   systems.

   To support identifying and is designed to be easy for humans to enter with
   basic text editors. conveying Markdown, the subject of this document, document defines
   a media type and parameters that indicate the author's intent on how
   to interpret the Markdown. This registration draws particular
   inspiration from text/troff [RFC4263], which is an
   /informal/ a plain text
   formatting syntax for typesetting based on tools from the 1960s
   ("RUNOFF") and 1970s ("nroff", et. al.). In that sense, Markdown 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]. a
   kind of troff for modern computing. A companion document [MDMTUSES]
   provides additional Markdown background and philosophy.

1.2. Markdown Design Philosophy Is About Writing and Editing

     "HTML is a *publishing* format; Markdown specifically is a family of syntaxes *writing* format.
      Thus, Markdown's formatting syntax only addresses issues
      that are based on can be conveyed in plain text." [MDSYNTAX]

   The paradigmatic use case for text/markdown is the
   original work Markdown editor:
   an application that presents Markdown content (which looks like an e-
   mail or other piece of John Gruber with substantial contributions from
   Aaron Swartz, released in 2004 [MARKDOWN]. Since its release plain text writing) alongside a published
   format, so that an author can see results instantaneously and can
   tweak his or her input in real-time. A significant number of web or web-facing applications have incorporated Markdown into
   their text entry systems, frequently with custom extensions. Fed up
   editors have adopted "split-screen view" (or "live preview")
   technology that looks like Figure 1:

+----------------------------------------------------------------------+
| File  Edit  (Cloud Stuff)  (Fork Me on GitHub)  Help                 |
+----------------------------------------------------------------------+
| [ such-and-such identifier ]                 [ useful statistics]    |
+----------------------------------++----------------------------------+
| (plain text, with the complexity                || (text/html, likely               |
|  syntax highlighting)            ||  rendered to screen)             |
|                                  ||                                  |
|# Introduction                    ||<h1>Introduction</h1>             |
|                                  ||                                  |
|## Markdown Is About Writing and security pitfalls of formal markup languages
   (e.g., HTML5)  /|<h2>Markdown Is About Writing 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 |
/ Editing                          ||Editing</h2>                      |
|                                  ||                                  |
|> HTML is a *publishing* format;  ||<blockquote><p>HTML is a          |
|> Markdown
   for online and offline projects.

   Informality is a bedrock premise of Gruber's design. Gruber created *writing* format. || <em>publishing</em> format;      |
|> Thus, Markdown's formatting     || 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 is a blog post, which was automatically copied via
   trackbacks across other sites [DIN2MD]. These scenarios led Gruber to
   believe <em>writing</em>   |
|> syntax only addresses issues    || format. Thus, Markdown's         |
|> that clients (e.g., web browsers) SHOULD try to make sense of
   data can be conveyed in plain   <> formatting syntax only addresses |
|> text. [MDSYNTAX][]              || issues that they receive, rather than rejecting data simply because it
   fails to adhere to strict, unforgiving standards. (In [DIN2MD],
   Gruber compared Postel's Law [RFC0793] with the XML standard, which
   says: "Once a fatal error is detected [...] the processor MUST NOT
   continue normal processing" [XML1.0-3].) As a result, there is no
   such thing as "invalid" Markdown; there can be conveyed in   |
|                                  || plain text. <a href="http://darin/
|The paradigmatic use case for     |/gfireball.net/projects/markdown/sy/
|`text/markdown` is no standard demanding
   adherence to the Markdown syntax; there is no governing body   |/ntax#html" title="Markdown: Syntax/
|editor: an application that
   guides or impedes its development. If the       |/: HTML">MDSYNTAX</a>              |
|presents Markdown syntax does not
   result in the "right" output (defined as output content         ||</p></blockquote>                 |
|...                               ||                                  |
|                                  ||<p>The paradigmatic use case for  |
|[MDSYNTAX]: http://daringfireball./| <code>text/markdown</code> is the|
/net/projects/markdown/syntax#html || Markdown editor: an application  |
|"Markdown: Syntax: HTML"          || that the author
   wants, presents Markdown content   |
|                                  || ...</p>                          |
+----------------------------------++----------------------------------+

 LEGEND: "/" embedded in a vertical line represents a line-continuation
  marker, since a line break is not output that adheres supposed to some dictated system of rules),
   Gruber's view is occur in that the author either should keep content.

          Figure 1: Markdown Split-Screen/Live Preview Editor

Users on experimenting,
   or should change the processor diverse platforms SHOULD be able to address the author's particular
   needs (see [MARKDOWN] Readme and [MD102b8] perldoc; see also
   [CATPICS]).

1.3. Uses collaborate with their
tools of Markdown

   Since its introduction in 2004, Markdown has enjoyed remarkable
   success. Markdown works for choice, whether those tools are desktop-based (MarkdownPad,
MultiMarkdown Composer), browser-based (Dillinger, Markable), integrated
widgets (Discourse, GitHub), general-purpose editors (emacs, vi), or
plain old "Notepad". Additionally, users for three key reasons. First, the
   markup instructions (in text) look similar to the markup that they
   represent; therefore the cognitive burden SHOULD be able to learn the syntax is low.
   Second, the primary arbiter identify
particular areas 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 content when 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], becomes
appreciably large (e.g., book chapters and even for music annotation [CITE]. Clearly, a
   screenwriter has no Internet-Drafts--not just
blog posts). Users SHOULD be able to use for specialized Markdown syntax for
   mathematicians; likewise, mathematicians do not need text/markdown to identify
   characters or props convey their
works in common ways. The overall gist is that all of progress, not just their finished products (for which full-
blown markups ranging from text/html to application/pdf are
appropriate). This registration facilitates interoperability between
these communities can take Markdown editors by conveying the common elements syntax of the particular
Markdown (which are
   rooted in variant and the common elements of HTML circa 2004) desired output format.

1.3. RFC 2119

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and build on them "OPTIONAL" 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 are to interpret
   the Markdown. be interpreted as described in [RFC2119].

2. Markdown Media Type Registration Application

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

   The primary purpose of an Internet 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 to label "content"
   on the Internet, as distinct from "files". Content REQUIRED. There
       is any computer-
   readable format that can be represented no default value. [MDSYNTAX] clearly describes Markdown as a primary sequence of
   octets, along with type-specific metadata (parameters) and type-
   agnostic metadata (protocol dependent). From this description, it is
   apparent that appending ".markdown" to
       writing format; its syntax rules operate on characters
       (specifically, on punctuation) rather than code points. Neither
       [MDSYNTAX] nor many popular implementations at the end of a filename is not a
   sufficient means to identify Markdown. Filenames are properties time of
   files in file systems, but this
       registration actually require or assume any particular encoding.
       Many Markdown frequently exists processors will get along just fine by operating on
       character codes that lie in databases or
   content management systems (CMSes) where the file metaphor does not
   apply. One CMS [RAILFROG] uses media types printable US-ASCII, blissfully
       oblivious to select appropriate
   processing, so a media type is necessary for the safe and
   interoperable use coded values outside of Markdown.

   Unlike complete HTML documents, [MDSYNTAX] provides no means to
   include metadata into that range.

    Optional parameters:

     The following parameters reflect the content stream. Several derivative flavors
   have invented metadata incorporation schemes (e.g., [MULTIMD]), but
   these schemes only address specific use cases. In general, author's intent regarding the
   metadata must
     content. A detailed specification can be supplied via supplementary means found in an encapsulating
   protocol, format, or convention. Section 3.

     syntax: The relationship between Markdown-derivative syntax of the content content, with
       optional version and named extensions. Default value: none
       (receiver's choice).

     output-type: The Content-Type (Internet media type) of the metadata is not directly addressed by this specification;
   however, by identifying Markdown output,
       with a media type, optional parameters. Default value: "text/html".

    Encoding considerations: Text.

    Security considerations:

     Markdown content
   can participate interpreted as a first-class citizen with a wide spectrum of
   metadata schemes.

   Finally, registering a media type through the IETF process plain text is not
   trivial. Markdown can no longer be considered a "vendor"-specific
   innovation, but relatively harmless. A text
     editor need only display the registration requirements even in text. The editor SHOULD take care to
     handle control characters appropriately, and to limit the vendor tree
   have proven effect of
     the Markdown to be overly burdensome for most the text editing area itself; malicious Unicode-
     based Markdown implementers.
   Moreover, registering hundreds could, for example, surreptitiously change the
     directionality of Markdown variants with distinct
   media types the text. An editor for normal text would impede interoperability: virtually all Markdown
   content can be processed by virtually any already
     take these control characters into consideration, however.

     Markdown processor, with
   varying degrees of success. The goal of this specification is interpreted as a precursor to
   reduce other formats, such as HTML,
     carries all of these burdens by having one media type that
   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
   document are the security considerations as the target formats.
     For example, HTML can contain instructions to be interpreted 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 described in [RFC2119].

2.  Example

   The following is an example 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 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 is processed. Since Markdown
      =============

      This may have different
     interpretations depending on the tool and the environment, a better
     approach 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 to analyze (and sanitize or block) the media type registration application output markup,
     rather than attempting to analyze the Markdown.

     Security provides a significant motivator 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 output-type
     parameter. Most Markdown processors emit byte (octet) streams.
     Without a well-defined means for a Markdown processor to pass
     metadata onwards, it is REQUIRED. There perilous for post-processing to assume that
     the content is no default value. UTF-8 always HTML or XHTML. A processor might emit
     PostScript (application/postscript) content, for example, in which
     case an HTML sanitizer would fail to excise dangerous instructions.

   Interoperability considerations:

     Markdown syntaxes are designed to be broadly compatible with humans
     ("humane"), but not necessarily with each other. Therefore, syntax
     in one Markdown derivative may be ignored or treated differently in
     another derivative. The overall effect is
     RECOMMENDED; however, neither [MDSYNTAX] nor popular
     implementations at a general degradation of
     the time output, proportional to the quantity of this registration actually require
     or assume any particular encoding. In fact, many syntax-specific
     Markdown
     processors can get along just fine by operating on character codes
     that lie used in the Portable Character Set (i.e., printable US-ASCII),
     blissfully oblivious text. When it is desirable to coded values outside of that range.

    Optional parameters:

     The following parameters reflect the
     author's intent regarding in the
     content. A detailed specification can be found output, stick with the syntax identified in Section 4.

     flavor: The variant, or "flavor" of
     the syntax parameter.

   Published specification: This specification; [MDSYNTAX].

   Applications that use this media type:

     Markdown content, with
       optional rules (qualifiers). Default value: "Original".

     processor: A specific conversion tools, 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 WYSIWYG editors, and plain text
     editors and viewers; markup processor targets indirectly use
     Markdown (e.g., web browsers for Markdown converted to HTML).

   Fragment identifier considerations:

     Markdown interpreted content acts as a "bridge" between plain text is relatively harmless. A text
     editor need only display the text. The editor SHOULD take care to
     handle control characters appropriately, and formal
     markup, so this specification permits fragment identifiers [[NB:
     used to limit the effect of be #i]] #t for the Markdown [[NB: used to the be input]] source text editing area itself; malicious Unicode-
     based Markdown could, and
     #o for example, surreptitiously change the
     directionality output content. The #l and #ldef fragment identifiers
     identify link references. A detailed specification can be found in
     Section 4.

   Additional information:

     Magic number(s): None
     File extension(s): .md, .markdown
     Macintosh file type code(s):
       TEXT. A uniform type identifier (UTI) of the text. An editor for normal text would already
     take these control characters into consideration, however.

     Markdown interpreted as a precursor
       "net.daringfireball.markdown", which conforms to other formats, such as HTML,
     carry all of "public.plain-
       text", is RECOMMENDED [MDUTI]. Additionally, implementations
       SHOULD record syntax and output-type parameters along with the security considerations
       Markdown, such as in extended attributes; however, 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 exact
       manner of storage is a local matter.

   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 registration? No

3.  Optional Parameters

   The optional rules.

   A flavor rule identifier is composed of any sequence of Unicode
   characters excluding spaces (Zs category), control characters,
   quotation marks """, exclamation marks "!", parameters "syntax" and "output-type" can be used by an
   author to indicate the plus sign "+";
   however, lowercase ASCII letters and author's intent regarding how the underscore "_" alone SHOULD Markdown
   ought to be used, where processed.

   All identifiers are case-sensitive; receivers MUST compare for exact
   equality. At the underscore SHOULD same time, identifiers MUST NOT be at registered in the beginning or end.
   The syntax for flavor rules derives
   IANA registry (see Section 6) if another registration differs only in significant part from pandoc
   [PANDOC].

   [[TODO: There
   the casing, as these registrations may cause confusion.

   The following ABNF definitions are no requirements about exclamation marks for
   unregistered rules...flavor rules SHOULD be registered along with used in this section:

          EXTCHAR  = <any character outside the
   flavor, but a receiver does not need printable US-ASCII
                      range, essentially amounting to reject Unicode code
                      points less than U+0020 or greater than U+007E
                      without requiring Unicode or any particular
                      encoding>

          REXTCHAR = <EXTCHAR without separators (Z category) or
                      control characters (C category)>

                  Figure X: ABNF Used in This Section

   The discussion in this section presumes that the flavor parameter
   simply because values are
   discrete strings. When encoded in protocols such as MIME [RFC2045],
   however, the value strings MUST be escaped properly. [MDMTUSES]
   provides some strategies to preserve this information when it does not recognize a rule...it can just ignore leaves
   the
   rule.]]

4.2. processor domain of IETF protocols.

3.1. syntax

   The processor syntax parameter indicates the specific Markdown
   implementation that Markdown-derivative syntax in
   which the author intends be used. The purpose of this
   parameter is composed the content, without regard to any
   particular implementation. With reference to control the automatic processing of "paradigmatic use
   case" (i.e., collaborative Markdown into
   some output format, but editing) in Section 1.3, the
   syntax parameter primarily affects the "left-hand" side of course actual recipients may use this
   information for any useful purpose. a Markdown
   editor. The entire parameter is case-
   sensitive.

   An IANA registry of processors will be created as discussed case-sensitive.

   Syntaxes other than [MDSYNTAX] extend the original rules in
   Section 5. some way.
   These extensions fall into broad categories: clarifying ambiguities
   in [MDSYNTAX], adding brand new features, repurposing [MDSYNTAX] for
   completely new use cases, and adding metadata or other structured
   data blocks. Occasionally new syntaxes directly contradict [MDSYNTAX]
   based on seasoned experience.

   A processor syntax identifier is composed of two or more Unicode characters excluding spaces (Zs category),
   (Unicode) separators, control characters, the hyphen-minus "-",
   quotation marks """, the less-than sign "<", and
   the greater-than sign angle brackets "<" and ">"; however, ASCII
   characters alone SHOULD be used. Additionally, To promote interoperability, only
   registered processor identifiers MUST NOT begin
   with "!", the exclamation mark. Unregistered processor identifiers
   MUST begin with "!" (plus two additional characters). syntaxes are permissible. An IANA registry of syntaxes
   will be created as discussed in Section 6.

   When omitted, the default value is unspecified, which means that the
   syntax interpretation is up to use whatever processor the receiver. However, the receiver prefers.
   SHOULD NOT "guess" based on content-sniffing, as this methodology is
   error-prone. Generators SHOULD always specify a syntax, whether
   explicitly or by context in embedding protocols or formats. All
   implementations MUST NOT emit empty processor
   parameters, but parsers support the syntax value "Original", with the
   meaning covered in Section 6. Generators MUST treat omit the syntax
   parameter rather than transmitting an empty processor parameters string (""); the
   same as if omitted. empty
   string is a syntax error per the ABNF below. The full ABNF of the processor
   syntax parameter is:

      processor-param

      syntax-param     = processor syntax-id [ "-" version ]
                         *( 1*WSP argument extension ) *WSP

      processor        = registered-pid / unregistered-pid

      registered-pid   = pid-char 1*("!" / pid-char)

      unregistered-pid

      syntax-id        = "!" 2*pid-char 2*sid-char

      version          = pid-char *("!" / pid-char)

      argument         = regular-argument / uri-argument

      regular-argument 1*sid-char

      sid-char         = 1*(regular-char %d33 / quoted-chars)

      pid-char         = %d35-%d44 %d35-44 / %d46-%d59 %d46-59 / %d61 /
                         %d63-126 / REXTCHAR

      regular-char

      extension        = ext-name [ ":" ( ext-string / ext-uri ) ]

      ext-name         = 1*( %d33 / %d35-%d59 %d35-57 / %d59 / %d61 /
                             %d63-126 / REXTCHAR
      quoted-chars )

      ext-string       = DQUOTE *pqcontent DQUOTE

      pqcontent ext-quoted [ ext-string ] /
                           ( ext-safe-char / ">" )
                           *( ext-safe-char / "<" / ">" / ext-quoted )

      ext-safe-char    = %d1-%d33 %d33 / %d35-127 %d35-59 / EXTCHAR %d61 / %d63-126 / REXTCHAR
        ; [[NB: Could be EXTCHAR ? depends on how we feel about Unicode
        ; high-order separators]]

      ext-quoted       = DQUOTE *eqcontent DQUOTE

      uri-argument

      ext-uri          = "<" URI-reference ">"         ; from [RFC3986]

      eqcontent        = %d0-33 / %d35-127 / EXTCHAR / DQUOTE DQUOTE

                 Figure X: processor parameter ABNF

4.2.1. processor of the syntax parameter

3.1.1. syntax version

   For better precision, an author MAY include the processor syntax version. The
   version is delimited from the processor syntax identifier with a hyphen-
   minus "-"; hyphen-minus
   "-" and has the same repertoire as the syntax identifier. The version
   string itself is an opaque string. string of at least one character. Version
   strings (e.g., "2.0", "3.0.5") are registered and updated along with
   the processor syntax registration. Updates to processor syntax registrations SHOULD only
   add new versions when those new versions have a material difference
   on the interpretation of the Markdown content. If a
   processor syntax has a
   version "2014.10" and a version "2014.11", for example, but "2014.11"
   only provides performance updates, then fixes typos in the specification, the
   processor registration SHOULD NOT
   separately register the "2014.11" version. The repertoire of the
   version string is the same as the
   processor syntax identifier (and like the
   processor identifier, ASCII characters alone SHOULD be used).

   A receiver that recognizes the processor syntax but not the processor version MAY use any
   version of the processor, syntax, preferably the latest version.

4.2.2. processor arguments

   Processor arguments MAY

3.1.2. syntax extensions

   Some Markdown syntaxes are self-contained, with no options. However,
   others have optional rules or features that may be supplied for finer-grained control over
   how the processor behaves. Multiple arguments and URI references applied with
   discretion. For those syntax systems where optional rules are
   supported.

4.2.2.1. Quoted Arguments

   According to an
   integral feature, the ABNF above, arguments are delimited by whitespace.
   Quotation marks are used to support zero-length arguments, as well as
   whitespace or quotation marks author MAY indicate that those named extensions
   be applied in a single argument. If a quotation
   mark appears anywhere whitespace-separated list. The syntax for extensions
   derives in significant part from pandoc [PANDOC].

   All extensions for a particular syntax are to be registered as part
   of the argument, the following text syntax registration in Section 7.

   An extension identifier is
   considered quoted; two successive quotation marks "" mean one
   quotation mark. A single quotation mark ends the quoting. Because composed of
   this rule, any sequence of characters
   excluding (Unicode) separators, control characters, the colon ":",
   quotation marks do not have to appear """, and angle brackets "<" and ">"; however,
   lowercase ASCII letters and the underscore "_" alone SHOULD be used,
   where the underscore SHOULD NOT be at the termini of beginning or end.

   When present, an
   argument; embedded quotation marks start (and end) quoting within extension is "enabled", "enabled, with string", or
   "enabled, with URI". When absent, an extension is "disabled". An
   extension can have different semantics depending on whether a
   single argument. For example:
      a""b
   means:
      ab

   for the actual argument.

4.2.2.2. string
   or URI Reference Arguments

   Certain processors can take supplementary content, such as metadata,
   from other resources. To support these workflows, is supplied. For example, an author MAY use
   the URI delimiters <> extension "bullet" could specify
   whether and how to signal a URI, such as cid: or mid: URLs
   [RFC2392] in render bulleted lists. "Disabled" could mean
   "bulleted" lists do not have bullets; "enabled" could mean that the context of MIME messages. The URI MUST comply
   bullet is some default character; "enabled, with
   [RFC3986], and MAY be a relative reference if string" could mean
   that the subject Markdown
   content has a base URI. The receiver string is to interpret this used as a
   request to retrieve the resource, and to supply that resource in a
   local reference form bullet; finally, "enabled, with URI"
   could mean that the processor can use (e.g., via a
   temporary file). The image identified by URI MUST be entire argument; is used as the URI cannot be
   combined bullet.

3.1.2.1. Enabled, with other text String

   According 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 above, extensions are delimited by whitespace.
   Quotation marks are used to some other file reference (such as parent directories like
   ../ support zero-length strings, whitespace
   or quotation marks in a single string, or special files such as /dev/hd0). If the processor accepts URI strings directly, where the string first
   character is to be supplied as "<". If a regular string
   without <> delimiters. For security reasons, direct file references
   MUST NOT be included quotation mark appears anywhere in the processor arguments.

   The prior paragraph notwithstanding, certain workflows may require
   file references. In such cases, file: URLs [RFC1738] (including
   relative references) are appropriate. The receiver SHOULD apply string,
   the
   same security and privacy analyses to file: URLs as it would to any
   other URI.

4.2.2.3. Appropriate Arguments and Security Considerations

   Not all arguments are appropriate for inclusion following text is considered quoted; two successive quotation
   marks "" within quoted text mean one quotation mark in the processor
   parameter. Appropriate arguments are basically limited to those that
   affect string. A
   single quotation mark ends the output markup, without side-effects. Arguments quoting. Generators MUST NOT
   identify input sources or output destinations. For example, if a
   processor normally reads Markdown input using the arguments "-i
   filename" or "< filename" (i.e., from standard input), those
   arguments MUST be omitted. Arguments that have no bearing on the
   output MUST be omitted as well, such generate
   unterminated quoted strings; however, parsers SHOULD treat an
   unterminated quoted string as arguments that control
   verbosity if it were terminated. Because of the processor (-v) or that cause side-effects (such as
   writing diagnostic messages this
   rule, quotation marks do not have to some other file). Of course, if
   warnings or errors are signaled within appear at the output, arguments enabling
   that output MAY be used.

   When in doubt, termini of a receiver SHOULD omit arguments with unknown or
   undocumented effects, and MAY ignore author-supplied arguments
   entirely, but SHALL NOT reorder arguments. An author has very little
   assurance that
   string; embedded quotation marks start (and end) quoting within a receiver will honor unregistered arguments.
   Consequently, the burden is squarely on processor registrants
   (Section 5.2) to document their arguments properly.
   single argument. For security reasons, example:
      a""b
   means:
      ab
   for the parsed argument array (or a actual argument. In spite of this relaxed positioning rule,
   for human readability generators SHOULD quote the entire string
   unambiguously representing in
   lieu of embedding quoted sub-strings.

3.1.2.2. Enabled, with URI

   Certain syntaxes can take supplementary content, such as metadata,
   from other resources. To support these workflows, an extension can
   use the delimited argument array) MUST be
   passed directly URI delimiters "<" and ">" to the processor. Emitting the argument array as-is
   in signal a batch script (for example) may cause risky side effects, URI, such as
   automatic substitutions, alias activation, a cid: or macro execution. The
   arguments
   mid: URL [RFC2392] in this parameter MUST be encoded to preserve characters
   outside the context of US-ASCII, MIME messages. The URI MUST
   comply with [RFC3986], and to signal the required encoding to MAY be a relative reference if the
   receiver. When going between (system) processes, some implementations
   may interpret character codes based on locale environment variables.
   Therefore, it is not sufficient to pass arguments from this subject
   Markdown content has a base URI. The charset parameter
   "as-is" to the processor: the routine MUST change the locale or
   transform specifies the arguments to an appropriate
   character encoding so that
   there is no ambiguity. Furthermore, relevant to the NUL character (%d0, U+0000)
   is not permitted because most common operating systems use URI's semantics (to the
   extent that code
   point as a delimiter.

4.2.3. Examples of processor parameters

   [[TODO: provide examples.]]

4.3. the URI needs it).

3.2. output-type

   The output-type parameter indicates the Internet media type (and
   parameters) of the output from output from the processor. With reference to the
   "paradigmatic use case" (i.e., collaborative Markdown editing) in
   Section 1.3, the outout-type parameter primarily affects the processor. "right-
   hand" side of a Markdown editor.

   When omitted, the default value is "text/html". Generators MUST NOT
   emit empty output-type parameters, but parsers MUST treat empty
   output-type parameters Implementations
   SHOULD anticipate and support HTML (text/html) and XHTML
   (application/xhtml+xml) output, to the same as if omitted. extent that a syntax targets
   those markup languages.

   The default value of text/html ought to be suitable for the majority
   of current purposes. However, Markdown is increasingly becoming
   integral to workflows where HTML is not the target output; examples
   range from TeX [CITE], TeX, to PDF [CITE], PDF, to OPML [CITE], OPML, and even to entire e-books [CITE].

   Security provides a significant motivator for this parameter. Most
   Markdown processors emit byte (octet) streams; without a well-defined
   means (e.g.,
   [PANDOC]). Anticipated output types for a Markdown processor to pass metadata onwards, it is
   perilous for post-processing particular syntax are to assume that be
   registered as part of the content is always
   HTML. A processor might emit PostScript (application/postscript)
   content, for example, syntax registration in which case an HTML sanitizer would fail to
   excise dangerous instructions. Section 7.

3.2.1. Value Format and Semantics

   The value of output-type is an Internet media type with optional
   parameters. The syntax (including case sensitivity considerations) is
   the same as specified in [RFC2045] for the Content-Type header (with
   updates over time), namely:

          type "/" subtype *(";" parameter)
                          ; Matching of media type and subtype
                          ; is ALWAYS case-insensitive.

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

   The Internet media type in the output-type parameter MUST be
   observed. Processors or processor arguments that conflict with the
   output-type parameter MUST be re-chosen, ignored, or rejected.

   Although arbitrary optional parameters may be passed along with the Internet
   media type, receivers are under no obligation to honor or interpret
   them in any particular way. For example, the parameter value
   "text/plain; format=flowed; charset=ISO-2022-JP" obligates the
   receiver to output text/plain (and to treat the output as plain text-
   -no text:
   no sneaking in or labeling the output as HTML!). In contrast, such a
   parameter value neither obligates the receiver to follow [RFC3676]
   (for flowed output) nor to output ISO-2022-JP Japanese character
   encoding (see [RFC1468]).

   Markdown implementations for all kinds of formats already exist,
   including formats that are not registered Internet media types, or
   that are inexpressible as Internet media types. For example, one
   Markdown processor for the mass media industry outputs formatted
   screenplays [CITE to fountain.io]: none of applicable media types
   application/pdf, text/html, or text/plain adequately distinguish this
   kind of output. Such distinctions SHOULD be made in the processor
   parameter (and to a lesser extent, the flavor parameter),
   underscoring that the primary concern of the output-type parameter is
   making technical and security-related decisions.

   The output-type parameter does not distinguish between fragment
   content and whole-document content. A Markdown processor MAY (and
   typically will) output HTML or XHTML fragment content, without
   preambles or postambles such as <!DOCTYPE>, <html>, <head>, </head>,
   <body>, </body>, or </html> elements. Receivers MUST be aware of this
   behavior and take appropriate precautions.

   [[TODO: consider.]] Fragment vs. whole-
   document output considerations are appropriate for addressing in
   syntax specifications, either as part of the syntax or by a syntax
   extension.

3.2.2. text/markdown Special Value

   The author may specify the output-type "text/markdown", which has a
   special meaning. "text/markdown" means that the author does not want
   to invoke Markdown processing at all: the receiver SHOULD view the
   Markdown source as-is. In this case, the processor choice has little
   practical effect because the Markdown is not actually processed, but
   other tools can use the flavor parameter (and secondarily if so
   inclined,
   special meaning. "text/markdown" means that the processor parameter) author does not want
   to perform useful services such as
   syntax highlighting. invoke Markdown processing at all: the receiver SHOULD view the
   Markdown source as-is.

   This output-type is not the default because one generally assumes
   that Markdown is meant for composing rather than reading: readers
   expect to see the output format (or dual-display of the output and
   the Markdown). However, if authors are collaboratively editing a
   document or are discussing Markdown, "text/markdown" may make sense.
   Furthermore, "text/markdown" differs from "text/plain" in that
   "text/plain" encompasses a wide range of characters and formatting
   techniques (in Unicode, examples include bullet points, roman
   numerals, unambiguous line and paragraph separators, and interlinear
   annotation). While the optional parameter output-type may be used
   recursively (as a sneaky way to stash the author's follow-on or
   secondary intent), receivers are not obligated to recognize it;
   optional parameters internal to output-type MAY be ignored.

5.  IANA Considerations

   IANA is asked to register the media type text/markdown in the
   Standards tree using the application provided in Section 2 of this
   document.

   IANA is also asked

4. Fragment Identifiers

4.1. #t

   [[NB: This section used to establish a subtype registry called "Markdown
   Parameters". say: The registry has two sub-registries: a registry of
   flavors and fragment #i refers to the content
   input into a registry of processors.

5.1. Registry Markdown processor, which for purposes of Flavors

   Each entry in this registry shall consist of a flavor identifier and
   information about the flavor, fragment
   identifier, MUST be treated 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 plain text (text/plain).]]

   The fragment #t refers to documentation.]

      Responsible Parties:
       {for each party}
        ([type: individual, corporate, representative])
        [Name] <contact info 1>...<contact info n>

      Currently Maintained? [Yes/No]
      Tools:
       {for each tool}
        Name: [Name]
        Version(s): [Significant version or versions that
                     implement the flavor]
        Type: ["Processor" or some other type]
        Reference(s): <contact info 1>...<contact info n>
        Purpose: [Concise, prose description Markdown content treated as plain text
   (text/plain). A specific area of the tool.]

   A responsible party text can be an individual author or maintainer, identified with a
   corporate author or maintainer (plus an individual contact),
   text/plain sub-fragment identifier (e.g., [RFC5147] or its
   successors) delimited by a
   representative second "#" character. For example:
   #t#line=10 identifies the eleventh line of a community Markdown input.
   Implementers should take heed that the "char" scheme counts by
   characters rather than octets (or, for that matter, code points);
   thus proper interpretation of interest dedicated to the Markdown
   syntax.

   Multiple tools MAY be listed, but only one charset parameter is necessary REQUIRED for a
   successful registration. If a tool is
   interoperability of the "char" scheme. For example, "character" and
   "code point" are NOT synonymous in the Unicode Standard.

4.2. #o

   The fragment #o refers to the content output from a Markdown
   processor, it MUST
   be registered; however, any Markdown-related tool (for example,
   graphical editors, emacs "major modes", web apps) which is acceptable. governed by the output-type parameter. A specific
   area of the output can be identified with a sub-fragment identifier
   delimited by a second "#" character. The
   purpose encoding and semantics of
   sub-fragment identifiers are also governed by the tool requirement is to ensure that output-type
   parameter. Examples: when the flavor output-type is
   actually used in practice.

5.1.2. Initial Registration

   The registry shall have text/html [RFC2854],
   #o#section6 identifies the named anchor "section6" specified by the
   input that the 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 processor converts to HTML or XHTML circa 2004.

5.1.3. Reserved Identifiers
   The flavors registry SHALL have <a
   name=section6>...</a>. When the following identifiers RESERVED.
   No one output-type is allowed application/pdf
   [RFC3778], #o#page=6 causes the sixth page to register them (or any case variations open.

   When the output-type is "text/markdown" (regardless of them).
      Standard
      Common
      Markdown

5.1.4. Standard parameters),
   the #o fragment identifier has no semantics; generators MUST use #t
   in lieu 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. #o.

4.3. #l and #ldef

   The designated expert SHALL review the flavor registration. fragment prefix #l refers to links by their link identifiers. The
   sub-component of this identifier MUST comply with is delimited by a second "#"
   character, followed by the syntax specified encoded link identifier, optionally
   followed by a 1-based index number. Without the index number, the
   fragment refers to all such identified links. Example: #l#eS matches
   links such as "The rain in [Spain][ES]" and "The word [es][] means
   'is' in this document.
   Additionally, Spanish." #l#es#2 only matches the identifier MUST NOT differ from other registered
   identifiers merely by case. second instance of the
   "es" link identifier.

   The description and documentation SHOULD
   provide sufficient guidance to an implementer fragment prefix #ldef refers to implement link reference definitions. The
   sub-component of this identifier is delimited by a tool to
   handle second "#"
   character, followed by the flavor. The designated expert SHOULD warn encoded link identifier. There is no index
   number; in the registrant
   if case of multiple link reference definitions, the description last
   definition wins.

   Both the #l and documentation #ldef REQUIRE that "#" characters be percent-encoded
   if they are inadequate; however,
   inadequacy (in the opinion part of the designated expert) will not bar a
   registration.

   All references (including contact information) MUST be verified as
   functional at the time link identifier. The percent-encoding of
   other characters follow the registration.

   If regular rules of [RFC3986]. [MDSYNTAX]
   states that identifiers (or names) "may consist of letters, numbers,
   spaces, and punctuation--but they are included in the registration, NOT case sensitive." Characters
   outside of the rule identifiers MUST
   comply URI character set SHALL be percent-encoded with the syntax specified in this document. The description
   same encoding as the Markdown content. For maximum compatibility and documentation of each rule
   readability, authors who intend to reference links in fragment
   identifiers SHOULD provide sufficient guidance limit themselves to
   an implementer URI characters that do not
   require percent-encoding.

4.4. Other Fragment Identifiers

   Specific syntaxes may define additional fragment identifiers specific
   to implement the syntax. For example, a tool syntax that incorporates "header"
   information might consider #h to refer to the "header" part, and #b
   to refer to the "body" part.

5.  Example

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

    MIME-Version: 1.0
    Content-Type: text/markdown; charset=UTF-8; syntax=Original;
     output-type="application/xhtml+xml"
    Content-Disposition: attachment; filename=readme.md

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

    This is some sample Markdown. [Hooray!][foo]
    (Remember that link identifiers 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/loc 'Will Not Work with Markdown.pl-1.0.1'

6.  IANA Considerations

   IANA is asked to handle the rule. The designated
   expert SHOULD warn the registrant if the description and
   documentation are inadequate; however, inadequacy (in the opinion of register the designated expert) will not bar a registration.

   The designated expert MUST determine that all tools listed media type text/markdown in the
   registration are real implementations. If a tool is a Markdown
   processor, the processor MUST be registered in
   Standards tree using the Registry of
   Flavors application provided in Section 5.2. The designated expert MAY request that the
   registrant provide evidence that a tool actually works (for example,
   that it passes certain test suites); however, the failure 2 of a tool
   to work according to the flavor registration will not bar a
   registration. (For example, not even Gruber's own Markdown.pl
   implementation complies with [MDSYNTAX]. C'est la vie!)

   If a registration this
   document.

   IANA is being updated, the designated expert SHOULD
   verify that the updating registrant matches the contact information
   on the prior registration, and if not, that the updating registrant
   has authority from the prior registrant also asked to update it. All fields may
   be updated except the Identifier, which is permanent: not even case
   may be changed.

5.2. Registry of Processors establish a subtype registry called "Markdown
   Syntaxes". Each entry in this registry SHALL shall consist of a processor syntax
   identifier and information about the processor, syntax, as follows:

5.2.1. Processor

6.1. Syntax Template

      {if provisional}
      PROVISIONAL REGISTRATION EXPIRES [YYYY-MM-DD date format]

      Identifier: [Identifier]

      Description: [Concise, prose description of the processor, syntax, with
                    emphasis on its purpose, the community
                    that it addresses, purpose and notable variations
                    from [MDSYNTAX] or another flavor.] syntax. If the syntax
                    permits structured data, this fact ought to be
                    included. Other Markdown syntaxes may be referenced
                    by quoting their registered identifiers.]

      Documentation: [References to documentation.]

      Community of Use: [Concise, prose description of the
                         community of use, such as
                         "scholarly publications" or "screenwriting".
                         "General" may be entered if the community
                         encompasses general users of the Internet.]
                        [[TODO: Users (screenwriters) or use cases
                          (screenwriting)?]]

      [[NB: Should Versions: and Extensions: be {optional} and
        therefore omittable, or should they have "None." to
        indicate that no versions or extensions apply?]]
      Versions:
       {for each version}
        Identifier: [Identifier]
        Description: [Optional, concise, prose description of the
          version. "N/A" SHALL be used to indicate no description.]

      Arguments:
       {in general}
        Argument Ordering: [Concise, prose description of how
                            arguments need to be ordered.]

      Extensions:
       {for each argument}
        Argument extension}
        Identifier: [Identifier]
        Syntax: [Syntax here; multiple consecutive argument
          positions are allowed, separated by a single space. Use
          braces for variable information (add : for example input),
          <URI> for URI references, and .. for sequences of arguments
         {if Enabled}
          Enabled
         {if Enabled, with # as a placeholder for the number String}
          Enabled, with String: [prose description of arguments or
          ..-.. to indicate what the first character
                                 string is (not what it does)]
         {if Enabled, with URI}
          Enabled, with URI: [prose description of what the subsequent
          argument that ends the sequence, e.g.:
                          -c
                          --title {title: "The Rain in Spain"}
                          --metadata <URI>
                          --bullet-chars:{#} {char 1}..{char #}
                          --verbs {verb: walk, run, sleep}..-..
                          ] URI
                              is (not what it does)]
        Description: [Concise, prose description of the argument.] extension,
                      i.e., what it does.]
        Documentation: [References to documentation.]

      Anticipated Output Type(s): [Internet media types, comma-separated
                       (with optional LWSP)]

      Security Considerations: [Sufficient Types:
       {for each output-type}
        [media type]
          {optional} [prose description of risks and
                                other considerations; "N/A" or
                                "None" responses are insufficient.] parameter considerations]

      {optional}
      Additional Fragment Identifiers:
       [Prose description of additional fragment identifiers,
        sufficient for interoperability.]

      Responsible Parties:
       {for each party}
        ([type: individual, corporate, representative])
        [Name] <contact info 1>...<contact info n>

      Currently Maintained? [Yes/No]

      {optional}
      Implementations:
       {for each implementation}
        Name: [Name]
        Version(s): [Significant version or versions that
                     implement the syntax]

        Type: ["Processor" or some other type]
        References: <contact info 1>...<contact info n>
        Purpose: [Concise, prose description of the implementation.]

   A responsible party can be an individual author or maintainer, a
   corporate author or maintainer (plus an individual contact), or a
   representative of a community of interest dedicated to the Markdown
   processor.

5.2.2.
   syntax.

   The Versions, Extensions, Additional Fragment Identifiers, and
   Implementations sections are optional.

6.2. Initial Registration

   The registry shall have the following initial registration: registration;
   implementations conforming to this document MUST handle this syntax.
   [MDMTUSES] provides additional exemplary syntaxes.

      Identifier: Markdown.pl Original

      Description: Gruber's original Markdown processor, written in
                   Perl. Requires Perl 5.6.0 or later. "Welcome to syntax.

      Documentation:
        [MDSYNTAX]. For the 21st Century." Works with Movable Type 2.6+,
                   Blosxom 2.0+, BBEdit 6.1+, and "2004" version, 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 documentation is
        provided in HTML and adds several new features; see
                    VERSION HISTORY in Markdown.pl.

      Arguments:
       Argument Syntax: --html4tags Markdown, as follows:
        syntax:      Content-Type: text/html; charset=UTF-8
                     Accessed at October 12, 2014 8:27 PM (-0700)
                     38570 bytes
                     SHA-256 hash: B2EC2A62 3257F164 FBC88AE8 C7E76F3F
                                   80F16845 105D9F3E 3E8CE25B 6F0CB33B

        syntax.text: Content-Type: text/plain; charset=UTF-8
                                   (actually text/markdown;
                                    syntax=Original;
                                    output-type="text/markdown")
                     Accessed at October 12, 2014 8:27 PM (-0700)
                     27784 bytes
                     SHA-256 hash: 01A6A07A F51838E1 8749454B 06D716BC
                                   B1BC0EAA A21B67B7 D6FB5A6B 4FFB5D5B

      Community of Use: General.

      Versions:
        Identifier: 2004
        Description:
         "Use the --html4tags command-line switch [MDSYNTAX] as it (is rumored to have) existed
                     since December 14, 2004, corresponding 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 1.0.1. The version "2004" SHOULD NOT
                     be analyzed as
         text/html; the processor makes no attempt to make
         its output well-formed application/html+xml
         (not surprising--see specified until further notice; is is only
                     documented for completeness (in case Gruber
                     revises the design philosophy).
       Documentation: [MARKDOWN] syntax with material contradictions).

      Anticipated Output Type: Types:
        text/html

      Security Considerations: The security of this implementation
                               has not been fully analyzed.
        application/xhtml+xml

      Responsible Parties:
       (individual) John Gruber <http://daringfireball.net/>
                                <comments@daringfireball.net>

      Currently Maintained? No [[TODO: maybe?]]

5.2.3.

      Implementations:
       Name: Markdown.pl
       Version(s): 1.0.1, 1.0.2b8
       Type: Processor
       References: [MARKDOWN]
       Purpose: Converts Markdown to HTML or XHTML circa 2004.
                The argument "--html4tags" causes HTML output.

6.3. Reserved Identifiers

   The processors registry SHALL have the following identifiers RESERVED. No one is
   allowed to register them (or any case variations of them).
      Standard
      Common
      Markdown
      md

5.2.4.

6.4. Standard of Review

   Registrations are made on a First-Come, First-Served [RFC5226]. [RFC5226] basis
   by anyone with a need to interoperate. While documentation is
   required, any level of documentation is sufficient; thus, neither
   Specification Required nor Expert Review are warranted. The checks
   prescribed by this section can be performed automatically.

   The identifier

   Syntax, version, and extension identifiers MUST comply with the syntax
   syntaxes specified in this document. Additionally, the identifier
   MUST NOT differ from other registered identifiers merely by case. The description and
   documentation SHOULD provide sufficient guidance to an implementer
   Identifiers MUST conform to
   know how [[TODO: PRECIS? STRINGPREP?]]. The
   purpose of this requirement is to invoke eliminate confusingly similar
   identifiers, placing the processor and handle burden on the output. registration process rather
   than on syntax parameter parsers.

   All references (including contact information) MUST be verified as
   functional at the time of the registration.

   If arguments are included in the registration, the Argument Syntax
   MUST comply with the template instructions in Section 5.2.1. Each
   description and documentation field SHOULD provide sufficient
   guidance to an implementer to know how to invoke the processor and
   handle the output.

   The Security Considerations field is not optional; it MUST be
   provided.

   If a registration is being updated, the contact information MUST
   either match the prior registration and be verified, or the prior
   registrant MUST confirm that the updating registrant has authority to
   update the registration. As a special "escape valve", registrations
   can be updated with IETF Review [RFC5226]. [[NB: Two purposes: 1) to
   deal with "harmful" registrations (stale references are not a
   sufficient justification); 2) to deal with registrations that are
   IETF registrations, like RFC-related Markdown (but this could be
   handled by listing the IETF as the contact organization, right?).]]
   All fields may be updated except the
   Identifier, syntax identifier, which is
   permanent: not even case may be changed.

6.

6.5. Provisional Registration

   Any registrant may make a provisional registration to reserve a
   syntax identifier. Provisional registrations include the ALL-CAPS
   legend as shown in Section 6.1. All fields are optional except for
   the syntax identifier and contact information. Provisional
   registrations expire after three months, after which time the syntax
   identifier may be reused.

7. Security Considerations

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

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

7.

8. References

7.1.

8.1. Normative References

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

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

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

   [MDUTI]    Gruber, J., "Daring Fireball: Uniform Type Identifier for
              Markdown", August 2011,
              <http://daringfireball.net/linked/2011/08/05/markdown-
              uti>.

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

   [RFC2854]  Connolly, D. and L. Masinter, "The 'text/html' Media
              Type", RFC 2854, June 2000.

   [RFC3778]  Taft, E., Pravetz, J., Zilles, S., and L. Masinter, "The
              application/pdf Media Type", RFC 3778, May 2004.

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

   [RFC5147]  Wilde, E. and M. Duerst, "URI Fragment Identifiers for the
              text/plain Media Type", RFC 5147, April 2008.

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

7.2.

8.2. Informative References

   [HUMANE]   Atwood, J., "Is HTML a Humane Markup Language?", May 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/>.

   [MDMTUSES] Leonard, S., "text/markdown Use Cases", draft-seantek-
              text-markdown-use-cases-00 (work in progress), October
              2014.

   [PANDOC]   MacFarlane, J., "Pandoc", 2014,
              <http://johnmacfarlane.net/pandoc/>.

   [RAILFROG] Railfrog Team, "Railfrog", April 2009,
              <http://railfrog.com/>.

   [RFC0793]  Postel,

   [RFC1468]  Murai, J., "Transmission Control Protocol", STD 7, Crispin, M., and E. van der Poel, "Japanese
              Character Encoding for Internet Messages", RFC
              793, September 1981. 1468, June
              1993.

   [RFC2392]  Levinson, E., "Content-ID and Message-ID Uniform Resource
              Locators", RFC 2392, August 1998. 2392, August 1998.

   [RFC3676]  Gellens, R., "The Text/Plain Format and DelSp Parameters",
              RFC 3676, February 2004.

   [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.,

   [FOUNTAIN] Maschwitz, S. 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.]] J. August, "Fountain | A markup language
              for screenwriting.", 2014, <http://fountain.io/>.

   [FTSYNTAX] Maschwitz, S. and J. August, "Syntax - Fountain | A markup
              language for screenwriting.", 1.1, March 2014,
              <http://fountain.io/syntax>.

Appendix A.  Change Log

   This draft is a continuation from draft-ietf-appsawg-text-markdown-
   01.txt.
   02.txt. These technical changes were made:

      1.  The entire  Proposed that the document was reorganized: optional parameters now
          have their own section, and be split into two documents: the Introduction section
          main document (which is
          divided into four subsections.
      2. normative), and a second document. The Introduction section
          second document (draft-seantek-text-markdown-use-cases-00)
          [MDMTUSES] provides substantial additional background information, along with goals
          suggestions for preserving metadata, registration templates
          for common Markdown syntaxes, and use cases examples for both common Markdown
          syntaxes. RFC 2119 key words are not included in draft-
          seantek-text-markdown-use-cases because this content is not
          normative (at least, not as normative) compared with the main
          document.
      2.  De-emphasized Unicode (and UTF-8 encoding) after close
          consideration of the original [MDSYNTAX], and the Internet media type registration. various
          proposed extensions to Markdown in the intervening time.
          "CommonMark", for example, places stronger emphasizes on
          Unicode (and UTF-8).
      3.  The rules  Deleted processor parameter.
      4.  Renamed flavor parameter was reverted back to flavor, and flavor
          was beefed up.
      4.  The processor parameters were consolidated and simplified. syntax parameter.
      5.  Dependencies on POSIX were removed.  Renamed "rules" to "extensions" in the syntax parameter.
      6.  The output-type parameter was added.
      7.  Unregistered identifiers  Parameterized "extensions" so that it can be used with their own ! syntax.
      8.  The IANA Considerations section was fleshed out have a string or a
          URI.
      7.  Simplified the syntax parameter (compared to draft-02, in great
          detail, any
          event) with emphasis on easing the registration process.
      9.  Security considerations were weaved throughout the
          specification. Overall, most of the complexity fewer exceptional cases in this
          specification comes directly from the security considerations.
          Those considerations are necessary since a lot ABNF.
      8.  Rewrote significant parts of bad things
          can and will happen when HTML, URIs, the output-type parameter, and executable code get
          together.
          gave text/markdown additional explanation.
      9.  Rewrote the introduction so that it is much shorter.
      10. Changed Moved the example in Section 2 to use initially registered
          identifiers. towards the end.
      11. Added output-type="text/markdown" for recursive handling
          (i.e., don't process this Markdown, just show it like Fragment Identifier Considerations.
      12. Consolidated the Security Considerations into the registration
          template.
      13. Rewrote the IANA Considerations section so that it is). only
          creates one new registry.
      14. Redefined the flavors registry (now called the Markdown
          Syntaxes registry).
      15. Rewrote the "Original" syntax registration to conform to the
          new registration template.
      16. Added a discussion and example of the Paradigmatic Use Case
          (Markdown Editors).

Author's Address

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

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