[Docs] [txt|pdf] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 draft-ietf-appsawg-text-markdown-use-cases

Network Working Group                                         S. Leonard
Internet-Draft                                             Penango, Inc.
Intended Status: Informational                          October 17, 2014
Expires: April 20, 2015



                        text/markdown Use Cases
                draft-seantek-text-markdown-use-cases-00

Abstract

   This document elaborates upon 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.
   Background information, local storage strategies, and additional
   syntax registrations are supplied.

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.

Table of Contents

   1.  Dive Into Markdown . . . . . . . . . . . . . . . . . . . . . .  2



Leonard                   Exp. April 20, 2015                   [Page 1]


Internet-Draft          text/markdown Use Cases             October 2014


     1.1. On Formats  . . . . . . . . . . . . . . . . . . . . . . . .  2
     1.2. Markdown Design Philosophy  . . . . . . . . . . . . . . . .  4
     1.3. Uses of Markdown  . . . . . . . . . . . . . . . . . . . . .  5
     1.4. Uses of Labeling Markdown Content as text/markdown  . . . .  5
   2.  Strategies for Preserving Media Type and Parameters  . . . . .  6
     2.1. Map to Attributes . . . . . . . . . . . . . . . . . . . . .  6
     2.2. Store Headers in Adjacent File  . . . . . . . . . . . . . .  6
     2.3. "Arm" Content with MIME Headers . . . . . . . . . . . . . .  7
     2.4. Create a Local Batch Script . . . . . . . . . . . . . . . .  7
     2.5. Process the Markdown  . . . . . . . . . . . . . . . . . . .  7
     2.6. Rely on Context . . . . . . . . . . . . . . . . . . . . . .  7
   3.  Registration Templates for Common Markdown Syntaxes  . . . . .  8
     3.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . .  8
     3.2. GitHub Flavored Markdown  . . . . . . . . . . . . . . . . . 10
     3.3. Pandoc  . . . . . . . . . . . . . . . . . . . . . . . . . . 11
     3.4. Fountain (Fountain.io)  . . . . . . . . . . . . . . . . . . 14
     3.5. CommonMark  . . . . . . . . . . . . . . . . . . . . . . . . 15
     3.6. kramdown-rfc2629 (Markdown for RFCs)  . . . . . . . . . . . 16
     3.7. rfc7328 (Pandoc2rfc)  . . . . . . . . . . . . . . . . . . . 17
   4.  Examples for Common Markdown Syntaxes  . . . . . . . . . . . . 17
     4.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 17
     4.2. GitHub Flavored Markdown  . . . . . . . . . . . . . . . . . 18
     4.3. Pandoc  . . . . . . . . . . . . . . . . . . . . . . . . . . 18
     4.4. Fountain (Fountain.io)  . . . . . . . . . . . . . . . . . . 18
     4.5. CommonMark  . . . . . . . . . . . . . . . . . . . . . . . . 18
     4.6. kramdown-rfc2629 (Markdown for RFCs)  . . . . . . . . . . . 18
     4.7. rfc7328 (Pandoc2rfc)  . . . . . . . . . . . . . . . . . . . 18
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 18
   6. Security Considerations . . . . . . . . . . . . . . . . . . . . 18
   7. References  . . . . . . . . . . . . . . . . . . . . . . . . . . 18
     7.1. Normative References  . . . . . . . . . . . . . . . . . . . 18
     7.2. Informative References  . . . . . . . . . . . . . . . . . . 18
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20


1.  Dive Into Markdown

   This document serves as an informational companion to [MDMTREG], the
   text/markdown media type registration. It should be considered
   jointly with [MDMTREG].

         "Sometimes the truth of a thing is not so much in the
         think of it, but in the feel of it." --Stanley Kubrick

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



Leonard                   Exp. April 20, 2015                   [Page 2]


Internet-Draft          text/markdown Use Cases             October 2014


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



Leonard                   Exp. April 20, 2015                   [Page 3]


Internet-Draft          text/markdown Use Cases             October 2014


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

   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 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-5].) As a result, there is no
   such thing as "invalid" Markdown; there is no standard demanding
   adherence to the Markdown syntax; there is no governing body that
   guides or impedes its development. If the Markdown syntax does not
   result in the "right" output (defined as output that the author
   wants, not output that adheres to some dictated system of rules),



Leonard                   Exp. April 20, 2015                   [Page 4]


Internet-Draft          text/markdown Use Cases             October 2014


   Gruber's view is that the author either should keep on experimenting,
   or should change the processor to address the author's particular
   needs (see [MARKDOWN] Readme and [MD102b8] perldoc; see also
   [CATPICS]).

1.3. Uses of Markdown

   Since its introduction in 2004, Markdown has enjoyed remarkable
   success. Markdown works for users for three key reasons. First, the
   markup instructions (in text) look similar to the markup that they
   represent; therefore the cognitive burden to learn the syntax is low.
   Second, the primary arbiter of the syntax's success is *running
   code*. The tool that converts the Markdown to a presentable format,
   and not a series of formal pronouncements by a standards body, is the
   basis for whether syntactic elements matter. Third, Markdown has
   become something of an Internet meme [INETMEME], in that Markdown
   gets received, reinterpreted, and reworked as additional communities
   encounter it. There are communities that are using Markdown for
   scholarly writing [CITE], for screenplays [FOUNTAIN], 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

   The primary purpose of an Internet media type is to label "content"
   on the Internet, as distinct from "files". Content is any computer-
   readable format that can be represented as a primary sequence of
   octets, along with type-specific metadata (parameters) and type-
   agnostic metadata (protocol dependent). From this description, it is
   apparent that appending ".markdown" to the end of a filename is not a
   sufficient means to identify Markdown. Filenames are properties of
   files in file systems, but Markdown frequently exists in databases or
   content management systems (CMSes) where the file metaphor does not
   apply. One CMS [RAILFROG] uses media types to select appropriate
   processing, so a media type is necessary for the safe and
   interoperable use of Markdown.

   Unlike complete HTML documents, [MDSYNTAX] provides no means to
   include metadata into the content stream. Several derivative flavors
   have invented metadata incorporation schemes (e.g., [MULTIMD]), but
   these schemes only address specific use cases. In general, the
   metadata must be supplied via supplementary means in an encapsulating
   protocol, format, or convention. The relationship between the content



Leonard                   Exp. April 20, 2015                   [Page 5]


Internet-Draft          text/markdown Use Cases             October 2014


   and the metadata is not directly addressed here or in [MDMTREG];
   however, by identifying Markdown with a media type, Markdown content
   can participate as a first-class citizen with a wide spectrum of
   metadata schemes.

   Finally, registering a media type through the IETF process is not
   trivial. Markdown can no longer be considered a "vendor"-specific
   innovation, but the registration requirements even in the vendor tree
   have proven to be overly burdensome for most Markdown implementers.
   Moreover, registering hundreds of Markdown variants with distinct
   media types would impede interoperability: virtually all Markdown
   content can be processed by virtually any Markdown processor, with
   varying degrees of success. The goal of [MDMTREG] is to reduce all of
   these burdens by having one media type that accommodates diversity
   and eases registration.

2.  Strategies for Preserving Media Type and Parameters

   The purpose of this document and [MDMTREG] is to promote
   interoperability between different Markdown-related systems,
   preserving the author's intent. While [MARKDOWN] was designed by
   Gruber in 2004 as a simple way to write blog posts and comments, as
   of 2014 Markdown and its derivatives are rapidly becoming the formats
   of record for many communities and use cases. While an individual
   member of (or software tool for) a community can probably look at
   some "Markdown" and declare its meaning intuitively obvious, software
   systems in different communities (or different times) need help.
   [MDSYNTAX] does not have a signaling mechanism like <!DOCTYPE>, so
   tagging Markdown internally is simply out of the question. Once tags
   or metadata are introduced, the content is no longer "just" Markdown.

   It is hoped that the media type and parameters in [MDMTREG] will
   provide this missing context for the foreseeable future. This section
   covers strategies for how an application might preserve this metadata
   information when it leaves the domain of IETF protocols.

2.1. Map to Attributes

   This strategy is to map the media type and parameters to "attributes"
   or "forks" in the local convention. Firstly, Markdown content saved
   to a file SHOULD have an appropriate file extension such as .md or
   .markdown, which serves to disambiguate it from other kinds of files.
   Many modern filesystems permit "extended attributes", "alternate data
   streams", or "resource forks". Some version control systems permit
   named properties, which are analogous to a filesystem's extended
   attributes.

2.2. Store Headers in Adjacent File



Leonard                   Exp. April 20, 2015                   [Page 6]


Internet-Draft          text/markdown Use Cases             October 2014


   This strategy is to save the Markdown content in a first file, and to
   save the metadata (specifically the Content-Type: header) in a second
   file with a filename that is rationally related to the first
   filename. For example, if the first file is named "readme.markdown",
   the second file could be named "readme.markdown.headers". (If stored
   in a database, the analogy would be to store the metadata in a second
   table with a field that is a key to the first table.)

2.3. "Arm" Content with MIME Headers

   This strategy is to save the Markdown content along with its headers
   in a file, "arming" the content by prepending the MIME headers
   (specifically the Content-Type: header). It should be appreciated
   that the file is no longer a "Markdown file"; rather, it is an
   Internet Message Format file (e.g., [RFC5322]) with a Markdown
   content part.

2.4. Create a Local Batch Script

   This strategy is to translate the processing instructions inferred
   from the syntax and output-type parameters into a sequence of
   commands in the local convention, storing those commands in a batch
   script. For example, when a MIME-aware client stores some Markdown to
   disk, the client can save a Makefile in the same directory with
   commands that are appropriate (and safe) for the local system.

2.5. Process the Markdown

   This strategy is to process the Markdown into the formal markup,
   which eliminates ambiguities. Once the Markdown is processed into
   (for example) valid XHTML, an application can save a file as
   "doc.xhtml" with no further loss of metadata. Of course, depending on
   the output-type, this process may not be reversible.

2.6. Rely on Context

   This last strategy is to use or create context to determine how to
   interpret the Markdown. For example, Markdown content that is of the
   Fountain.io type [FOUNTAIN] could be saved with the filename
   "script.fountain" instead of "script.markdown". Alternatively,
   scripts could be stored in a "/screenplays" directory while other
   kinds of Markdown could be stored elsewhere. For reasons that should
   be intuitively obvious, this method is the most error-prone.
   "Context" can be easily lost over time, and the trend of passing
   Markdown between systems--taking them *out* of context--is
   increasing.





Leonard                   Exp. April 20, 2015                   [Page 7]


Internet-Draft          text/markdown Use Cases             October 2014


3.  Registration Templates for Common Markdown Syntaxes

   The purpose of this section is to register certain syntaxes in the
   Markdown Syntaxes Registry [MDMTREG] because they illustrate
   particularly interesting use cases or are broadly applicable to the
   Internet community; thus, these syntaxes would benefit from the level
   of review associated with publication as IETF documents. [[TODO: The
   maintainers of these syntaxes were consulted and provided valuable
   input into these registrations.]]

   [[NB: This section was rushed through. It is meant to get the gist
   until the next draft(s).]]

   [[NB: Different registration syntaxes in the Extensions field are
   experimented with.]]

   [[NB: The Documentation sub-field in Extensions may be optional if it
   merely duplicates existing information.]]

   [[NB: Output types annotated with * are not registered as of the time
   of this draft; they ought to be registered to ensure
   interoperability.]]

3.1. MultiMarkdown

   Identifier: MultiMarkdown

   Description: MultiMarkdown (MMD) is a superset of "Original". It adds
                multiple syntax features (tables, footnotes, and
                citations, to name a few), in addition various output
                formats. Additionally, it builds in "smart" typography
                for various languages (proper left- and right-sided
                quotes, for example).

   Documentation: <http://fletcher.github.io/MultiMarkdown-4/syntax>

   Community of Use: General.

   Versions:
     Identifier: 4
     Description: The fourth revision of MultiMarkdown, released in
                  2014. The version "4" SHOULD NOT be specified until
                  further notice; is is only documented for completeness
                  (in case Penney revises the syntax with material
                  contradictions).

   Extensions:
     Identifier: latex_mode



Leonard                   Exp. April 20, 2015                   [Page 8]


Internet-Draft          text/markdown Use Cases             October 2014


     Syntax:
       Enabled, with String: "memoir" or "beamer"
     Description: If the output-type is LaTeX, and a LaTeX header block
                  is not included, this extension sets the document
                  class. This extension has no effect if the output-type
                  is not LaTeX or if a LaTeX header block already
                  specifies the mode.
     Documentation: <http://fletcher.github.io/MultiMarkdown-4/
                     using_mmd>

     Identifier: force
     Syntax:
       Enabled, with String: "full" or "snippet"
     Description: Forces either "full": a complete document, even if it
                  does not contain enough metadata to otherwise trigger
                  a complete document; or "snippet": a snippet, meaning
                  that header and footer information is left out.
     Documentation: <http://fletcher.github.io/MultiMarkdown-4/
                     using_mmd>

     Identifier: process_html
     Syntax:
       Enabled
     Description: Process the text included within HTML tags in the
     source document.
     Documentation: <http://fletcher.github.io/MultiMarkdown-
                     4/using_mmd>

   > random_footnote_identifiers
     Syntax:      Enabled
     Description: Use random identifier numbers for footnotes. Useful
                    when you might combine multiple HTML documents
                    together, e.g. in a weblog.

   > CriticMarkup
    @  ES ("a", "r", or "a&r")
    |Accept ("a"), reject ("r"), or highlight changes ("a&r") using
    |CriticMarkup syntax. When disabled, MultiMarkdown will leave the
    |CriticMarkup syntax in place.
    ~ <http://fletcher.github.io/MultiMarkdown-4/criticmarkup>
    ~ <http://criticmarkup.com/>
    ~ <http://fletcher.github.io/MultiMarkdown-4/using_mmd>

   > no_smart
    @  E
    |Disables "smart" typography, similar to John Gruber's SmartyPants
    |program. "Smart" typography is enabled by default in MultiMarkdown.
    ~ <http://fletcher.github.io/MultiMarkdown-4/using_mmd>



Leonard                   Exp. April 20, 2015                   [Page 9]


Internet-Draft          text/markdown Use Cases             October 2014


   > no_notes
    %  E
    |Disables footnotes and similar markup (glossary, citations).
    ~ <http://fletcher.github.io/MultiMarkdown-4/using_mmd>

   > no_labels
    %  E
    |Disables adding id attributes to headers in HTML.
    ~ <http://fletcher.github.io/MultiMarkdown-4/using_mmd>

   Identifier: no_mask
   Syntax:
     Enabled
   Description: Disables masking of e-mail addresses when creating HTML.
   Documentation: <http://fletcher.github.io/MultiMarkdown-4/using_mmd>

   [[TODO: continue analysis with --help_all.]]

   Anticipated Output Types:
     text/html
     text/x-opml (or text/opml+xml)*
     text/tex*
     application/vnd.oasis.opendocument.text
       Specifically Flat OpenDocument Text (in XML)

   Additional Fragment Identifiers:
     See <http://fletcher.github.io/MultiMarkdown-4/metadata>.

     #meta       Metadata.
     #meta#<key> Metadata; <key> is the key string.

   Responsible Parties:
     (individual) Fletcher T. Penney <fletcher@fletcherpenney.net>
                        <http://fletcherpenney.net/multimarkdown/>

   Currently Maintained? Yes

   Implementations:
     Name: MultiMarkdown
     Type: Processor
     References: <http://fletcherpenney.net/multimarkdown/>
     Purpose: Converts Markdown to various output formats, with
              very interesting extensions, using peg-markdown
              in a fast, portable C implementation.

3.2. GitHub Flavored Markdown

   Identifier: GFM



Leonard                   Exp. April 20, 2015                  [Page 10]


Internet-Draft          text/markdown Use Cases             October 2014


   Description: "Original" with the following differences:
      1. Multiple underscores in words
      2. URL (URI) autolinking
      3. Strikethrough
      4. Fenced code blocks
      5. Syntax highlighting
      6. Tables (- for rows; | for columns; : for alignment)
      7. Only some HTML allowed; sanitization is integral
         to the format

   Documentation:
     <https://help.github.com/articles/github-flavored-markdown/>
     <https://github.com/github/markup/tree/master#html-sanitization>

   Community of Use: GitHub users (software developers, Git users)

   Anticipated Output Types:
     text/html

   Responsible Parties:
     (corporate) GitHub, Inc. <https://github.com/contact>
               [[Vicent Marti <vicent@github.com>??]]

   Currently Maintained? Yes

   Implementations:
     Name: GitHub
     Type: Web Application
     References: <https://github.com/>
     Purpose: Distributed revision control and source code management.

3.3. Pandoc

   Identifier: pandoc

   Description:
     Markdown is designed to be easy to write and to read: the content
     should be publishable as-is, as plain text, without looking like it
     has been marked up with tags or formatting instructions. Yet
     whereas "Original" has HTML generation in mind, pandoc is designed
     for multiple output formats. Thus, while pandoc allows the
     embedding of raw HTML, it discourages it, and provides other, non-
     HTMLish ways of representing important document elements like
     definition lists, tables, mathematics, and footnotes.

   Documentation: <http://johnmacfarlane.net/pandoc/README.html#
                   pandocs-markdown>




Leonard                   Exp. April 20, 2015                  [Page 11]


Internet-Draft          text/markdown Use Cases             October 2014


   Community of Use: General.

   Extensions:

   [[Stuff to turn off:]]

   > no_escaped_line_breaks
   > no_blank_before_header
   > no_header_attributes
   > no_auto_identifiers
   > no_implicit_header_references
   > no_blank_before_blockquote
   > no_fenced_code_blocks
   > no_fenced_code_attributes
   > no_line_blocks
   > no_fancy_lists
   > no_startnum
   > no_definition_lists
   > no_example_lists
   > no_table_captions
   > no_simple_tables
   > no_multiline_tables
   > no_grid_tables
   > no_pipe_tables
   > no_pandoc_title_block
   > no_yaml_metadata_block
   > no_all_symbols_escapable
   > no_intraword_underscores
   > no_strikeout
   > no_superscript
   > no_subscript
   > no_inline_code_attributes
   > no_tex_math_dollars
   > no_raw_html
   > no_markdown_in_html_blocks
   > no_native_divs
   > no_native_spans
   > no_raw_tex
   > no_latex_macros
   > no_implicit_figures
   > no_footnotes
   > no_inline_notes
   > no_citations

   [[New stuff:]]

   > lists_without_preceding_blankline
   > hard_line_breaks



Leonard                   Exp. April 20, 2015                  [Page 12]


Internet-Draft          text/markdown Use Cases             October 2014


   > ignore_line_breaks
   > tex_math_single_backslash
   > tex_match_double_backslash
   > markdown_attribute
   > mmd_title_block
   > abbreviations
   > autolink_bare_uris
   > ascii_identifiers
   > link_attributes
   > mmd_header_identifiers
   > compact_definition_lists

   [[Output controls:]]

   > epub_version: ES ("2" / "3")
    |When the output-type is application/epub+zip, this extension
    |specifies the EPUB version to emit.

   Anticipated Output Types:
     text/html
     application/xhtml+xml
     application/epub+zip*
       [[This media type does not distinguish between v2 and v3.]]
     text/tex*
     text/plain
     text/rtf
     text/x-opml*
     [[InDesign Markup Language, icml]]*
     text/x-asciidoc (AsciiDoc)*
     application/json
     [[native (Haskell)]]*
     text/x-rst*
     [[man]]*
     [[mediawiki]]
     [[dokuwiki]]
     [[textile]]
     [[Emacs org-mode]]
     [[GNU Texinfo]]
     application/docbook+xml*
     application/vnd.oasis.opendocument.text
     application/vnd.openxmlformats-officedocument.
                 wordprocessingml.document
     [[Haddock Markup]]
     [[FictionBook fb2, fb3]]
     [[slidy, slideous, dzslides, revealjs, s5]]
     [[custom lua writer]]

   Additional Fragment Identifiers:



Leonard                   Exp. April 20, 2015                  [Page 13]


Internet-Draft          text/markdown Use Cases             October 2014


     #id#<id>   Identifier in attribute; <id> is the identifier in the
                {#<id> .class ...} production. Used for Header
                Identifiers and Code Block Identifiers. Not used
                for the (no_)auto_identifiers extension:
                (no_)auto_identifiers only modifies the output,
                for certain output types.
     #ptb       Pandoc Title Block.
     #ptb#t     Pandoc Title Block - Title.
     #ptb#a     Pandoc Title Block - Author(s).
     #ptb#d     Pandoc Title Block - Date.
     #ymb       YAML Metadata Block.
     #ymb#<key> YAML Metadata Block; <key> is the key string.
     #mtb       MultiMarkdown Title Block (Metadata).
     #mtb#<key> MultiMarkdown Title Block (Metadata); <key> is
                the key string.

   Responsible Parties:
     (individual) Prof. John MacFarlane <jgm@berkeley.edu>
                              <http://johnmacfarlane.net/>

   Currently Maintained? Yes

   Implementations:
     Name: pandoc
     Versions: 1.13.1
     Type: Processor
     References: <http://johnmacfarlane.net/pandoc/>
     Purpose: Convert files from Markdown to a wide variety of
              markup formats; pandoc is your swiss-army knife.

3.4. Fountain (Fountain.io)

   Identifier: Fountain

   Versions:
     Identifier: 1.1
     Description: Version 1.1 was released March 14, 2014. [[? The
                  version "1.1" SHOULD NOT be specified until further
                  notice; it is only documented for completeness.]]

   Description: Fountain is a simple markup syntax for writing, editing
                and sharing screenplays in plain, human-readable text.
                Fountain allows you to work on your screenplay anywhere,
                on any computer or tablet, using any software that edits
                text files.

   Documentation: <http://fountain.io/syntax>




Leonard                   Exp. April 20, 2015                  [Page 14]


Internet-Draft          text/markdown Use Cases             October 2014


   Community of Use: Screenwriters (mass media production).

   Anticipated Output Types:
     application/pdf
     text/fdx+xml*
       [[Final Draft FDX format]]

   Additional Fragment Identifiers:
     See <http://fountain.io/syntax#section-titlepage> and
     <http://fountain.io/syntax#section-sections>.

     #TitlePage       Title Page (acts as metadata).
     #TitlePage#<key> Title Page; <key> is the key string.
     #Section#<sec1> *(#<secn>)
                      Section or subsection. The <sec1>..<secn>
                      productions are the text of the Section line,
                      with whitespace trimmed from both ends.
                      Sub-sections (sections with multiple # at
                      at the beginnings) are addressed hierarchically
                      by preceding the sub-section with higher-order
                      sections. If the section hierarchy "skips",
                      e.g., # to ###, use a blank section name,
                      e.g., #Section#ACT%20I##PATIO%20SCENE.

   Responsible Parties:
     (individual) Stu Maschwitz <http://prolost.com/>
     (individual) John August <http://johnaugust.com/>

   Currently Maintained? Yes

3.5. CommonMark

   Identifier: CommonMark

   Description:
     CommonMark is a standard, unambiguous syntax specification for
     Markdown, along with a suite of comprehensive tests to validate
     Markdown implementations against this specification. The
     responsible parties believe this is necessary, even essential, for
     the future of Markdown.

     Compared to "Original", CommonMark is much longer and in a few
     instances contradicts "Original" based on seasoned experience.
     Although CommonMark specifically does not mandate any particular
     encoding for the input content, CommonMark draws in more of
     Unicode, UTF-8, and HTML (including HTML5) than "Original".

   Documentation: <http://spec.commonmark.org/>



Leonard                   Exp. April 20, 2015                  [Page 15]


Internet-Draft          text/markdown Use Cases             October 2014


   Community of Use: General.

   Versions:
     Identifier: 2
     Description: Version 2 was released September 19, 2014. [[? The
                  version "2" SHOULD NOT be specified until further
                  notice; it is only documented for completeness.]]

   Anticipated Output Types:
     text/html

   Responsible Parties:
     (individual) John MacFarlane <jgm@berkeley.edu>
     (individual) David Greenspan <david@meteor.com>
     (individual) Vicent Marti <vicent@github.com>
     (individual) Neil Williams <neil@reddit.com>
     (individual) Benjamin Dumke-von der Ehe <ben@stackexchange.com>
     (individual) Jeff Atwood <jatwood@codinghorror.com>

   Implementations:
     Name: stmd
     Type: Processor
     References: <https://github.com/jgm/stmd>
     Purpose: Converts CommonMark Markdown to HTML in a C99
              implementation and a JavaScript implementation.

3.6. kramdown-rfc2629 (Markdown for RFCs)

   Identifier: kramdown-rfc2629

   Description:
     kramdown is a markdown parser by Thomas Leitner, which has a number
     of backends for generating HTML, Latex, and Markdown again.

     kramdown-rfc2629 is an additional backend to that: It allows the
     generation of XML2RFC XML markup (also known as RFC 2629 compliant
     markup).

   Documentation: <https://github.com/cabo/kramdown-rfc2629>

   Community of Use: Anybody who is writing Internet-Drafts and RFCs in
   the IETF and prefers (or has co-authors who prefer) to do part of
   their work in Markdown.

   Anticipated Output Types:
     text/xml (application/xml)    The output is in xml2rfc syntax.

   Responsible Parties:



Leonard                   Exp. April 20, 2015                  [Page 16]


Internet-Draft          text/markdown Use Cases             October 2014


     (individual) Carsten Bormann <cabo@tzi.org>

   Implementations:
     Name: kramdown-rfc2629
     Type: Processor
     References: <https://github.com/cabo/kramdown-rfc2629>
     Purpose: Converts the input into xml2rfc syntax.

3.7. rfc7328 (Pandoc2rfc)

   Identifier: rfc7328

   Description:
     Pandoc2rfc allows authors to write in "pandoc" that is then
     transformed to XML and given to xml2rfc.  The conversions are, in a
     way, amusing, as we start off with (almost) plain text, use
     elaborate XML, and end up with plain text again.

   Documentation: RFC 7328;
                  <https://github.com/miekg/pandoc2rfc>

   Community of Use: Anybody who is writing Internet-Drafts and RFCs in
   the IETF and prefers (or has co-authors who prefer) to do part of
   their work in this syntax, which is a profile of "pandoc" plus a
   specific workflow involving additional tools.

   Anticipated Output Types:
     text/plain
       The output is in Internet-Draft (or RFC) format,
       in US-ASCII encoding.

   Responsible Parties:
     (individual) R. (Miek) Gieben <miek@google.com>

   Implementations:
     Name: pandoc2rfc
     Type: Bundle of Scripts and Templates
     References: <https://github.com/miekg/pandoc2rfc>
     Purpose: By following the included instructions, a variant
              of the pandoc syntax is converted into xml2rfc,
              which is then converted into Internet-Draft.

4.  Examples for Common Markdown Syntaxes

   This section provides examples of the syntaxes registered in Appendix
   C.

4.1. MultiMarkdown



Leonard                   Exp. April 20, 2015                  [Page 17]


Internet-Draft          text/markdown Use Cases             October 2014


4.2. GitHub Flavored Markdown

4.3. Pandoc

4.4. Fountain (Fountain.io)

4.5. CommonMark

4.6. kramdown-rfc2629 (Markdown for RFCs)

4.7. rfc7328 (Pandoc2rfc)

   [[TODO: complete.]]

5.  IANA Considerations

   IANA is asked to register the syntaxes specified in Section 3 in the
   Markdown Syntaxes Registry.

6. Security Considerations

   See the respective syntax descriptions and output media type
   registrations for their respective security considerations.

7. References

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

   [MDMTREG]  Leonard, S., "The text/markdown Media Type", draft-ietf-
              appsawg-text-markdown-03 (work in progress), October 2014.

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

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

7.2. Informative References






Leonard                   Exp. April 20, 2015                  [Page 18]


Internet-Draft          text/markdown Use Cases             October 2014


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

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

   [RFC4263]  Lilly, B., "Media Subtype Registration for Media Type
              text/troff", RFC 4263, January 2006.

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

   [XML1.0-5] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
              F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
              Edition)", World Wide Web Consortium Recommendation REC-
              xml-20081126, November 2008,
              <http://www.w3.org/TR/2008/REC-xml-20081126#dt-fatal>.

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



Leonard                   Exp. April 20, 2015                  [Page 19]


Internet-Draft          text/markdown Use Cases             October 2014


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


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/



































Leonard                   Exp. April 20, 2015                  [Page 20]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/