idnits 2.17.1 draft-ietf-appsawg-text-markdown-use-cases-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 5 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 155 has weird spacing: '... markup form...' == Line 756 has weird spacing: '...scribed in th...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (August 26, 2015) is 3159 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Haskell' is mentioned on line 800, but not defined == Unused Reference: 'RFC5147' is defined on line 1059, but no explicit reference was found in the text == Unused Reference: 'RFC2231' is defined on line 1107, but no explicit reference was found in the text == Unused Reference: 'RFC4263' is defined on line 1111, but no explicit reference was found in the text == Unused Reference: 'FTSYNTAX' is defined on line 1139, but no explicit reference was found in the text == Outdated reference: A later version (-12) exists of draft-ietf-appsawg-text-markdown-06 -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) Summary: 1 error (**), 0 flaws (~~), 10 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Applications Area Working Group S. Leonard 3 Internet-Draft Penango, Inc. 4 Intended Status: Informational August 26, 2015 5 Expires: February 27, 2016 7 Guidance on Markdown: 8 Design Philosophies, Stability Strategies, and Select Registrations 9 draft-ietf-appsawg-text-markdown-use-cases-03 11 Abstract 13 This document elaborates upon the text/markdown media type for use 14 with Markdown, a family of plain text formatting syntaxes that 15 optionally can be converted to formal markup languages such as HTML. 16 Background information, local storage strategies, and additional 17 syntax registrations are supplied. 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 Copyright Notice 36 Copyright (c) 2015 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Dive Into Markdown . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. On Formats . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.2. Markdown Design Philosophy . . . . . . . . . . . . . . . . 4 54 1.3. Uses of Markdown . . . . . . . . . . . . . . . . . . . . . 5 55 1.4. Uses of Labeling Markdown Content as text/markdown . . . . 5 56 1.5. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 6 57 2. Strategies for Preserving Media Type and Parameters . . . . . 6 58 2.1. Map to Filename and Attributes . . . . . . . . . . . . . . 7 59 2.2. Store Headers in Adjacent File . . . . . . . . . . . . . . 8 60 2.3. "Arm" Content with MIME Headers . . . . . . . . . . . . . . 8 61 2.4. Create a Local Batch Script . . . . . . . . . . . . . . . . 8 62 2.5. Process the Markdown in Advance . . . . . . . . . . . . . . 9 63 2.6. Rely on Context . . . . . . . . . . . . . . . . . . . . . . 9 64 2.7. Specific Strategies . . . . . . . . . . . . . . . . . . . . 9 65 2.7.1. Subversion . . . . . . . . . . . . . . . . . . . . . . 9 66 2.7.2. Git . . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 3. Registration Templates for Common Markdown Syntaxes . . . . . 10 68 3.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 10 69 3.2. GitHub Flavored Markdown . . . . . . . . . . . . . . . . . 11 70 3.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 3.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 13 72 3.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 14 73 3.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 15 74 3.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 15 75 3.8. PHP Markdown Extra . . . . . . . . . . . . . . . . . . . . 15 76 4. Examples for Common Markdown Syntaxes . . . . . . . . . . . . 16 77 4.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 16 78 4.2. GitHub Flavored Markdown . . . . . . . . . . . . . . . . . 16 79 4.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 17 80 4.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 18 81 4.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 18 82 4.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 19 83 4.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 22 84 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 85 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 23 86 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 87 7.1. Normative References . . . . . . . . . . . . . . . . . . . 23 88 7.2. Informative References . . . . . . . . . . . . . . . . . . 23 89 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 25 91 1. Dive Into Markdown 93 This document serves as an informational companion to [MDMTREG], the 94 text/markdown media type registration. It should be considered 95 jointly with [MDMTREG]. 97 "Sometimes the truth of a thing is not so much in the 98 think of it, but in the feel of it." --Stanley Kubrick 100 1.1. On Formats 102 In computer systems, textual data is stored and processed using a 103 continuum of techniques. On the one end is plain text: computer- 104 encoded text that consists only of a sequence of code points from a 105 given standard, with no other formatting or structural information 106 [UNICODE]. Plain text provides /some/ fixed facilities for formatting 107 instructions, namely codes in the character set that have meanings 108 other than "represent this character graphically on the output 109 medium"; however, these facilities are not particularly extensible. 110 Compare with [RFC6838] Section 4.2.1. Applications may neuter the 111 effects of these special characters by prohibiting them or by 112 ignoring their dictated meanings, as is the case with how modern 113 applications treat most control characters in US-ASCII. On this end, 114 any text reader or editor that interprets the character set can be 115 used to see or manipulate the text. If some characters are corrupted, 116 the corruption is unlikely to affect the ability of a computer system 117 to process the text (even if the human meaning is changed). 119 On the other end is binary data: a sequence of bits intended for some 120 computer application to interpret and act upon. Binary formats are 121 flexible in that they can store non-textual data efficiently (perhaps 122 storing no text at all, or only storing certain kinds of text for 123 very specialized purposes). Binary formats require an application to 124 be coded specifically to handle the format; no partial 125 interoperability is possible. Furthermore, if even one bit is 126 corrupted in a binary format, it may prevent an application from 127 processing any of the data correctly. 129 Between these two extremes lies formatted text, i.e., text that 130 includes non-textual information coded in a particular way, that 131 affects the interpretation of the text by computer programs. 132 Formatted text is distinct from plain text and binary data in that 133 the non-textual information is encoded into textual characters, which 134 are assigned specialized meanings not defined by the character set. 135 With a regular text editor and a standard keyboard (or other standard 136 input mechanism), a user can enter these textual characters to 137 express the non-textual meanings. For example, a character like "<" 138 no longer means "LESS-THAN SIGN"; it means the start of a tag or 139 element that affects the document in some way. 141 On the formal end of the formatted text spectrum is markup, a family 142 of languages for annotating a document in such a way that the 143 annotations are syntactically distinguishable from the text. Markup 144 languages are (reasonably) well-specified and tend to follow (mostly) 145 standardized syntax rules. Examples of markup languages include SGML, 146 HTML, XML, and LaTeX. Standardized rules lead to interoperability 147 between markup processors, but a skill requirement for new (human) 148 users of the language that they learn these rules in order to do 149 useful work. This imposition makes markup less accessible for non- 150 technical users (i.e., users who are unwilling or unable to invest in 151 the requisite skill development). 153 informal /---------formatted text----------\ formal 154 <------v-------------v-------------v-----------------------v----> 155 plain text informal markup formal markup binary format 156 (Markdown) (HTML, XML, etc.) 158 Figure 1: Degrees of Formality in Data Storage Formats for Text 160 On the informal end of the spectrum are lightweight markup languages. 161 In comparison with formal markup like XML, lightweight markup uses 162 simple syntax, and is designed to be easy for humans to enter with 163 basic text editors. Markdown, the subject of this document, is an 164 /informal/ plain text formatting syntax that is intentionally 165 targeted at non-technical users (i.e., users upon whom little to no 166 skill development is imposed) using unspecialized tools (i.e., text 167 boxes). Jeff Atwood once described these informal markup languages as 168 "humane" [HUMANE]. 170 1.2. Markdown Design Philosophy 172 Markdown specifically is a family of syntaxes that are based on the 173 original work of John Gruber with substantial contributions from 174 Aaron Swartz, released in 2004 [MARKDOWN]. Since its release a number 175 of web or web-facing applications have incorporated Markdown into 176 their text entry systems, frequently with custom extensions. Fed up 177 with the complexity and security pitfalls of formal markup languages 178 (e.g., HTML5) and proprietary binary formats (e.g., commercial word 179 processing software), yet unwilling to be confined to the 180 restrictions of plain text, many users have turned to Markdown for 181 document processing. Whole toolchains now exist to support Markdown 182 for online and offline projects. 184 Informality is a bedrock premise of Gruber's design. Gruber created 185 Markdown after disastrous experiences with strict XML and XHTML 186 processing of syndicated feeds. In Mark Pilgrim's "thought 187 experiment", several websites went down because one site included 188 invalid XHTML in a blog post, which was automatically copied via 189 trackbacks across other sites [DIN2MD]. These scenarios led Gruber to 190 believe that clients (e.g., web browsers) SHOULD try to make sense of 191 data that they receive, rather than rejecting data simply because it 192 fails to adhere to strict, unforgiving standards. (In [DIN2MD], 193 Gruber compared Postel's Law [RFC0793] with the XML standard, which 194 says: "Once a fatal error is detected [...] the processor MUST NOT 195 continue normal processing" [XML1.0-5].) As a result, there is no 196 such thing as "invalid" Markdown; there is no standard demanding 197 adherence to the Markdown syntax; there is no governing body that 198 guides or impedes its development. If the Markdown syntax does not 199 result in the "right" output (defined as output that the author 200 wants, not output that adheres to some dictated system of rules), 201 Gruber's view is that the author either should keep on experimenting, 202 or should change the processor to address the author's particular 203 needs (see [MARKDOWN] Readme and [MD102b8] perldoc; see also 204 [CATPICS]). 206 1.3. Uses of Markdown 208 Since its introduction in 2004, Markdown has enjoyed remarkable 209 success. Markdown works for users for three key reasons. First, the 210 markup instructions (in text) look similar to the markup that they 211 represent; therefore the cognitive burden to learn the syntax is low. 212 Second, the primary arbiter of the syntax's success is *running 213 code*. The tool that converts the Markdown to a presentable format, 214 and not a series of formal pronouncements by a standards body, is the 215 basis for whether syntactic elements matter. Third, Markdown has 216 become something of an Internet meme [INETMEME], in that Markdown 217 gets received, reinterpreted, and reworked as additional communities 218 encounter it. There are communities that are using Markdown for 219 scholarly writing [OCCASION], for screenplays [FOUNTAIN], and even 220 for mathematical formulae [MATHDOWN]. Clearly, a screenwriter has no 221 use for specialized Markdown syntax for mathematicians; likewise, 222 mathematicians do not need to identify characters or props in common 223 ways. The overall gist is that all of these communities can take the 224 common elements of Markdown (which are rooted in the common elements 225 of HTML circa 2004) and build on them in ways that best fit their 226 needs. 228 1.4. Uses of Labeling Markdown Content as text/markdown 230 The primary purpose of an Internet media type is to label "content" 231 on the Internet, as distinct from "files". Content is any computer- 232 readable format that can be represented as a primary sequence of 233 octets, along with type-specific metadata (parameters) and type- 234 agnostic metadata (protocol dependent). From this description, it is 235 apparent that appending ".markdown" to the end of a filename is not a 236 sufficient means to identify Markdown. Filenames are properties of 237 files in file systems, but Markdown frequently exists in databases or 238 content management systems (CMSes) where the file metaphor does not 239 apply. One CMS [RAILFROG] uses media types to select appropriate 240 processing, so a media type is necessary for the safe and 241 interoperable use of Markdown. 243 Unlike complete HTML documents, [MDSYNTAX] provides no means to 244 include metadata into the content stream. Several derivative flavors 245 have invented metadata incorporation schemes (e.g., [MULTIMD]), but 246 these schemes only address specific use cases. In general, the 247 metadata must be supplied via supplementary means in an encapsulating 248 protocol, format, or convention. The relationship between the content 249 and the metadata is not directly addressed here or in [MDMTREG]; 250 however, by identifying Markdown with a media type, Markdown content 251 can participate as a first-class citizen with a wide spectrum of 252 metadata schemes. 254 Finally, registering a media type through the IETF process is not 255 trivial. Markdown can no longer be considered a "vendor"-specific 256 innovation, but the registration requirements even in the vendor tree 257 have proven to be overly burdensome for most Markdown implementers. 258 Moreover, registering hundreds of Markdown variants with distinct 259 media types would impede interoperability: virtually all Markdown 260 content can be processed by virtually any Markdown processor, with 261 varying degrees of success. The goal of [MDMTREG] is to reduce all of 262 these burdens by having one media type that accommodates diversity 263 and eases registration. 265 1.5. Definitions 267 The key words "MUST" and "SHOULD" in this document are to be 268 interpreted as described in [RFC2119]. 270 Since Markdown signifies a family of related formats with varying 271 degrees of formal documentation and implementation, this 272 specification uses the term "variant" to identify such formats. 274 2. Strategies for Preserving Media Type and Parameters 276 The purpose of this document and [MDMTREG] is to promote 277 interoperability between different Markdown-related systems, 278 preserving the author's intent. While [MARKDOWN] was designed by 279 Gruber in 2004 as a simple way to write blog posts and comments, as 280 of 2014 Markdown and its derivatives are rapidly becoming the formats 281 of record for many communities and use cases. While an individual 282 member of (or software tool for) a community can probably look at 283 some "Markdown" and declare its meaning intuitively obvious, software 284 systems in different communities (or different times) need help. 285 [MDSYNTAX] does not have a signaling mechanism like , so 286 tagging Markdown internally is simply out of the question. Once tags 287 or metadata are introduced, the content is no longer "just" Markdown. 289 Some commentators have suggested that an in-band signaling mechanism, 290 such as in Markdown link definitions at the top of the content, could 291 be used to signal the variant. Unfortunately this signaling mechanism 292 is incompatible with other Markdown variants (e.g., [PANDOC]) that 293 expect their own kinds of metadata at the top of the file. Markdown 294 content is just a stream of text; the semantics of that text can only 295 be furnished by context. 297 The media type and variant parameter in [MDMTREG] furnish this 298 missing context, while allowing for additional extensibility. This 299 section covers strategies for how an application might preserve 300 metadata when it leaves the domain of IETF protocols. 302 [MDMTREG] only defines two parameters: the charset parameter 303 (required for all text/* media types) and the variant parameter. 304 [RFC6657] provides guidance on character set parameter handling. The 305 variant parameter provides a simple identifier--nothing less or more. 306 Variants are allowed to define additional parameters when sent with 307 the text/markdown media type; the variant can also introduce control 308 information into the textual content stream (such as via a metadata 309 block). Neither [MDMTREG] nor this specification recommend any 310 particular approach. However, the philosophy behind [MDMTREG] is to 311 preserve formats rather than create new ones, since supporting 312 existing toolchains is more realistic than creating novel ones that 313 lack traction in the Markdown community. 315 2.1. Map to Filename and Attributes 317 This strategy is to map the media type, variant, and parameters to 318 "attributes" or "forks" in the local convention. Firstly, Markdown 319 content saved to a file should have an appropriate file extension 320 ending in .md or .markdown, which serves to disambiguate it from 321 other kinds of files. The character repertoire of variant identifiers 322 in [MDMTREG] is designed to be compatible with most filename 323 conventions. Therefore, a recommended strategy is to record the 324 variant identifier as the prefix to the file extension. For example, 325 for [PANDOC] content, a file could be named 326 "example.pandoc.markdown". 328 Many filesystems are case-sensitive or case-preserving; however, file 329 extensions tend to be all-lowercase. This document takes no position 330 on whether variant identifiers should be case-preserved or all- 331 lowercase when Markdown content is written to a file. However, when 332 the variant identifier is read to influence operational behavior, it 333 needs to be compared case-insensitively. 335 Many modern filesystems support "extended attributes", "alternate 336 data streams", or "resource forks". Some version control systems 337 support named properties. If the variant defines additional 338 parameters, these parameters should be stored in these resources, 339 where the parameter name includes the name of the resource, and the 340 parameter value is the value of the resource (data in the resource), 341 preferably UTF-8 encoded (unless the parameter definition explicitly 342 defines a different encoding or repertoire). The variant identifier 343 itself should be stored in a resource with a name including the term 344 "variant" (possibly including other decorations to avoid namespace 345 collisions). 347 2.2. Store Headers in Adjacent File 349 This strategy is to save the Markdown content in a first file, and to 350 save the metadata (specifically the Content-Type: header) in a second 351 file with a filename that is rationally related to the first 352 filename. For example, if the first file is named "readme.markdown", 353 the second file could be named "readme.markdown.headers". (If stored 354 in a database, the analogy would be to store the metadata in a second 355 table with a field that is a key to the first table.) This header 356 file has the media type "message/global-headers" [RFC6533] (".u8hdr" 357 suggestion notwithstanding). 359 2.3. "Arm" Content with MIME Headers 361 This strategy is to save the Markdown content along with its headers 362 in a file, "arming" the content by prepending the MIME headers 363 (specifically the Content-Type: header). It should be appreciated 364 that the file is no longer a "Markdown file"; rather, it is an 365 Internet Message Format file (e.g., [RFC5322]) with a Markdown 366 content part. Therefore, the file should have an Internet message 367 extension (e.g., ".eml", ".msg", or ".u8msg"), not a Markdown 368 extension (e.g., ".md" or ".markdown"). 370 2.4. Create a Local Batch Script 372 This strategy is to translate the processing instructions inferred 373 from the Content-Type and other parameters (e.g., Content- 374 Disposition) into a sequence of commands in the local convention, 375 storing those commands in a batch script. For example, when a MIME- 376 aware client stores some Markdown to disk, the client can save a 377 Makefile in the same directory with commands that are appropriate 378 (and safe) for the local system. 380 2.5. Process the Markdown in Advance 382 This strategy is to process the Markdown into the formal markup, 383 before a recipient receives it, which eliminates ambiguities. Once 384 the Markdown is processed into (for example) valid XHTML, an 385 application can save a file as "doc.xhtml" or can send MIME content 386 as application/xhtml+xml with no further loss of metadata. While 387 unambiguous, this process may not be reversible. 389 2.6. Rely on Context 391 This last strategy is to use or create context to determine how to 392 interpret the Markdown. For example, Markdown content that is of the 393 Fountain.io type [FOUNTAIN] could be saved with the filename 394 "script.fountain" instead of "script.markdown". Alternatively, 395 scripts could be stored in a "/screenplays" directory while other 396 kinds of Markdown could be stored elsewhere. For reasons that should 397 be intuitively obvious, this method is the most error-prone. 398 "Context" can be easily lost over time, and the trend of passing 399 Markdown between systems--taking them *out* of context--is 400 increasing. 402 2.7. Specific Strategies 404 2.7.1. Subversion 406 This subsection covers a preservation strategy in Subversion [SVN], a 407 common client-server version control system. 409 Subversion supports named properties. The "svn:mime-type" property 410 duplicates the entire Content-Type header, so parameters SHOULD be 411 stored there (Section 2.1). The filename SHOULD be consistent with 412 this Content-Type header, i.e., the extension SHOULD be the variant 413 identifier plus ".markdown" (Section 2.1). 415 2.7.2. Git 417 This subsection covers a preservation strategy in Git [GIT], a common 418 distributed version control system. 420 Versions of Git as of the time of this writing do not support 421 arbitrary metadata storage; however, third-party projects add this 422 support. 424 If Git is used without a metadata storage service, then a reasonable 425 strategy is to include the variant identifier in the filename 426 (Section 2.1). The default text encoding SHOULD be UTF-8. For other 427 or different properties, a header file SHOULD be recorded alongside 428 the Markdown file (Section 2.2). 430 If a metadata storage service is used with Git, then use a convention 431 that is most analogous to the service. For example, the "metastore" 432 project emulates extended attributes (xattrs) of a POSIX-like system, 433 so whatever "xattr" methodology is developed would be usable with 434 metastore and Git. 436 3. Registration Templates for Common Markdown Syntaxes 438 The purpose of this section is to register certain syntaxes in the 439 Markdown Syntaxes Registry [MDMTREG] because they illustrate 440 particularly interesting use cases or are broadly applicable to the 441 Internet community; thus, these syntaxes would benefit from the level 442 of review associated with publication as IETF documents. 444 3.1. MultiMarkdown 446 Identifier: MultiMarkdown 448 Name: MultiMarkdown 450 Description: 451 MultiMarkdown (MMD) is a superset of "Original". It adds multiple 452 syntax features (tables, footnotes, and citations, to name a few), 453 and is intended to output to various formats. Additionally, it builds 454 in "smart" typography for various languages (proper left- and right- 455 sided quotes, for example). 457 Additional Parameters: 458 options: String with zero or more of the following WSP-delimited 459 tokens: 461 "memoir" / "beamer" 462 "full" / "snippet" 463 "process-html" 464 "random-footnote-identifiers" 465 "accept" 466 "reject" 467 "nosmart" 468 "nonotes" 469 "nolabels" 470 "nomask" 472 The meanings of these tokens are defined in the 473 MultiMarkdown documentation. 475 References: 477 479 Contact Information: 480 (individual) Fletcher T. Penney 481 483 3.2. GitHub Flavored Markdown 485 Identifier: GFM 487 Name: GitHub Flavored Markdown 489 Description: 490 "Original" with the following differences: 491 1. Multiple underscores in words 492 2. URL (URI) autolinking 493 3. Strikethrough 494 4. Fenced code blocks 495 5. Syntax highlighting 496 6. Tables (- for rows; | for columns; : for alignment) 497 7. Only some HTML allowed; sanitization is integral 498 to the format 500 References: 501 502 504 Contact Information: 505 (corporate) GitHub, Inc. 507 3.3. Pandoc 509 Identifier: pandoc 511 Name: Pandoc 513 Description: 514 Markdown is designed to be easy to write and to read: the content 515 should be publishable as-is, as plain text, without looking like it 516 has been marked up with tags or formatting instructions. Yet whereas 517 "Original" has HTML generation in mind, pandoc is designed for 518 multiple output formats. Thus, while pandoc allows the embedding of 519 raw HTML, it discourages it, and provides other, non-HTMLish ways of 520 representing important document elements like definition lists, 521 tables, mathematics, and footnotes. 523 Additional Parameters: 524 extensions: String with an optional starting syntax token, followed 525 by a "+" and "-" delimited list of extension tokens. "+" 526 preceding an extension token turns the extension on; "-" 527 turns the extension off. The starting syntax tokens are 528 "markdown", "markdown_strict", "markdown_phpextra", and 529 "markdown_github". If no starting syntax token is given, 530 "markdown" is assumed. The extension tokens include: 532 Extensions to turn off (on by default): 534 escaped_line_breaks 535 blank_before_header 536 header_attributes 537 auto_identifiers 538 implicit_header_references 539 blank_before_blockquote 540 fenced_code_blocks 541 fenced_code_attributes 542 line_blocks 543 fancy_lists 544 startnum 545 definition_lists 546 example_lists 547 table_captions 548 simple_tables 549 multiline_tables 550 grid_tables 551 pipe_tables 552 pandoc_title_block 553 yaml_metadata_block 554 all_symbols_escapable 555 intraword_underscores 556 strikeout 557 superscript 558 subscript 559 inline_code_attributes 560 tex_math_dollars 561 raw_html 562 markdown_in_html_blocks 563 native_divs 564 native_spans 565 raw_tex 566 latex_macros 567 implicit_figures 568 footnotes 569 inline_notes 570 citations 572 Extensions to turn on (off by default): 574 lists_without_preceding_blankline 575 hard_line_breaks 576 ignore_line_breaks 577 tex_math_single_backslash 578 tex_match_double_backslash 579 markdown_attribute 580 mmd_title_block 581 abbreviations 582 autolink_bare_uris 583 ascii_identifiers 584 link_attributes 585 mmd_header_identifiers 586 compact_definition_lists 588 Fragment Identifiers: 589 Pandoc defines fragment identifiers using the in the 590 {# .class ...} production (PHP Markdown Extra attribute block). 591 This syntax works for Header Identifiers and Code Block Identifiers. 593 References: 594 596 Contact Information: 597 (individual) Prof. John MacFarlane 598 600 3.4. Fountain (Fountain.io) 602 Identifier: Fountain 604 Name: Fountain 606 Description: 607 Fountain is a simple markup syntax for writing, editing and sharing 608 screenplays in plain, human-readable text. Fountain allows you to 609 work on your screenplay anywhere, on any computer or tablet, using 610 any software that edits text files. 612 Fragment Identifiers: 613 See and 614 . In the following 615 fragment identifiers, the and productions MUST have "/" 616 characters percent-encoded. 618 #/ Title Page (acts as metadata). 619 #/ Title Page; is the key string. 620 # *("/" ) 621 Section or subsection. The .. 622 productions are the text of the Section line, 623 with whitespace trimmed from both ends. 624 Sub-sections (sections with multiple # at 625 at the beginning of the line in the source) 626 are addressed hierarchically by preceding 627 the sub-section with higher-order 628 sections. If the section hierarchy "skips", 629 e.g., # to ###, use a blank section name, 630 e.g., #Section/ACT%20I//PATIO%20SCENE. 632 References: 633 635 Contact Information: 636 (individual) Stu Maschwitz 637 (individual) John August 639 3.5. CommonMark 641 Identifier: CommonMark 643 Name: CommonMark 645 Description: 646 CommonMark is a standard, unambiguous syntax specification for 647 Markdown, along with a suite of comprehensive tests to validate 648 Markdown implementations against this specification. The maintainers 649 believe that CommonMark is necessary, even essential, for the future 650 of Markdown. 652 Compared to "Original", CommonMark is much longer and in a few 653 instances contradicts "Original" based on seasoned experience. 654 Although CommonMark specifically does not mandate any particular 655 encoding for the input content, CommonMark draws in more of Unicode, 656 UTF-8, and HTML (including HTML5) than "Original". 658 This registration always refers to the latest version or an 659 unspecified version (receiver's choice). Version 0.13 of the 660 CommonMark specification was released 2014-12-10. 662 References: 663 665 Contact Information: 666 (individual) John MacFarlane 667 (individual) David Greenspan 668 (individual) Vicent Marti 669 (individual) Neil Williams 670 (individual) Benjamin Dumke-von der Ehe 671 (individual) Jeff Atwood 673 3.6. kramdown-rfc2629 (Markdown for RFCs) 675 Identifier: kramdown-rfc2629 677 Name: Markdown for RFCs 679 Description: 680 kramdown is a markdown parser by Thomas Leitner, which has a number 681 of backends for generating HTML, Latex, and Markdown again. kramdown- 682 rfc2629 is an additional backend to that: It allows the generation of 683 XML2RFC XML markup (also known as RFC 2629 compliant markup). 685 References: 686 688 Contact Information: 689 (individual) Carsten Bormann 691 3.7. rfc7328 (Pandoc2rfc) 693 Identifier: rfc7328 695 Name: Pandoc2rfc 697 Description: 698 Pandoc2rfc allows authors to write in "pandoc" that is then 699 transformed to XML and given to xml2rfc. The conversions are, in a 700 way, amusing, as we start off with (almost) plain text, use elaborate 701 XML, and end up with plain text again. 703 References: 704 RFC 7328 705 707 Contact Information: 708 (individual) R. (Miek) Gieben 710 3.8. PHP Markdown Extra 712 Identifier: Extra 714 Name: Markdown Extra 716 Description: 717 Markdown Extra is an extension to PHP Markdown implementing some 718 features currently not available with the plain Markdown syntax. 719 Markdown Extra is available as a separate parser class in PHP 720 Markdown Lib. Other implementations include Maruku (Ruby) and Python 721 Markdown. Markdown Extra is supported in several content management 722 systems, including Drupal, TYPO3, and MediaWiki. 724 Fragment Identifiers: 725 Markdown Extra defines fragment identifiers using the in the 726 {# .class ...} production (attribute block). This syntax works 727 for headers, fenced code blocks, links, and images. 729 References: 730 732 Contact Information: 733 (individual) Michel Fortin 735 4. Examples for Common Markdown Syntaxes 737 This section provides examples of the variants in Appendix C. 739 4.1. MultiMarkdown 741 Title: Example of MultiMarkdown 742 Keywords: IETF, example, footnotes 744 # MutliMarkdown Example # 746 MultiMarkdown supports several cool features, as well as 747 several output formats: 748 * HTML 749 * PDF 750 * OpenDocument 751 * OPML 752 * LaTeX 754 ## Footnotes ## 756 Footnotes are described in the 757 MultiMarkdown Syntax Guide.[^somesamplefootnote] 759 [^somesamplefootnote]: Here is the text of the footnote itself. 761 Figure 1: MultiMarkdown Example 763 4.2. GitHub Flavored Markdown 764 # Start Out # 766 GFM is like regular Markdown with a few extra features. For example, 767 http://www.example.com/ will get auto-linked. ~~Oops this is 768 some mistaken text.~~ 770 ``` 771 function test() { 772 return "notice this feature?"); 773 } 774 ``` 776 # Table Alignments # 778 | Left | Center | Right | 779 |:--------- |:-------:| ------:| 780 | cats | Paxton | $1600 | 781 | dogs | Ruff | $30 | 782 | zebras | Stripes | $20900 | 784 Figure 2: GitHub Flavored Markdown Example 786 4.3. Pandoc 788 % Pandoc User's Guide 789 % John MacFarlane 790 % August 30, 2014 792 Synopsis {#syn} 793 ======== 795 pandoc [*options*] [*input-file*]... 797 Description {#desc} 798 =========== 800 Pandoc is a [Haskell] library for converting from one markup format to 801 another, and a command-line tool that uses this library. 803 #### Extension: `header_attributes` #### {#ext-header-attributes} 805 Headers can be assigned attributes using this syntax at the end 806 of the line containing the header text: 808 {#identifier .class .class key=value key=value} 810 Thus, for example, the following headers will all be assigned 811 the identifier `foo`: 813 # My header {#foo} 815 ## My header ## {#foo} 817 My other header {#foo} 818 --------------- 820 Figure 3: Pandoc Example 822 4.4. Fountain (Fountain.io) 824 INT. BOXCAR - MOVING - DAY 825 ?AGENT MORTIMER lies bleeding in the corner. The car ROCKS gently. 826 Mortimer pulls out his cell phone and dials. 828 MORTIMER? 829 Come on. Pick up. 831 CUT TO:? 832 ext. hotel bar - day? 833 A fiercely gorgeous brunette sips the last of something from a 834 rocks glass. This is REBECCA. 836 Behind her, a dark FIGURE approaches. She seems not to notice. 838 REBECCA?(to Bartender) 839 Ritenhouse, neat. 841 FIGURE (O.S.) ^ 842 Ritenhouse, neat. 844 She turns to find the source of the voice. 846 FIGURE 847 Excellent choice. 849 Before she can reply, her phone RINGS.? 851 > INTERCUT WITH:? 853 .THE BOXCAR 855 Where MORTIMER is just barely holding on to life. 857 Figure 4: Fountain Example 859 4.5. CommonMark 860 CommonMark is like Markdown. 862 Here are some entity names that you can use with CommonMark: `  863 & © Æ Ď ¾ ℋ ⅆ 864 ∲` 866 You can see more at [the CommonMark website](http://commonmark.org/ 867 "CommonMark"). 869 - foo 870 *** 871 - bar 873 Tildes can be used for fenced code blocks: 875 ~~~ 876 < 877 > 878 ~~~ 880 Figure 5: CommonMark Example 882 4.6. kramdown-rfc2629 (Markdown for RFCs) 884 --- 885 title: STUN/TURN using PHP in Despair 886 abbrev: STuPiD-excerpt 887 docname: draft-hartke-xmpp-stupid-excerpt-00 888 date: 2009-07-05 889 category: info 891 ipr: trust200902 892 area: General 893 workgroup: XMPP Working Group 894 keyword: Internet-Draft 896 stand_alone: yes 897 pi: [toc, sortrefs, symrefs] 899 author: 900 - 901 ins: K. Hartke 902 name: Klaus Hartke 903 email: example@tzi.org 905 normative: 906 RFC2119: 908 informative: 909 RFC5389: 910 STUNT: 911 target: http://www.example.com/oob 912 title: STUNT & out-of-band channels 913 author: 914 name: Robbie Hanson 915 ins: R. Hanson 916 date: 2007-09-17 918 --- abstract 920 NAT (Network Address Translator) Traversal may require TURN 921 (Traversal Using Relays around NAT) functionality in certain 922 cases that are not unlikely to occur. There is little 923 incentive to deploy TURN servers, except by those who need 924 them—who may not be in a position to deploy a new protocol 925 on an Internet-connected node, in particular not one with 926 deployment requirements as high as those of TURN. 928 --- middle 930 Introduction {#problems} 931 ============ 933 "STUN/TURN using PHP in Despair" is a highly deployable 934 protocol for obtaining TURN-like functionality, while also 935 providing the most important function of STUN 936 {{RFC5389}}. 938 The Need for Standardization {#need} 939 ---------------------------- 941 Having one standard form of STuPiD service instead of one 942 specific to each kind of client also creates an incentive 943 for optimized implementations. 945 ~~~~~~~~~~ 947 STuPiD ```````````````````````````````, 948 Script <----------------------------. , 949 | , 950 ^ , | , 951 | , | , 952 (1) | , | , (3) 953 POST | , | , GET 954 | , | , 955 | v | v 957 Peer A -----------------------> Peer B 958 (2) 959 out-of-band 960 Notification 961 ~~~~~~~~~~ 962 {: #figops title="STuPiD Protocol Operation"} 964 Terminology {#Terminology} 965 ----------- 966 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 967 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 968 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 969 {{RFC2119}} and indicate requirement levels for compliant STuPiD 970 implementations. 972 --- back 974 Sample Implementation {#impl} 975 ===================== 977 ~~~~~~~~~~ 978 984 ~~~~~~~~~~ 985 {: #figimpl title="STuPiD Sample Implementation"} 987 Figure 6: Markdown for RFCs Example 989 4.7. rfc7328 (Pandoc2rfc) 991 Pandoc2rfc expects multiple files as input. The following figure is 992 example of "middle.mkd". 994 # Introduction 996 997 998 999 1000 1001 1003 This document presents a technique for using Pandoc syntax as a source 1004 format for documents in the Internet-Drafts (I-Ds) and Request 1005 for Comments (RFC) series. 1007 This version is adapted to work with `xml2rfc` version 2.x. 1009 Pandoc is an "almost plain text" format and therefore particularly 1010 well suited for editing RFC-like documents. 1012 > Note: this document is typeset in Pandoc. 1014 > NB: this is mostly text to test Pandoc2rfc, the canonical 1015 > documentation is [draft-gieben-pandoc2rfc][p2r]. 1017 [p2r]: http://tools.ietf.org/html/draft-gieben-pandoc2rfc-01 1019 # Pandoc to RFC 1021 > Pandoc2rfc -- designed to do the right thing, until it doesn't. 1023 When writing [](#RFC4641) we directly wrote the 1024 XML. Needless to say it was tedious even thought the XML of 1025 [xml2rfc](http://xml.resource.org/experimental) is very "light". 1026 The [latest version of xml2rfc version 2 can be found 1027 here](http://pypi.python.org/pypi/xml2rfc/). 1029 Figure 7: Pandoc2rfc Example (middle.mkd). 1031 5. IANA Considerations 1033 IANA is asked to register the syntaxes specified in Section 3 in the 1034 Markdown Variants Registry. 1036 6. Security Considerations 1038 See the respective syntax descriptions and output media type 1039 registrations for their respective security considerations. 1041 7. References 1043 7.1. Normative References 1045 [MARKDOWN] Gruber, J., "Daring Fireball: Markdown", December 2004, 1046 . 1048 [MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax 1049 Documentation", December 2004, 1050 . 1052 [MDMTREG] Leonard, S., "The text/markdown Media Type", draft-ietf- 1053 appsawg-text-markdown-06 (work in progress), February 1054 2015. 1056 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1057 Requirement Levels", BCP 14, RFC 2119, March 1997. 1059 [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the 1060 text/plain Media Type", RFC 5147, April 2008. 1062 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1063 October 2008. 1065 [RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding 1066 "charset" Parameter Handling in Textual Media Types", RFC 1067 6657, July 2012. 1069 7.2. Informative References 1071 [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 1072 8.0.0", The Unicode Consortium, August 2015. 1074 [HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", May 2008, 1075 . 1078 [DIN2MD] Gruber, J., "Dive Into Markdown", March 2004, 1079 . 1081 [MD102b8] Gruber, J., "[ANN] Markdown.pl 1.0.2b8", May 2007, 1082 , . 1086 [CATPICS] Gruber, J. and M. Arment, "The Talk Show: Ep. 88: 'Cat 1087 Pictures' (Side 1)", July 2014, 1088 . 1090 [INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of 1091 the word 'meme'", June 2013, 1092 , . 1095 [MULTIMD] Penney, F., "MultiMarkdown", April 2014, 1096 . 1098 [PANDOC] MacFarlane, J., "Pandoc", 2014, 1099 . 1101 [RAILFROG] Railfrog Team, "Railfrog", April 2009, 1102 . 1104 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 1105 793, September 1981. 1107 [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded 1108 Word Extensions: Character Sets, Languages, and 1109 Continuations", RFC 2231, November 1997. 1111 [RFC4263] Lilly, B., "Media Subtype Registration for Media Type 1112 text/troff", RFC 4263, January 2006. 1114 [RFC6533] Hansen, T., Ed., Newman, C. and A. Melnikov, 1115 "Internationalized Delivery Status and Disposition 1116 Notifications", RFC 6533, February 2012. 1118 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1119 Specifications and Registration Procedures", BCP 13, RFC 1120 6838, January 2013. 1122 [XML1.0-5] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1123 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 1124 Edition)", World Wide Web Consortium Recommendation REC- 1125 xml-20081126, November 2008, 1126 . 1128 [OCCASION] Shieber, S., "Switching to Markdown for scholarly article 1129 production", August 2014, 1130 . 1133 [FOUNTAIN] Maschwitz, S. and J. August, "Fountain | A markup language 1134 for screenwriting.", 2014, . 1136 [MATHDOWN] Cherniavsky-Paskin, B., "math in markdown", 2015, 1137 . 1139 [FTSYNTAX] Maschwitz, S. and J. August, "Syntax - Fountain | A markup 1140 language for screenwriting.", 1.1, March 2014, 1141 . 1143 [SVN] Apache Subversion, August 2015, 1144 . 1146 [GIT] Git, July 2015, . 1148 Author's Address 1150 Sean Leonard 1151 Penango, Inc. 1152 5900 Wilshire Boulevard 1153 21st Floor 1154 Los Angeles, CA 90036 1155 USA 1157 EMail: dev+ietf@seantek.com 1158 URI: http://www.penango.com/