idnits 2.17.1 draft-seantek-text-markdown-media-type-00.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: ---------------------------------------------------------------------------- == Mismatching filename: the document gives the document name as 'draft-seantek-text-markdown-00', but the file name used is 'draft-seantek-text-markdown-media-type-00' Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 101 has weird spacing: '... markup form...' == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- The document date (July 4, 2014) is 3583 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). 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 July 4, 2014 5 Expires: January 5, 2015 7 The text/markdown Media Type 8 draft-seantek-text-markdown-00.txt 10 Abstract 12 This document registers the text/markdown media type for use with 13 Markdown, a family of plain text formatting syntaxes that optionally 14 can be converted to formal markup languages such as HTML. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 Copyright Notice 33 Copyright (c) 2014 IETF Trust and the persons identified as the 34 document authors. All rights reserved. 36 This document is subject to BCP 78 and the IETF Trust's Legal 37 Provisions Relating to IETF Documents 38 (http://trustee.ietf.org/license-info) in effect on the date of 39 publication of this document. Please review these documents 40 carefully, as they describe your rights and restrictions with respect 41 to this document. Code Components extracted from this document must 42 include Simplified BSD License text as described in Section 4.e of 43 the Trust Legal Provisions and are provided without warranty as 44 described in the Simplified BSD License. 46 1. Introduction 48 In computer systems, textual data is stored and processed using a 49 continuum of techniques. On the one end is plain text: a linear 50 sequence of characters in some character set (code), possibly 51 interrupted by line breaks, page breaks, or other control characters. 52 Plain text provides /some/ fixed facilities for formatting 53 instructions, namely codes in the character set that have meanings 54 other than "represent this character on the output medium"; however, 55 these facilities are not particularly extensible. Compare with 56 [RFC6838] Section 4.2.1. (Applications may neuter the effects of 57 these special characters by prohibiting them or by ignoring their 58 dictated meanings, as is the case with how modern applications treat 59 most control characters in US-ASCII.) On this end, any text reader or 60 editor that interprets the character set can be used to see or 61 manipulate the text. If some characters are corrupted, the corruption 62 is unlikely to affect the ability of a computer system to process the 63 text (even if the human meaning is changed). 65 On the other end is binary format: a sequence of instructions 66 intended for some computer application to interpret and act upon. 67 Binary formats are flexible in that they can store non-textual data 68 efficiently (perhaps storing no text at all, or only storing certain 69 kinds of text for very specialized purposes). Binary formats require 70 an application to be coded specifically to handle the format; no 71 partial interoperability is possible. Furthermore, if even one byte 72 or bit are corrupted in a binary format, it may prevent an 73 application from processing any of the data correctly. 75 Between these two extremes lies formatted text, i.e., text that 76 includes non-textual information coded in a particular way, that 77 affects the interpretation of the text by computer programs. 78 Formatted text is distinct from plain text and binary format in that 79 the non-textual information is encoded into textual characters, which 80 are assigned specialized meanings /not/ defined by the character set. 81 With a regular text editor and a standard keyboard (or other standard 82 input mechanism), a user can enter these textual characters to 83 express the non-textual meanings. For example, a character like "<" 84 no longer means "LESS-THAN SIGN"; it means the start of a tag or 85 element that affects the document in some way. 87 On the formal end of the spectrum is markup, a family of languages 88 for annotating a document in such a way that the annotations are 89 syntactically distinguishable from the text. Markup languages are 90 (reasonably) well-specified and tend to follow (mostly) standardized 91 syntax rules. Examples of markup languages include SGML, HTML, XML, 92 and LaTeX. Standardized rules lead to interoperability between markup 93 processors, but a skill requirement for new (human) users of the 94 language that they learn these rules in order to do useful work. This 95 imposition makes markup less accessible for non-technical users 96 (i.e., users who are unwilling or unable to invest in the requisite 97 skill development). 99 informal /---------formatted text----------\ formal 100 <------v-------------v-------------v-----------------------v----> 101 plain text informal markup formal markup binary format 102 (Markdown) (HTML, XML, etc.) 104 Figure 1: Degrees of Formality in Data Storage Formats for Text 106 On the informal end of the spectrum are lightweight markup languages. 107 In comparison with formal markup like XML, lightweight markup uses 108 simple syntax, and is designed to be easy for humans to enter with 109 basic text editors. Markdown, the subject of this document, is an 110 /informal/ plain text formatting syntax that is intentionally 111 targeted at non-technical users (i.e., users upon whom little to no 112 skill development is imposed) using unspecialized tools (i.e., text 113 boxes). Jeff Atwood once described these informal markup languages as 114 /humane/.[HUMANE] 116 Markdown specifically is a family of syntaxes that are based on the 117 original work of John Gruber with substantial contributions from 118 Aaron Swartz, released in 2004.[MARKDOWN] Since its release a number 119 of web or web-facing applications have incorporated Markdown into 120 their text entry systems, frequently with proprietary extensions. Fed 121 up with the complexity and security pitfalls of formal markup 122 languages (e.g., HTML5) and proprietary binary formats (e.g., 123 commercial word processing software), yet unwilling to be confined to 124 the restrictions of plain text, many users have turned to Markdown 125 for document processing. Whole toolchains now exist to support 126 Markdown for online and offline projects. 128 Due to Markdown's intentional informality, there is no standard 129 specifying the Markdown syntax, and no governing body that guides or 130 impedes its development. Markdown works for users for two key 131 reasons. First, the markup instructions (in text) look similar to the 132 markup that they represent; therefore the cognitive burden to learn 133 the syntax is very low. Second, the primary arbiter of the syntax's 134 success is *running code*. The tool that converts the Markdown to a 135 presentable format, and not a series of formal pronouncements by a 136 standards body, is the basis for whether syntactic elements matter. 138 To support identifying and conveying Markdown (as distinguished from 139 plain text), this document defines a media type and a "flavor" 140 parameter that indicates, in broad strokes, the author's intent on 141 how to interpret the Markdown. 143 1.1. Requirements Terminology 145 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 146 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 147 document are to be interpreted as described in [RFC2119]. 149 2. Markdown Media Type Registration Applications 151 This section provides the media type registration application for the 152 text/markdown media type (see [RFC6838], Section 5.6). 154 Type name: text 156 Subtype name: markdown 158 Required parameters: charset. Per Section 4.2.1 of [RFC6838], charset 159 is REQUIRED. The default value is UTF-8. If omitted, parsers MAY 160 reject the input; if parsers accept the input, they MUST interpret 161 the content as UTF-8. 163 Optional parameters: 165 flavor=f; where f is an identifier that specifies the "flavor", or 166 variation, of the Markdown syntax. The parameter represents the 167 intent of the author, namely, that the Markdown will be interpreted 168 "best" (i.e., as the author intended) when processed with tools 169 associated with the identified flavor. 171 The flavor parameter is opaque and case-sensitive. Valid flavor 172 values can be any sequence of characters or bytes; in practice, 173 however, virtually all will be alphanumeric (US-ASCII) and 174 registered in the IANA Markdown Flavors Registry, discussed in 175 Section 4. Implementations checking flavor parameters MUST only 176 compare them for exact equality. 178 Encoding considerations: Text. 180 Security considerations: 182 Markdown interpreted as plain text is relatively harmless. A text 183 editor need only display the text. The editor SHOULD take care to 184 handle control characters appropriately, and to limit the effect of 185 the Markdown to the text editing area itself; malicious Unicode- 186 based Markdown could, for example, surreptitiously change the 187 directionality of the text. An editor for normal text would already 188 take these control characters into consideration, however. 190 Markdown interpreted as a precursor to other formats, such as HTML, 191 carry all of the security considerations as the target formats. For 192 example, HTML can contain instructions to execute scripts, redirect 193 the user to other webpages, download remote content, and upload 194 personally identifiable information. Markdown also can contain 195 islands of formal markup, such as HTML. These islands of formal 196 markup may be passed as-is, transformed, or ignored (perhaps 197 because the islands are conditional or incompatible) when the 198 Markdown is interpreted into the target format. Since Markdown may 199 have different interpretations depending on the tool and the 200 environment, a better approach is to analyze (and sanitize or 201 block) the output markup, rather than attempting to analyze the 202 Markdown. 204 Interoperability considerations: 206 Markdown flavors are designed to be broadly compatible with humans 207 ("humane"), but not necessarily with each other. Therefore, syntax 208 in one Markdown flavor may be ignored or treated differently in 209 another flavor. The overall effect is a general degradation of the 210 output, proportional to the quantity of flavor-specific Markdown 211 used in the text. When it is desirable to reflect the author's 212 intent in the output, stick with the flavor identified in the 213 flavor parameter. 215 Published specification: This specification. 217 Applications that use this media type: 219 Markdown conversion tools, Markdown WYSIWYG editors, and plain text 220 editors and viewers; target markup processors indirectly use 221 Markdown (e.g., web browsers for Markdown converted to HTML). 223 Additional information: 225 Magic number(s): None 226 File extension(s): .md, .markdown 227 Macintosh File Type Code(s): TEXT 229 Person & email address to contact for further information: 231 Sean Leonard 233 Restrictions on usage: None. 235 Author: Sean Leonard 237 Intended usage: COMMON 238 Change controller: The IESG 240 3. Example 242 The following is an example of Markdown as an e-mail attachment: 244 MIME-Version: 1.0 245 Content-Type: text/markdown; charset=UTF-8; flavor=GitHub 246 Content-Disposition: attachment; filename=readme.md 248 Sample GitHub Markdown 249 ============= 251 This is some sample GitHub Flavored Markdown (*GFM*). 252 The generated HTML is then run through filters in the 253 [html-pipeline](https://github.com/jch/html-pipeline) 254 to perform things like [sanitization](#html-sanitization) and 255 [syntax highlighting](#syntax-highlighting). 257 Bulleted Lists 258 ------- 260 Here are some bulleted lists... 262 * One Potato 263 * Two Potato 264 * Three Potato 266 - One Tomato 267 - Two Tomato 268 - Three Tomato 270 More Information 271 ----------- 273 [.markdown, .md](http://daringfireball.net/projects/markdown/) 274 has more information. 276 4. IANA Considerations 278 IANA is asked to register the media type text/markdown in the 279 Standards tree using the application provided in Section 2 of this 280 document. 282 IANA is also asked to establish a subtype registry called "Markdown 283 Flavors". Entries in these registries is by Expert Review [RFC5226]. 284 The Expert will determine whether the registration represents a bona- 285 fide variation of the Markdown syntax (i.e., neither a duplicate of 286 an existing registration nor a syntax that is something other than 287 Markdown; [MARKDOWN] SHALL be treated as a normative basis), a brief 288 description, one or more responsible parties, whether the flavor is 289 being maintained at the time of registration, and the existence of at 290 least one complete tool (with or without documentation) that 291 processes the Markdown syntax into a formal document language. 293 A responsible party can be an individual author or maintainer, a 294 corporate author or maintainer (plus an individual contact), or a 295 representative of a community of interest dedicated to the Markdown 296 syntax. 298 The registry shall have one initial value, "Standard", with the 299 following data: 301 Description: 302 The Markdown syntax as it exists in the Markdown 1.0.1 Perl script 303 at , with accompanying 304 documentation at 305 . 307 Responsible Parties: 308 (individual) 309 John Gruber 310 312 Currently Maintained? No 314 Tool: 315 Name: Markdown 1.0.1 316 Reference: 317 Purpose: Converts to HTML or XHTML circa 2004. 319 5. Security Considerations 321 See the answer to the Security Considerations template questions in 322 Section 2. 324 6. References 326 6.1. Normative References 328 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 329 Requirement Levels", BCP 14, RFC 2119, March 1997. 331 [RFC5226] Narten, T., and H. Alvestrand, "Guidelines for Writing an 332 IANA Considerations Section in RFCs", RFC 5226, May 2008. 334 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 335 Specifications and Registration Procedures", BCP 13, RFC 336 6838, January 2013. 338 6.2. Informative References 340 [HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", WWW 341 http://blog.codinghorror.com/is-html-a-humane-markup- 342 language/, May 2008. 344 [MARKDOWN] Gruber, J., "Daring Fireball: Markdown", WWW 345 http://daringfireball.net/projects/markdown/, December 346 2004. 348 Author's Address 350 Sean Leonard 351 Penango, Inc. 352 5900 Wilshire Boulevard 353 21st Floor 354 Los Angeles, CA 90036 355 USA 357 EMail: dev+ietf@seantek.com 358 URI: http://www.penango.com/