idnits 2.17.1 draft-seantek-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 : ---------------------------------------------------------------------------- ** 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 185: '...., web browsers) SHOULD try to make se...' RFC 2119 keyword, line 189: '... detected [...] the processor MUST NOT...' RFC 2119 keyword, line 395: '...t-Type header, so parameters SHOULD be...' RFC 2119 keyword, line 396: '...re. The filename SHOULD be consistent ...' RFC 2119 keyword, line 397: '...., 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 150 has weird spacing: '... markup form...' -- The document date (December 28, 2014) is 3401 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 215, but not defined == Missing Reference: 'RFC6532' is mentioned on line 401, but not defined == Unused Reference: 'RFC5147' is defined on line 775, but no explicit reference was found in the text == Unused Reference: 'RFC4263' is defined on line 820, but no explicit reference was found in the text == Unused Reference: 'FTSYNTAX' is defined on line 840, but no explicit reference was found in the text == Outdated reference: A later version (-12) exists of draft-ietf-appsawg-text-markdown-03 -- Obsolete informational reference (is this intentional?): RFC 793 (Obsoleted by RFC 9293) Summary: 1 error (**), 0 flaws (~~), 8 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Leonard 3 Internet-Draft Penango, Inc. 4 Intended Status: Informational December 28, 2014 5 Expires: July 1, 2015 7 text/markdown Use Cases 8 draft-seantek-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) 2014 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. 45 Table of Contents 47 1. Dive Into Markdown . . . . . . . . . . . . . . . . . . . . . . 2 48 1.1. On Formats . . . . . . . . . . . . . . . . . . . . . . . . 3 49 1.2. Markdown Design Philosophy . . . . . . . . . . . . . . . . 4 50 1.3. Uses of Markdown . . . . . . . . . . . . . . . . . . . . . 5 51 1.4. Uses of Labeling Markdown Content as text/markdown . . . . 5 52 2. Strategies for Preserving Media Type and Parameters . . . . . 6 53 2.1. Map to Filename and Attributes . . . . . . . . . . . . . . 7 54 2.2. Store Headers in Adjacent File . . . . . . . . . . . . . . 7 55 2.3. "Arm" Content with MIME Headers . . . . . . . . . . . . . . 8 56 2.4. Create a Local Batch Script . . . . . . . . . . . . . . . . 8 57 2.5. Process the Markdown . . . . . . . . . . . . . . . . . . . 8 58 2.6. Rely on Context . . . . . . . . . . . . . . . . . . . . . . 8 59 2.7. Specific Strategies . . . . . . . . . . . . . . . . . . . . 9 60 2.7.1. Subversion . . . . . . . . . . . . . . . . . . . . . . 9 61 2.7.2. Git . . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 3. Registration Templates for Common Markdown Syntaxes . . . . . 10 63 3.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 10 64 3.2. GitHub Flavored Markdown . . . . . . . . . . . . . . . . . 10 65 3.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 11 66 3.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 13 67 3.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 14 68 3.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 14 69 3.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 15 70 3.8. PHP Markdown Extra . . . . . . . . . . . . . . . . . . . . 15 71 4. Examples for Common Markdown Syntaxes . . . . . . . . . . . . 16 72 4.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 16 73 4.2. GitHub Flavored Markdown . . . . . . . . . . . . . . . . . 16 74 4.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 16 75 4.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 16 76 4.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 16 77 4.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 16 78 4.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 16 79 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 80 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 16 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 82 7.1. Normative References . . . . . . . . . . . . . . . . . . . 16 83 7.2. Informative References . . . . . . . . . . . . . . . . . . 17 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 18 86 1. Dive Into Markdown 88 This document serves as an informational companion to [MDMTREG], the 89 text/markdown media type registration. It should be considered 90 jointly with [MDMTREG]. 92 "Sometimes the truth of a thing is not so much in the 93 think of it, but in the feel of it." --Stanley Kubrick 95 1.1. On Formats 97 In computer systems, textual data is stored and processed using a 98 continuum of techniques. On the one end is plain text: a linear 99 sequence of characters in some character set (code), possibly 100 interrupted by line breaks, page breaks, or other control characters. 101 Plain text provides /some/ fixed facilities for formatting 102 instructions, namely codes in the character set that have meanings 103 other than "represent this character on the output medium"; however, 104 these facilities are not particularly extensible. Compare with 105 [RFC6838] Section 4.2.1. Applications may neuter the effects of these 106 special characters by prohibiting them or by ignoring their dictated 107 meanings, as is the case with how modern applications treat most 108 control characters in US-ASCII. On this end, any text reader or 109 editor that interprets the character set can be used to see or 110 manipulate the text. If some characters are corrupted, the corruption 111 is unlikely to affect the ability of a computer system to process the 112 text (even if the human meaning is changed). 114 On the other end is binary format: a sequence of instructions 115 intended for some computer application to interpret and act upon. 116 Binary formats are flexible in that they can store non-textual data 117 efficiently (perhaps storing no text at all, or only storing certain 118 kinds of text for very specialized purposes). Binary formats require 119 an application to be coded specifically to handle the format; no 120 partial interoperability is possible. Furthermore, if even one byte 121 or bit are corrupted in a binary format, it may prevent an 122 application from processing any of the data correctly. 124 Between these two extremes lies formatted text, i.e., text that 125 includes non-textual information coded in a particular way, that 126 affects the interpretation of the text by computer programs. 127 Formatted text is distinct from plain text and binary format in that 128 the non-textual information is encoded into textual characters, which 129 are assigned specialized meanings /not/ defined by the character set. 130 With a regular text editor and a standard keyboard (or other standard 131 input mechanism), a user can enter these textual characters to 132 express the non-textual meanings. For example, a character like "<" 133 no longer means "LESS-THAN SIGN"; it means the start of a tag or 134 element that affects the document in some way. 136 On the formal end of the spectrum is markup, a family of languages 137 for annotating a document in such a way that the annotations are 138 syntactically distinguishable from the text. Markup languages are 139 (reasonably) well-specified and tend to follow (mostly) standardized 140 syntax rules. Examples of markup languages include SGML, HTML, XML, 141 and LaTeX. Standardized rules lead to interoperability between markup 142 processors, but a skill requirement for new (human) users of the 143 language that they learn these rules in order to do useful work. This 144 imposition makes markup less accessible for non-technical users 145 (i.e., users who are unwilling or unable to invest in the requisite 146 skill development). 148 informal /---------formatted text----------\ formal 149 <------v-------------v-------------v-----------------------v----> 150 plain text informal markup formal markup binary format 151 (Markdown) (HTML, XML, etc.) 153 Figure 1: Degrees of Formality in Data Storage Formats for Text 155 On the informal end of the spectrum are lightweight markup languages. 156 In comparison with formal markup like XML, lightweight markup uses 157 simple syntax, and is designed to be easy for humans to enter with 158 basic text editors. Markdown, the subject of this document, is an 159 /informal/ plain text formatting syntax that is intentionally 160 targeted at non-technical users (i.e., users upon whom little to no 161 skill development is imposed) using unspecialized tools (i.e., text 162 boxes). Jeff Atwood once described these informal markup languages as 163 "humane" [HUMANE]. 165 1.2. Markdown Design Philosophy 167 Markdown specifically is a family of syntaxes that are based on the 168 original work of John Gruber with substantial contributions from 169 Aaron Swartz, released in 2004 [MARKDOWN]. Since its release a number 170 of web or web-facing applications have incorporated Markdown into 171 their text entry systems, frequently with custom extensions. Fed up 172 with the complexity and security pitfalls of formal markup languages 173 (e.g., HTML5) and proprietary binary formats (e.g., commercial word 174 processing software), yet unwilling to be confined to the 175 restrictions of plain text, many users have turned to Markdown for 176 document processing. Whole toolchains now exist to support Markdown 177 for online and offline projects. 179 Informality is a bedrock premise of Gruber's design. Gruber created 180 Markdown after disastrous experiences with strict XML and XHTML 181 processing of syndicated feeds. In Mark Pilgrim's "thought 182 experiment", several websites went down because one site included 183 invalid XHTML in a blog post, which was automatically copied via 184 trackbacks across other sites [DIN2MD]. These scenarios led Gruber to 185 believe that clients (e.g., web browsers) SHOULD try to make sense of 186 data that they receive, rather than rejecting data simply because it 187 fails to adhere to strict, unforgiving standards. (In [DIN2MD], 188 Gruber compared Postel's Law [RFC0793] with the XML standard, which 189 says: "Once a fatal error is detected [...] the processor MUST NOT 190 continue normal processing" [XML1.0-5].) As a result, there is no 191 such thing as "invalid" Markdown; there is no standard demanding 192 adherence to the Markdown syntax; there is no governing body that 193 guides or impedes its development. If the Markdown syntax does not 194 result in the "right" output (defined as output that the author 195 wants, not output that adheres to some dictated system of rules), 196 Gruber's view is that the author either should keep on experimenting, 197 or should change the processor to address the author's particular 198 needs (see [MARKDOWN] Readme and [MD102b8] perldoc; see also 199 [CATPICS]). 201 1.3. Uses of Markdown 203 Since its introduction in 2004, Markdown has enjoyed remarkable 204 success. Markdown works for users for three key reasons. First, the 205 markup instructions (in text) look similar to the markup that they 206 represent; therefore the cognitive burden to learn the syntax is low. 207 Second, the primary arbiter of the syntax's success is *running 208 code*. The tool that converts the Markdown to a presentable format, 209 and not a series of formal pronouncements by a standards body, is the 210 basis for whether syntactic elements matter. Third, Markdown has 211 become something of an Internet meme [INETMEME], in that Markdown 212 gets received, reinterpreted, and reworked as additional communities 213 encounter it. There are communities that are using Markdown for 214 scholarly writing [CITE], for screenplays [FOUNTAIN], for 215 mathematical formulae [CITE], and even for music annotation [CITE]. 216 Clearly, a screenwriter has no use for specialized Markdown syntax 217 for mathematicians; likewise, mathematicians do not need to identify 218 characters or props in common ways. The overall gist is that all of 219 these communities can take the common elements of Markdown (which are 220 rooted in the common elements of HTML circa 2004) and build on them 221 in ways that best fit their needs. 223 1.4. Uses of Labeling Markdown Content as text/markdown 225 The primary purpose of an Internet media type is to label "content" 226 on the Internet, as distinct from "files". Content is any computer- 227 readable format that can be represented as a primary sequence of 228 octets, along with type-specific metadata (parameters) and type- 229 agnostic metadata (protocol dependent). From this description, it is 230 apparent that appending ".markdown" to the end of a filename is not a 231 sufficient means to identify Markdown. Filenames are properties of 232 files in file systems, but Markdown frequently exists in databases or 233 content management systems (CMSes) where the file metaphor does not 234 apply. One CMS [RAILFROG] uses media types to select appropriate 235 processing, so a media type is necessary for the safe and 236 interoperable use of Markdown. 238 Unlike complete HTML documents, [MDSYNTAX] provides no means to 239 include metadata into the content stream. Several derivative flavors 240 have invented metadata incorporation schemes (e.g., [MULTIMD]), but 241 these schemes only address specific use cases. In general, the 242 metadata must be supplied via supplementary means in an encapsulating 243 protocol, format, or convention. The relationship between the content 244 and the metadata is not directly addressed here or in [MDMTREG]; 245 however, by identifying Markdown with a media type, Markdown content 246 can participate as a first-class citizen with a wide spectrum of 247 metadata schemes. 249 Finally, registering a media type through the IETF process is not 250 trivial. Markdown can no longer be considered a "vendor"-specific 251 innovation, but the registration requirements even in the vendor tree 252 have proven to be overly burdensome for most Markdown implementers. 253 Moreover, registering hundreds of Markdown variants with distinct 254 media types would impede interoperability: virtually all Markdown 255 content can be processed by virtually any Markdown processor, with 256 varying degrees of success. The goal of [MDMTREG] is to reduce all of 257 these burdens by having one media type that accommodates diversity 258 and eases registration. 260 2. Strategies for Preserving Media Type and Parameters 262 The purpose of this document and [MDMTREG] is to promote 263 interoperability between different Markdown-related systems, 264 preserving the author's intent. While [MARKDOWN] was designed by 265 Gruber in 2004 as a simple way to write blog posts and comments, as 266 of 2014 Markdown and its derivatives are rapidly becoming the formats 267 of record for many communities and use cases. While an individual 268 member of (or software tool for) a community can probably look at 269 some "Markdown" and declare its meaning intuitively obvious, software 270 systems in different communities (or different times) need help. 271 [MDSYNTAX] does not have a signaling mechanism like , so 272 tagging Markdown internally is simply out of the question. Once tags 273 or metadata are introduced, the content is no longer "just" Markdown. 275 Some commentators have suggested that an in-band signaling mechanism, 276 such as in Markdown link definitions at the top of the content, could 277 be used to signal the variant. Unfortunately this signaling mechanism 278 is incompatible with other Markdown variants (e.g., [PANDOC]) that 279 expect their own kinds of metadata at the top of the file. Markdown 280 content is just a stream of text; the semantics of that text can only 281 be furnished by context. 283 The media type and variant parameter in [MDMTREG] furnish this 284 missing context, while allowing for additional extensibility. This 285 section covers strategies for how an application might preserve 286 metadata when it leaves the domain of IETF protocols. 288 [MDMTREG] (draft-05) only defines two parameters: the charset 289 parameter (required for all text/* media types) and the variant 290 parameter. Character set interoperability is well-studied territory 291 [NB: CITE?] and so is not further covered here. The variant parameter 292 provides a simple identifier--nothing less or more. Variants are 293 allowed to define additional parameters when sent with the 294 text/markdown media type; the variant can also introduce control 295 information into the textual content stream (such as via a metadata 296 block). Neither [MDMTREG] nor this specification recommend any 297 particular approach. However, the philosophy behind [MDMTREG] is to 298 preserve formats rather than create new ones, since supporting 299 existing toolchains is more realistic than creating novel ones that 300 lack traction in the Markdown community. 302 2.1. Map to Filename and Attributes 304 This strategy is to map the media type, variant, and parameters to 305 "attributes" or "forks" in the local convention. Firstly, Markdown 306 content saved to a file should have an appropriate file extension 307 ending in .md or .markdown, which serves to disambiguate it from 308 other kinds of files. The character repertoire of variant identifiers 309 in [MDMTREG] is designed to be compatible with most filename 310 conventions. Therefore, a recommended strategy is to record the 311 variant identifier as the prefix to the file extension. For example, 312 for [PANDOC] content, a file could be named 313 "example.pandoc.markdown". 315 Many filesystems are case-sensitive or case-preserving; however, file 316 extensions tend to be all-lowercase. This document takes no position 317 on whether variant identifiers should be case-preserved or all- 318 lowercase when Markdown content is written to a file. However, when 319 the variant identifier is read to influence operational behavior, it 320 needs to be compared case-insensitively. 322 Many modern filesystems support "extended attributes", "alternate 323 data streams", or "resource forks". Some version control systems 324 support named properties. If the variant defines additional 325 parameters, these parameters should be stored in these resources, 326 where the parameter name includes the name of the resource, and the 327 parameter value is the value of the resource (data in the resource), 328 preferably UTF-8 encoded (unless the parameter definition explicitly 329 defines a different encoding or repertoire). The variant identifier 330 itself should be stored in a resource with a name including the term 331 "variant". 333 2.2. Store Headers in Adjacent File 335 This strategy is to save the Markdown content in a first file, and to 336 save the metadata (specifically the Content-Type: header) in a second 337 file with a filename that is rationally related to the first 338 filename. For example, if the first file is named "readme.markdown", 339 the second file could be named "readme.markdown.headers". (If stored 340 in a database, the analogy would be to store the metadata in a second 341 table with a field that is a key to the first table.) This header 342 file has the media type "message/global-headers" [RFC6533] (".u8hdr" 343 suggestion notwithstanding). 345 2.3. "Arm" Content with MIME Headers 347 This strategy is to save the Markdown content along with its headers 348 in a file, "arming" the content by prepending the MIME headers 349 (specifically the Content-Type: header). It should be appreciated 350 that the file is no longer a "Markdown file"; rather, it is an 351 Internet Message Format file (e.g., [RFC5322]) with a Markdown 352 content part. Therefore, the file should have an Internet message 353 extension (e.g., ".eml", ".msg", or ".u8msg"), not a Markdown 354 extension (e.g., ".md" or ".markdown"). 356 2.4. Create a Local Batch Script 358 This strategy is to translate the processing instructions inferred 359 from the Content-Type and other parameters (e.g., Content- 360 Disposition) into a sequence of commands in the local convention, 361 storing those commands in a batch script. For example, when a MIME- 362 aware client stores some Markdown to disk, the client can save a 363 Makefile in the same directory with commands that are appropriate 364 (and safe) for the local system. 366 2.5. Process the Markdown 368 This strategy is to process the Markdown into the formal markup, 369 which eliminates ambiguities. Once the Markdown is processed into 370 (for example) valid XHTML, an application can save a file as 371 "doc.xhtml" with no further loss of metadata. While unambiguous, this 372 process may not be reversible. 374 2.6. Rely on Context 376 This last strategy is to use or create context to determine how to 377 interpret the Markdown. For example, Markdown content that is of the 378 Fountain.io type [FOUNTAIN] could be saved with the filename 379 "script.fountain" instead of "script.markdown". Alternatively, 380 scripts could be stored in a "/screenplays" directory while other 381 kinds of Markdown could be stored elsewhere. For reasons that should 382 be intuitively obvious, this method is the most error-prone. 383 "Context" can be easily lost over time, and the trend of passing 384 Markdown between systems--taking them *out* of context--is 385 increasing. 387 2.7. Specific Strategies 389 2.7.1. Subversion 391 This subsection covers a preservation strategy in Subversion [SVN], a 392 common client-server version control system. 394 Subversion supports named properties. The "svn:mime-type" property 395 duplicates the entire Content-Type header, so parameters SHOULD be 396 stored there. The filename SHOULD be consistent with this Content- 397 Type header, i.e., the extension SHOULD be the variant identifier 398 plus ".markdown". 400 [[TODO: Versions of Subversion after [[1.x]] treat svn:mime-type as 401 UTF-8 encoded, rather than US-ASCII. (See [RFC6532].) Therefore, the 402 encoding of [RFC2231] will not be necessary in the vast majority of 403 cases in newer versions. However, both for backwards compatibility 404 and for support for non-Unicode character sets, [RFC2231] still needs 405 to be supported.]] 407 [[TODO: Where to store Content-Disposition?]] 409 2.7.2. Git 411 This subsection covers a preservation strategy in Git [GIT], a common 412 distributed version control system. 414 Versions of Git as of the time of this writing do not support 415 arbitrary metadata storage; however, third-party projects add this 416 support. 418 If Git is used without a metadata storage service, then a reasonable 419 strategy is to include the variant identifier in the filename. The 420 encoding of the file should be transcoded to UTF-8. For other 421 properties, a header file should be recorded alongside the Markdown 422 file in accordance with Section 2.2. The contents of the header file 423 should be consistent with the rest of this paragraph, i.e., the 424 charset parameter should be "UTF-8" and the variant parameter should 425 match the identifier in the filename. 427 If a metadata storage service is used with Git, then use a convention 428 that is most analogous to the service. For example, the "metastore" 429 project emulates extended attributes (xattrs) of a POSIX-like system, 430 so whatever "xattr" methodology is developed would be usable with 431 metastore and Git. 433 3. Registration Templates for Common Markdown Syntaxes 435 The purpose of this section is to register certain syntaxes in the 436 Markdown Syntaxes Registry [MDMTREG] because they illustrate 437 particularly interesting use cases or are broadly applicable to the 438 Internet community; thus, these syntaxes would benefit from the level 439 of review associated with publication as IETF documents. 441 3.1. MultiMarkdown 443 Identifier: MultiMarkdown 445 Name: MultiMarkdown 447 Description: 448 MultiMarkdown (MMD) is a superset of "Original". It adds multiple 449 syntax features (tables, footnotes, and citations, to name a few), 450 and is intended to output to various formats. Additionally, it builds 451 in "smart" typography for various languages (proper left- and right- 452 sided quotes, for example). 454 Additional Parameters: 455 options: String with zero or more of the following WSP-delimited 456 tokens: 458 "memoir" / "beamer" 459 "full" / "snippet" 460 "process-html" 461 "random-footnote-identifiers" 462 "accept" 463 "reject" 464 "nosmart" 465 "nonotes" 466 "nolabels" 467 "nomask" 469 The meanings of these tokens are defined in the 470 MultiMarkdown documentation. 472 References: 473 475 Contact Information: 476 (individual) Fletcher T. Penney 477 479 3.2. GitHub Flavored Markdown 480 Identifier: GFM 482 Name: GitHub Flavored Markdown 484 Description: 485 "Original" with the following differences: 486 1. Multiple underscores in words 487 2. URL (URI) autolinking 488 3. Strikethrough 489 4. Fenced code blocks 490 5. Syntax highlighting 491 6. Tables (- for rows; | for columns; : for alignment) 492 7. Only some HTML allowed; sanitization is integral 493 to the format 495 References: 496 497 499 Contact Information: 500 (corporate) GitHub, Inc. 501 [[Vicent Marti ??]] 503 3.3. Pandoc 505 Identifier: pandoc 507 Name: Pandoc 509 Description: 510 Markdown is designed to be easy to write and to read: the content 511 should be publishable as-is, as plain text, without looking like it 512 has been marked up with tags or formatting instructions. Yet whereas 513 "Original" has HTML generation in mind, pandoc is designed for 514 multiple output formats. Thus, while pandoc allows the embedding of 515 raw HTML, it discourages it, and provides other, non-HTMLish ways of 516 representing important document elements like definition lists, 517 tables, mathematics, and footnotes. 519 Additional Parameters: 520 extensions: String with an optional starting syntax token, followed 521 by a "+" and "-" delimited list of extension tokens. "+" 522 preceding an extension token turns the extension on; "-" 523 turns the extension off. The starting syntax tokens are 524 "markdown", "markdown_strict", "markdown_phpextra", and 525 "markdown_github". If no starting syntax token is given, 526 "markdown" is assumed. The extension tokens include: 528 [[Stuff to turn off:]] 530 escaped_line_breaks 531 blank_before_header 532 header_attributes 533 auto_identifiers 534 implicit_header_references 535 blank_before_blockquote 536 fenced_code_blocks 537 fenced_code_attributes 538 line_blocks 539 fancy_lists 540 startnum 541 definition_lists 542 example_lists 543 table_captions 544 simple_tables 545 multiline_tables 546 grid_tables 547 pipe_tables 548 pandoc_title_block 549 yaml_metadata_block 550 all_symbols_escapable 551 intraword_underscores 552 strikeout 553 superscript 554 subscript 555 inline_code_attributes 556 tex_math_dollars 557 raw_html 558 markdown_in_html_blocks 559 native_divs 560 native_spans 561 raw_tex 562 latex_macros 563 implicit_figures 564 footnotes 565 inline_notes 566 citations 568 [[New stuff:]] 570 lists_without_preceding_blankline 571 hard_line_breaks 572 ignore_line_breaks 573 tex_math_single_backslash 574 tex_match_double_backslash 575 markdown_attribute 576 mmd_title_block 577 abbreviations 578 autolink_bare_uris 579 ascii_identifiers 580 link_attributes 581 mmd_header_identifiers 582 compact_definition_lists 584 Fragment Identifiers: 585 Pandoc defines fragment identifiers using the in the 586 {# .class ...} production (PHP Markdown Extra attribute block). 587 This syntax works for Header Identifiers and Code Block Identifiers. 589 References: 590 592 Contact Information: 593 (individual) Prof. John MacFarlane 594 596 3.4. Fountain (Fountain.io) 598 Identifier: Fountain 600 Name: Fountain 602 Description: 603 Fountain is a simple markup syntax for writing, editing and sharing 604 screenplays in plain, human-readable text. Fountain allows you to 605 work on your screenplay anywhere, on any computer or tablet, using 606 any software that edits text files. 608 Fragment Identifiers: 609 See and 610 . In the following 611 fragment identifiers, the and productions MUST have "/" 612 characters percent-encoded. 614 #/ Title Page (acts as metadata). 615 #/ Title Page; is the key string. 616 # *("/" ) 617 Section or subsection. The .. 618 productions are the text of the Section line, 619 with whitespace trimmed from both ends. 620 Sub-sections (sections with multiple # at 621 at the beginning of the line in the source) 622 are addressed hierarchically by preceding 623 the sub-section with higher-order 624 sections. If the section hierarchy "skips", 625 e.g., # to ###, use a blank section name, 626 e.g., #Section/ACT%20I//PATIO%20SCENE. 628 References: 629 631 Contact Information: 632 (individual) Stu Maschwitz 633 (individual) John August 635 3.5. CommonMark 637 Identifier: CommonMark 639 Name: CommonMark 641 Description: 642 CommonMark is a standard, unambiguous syntax specification for 643 Markdown, along with a suite of comprehensive tests to validate 644 Markdown implementations against this specification. The maintainers 645 believe that CommonMark is necessary, even essential, for the future 646 of Markdown. 648 Compared to "Original", CommonMark is much longer and in a few 649 instances contradicts "Original" based on seasoned experience. 650 Although CommonMark specifically does not mandate any particular 651 encoding for the input content, CommonMark draws in more of Unicode, 652 UTF-8, and HTML (including HTML5) than "Original". 654 This registration always refers to the latest version or an 655 unspecified version (receiver's choice). Version 0.13 of the 656 CommonMark specification was released 2014-12-10. 658 References: 659 661 Contact Information: 662 (individual) John MacFarlane 663 (individual) David Greenspan 664 (individual) Vicent Marti 665 (individual) Neil Williams 666 (individual) Benjamin Dumke-von der Ehe 667 (individual) Jeff Atwood 669 3.6. kramdown-rfc2629 (Markdown for RFCs) 671 Identifier: kramdown-rfc2629 672 Name: Markdown for RFCs 674 Description: 675 kramdown is a markdown parser by Thomas Leitner, which has a number 676 of backends for generating HTML, Latex, and Markdown again. kramdown- 677 rfc2629 is an additional backend to that: It allows the generation of 678 XML2RFC XML markup (also known as RFC 2629 compliant markup). 680 References: 681 683 Contact Information: 684 (individual) Carsten Bormann 686 3.7. rfc7328 (Pandoc2rfc) 688 Identifier: rfc7328 690 Name: Pandoc2rfc 692 Description: 693 Pandoc2rfc allows authors to write in "pandoc" that is then 694 transformed to XML and given to xml2rfc. The conversions are, in a 695 way, amusing, as we start off with (almost) plain text, use elaborate 696 XML, and end up with plain text again. 698 References: 699 RFC 7328 700 702 Contact Information: 703 (individual) R. (Miek) Gieben 705 3.8. PHP Markdown Extra 707 Identifier: Extra 709 Name: Markdown Extra 711 Description: 712 Markdown Extra is an extension to PHP Markdown implementing some 713 features currently not available with the plain Markdown syntax. 714 Markdown Extra is available as a separate parser class in PHP 715 Markdown Lib. Other implementations include Maruku (Ruby) and Python 716 Markdown. Markdown Extra is supported in several content management 717 systems, including Drupal, TYPO3, and MediaWiki. 719 Fragment Identifiers: 720 Markdown Extra defines fragment identifiers using the in the 721 {# .class ...} production (attribute block). This syntax works 722 for headers, fenced code blocks, links, and images. 724 References: 725 727 Contact Information: 728 (individual) Michel Fortin 730 4. Examples for Common Markdown Syntaxes 732 This section provides examples of the variants registered in Appendix 733 C. 735 4.1. MultiMarkdown 737 4.2. GitHub Flavored Markdown 739 4.3. Pandoc 741 4.4. Fountain (Fountain.io) 743 4.5. CommonMark 745 4.6. kramdown-rfc2629 (Markdown for RFCs) 747 4.7. rfc7328 (Pandoc2rfc) 749 [[TODO: complete.]] 751 5. IANA Considerations 753 IANA is asked to register the syntaxes specified in Section 3 in the 754 Markdown Variants Registry. 756 6. Security Considerations 758 See the respective syntax descriptions and output media type 759 registrations for their respective security considerations. 761 7. References 763 7.1. Normative References 765 [MARKDOWN] Gruber, J., "Daring Fireball: Markdown", December 2004, 766 . 768 [MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax 769 Documentation", December 2004, 770 . 772 [MDMTREG] Leonard, S., "The text/markdown Media Type", draft-ietf- 773 appsawg-text-markdown-03 (work in progress), October 2014. 775 [RFC5147] Wilde, E. and M. Duerst, "URI Fragment Identifiers for the 776 text/plain Media Type", RFC 5147, April 2008. 778 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 779 October 2008. 781 7.2. Informative References 783 [HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", May 2008, 784 . 787 [DIN2MD] Gruber, J., "Dive Into Markdown", March 2004, 788 . 790 [MD102b8] Gruber, J., "[ANN] Markdown.pl 1.0.2b8", May 2007, 791 , . 795 [CATPICS] Gruber, J. and M. Arment, "The Talk Show: Ep. 88: 'Cat 796 Pictures' (Side 1)", July 2014, 797 . 799 [INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of 800 the word 'meme'", June 2013, 801 , . 804 [MULTIMD] Penney, F., "MultiMarkdown", April 2014, 805 . 807 [PANDOC] MacFarlane, J., "Pandoc", 2014, 808 . 810 [RAILFROG] Railfrog Team, "Railfrog", April 2009, 811 . 813 [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 814 793, September 1981. 816 [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded 817 Word Extensions: Character Sets, Languages, and 818 Continuations", RFC 2231, November 1997. 820 [RFC4263] Lilly, B., "Media Subtype Registration for Media Type 821 text/troff", RFC 4263, January 2006. 823 [RFC6533] Hansen, T., Ed., Newman, C. and A. Melnikov, 824 "Internationalized Delivery Status and Disposition 825 Notifications", RFC 6533, February 2012. 827 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 828 Specifications and Registration Procedures", BCP 13, RFC 829 6838, January 2013. 831 [XML1.0-5] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 832 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 833 Edition)", World Wide Web Consortium Recommendation REC- 834 xml-20081126, November 2008, 835 . 837 [FOUNTAIN] Maschwitz, S. and J. August, "Fountain | A markup language 838 for screenwriting.", 2014, . 840 [FTSYNTAX] Maschwitz, S. and J. August, "Syntax - Fountain | A markup 841 language for screenwriting.", 1.1, March 2014, 842 . 844 [SVN] Apache Subversion, December 2014, 845 . 847 [GIT] Git, December 2014, . 849 Author's Address 851 Sean Leonard 852 Penango, Inc. 853 5900 Wilshire Boulevard 854 21st Floor 855 Los Angeles, CA 90036 856 USA 858 EMail: dev+ietf@seantek.com 859 URI: http://www.penango.com/