idnits 2.17.1 draft-ietf-appsawg-text-markdown-use-cases-01.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. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 188: '...., web browsers) SHOULD try to make se...' RFC 2119 keyword, line 192: '... detected [...] the processor MUST NOT...' RFC 2119 keyword, line 398: '...t-Type header, so parameters SHOULD be...' RFC 2119 keyword, line 399: '...re. The filename SHOULD be consistent ...' RFC 2119 keyword, line 400: '...., the extension SHOULD be the variant...' (1 more instance...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 153 has weird spacing: '... markup form...' == Line 755 has weird spacing: '...scribed in th...' -- The document date (March 9, 2015) is 3326 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: 'CITE' is mentioned on line 218, but not defined == Missing Reference: 'RFC6532' is mentioned on line 404, but not defined == Missing Reference: 'Haskell' is mentioned on line 800, but not defined == Unused Reference: 'RFC5147' is defined on line 1056, but no explicit reference was found in the text == Unused Reference: 'RFC4263' is defined on line 1101, but no explicit reference was found in the text == Unused Reference: 'FTSYNTAX' is defined on line 1121, 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: 2 errors (**), 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 March 9, 2015 5 Expires: September 10, 2015 7 text/markdown Use Cases 8 draft-ietf-appsawg-text-markdown-use-cases-01 10 Abstract 12 This document elaborates upon the text/markdown media type for use 13 with Markdown, a family of plain text formatting syntaxes that 14 optionally can be converted to formal markup languages such as HTML. 15 Background information, local storage strategies, and additional 16 syntax registrations are supplied. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 Copyright Notice 35 Copyright (c) 2015 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Dive Into Markdown . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. On Formats . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.2. Markdown Design Philosophy . . . . . . . . . . . . . . . . 4 53 1.3. Uses of Markdown . . . . . . . . . . . . . . . . . . . . . 5 54 1.4. Uses of Labeling Markdown Content as text/markdown . . . . 5 55 2. Strategies for Preserving Media Type and Parameters . . . . . 6 56 2.1. Map to Filename and Attributes . . . . . . . . . . . . . . 7 57 2.2. Store Headers in Adjacent File . . . . . . . . . . . . . . 8 58 2.3. "Arm" Content with MIME Headers . . . . . . . . . . . . . . 8 59 2.4. Create a Local Batch Script . . . . . . . . . . . . . . . . 8 60 2.5. Process the Markdown . . . . . . . . . . . . . . . . . . . 8 61 2.6. Rely on Context . . . . . . . . . . . . . . . . . . . . . . 8 62 2.7. Specific Strategies . . . . . . . . . . . . . . . . . . . . 9 63 2.7.1. Subversion . . . . . . . . . . . . . . . . . . . . . . 9 64 2.7.2. Git . . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 3. Registration Templates for Common Markdown Syntaxes . . . . . 10 66 3.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 10 67 3.2. GitHub Flavored Markdown . . . . . . . . . . . . . . . . . 11 68 3.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 3.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 13 70 3.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 14 71 3.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 15 72 3.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 15 73 3.8. PHP Markdown Extra . . . . . . . . . . . . . . . . . . . . 15 74 4. Examples for Common Markdown Syntaxes . . . . . . . . . . . . 16 75 4.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 16 76 4.2. GitHub Flavored Markdown . . . . . . . . . . . . . . . . . 16 77 4.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 17 78 4.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 18 79 4.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 18 80 4.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 19 81 4.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 22 82 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 22 84 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 85 7.1. Normative References . . . . . . . . . . . . . . . . . . . 23 86 7.2. Informative References . . . . . . . . . . . . . . . . . . 23 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 25 89 1. Dive Into Markdown 91 This document serves as an informational companion to [MDMTREG], the 92 text/markdown media type registration. It should be considered 93 jointly with [MDMTREG]. 95 "Sometimes the truth of a thing is not so much in the 96 think of it, but in the feel of it." --Stanley Kubrick 98 1.1. On Formats 100 In computer systems, textual data is stored and processed using a 101 continuum of techniques. On the one end is plain text: a linear 102 sequence of characters in some character set (code), possibly 103 interrupted by line breaks, page breaks, or other control characters. 104 Plain text provides /some/ fixed facilities for formatting 105 instructions, namely codes in the character set that have meanings 106 other than "represent this character on the output medium"; however, 107 these facilities are not particularly extensible. Compare with 108 [RFC6838] Section 4.2.1. Applications may neuter the effects of these 109 special characters by prohibiting them or by ignoring their dictated 110 meanings, as is the case with how modern applications treat most 111 control characters in US-ASCII. On this end, any text reader or 112 editor that interprets the character set can be used to see or 113 manipulate the text. If some characters are corrupted, the corruption 114 is unlikely to affect the ability of a computer system to process the 115 text (even if the human meaning is changed). 117 On the other end is binary format: a sequence of instructions 118 intended for some computer application to interpret and act upon. 119 Binary formats are flexible in that they can store non-textual data 120 efficiently (perhaps storing no text at all, or only storing certain 121 kinds of text for very specialized purposes). Binary formats require 122 an application to be coded specifically to handle the format; no 123 partial interoperability is possible. Furthermore, if even one byte 124 or bit are corrupted in a binary format, it may prevent an 125 application from processing any of the data correctly. 127 Between these two extremes lies formatted text, i.e., text that 128 includes non-textual information coded in a particular way, that 129 affects the interpretation of the text by computer programs. 130 Formatted text is distinct from plain text and binary format in that 131 the non-textual information is encoded into textual characters, which 132 are assigned specialized meanings /not/ defined by the character set. 133 With a regular text editor and a standard keyboard (or other standard 134 input mechanism), a user can enter these textual characters to 135 express the non-textual meanings. For example, a character like "<" 136 no longer means "LESS-THAN SIGN"; it means the start of a tag or 137 element that affects the document in some way. 139 On the formal end of the spectrum is markup, a family of languages 140 for annotating a document in such a way that the annotations are 141 syntactically distinguishable from the text. Markup languages are 142 (reasonably) well-specified and tend to follow (mostly) standardized 143 syntax rules. Examples of markup languages include SGML, HTML, XML, 144 and LaTeX. Standardized rules lead to interoperability between markup 145 processors, but a skill requirement for new (human) users of the 146 language that they learn these rules in order to do useful work. This 147 imposition makes markup less accessible for non-technical users 148 (i.e., users who are unwilling or unable to invest in the requisite 149 skill development). 151 informal /---------formatted text----------\ formal 152 <------v-------------v-------------v-----------------------v----> 153 plain text informal markup formal markup binary format 154 (Markdown) (HTML, XML, etc.) 156 Figure 1: Degrees of Formality in Data Storage Formats for Text 158 On the informal end of the spectrum are lightweight markup languages. 159 In comparison with formal markup like XML, lightweight markup uses 160 simple syntax, and is designed to be easy for humans to enter with 161 basic text editors. Markdown, the subject of this document, is an 162 /informal/ plain text formatting syntax that is intentionally 163 targeted at non-technical users (i.e., users upon whom little to no 164 skill development is imposed) using unspecialized tools (i.e., text 165 boxes). Jeff Atwood once described these informal markup languages as 166 "humane" [HUMANE]. 168 1.2. Markdown Design Philosophy 170 Markdown specifically is a family of syntaxes that are based on the 171 original work of John Gruber with substantial contributions from 172 Aaron Swartz, released in 2004 [MARKDOWN]. Since its release a number 173 of web or web-facing applications have incorporated Markdown into 174 their text entry systems, frequently with custom extensions. Fed up 175 with the complexity and security pitfalls of formal markup languages 176 (e.g., HTML5) and proprietary binary formats (e.g., commercial word 177 processing software), yet unwilling to be confined to the 178 restrictions of plain text, many users have turned to Markdown for 179 document processing. Whole toolchains now exist to support Markdown 180 for online and offline projects. 182 Informality is a bedrock premise of Gruber's design. Gruber created 183 Markdown after disastrous experiences with strict XML and XHTML 184 processing of syndicated feeds. In Mark Pilgrim's "thought 185 experiment", several websites went down because one site included 186 invalid XHTML in a blog post, which was automatically copied via 187 trackbacks across other sites [DIN2MD]. These scenarios led Gruber to 188 believe that clients (e.g., web browsers) SHOULD try to make sense of 189 data that they receive, rather than rejecting data simply because it 190 fails to adhere to strict, unforgiving standards. (In [DIN2MD], 191 Gruber compared Postel's Law [RFC0793] with the XML standard, which 192 says: "Once a fatal error is detected [...] the processor MUST NOT 193 continue normal processing" [XML1.0-5].) As a result, there is no 194 such thing as "invalid" Markdown; there is no standard demanding 195 adherence to the Markdown syntax; there is no governing body that 196 guides or impedes its development. If the Markdown syntax does not 197 result in the "right" output (defined as output that the author 198 wants, not output that adheres to some dictated system of rules), 199 Gruber's view is that the author either should keep on experimenting, 200 or should change the processor to address the author's particular 201 needs (see [MARKDOWN] Readme and [MD102b8] perldoc; see also 202 [CATPICS]). 204 1.3. Uses of Markdown 206 Since its introduction in 2004, Markdown has enjoyed remarkable 207 success. Markdown works for users for three key reasons. First, the 208 markup instructions (in text) look similar to the markup that they 209 represent; therefore the cognitive burden to learn the syntax is low. 210 Second, the primary arbiter of the syntax's success is *running 211 code*. The tool that converts the Markdown to a presentable format, 212 and not a series of formal pronouncements by a standards body, is the 213 basis for whether syntactic elements matter. Third, Markdown has 214 become something of an Internet meme [INETMEME], in that Markdown 215 gets received, reinterpreted, and reworked as additional communities 216 encounter it. There are communities that are using Markdown for 217 scholarly writing [CITE], for screenplays [FOUNTAIN], for 218 mathematical formulae [CITE], and even for music annotation [CITE]. 219 Clearly, a screenwriter has no use for specialized Markdown syntax 220 for mathematicians; likewise, mathematicians do not need to identify 221 characters or props in common ways. The overall gist is that all of 222 these communities can take the common elements of Markdown (which are 223 rooted in the common elements of HTML circa 2004) and build on them 224 in ways that best fit their needs. 226 1.4. Uses of Labeling Markdown Content as text/markdown 228 The primary purpose of an Internet media type is to label "content" 229 on the Internet, as distinct from "files". Content is any computer- 230 readable format that can be represented as a primary sequence of 231 octets, along with type-specific metadata (parameters) and type- 232 agnostic metadata (protocol dependent). From this description, it is 233 apparent that appending ".markdown" to the end of a filename is not a 234 sufficient means to identify Markdown. Filenames are properties of 235 files in file systems, but Markdown frequently exists in databases or 236 content management systems (CMSes) where the file metaphor does not 237 apply. One CMS [RAILFROG] uses media types to select appropriate 238 processing, so a media type is necessary for the safe and 239 interoperable use of Markdown. 241 Unlike complete HTML documents, [MDSYNTAX] provides no means to 242 include metadata into the content stream. Several derivative flavors 243 have invented metadata incorporation schemes (e.g., [MULTIMD]), but 244 these schemes only address specific use cases. In general, the 245 metadata must be supplied via supplementary means in an encapsulating 246 protocol, format, or convention. The relationship between the content 247 and the metadata is not directly addressed here or in [MDMTREG]; 248 however, by identifying Markdown with a media type, Markdown content 249 can participate as a first-class citizen with a wide spectrum of 250 metadata schemes. 252 Finally, registering a media type through the IETF process is not 253 trivial. Markdown can no longer be considered a "vendor"-specific 254 innovation, but the registration requirements even in the vendor tree 255 have proven to be overly burdensome for most Markdown implementers. 256 Moreover, registering hundreds of Markdown variants with distinct 257 media types would impede interoperability: virtually all Markdown 258 content can be processed by virtually any Markdown processor, with 259 varying degrees of success. The goal of [MDMTREG] is to reduce all of 260 these burdens by having one media type that accommodates diversity 261 and eases registration. 263 2. Strategies for Preserving Media Type and Parameters 265 The purpose of this document and [MDMTREG] is to promote 266 interoperability between different Markdown-related systems, 267 preserving the author's intent. While [MARKDOWN] was designed by 268 Gruber in 2004 as a simple way to write blog posts and comments, as 269 of 2014 Markdown and its derivatives are rapidly becoming the formats 270 of record for many communities and use cases. While an individual 271 member of (or software tool for) a community can probably look at 272 some "Markdown" and declare its meaning intuitively obvious, software 273 systems in different communities (or different times) need help. 274 [MDSYNTAX] does not have a signaling mechanism like , so 275 tagging Markdown internally is simply out of the question. Once tags 276 or metadata are introduced, the content is no longer "just" Markdown. 278 Some commentators have suggested that an in-band signaling mechanism, 279 such as in Markdown link definitions at the top of the content, could 280 be used to signal the variant. Unfortunately this signaling mechanism 281 is incompatible with other Markdown variants (e.g., [PANDOC]) that 282 expect their own kinds of metadata at the top of the file. Markdown 283 content is just a stream of text; the semantics of that text can only 284 be furnished by context. 286 The media type and variant parameter in [MDMTREG] furnish this 287 missing context, while allowing for additional extensibility. This 288 section covers strategies for how an application might preserve 289 metadata when it leaves the domain of IETF protocols. 291 [MDMTREG] (draft-05) only defines two parameters: the charset 292 parameter (required for all text/* media types) and the variant 293 parameter. Character set interoperability is well-studied territory 294 [NB: CITE?] and so is not further covered here. The variant parameter 295 provides a simple identifier--nothing less or more. Variants are 296 allowed to define additional parameters when sent with the 297 text/markdown media type; the variant can also introduce control 298 information into the textual content stream (such as via a metadata 299 block). Neither [MDMTREG] nor this specification recommend any 300 particular approach. However, the philosophy behind [MDMTREG] is to 301 preserve formats rather than create new ones, since supporting 302 existing toolchains is more realistic than creating novel ones that 303 lack traction in the Markdown community. 305 2.1. Map to Filename and Attributes 307 This strategy is to map the media type, variant, and parameters to 308 "attributes" or "forks" in the local convention. Firstly, Markdown 309 content saved to a file should have an appropriate file extension 310 ending in .md or .markdown, which serves to disambiguate it from 311 other kinds of files. The character repertoire of variant identifiers 312 in [MDMTREG] is designed to be compatible with most filename 313 conventions. Therefore, a recommended strategy is to record the 314 variant identifier as the prefix to the file extension. For example, 315 for [PANDOC] content, a file could be named 316 "example.pandoc.markdown". 318 Many filesystems are case-sensitive or case-preserving; however, file 319 extensions tend to be all-lowercase. This document takes no position 320 on whether variant identifiers should be case-preserved or all- 321 lowercase when Markdown content is written to a file. However, when 322 the variant identifier is read to influence operational behavior, it 323 needs to be compared case-insensitively. 325 Many modern filesystems support "extended attributes", "alternate 326 data streams", or "resource forks". Some version control systems 327 support named properties. If the variant defines additional 328 parameters, these parameters should be stored in these resources, 329 where the parameter name includes the name of the resource, and the 330 parameter value is the value of the resource (data in the resource), 331 preferably UTF-8 encoded (unless the parameter definition explicitly 332 defines a different encoding or repertoire). The variant identifier 333 itself should be stored in a resource with a name including the term 334 "variant". 336 2.2. Store Headers in Adjacent File 338 This strategy is to save the Markdown content in a first file, and to 339 save the metadata (specifically the Content-Type: header) in a second 340 file with a filename that is rationally related to the first 341 filename. For example, if the first file is named "readme.markdown", 342 the second file could be named "readme.markdown.headers". (If stored 343 in a database, the analogy would be to store the metadata in a second 344 table with a field that is a key to the first table.) This header 345 file has the media type "message/global-headers" [RFC6533] (".u8hdr" 346 suggestion notwithstanding). 348 2.3. "Arm" Content with MIME Headers 350 This strategy is to save the Markdown content along with its headers 351 in a file, "arming" the content by prepending the MIME headers 352 (specifically the Content-Type: header). It should be appreciated 353 that the file is no longer a "Markdown file"; rather, it is an 354 Internet Message Format file (e.g., [RFC5322]) with a Markdown 355 content part. Therefore, the file should have an Internet message 356 extension (e.g., ".eml", ".msg", or ".u8msg"), not a Markdown 357 extension (e.g., ".md" or ".markdown"). 359 2.4. Create a Local Batch Script 361 This strategy is to translate the processing instructions inferred 362 from the Content-Type and other parameters (e.g., Content- 363 Disposition) into a sequence of commands in the local convention, 364 storing those commands in a batch script. For example, when a MIME- 365 aware client stores some Markdown to disk, the client can save a 366 Makefile in the same directory with commands that are appropriate 367 (and safe) for the local system. 369 2.5. Process the Markdown 371 This strategy is to process the Markdown into the formal markup, 372 which eliminates ambiguities. Once the Markdown is processed into 373 (for example) valid XHTML, an application can save a file as 374 "doc.xhtml" with no further loss of metadata. While unambiguous, this 375 process may not be reversible. 377 2.6. Rely on Context 379 This last strategy is to use or create context to determine how to 380 interpret the Markdown. For example, Markdown content that is of the 381 Fountain.io type [FOUNTAIN] could be saved with the filename 382 "script.fountain" instead of "script.markdown". Alternatively, 383 scripts could be stored in a "/screenplays" directory while other 384 kinds of Markdown could be stored elsewhere. For reasons that should 385 be intuitively obvious, this method is the most error-prone. 386 "Context" can be easily lost over time, and the trend of passing 387 Markdown between systems--taking them *out* of context--is 388 increasing. 390 2.7. Specific Strategies 392 2.7.1. Subversion 394 This subsection covers a preservation strategy in Subversion [SVN], a 395 common client-server version control system. 397 Subversion supports named properties. The "svn:mime-type" property 398 duplicates the entire Content-Type header, so parameters SHOULD be 399 stored there. The filename SHOULD be consistent with this Content- 400 Type header, i.e., the extension SHOULD be the variant identifier 401 plus ".markdown". 403 [[TODO: Versions of Subversion after [[1.x]] treat svn:mime-type as 404 UTF-8 encoded, rather than US-ASCII. (See [RFC6532].) Therefore, the 405 encoding of [RFC2231] will not be necessary in the vast majority of 406 cases in newer versions. However, both for backwards compatibility 407 and for support for non-Unicode character sets, [RFC2231] still needs 408 to be supported.]] 410 [[TODO: Where to store Content-Disposition?]] 412 2.7.2. Git 414 This subsection covers a preservation strategy in Git [GIT], a common 415 distributed version control system. 417 Versions of Git as of the time of this writing do not support 418 arbitrary metadata storage; however, third-party projects add this 419 support. 421 If Git is used without a metadata storage service, then a reasonable 422 strategy is to include the variant identifier in the filename. The 423 encoding of the file should be transcoded to UTF-8. For other 424 properties, a header file should be recorded alongside the Markdown 425 file in accordance with Section 2.2. The contents of the header file 426 should be consistent with the rest of this paragraph, i.e., the 427 charset parameter should be "UTF-8" and the variant parameter should 428 match the identifier in the filename. 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: 476 478 Contact Information: 479 (individual) Fletcher T. Penney 480 482 3.2. GitHub Flavored Markdown 484 Identifier: GFM 486 Name: GitHub Flavored Markdown 488 Description: 489 "Original" with the following differences: 490 1. Multiple underscores in words 491 2. URL (URI) autolinking 492 3. Strikethrough 493 4. Fenced code blocks 494 5. Syntax highlighting 495 6. Tables (- for rows; | for columns; : for alignment) 496 7. Only some HTML allowed; sanitization is integral 497 to the format 499 References: 500 501 503 Contact Information: 504 (corporate) GitHub, Inc. 506 3.3. Pandoc 508 Identifier: pandoc 510 Name: Pandoc 512 Description: 513 Markdown is designed to be easy to write and to read: the content 514 should be publishable as-is, as plain text, without looking like it 515 has been marked up with tags or formatting instructions. Yet whereas 516 "Original" has HTML generation in mind, pandoc is designed for 517 multiple output formats. Thus, while pandoc allows the embedding of 518 raw HTML, it discourages it, and provides other, non-HTMLish ways of 519 representing important document elements like definition lists, 520 tables, mathematics, and footnotes. 522 Additional Parameters: 523 extensions: String with an optional starting syntax token, followed 524 by a "+" and "-" delimited list of extension tokens. "+" 525 preceding an extension token turns the extension on; "-" 526 turns the extension off. The starting syntax tokens are 527 "markdown", "markdown_strict", "markdown_phpextra", and 528 "markdown_github". If no starting syntax token is given, 529 "markdown" is assumed. The extension tokens include: 531 [[Stuff to turn off:]] 533 escaped_line_breaks 534 blank_before_header 535 header_attributes 536 auto_identifiers 537 implicit_header_references 538 blank_before_blockquote 539 fenced_code_blocks 540 fenced_code_attributes 541 line_blocks 542 fancy_lists 543 startnum 544 definition_lists 545 example_lists 546 table_captions 547 simple_tables 548 multiline_tables 549 grid_tables 550 pipe_tables 551 pandoc_title_block 552 yaml_metadata_block 553 all_symbols_escapable 554 intraword_underscores 555 strikeout 556 superscript 557 subscript 558 inline_code_attributes 559 tex_math_dollars 560 raw_html 561 markdown_in_html_blocks 562 native_divs 563 native_spans 564 raw_tex 565 latex_macros 566 implicit_figures 567 footnotes 568 inline_notes 569 citations 571 [[New stuff:]] 573 lists_without_preceding_blankline 574 hard_line_breaks 575 ignore_line_breaks 576 tex_math_single_backslash 577 tex_match_double_backslash 578 markdown_attribute 579 mmd_title_block 580 abbreviations 581 autolink_bare_uris 582 ascii_identifiers 583 link_attributes 584 mmd_header_identifiers 585 compact_definition_lists 587 Fragment Identifiers: 588 Pandoc defines fragment identifiers using the in the 589 {# .class ...} production (PHP Markdown Extra attribute block). 590 This syntax works for Header Identifiers and Code Block Identifiers. 592 References: 593 595 Contact Information: 596 (individual) Prof. John MacFarlane 597 599 3.4. Fountain (Fountain.io) 601 Identifier: Fountain 603 Name: Fountain 605 Description: 606 Fountain is a simple markup syntax for writing, editing and sharing 607 screenplays in plain, human-readable text. Fountain allows you to 608 work on your screenplay anywhere, on any computer or tablet, using 609 any software that edits text files. 611 Fragment Identifiers: 612 See and 613 . In the following 614 fragment identifiers, the and productions MUST have "/" 615 characters percent-encoded. 617 #/ Title Page (acts as metadata). 618 #/ Title Page; is the key string. 619 # *("/" ) 620 Section or subsection. The .. 621 productions are the text of the Section line, 622 with whitespace trimmed from both ends. 623 Sub-sections (sections with multiple # at 624 at the beginning of the line in the source) 625 are addressed hierarchically by preceding 626 the sub-section with higher-order 627 sections. If the section hierarchy "skips", 628 e.g., # to ###, use a blank section name, 629 e.g., #Section/ACT%20I//PATIO%20SCENE. 631 References: 632 634 Contact Information: 635 (individual) Stu Maschwitz 636 (individual) John August 638 3.5. CommonMark 640 Identifier: CommonMark 642 Name: CommonMark 644 Description: 645 CommonMark is a standard, unambiguous syntax specification for 646 Markdown, along with a suite of comprehensive tests to validate 647 Markdown implementations against this specification. The maintainers 648 believe that CommonMark is necessary, even essential, for the future 649 of Markdown. 651 Compared to "Original", CommonMark is much longer and in a few 652 instances contradicts "Original" based on seasoned experience. 653 Although CommonMark specifically does not mandate any particular 654 encoding for the input content, CommonMark draws in more of Unicode, 655 UTF-8, and HTML (including HTML5) than "Original". 657 This registration always refers to the latest version or an 658 unspecified version (receiver's choice). Version 0.13 of the 659 CommonMark specification was released 2014-12-10. 661 References: 662 664 Contact Information: 665 (individual) John MacFarlane 666 (individual) David Greenspan 667 (individual) Vicent Marti 668 (individual) Neil Williams 669 (individual) Benjamin Dumke-von der Ehe 670 (individual) Jeff Atwood 672 3.6. kramdown-rfc2629 (Markdown for RFCs) 674 Identifier: kramdown-rfc2629 676 Name: Markdown for RFCs 678 Description: 679 kramdown is a markdown parser by Thomas Leitner, which has a number 680 of backends for generating HTML, Latex, and Markdown again. kramdown- 681 rfc2629 is an additional backend to that: It allows the generation of 682 XML2RFC XML markup (also known as RFC 2629 compliant markup). 684 References: 685 687 Contact Information: 688 (individual) Carsten Bormann 690 3.7. rfc7328 (Pandoc2rfc) 692 Identifier: rfc7328 694 Name: Pandoc2rfc 696 Description: 697 Pandoc2rfc allows authors to write in "pandoc" that is then 698 transformed to XML and given to xml2rfc. The conversions are, in a 699 way, amusing, as we start off with (almost) plain text, use elaborate 700 XML, and end up with plain text again. 702 References: 703 RFC 7328 704 706 Contact Information: 707 (individual) R. (Miek) Gieben 709 3.8. PHP Markdown Extra 711 Identifier: Extra 713 Name: Markdown Extra 715 Description: 716 Markdown Extra is an extension to PHP Markdown implementing some 717 features currently not available with the plain Markdown syntax. 718 Markdown Extra is available as a separate parser class in PHP 719 Markdown Lib. Other implementations include Maruku (Ruby) and Python 720 Markdown. Markdown Extra is supported in several content management 721 systems, including Drupal, TYPO3, and MediaWiki. 723 Fragment Identifiers: 724 Markdown Extra defines fragment identifiers using the in the 725 {# .class ...} production (attribute block). This syntax works 726 for headers, fenced code blocks, links, and images. 728 References: 729 731 Contact Information: 732 (individual) Michel Fortin 734 4. Examples for Common Markdown Syntaxes 736 This section provides examples of the variants in Appendix C. 738 4.1. MultiMarkdown 740 Title: Example of MultiMarkdown 741 Keywords: IETF, example, footnotes 743 # MutliMarkdown Example # 745 MultiMarkdown supports several cool features, as well as 746 several output formats: 747 * HTML 748 * PDF 749 * OpenDocument 750 * OPML 751 * LaTeX 753 ## Footnotes ## 755 Footnotes are described in the 756 MultiMarkdown Syntax Guide.[^somesamplefootnote] 758 [^somesamplefootnote]: Here is the text of the footnote itself. 760 Figure 1: MultiMarkdown Example 762 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} 814 ## My header ## {#foo} 816 My other header {#foo} 817 --------------- 819 Figure 3: Pandoc Example 821 4.4. Fountain (Fountain.io) 823 INT. BOXCAR - MOVING - DAY 824 ?AGENT MORTIMER lies bleeding in the corner. The car ROCKS gently. 825 Mortimer pulls out his cell phone and dials. 827 MORTIMER? 828 Come on. Pick up. 830 CUT TO:? 831 ext. hotel bar - day? 832 A fiercely gorgeous brunette sips the last of something from a 833 rocks glass. This is REBECCA. 835 Behind her, a dark FIGURE approaches. She seems not to notice. 837 REBECCA?(to Bartender) 838 Ritenhouse, neat. 840 FIGURE (O.S.) ^ 841 Ritenhouse, neat. 843 She turns to find the source of the voice. 845 FIGURE 846 Excellent choice. 848 Before she can reply, her phone RINGS.? 850 > INTERCUT WITH:? 852 .THE BOXCAR 854 Where MORTIMER is just barely holding on to life. 856 Figure 4: Fountain Example 858 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: 911 STUNT: 912 target: http://www.example.com/oob 913 title: STUNT & out-of-band channels 914 author: 915 name: Robbie Hanson 916 ins: R. Hanson 917 date: 2007-09-17 919 --- abstract 921 NAT (Network Address Translator) Traversal may require TURN 922 (Traversal Using Relays around NAT) functionality in certain 923 cases that are not unlikely to occur. There is little 924 incentive to deploy TURN servers, except by those who need 925 them—who may not be in a position to deploy a new protocol 926 on an Internet-connected node, in particular not one with 927 deployment requirements as high as those of TURN. 929 --- middle 931 Introduction {#problems} 932 ============ 934 "STUN/TURN using PHP in Despair" is a highly deployable 935 protocol for obtaining TURN-like functionality, while also 936 providing the most important function of STUN 937 {{RFC5389}}. 939 The Need for Standardization {#need} 940 ---------------------------- 942 Having one standard form of STuPiD service instead of one 943 specific to each kind of client also creates an incentive 944 for optimized implementations. 946 ~~~~~~~~~~ 948 STuPiD ```````````````````````````````, 949 Script <----------------------------. , 950 | , 951 ^ , | , 952 | , | , 953 (1) | , | , (3) 954 POST | , | , GET 955 | , | , 956 | v | v 958 Peer A -----------------------> Peer B 959 (2) 960 out-of-band 961 Notification 962 ~~~~~~~~~~ 963 {: #figops title="STuPiD Protocol Operation"} 965 Terminology {#Terminology} 966 ----------- 967 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 968 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 969 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 970 {{RFC2119}} and indicate requirement levels for compliant STuPiD 971 implementations. 973 --- back 975 Sample Implementation {#impl} 976 ===================== 978 ~~~~~~~~~~ 979 985 ~~~~~~~~~~ 986 {: #figimpl title="STuPiD Sample Implementation"} 988 Figure 6: Markdown for RFCs Example 990 4.7. rfc7328 (Pandoc2rfc) 992 Pandoc2rfc expects multiple files as input. The following figure is 993 example of "middle.mkd". 995 # Introduction 997 998 999 1000 1001 1002 1004 This document presents a technique for using Pandoc syntax as a source 1005 format for documents in the Internet-Drafts (I-Ds) and Request 1006 for Comments (RFC) series. 1008 This version is adapted to work with `xml2rfc` version 2.x. 1010 Pandoc is an "almost plain text" format and therefore particularly 1011 well suited for editing RFC-like documents. 1013 > Note: this document is typeset in Pandoc. 1015 > NB: this is mostly text to test Pandoc2rfc, the canonical 1016 > documentation is [draft-gieben-pandoc2rfc][p2r]. 1018 [p2r]: http://tools.ietf.org/html/draft-gieben-pandoc2rfc-01 1020 # Pandoc to RFC 1022 > Pandoc2rfc -- designed to do the right thing, until it doesn't. 1024 When writing [](#RFC4641) we directly wrote the 1025 XML. Needless to say it was tedious even thought the XML of 1026 [xml2rfc](http://xml.resource.org/experimental) is very "light". 1027 The [latest version of xml2rfc version 2 can be found 1028 here](http://pypi.python.org/pypi/xml2rfc/). 1030 Figure 7: Pandoc2rfc Example (middle.mkd). 1032 5. IANA Considerations 1034 IANA is asked to register the syntaxes specified in Section 3 in the 1035 Markdown Variants Registry. 1037 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 [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the 1057 text/plain Media Type", RFC 5147, April 2008. 1059 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 1060 October 2008. 1062 7.2. Informative References 1064 [HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", May 2008, 1065 . 1068 [DIN2MD] Gruber, J., "Dive Into Markdown", March 2004, 1069 . 1071 [MD102b8] Gruber, J., "[ANN] Markdown.pl 1.0.2b8", May 2007, 1072 , . 1076 [CATPICS] Gruber, J. and M. Arment, "The Talk Show: Ep. 88: 'Cat 1077 Pictures' (Side 1)", July 2014, 1078 . 1080 [INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of 1081 the word 'meme'", June 2013, 1082 , . 1085 [MULTIMD] Penney, F., "MultiMarkdown", April 2014, 1086 . 1088 [PANDOC] MacFarlane, J., "Pandoc", 2014, 1089 . 1091 [RAILFROG] Railfrog Team, "Railfrog", April 2009, 1092 . 1094 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 1095 793, September 1981. 1097 [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded 1098 Word Extensions: Character Sets, Languages, and 1099 Continuations", RFC 2231, November 1997. 1101 [RFC4263] Lilly, B., "Media Subtype Registration for Media Type 1102 text/troff", RFC 4263, January 2006. 1104 [RFC6533] Hansen, T., Ed., Newman, C. and A. Melnikov, 1105 "Internationalized Delivery Status and Disposition 1106 Notifications", RFC 6533, February 2012. 1108 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 1109 Specifications and Registration Procedures", BCP 13, RFC 1110 6838, January 2013. 1112 [XML1.0-5] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 1113 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 1114 Edition)", World Wide Web Consortium Recommendation REC- 1115 xml-20081126, November 2008, 1116 . 1118 [FOUNTAIN] Maschwitz, S. and J. August, "Fountain | A markup language 1119 for screenwriting.", 2014, . 1121 [FTSYNTAX] Maschwitz, S. and J. August, "Syntax - Fountain | A markup 1122 language for screenwriting.", 1.1, March 2014, 1123 . 1125 [SVN] Apache Subversion, December 2014, 1126 . 1128 [GIT] Git, December 2014, . 1130 Author's Address 1132 Sean Leonard 1133 Penango, Inc. 1134 5900 Wilshire Boulevard 1135 21st Floor 1136 Los Angeles, CA 90036 1137 USA 1139 EMail: dev+ietf@seantek.com 1140 URI: http://www.penango.com/