Internet Engineering Task Force (IETF) S. Leonard Request for Comments: 7764 Penango, Inc. Category: Informational March 2016 ISSN: 2070-1721
Internet Engineering Task Force (IETF) S. Leonard Request for Comments: 7764 Penango, Inc. Category: Informational March 2016 ISSN: 2070-1721
Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations
降价指南:设计理念、稳定性策略和选择注册
Abstract
摘要
This document elaborates upon the text/markdown media type for use with Markdown, a family of plain-text formatting syntaxes that optionally can be converted to formal markup languages such as HTML. Background information, local storage strategies, and additional syntax registrations are supplied.
本文档详细介绍了与markdown一起使用的文本/标记媒体类型,markdown是一系列纯文本格式语法,可以选择将其转换为HTML等正式标记语言。提供了背景信息、本地存储策略和其他语法注册。
Status of This Memo
关于下段备忘
This document is not an Internet Standards Track specification; it is published for informational purposes.
本文件不是互联网标准跟踪规范;它是为了提供信息而发布的。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are a candidate for any level of Internet Standard; see Section 2 of RFC 5741.
本文件是互联网工程任务组(IETF)的产品。它代表了IETF社区的共识。它已经接受了公众审查,并已被互联网工程指导小组(IESG)批准出版。并非IESG批准的所有文件都适用于任何级别的互联网标准;见RFC 5741第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7764.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息,请访问http://www.rfc-editor.org/info/rfc7764.
Copyright Notice
版权公告
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有(c)2016 IETF信托基金和确定为文件作者的人员。版权所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(http://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件,因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本,并提供简化BSD许可证中所述的无担保。
Table of Contents
目录
1. Dive into Markdown . . . . . . . . . . . . . . . . . . . . . . 3 1.1. On Formats . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Markdown Design Philosophy . . . . . . . . . . . . . . . . 4 1.3. Uses of Markdown . . . . . . . . . . . . . . . . . . . . . 5 1.4. Uses of Labeling Markdown Content as text/markdown . . . . 6 1.5. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Strategies for Preserving Media Type and Parameters . . . . . 7 2.1. Map to Filename and Attributes . . . . . . . . . . . . . . 7 2.2. Store Headers in Adjacent File . . . . . . . . . . . . . . 8 2.3. "Arm" Content with MIME Headers . . . . . . . . . . . . . . 8 2.4. Create a Local Batch Script . . . . . . . . . . . . . . . . 9 2.5. Process the Markdown in Advance . . . . . . . . . . . . . . 9 2.6. Rely on Context . . . . . . . . . . . . . . . . . . . . . . 9 2.7. Specific Strategies . . . . . . . . . . . . . . . . . . . . 9 2.7.1. Subversion . . . . . . . . . . . . . . . . . . . . . . 9 2.7.2. Git . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Registration Templates for Common Markdown Syntaxes . . . . . 10 3.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 10 3.2. GitHub-Flavored Markdown . . . . . . . . . . . . . . . . . 11 3.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 14 3.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 14 3.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 15 3.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 16 3.8. PHP Markdown Extra . . . . . . . . . . . . . . . . . . . . 16 4. Examples for Common Markdown Syntaxes . . . . . . . . . . . . 17 4.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 17 4.2. GitHub Flavored Markdown . . . . . . . . . . . . . . . . . 18 4.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 20 4.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 21 4.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 22 4.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 25 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 26 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 7.1. Normative References . . . . . . . . . . . . . . . . . . . 26 7.2. Informative References . . . . . . . . . . . . . . . . . . 26 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 28
1. Dive into Markdown . . . . . . . . . . . . . . . . . . . . . . 3 1.1. On Formats . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Markdown Design Philosophy . . . . . . . . . . . . . . . . 4 1.3. Uses of Markdown . . . . . . . . . . . . . . . . . . . . . 5 1.4. Uses of Labeling Markdown Content as text/markdown . . . . 6 1.5. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 6 2. Strategies for Preserving Media Type and Parameters . . . . . 7 2.1. Map to Filename and Attributes . . . . . . . . . . . . . . 7 2.2. Store Headers in Adjacent File . . . . . . . . . . . . . . 8 2.3. "Arm" Content with MIME Headers . . . . . . . . . . . . . . 8 2.4. Create a Local Batch Script . . . . . . . . . . . . . . . . 9 2.5. Process the Markdown in Advance . . . . . . . . . . . . . . 9 2.6. Rely on Context . . . . . . . . . . . . . . . . . . . . . . 9 2.7. Specific Strategies . . . . . . . . . . . . . . . . . . . . 9 2.7.1. Subversion . . . . . . . . . . . . . . . . . . . . . . 9 2.7.2. Git . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3. Registration Templates for Common Markdown Syntaxes . . . . . 10 3.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 10 3.2. GitHub-Flavored Markdown . . . . . . . . . . . . . . . . . 11 3.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 14 3.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 14 3.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 15 3.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 16 3.8. PHP Markdown Extra . . . . . . . . . . . . . . . . . . . . 16 4. Examples for Common Markdown Syntaxes . . . . . . . . . . . . 17 4.1. MultiMarkdown . . . . . . . . . . . . . . . . . . . . . . . 17 4.2. GitHub Flavored Markdown . . . . . . . . . . . . . . . . . 18 4.3. Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.4. Fountain (Fountain.io) . . . . . . . . . . . . . . . . . . 20 4.5. CommonMark . . . . . . . . . . . . . . . . . . . . . . . . 21 4.6. kramdown-rfc2629 (Markdown for RFCs) . . . . . . . . . . . 22 4.7. rfc7328 (Pandoc2rfc) . . . . . . . . . . . . . . . . . . . 25 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 26 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26 7.1. Normative References . . . . . . . . . . . . . . . . . . . 26 7.2. Informative References . . . . . . . . . . . . . . . . . . 26 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 28
This document serves as an informational companion to [RFC7763], the text/markdown media type registration. It should be considered jointly with [RFC7763].
本文档是[RFC7763]的信息补充,即文本/标记媒体类型注册。应与[RFC7763]共同考虑。
"Sometimes the truth of a thing is not so much in the think of it, but in the feel of it." -- Stanley Kubrick
“有时候,一件事情的真相不在于它的思想,而在于它的感觉。”——斯坦利·库布里克
In computer systems, textual data is stored and processed using a continuum of techniques. On the one end is plain text: computer-encoded text that consists only of a sequence of code points from a given standard, with no other formatting or structural information [UNICODE]. Plain text provides /some/ fixed facilities for formatting instructions (namely, codes in the character set that have meanings other than "represent this character graphically on the output medium"); however, these facilities are not particularly extensible. Compare with Section 4.2.1 of [RFC6838]. Applications may neuter the effects of these special characters by prohibiting them or by ignoring their dictated meanings, as is the case with how modern applications treat most control characters in US-ASCII. On this end, any text reader or editor that interprets the character set can be used to see or manipulate the text. If some characters are corrupted, the corruption is unlikely to affect the ability of a computer system to process the text (even if the human meaning is changed).
在计算机系统中,文本数据是使用一系列技术存储和处理的。一端是纯文本:计算机编码的文本,仅由给定标准的一系列代码点组成,没有其他格式或结构信息[UNICODE]。纯文本为格式化指令提供了/某些/固定的功能(即字符集中的代码,其含义不同于“在输出介质上以图形方式表示此字符”);然而,这些设施不是特别可扩展的。与[RFC6838]第4.2.1节进行比较。应用程序可能会通过禁止这些特殊字符或忽略其指定含义来消除其影响,现代应用程序处理US-ASCII中大多数控制字符的情况就是如此。在这方面,任何解释字符集的文本阅读器或编辑器都可以用来查看或操作文本。如果某些字符已损坏,则损坏不太可能影响计算机系统处理文本的能力(即使人类的含义已更改)。
On the other end is binary data: a sequence of bits intended for some computer application to interpret and act upon. Binary formats are flexible in that they can store non-textual data efficiently (perhaps storing no text at all, or only storing certain kinds of text for very specialized purposes). Binary formats require an application to be coded specifically to handle the format; no partial interoperability is possible. Furthermore, if even one bit is corrupted in a binary format, it may prevent an application from processing any of the data correctly.
另一端是二进制数据:用于某些计算机应用程序进行解释和操作的位序列。二进制格式非常灵活,因为它们可以高效地存储非文本数据(可能根本不存储文本,或者仅存储某些类型的文本用于非常特殊的目的)。二进制格式要求对应用程序进行专门编码以处理该格式;不可能有部分互操作性。此外,即使二进制格式中有一位损坏,也可能会阻止应用程序正确处理任何数据。
Between these two extremes lies formatted text, i.e., text that includes non-textual information coded in a particular way, that affects the interpretation of the text by computer programs. Formatted text is distinct from plain text and binary data in that the non-textual information is encoded into textual characters that are assigned specialized meanings not defined by the character set. With a regular text editor and a standard keyboard (or other standard input mechanism), a user can enter these textual characters to express the non-textual meanings. For example, a character like "<"
在这两个极端之间是格式化文本,即包含以特定方式编码的非文本信息的文本,它影响计算机程序对文本的解释。格式化文本不同于纯文本和二进制数据,因为非文本信息被编码为文本字符,这些字符被赋予了字符集未定义的特殊含义。使用常规文本编辑器和标准键盘(或其他标准输入机制),用户可以输入这些文本字符来表达非文本含义。例如,像“<”这样的字符
no longer means "LESS-THAN SIGN"; it means the start of a tag or element that affects the document in some way.
不再表示“小于符号”;它表示以某种方式影响文档的标记或元素的开始。
On the formal end of the formatted text spectrum is markup, a family of languages for annotating a document in such a way that the annotations are syntactically distinguishable from the text. Markup languages are (reasonably) well-specified and tend to follow (mostly) standardized syntax rules. Examples of markup languages include Standard Generalized Markup Language (SGML), HTML, XML, and LaTeX. Standardized rules lead to interoperability between markup processors, but a skill requirement for new (human) users of the language that they learn these rules in order to do useful work. This imposition makes markup less accessible for non-technical users (i.e., users who are unwilling or unable to invest in the requisite skill development).
在格式化文本谱的正式端是标记,这是一个用于注释文档的语言家族,注释在语法上与文本是可区分的。标记语言(合理地)被很好地指定,并且倾向于遵循(大部分)标准化的语法规则。标记语言的示例包括标准通用标记语言(SGML)、HTML、XML和LaTeX。标准化规则导致标记处理器之间的互操作性,但对于语言的新(人类)用户来说,他们需要学习这些规则以完成有用的工作。这种强加使得非技术用户(即不愿意或无法投资于必要技能开发的用户)更难获得标记。
informal /---------formatted text----------\ formal <------v-------------v-------------v-----------------------v----> plain text informal markup formal markup binary format (Markdown) (HTML, XML, etc.)
informal /---------formatted text----------\ formal <------v-------------v-------------v-----------------------v----> plain text informal markup formal markup binary format (Markdown) (HTML, XML, etc.)
Figure 1: Degrees of Formality in Data-Storage Formats for Text
图1:文本数据存储格式的正式程度
On the informal end of the spectrum are lightweight markup languages. In comparison with formal markup like XML, lightweight markup uses simple syntax, and is designed to be easy for humans to enter with basic text editors. Markdown, the subject of this document, is an /informal/ plain-text formatting syntax that is intentionally targeted at non-technical users (i.e., users upon whom little to no skill development is imposed) using unspecialized tools (i.e., text boxes). Jeff Atwood once described these informal markup languages as "humane" [HUMANE].
轻量级标记语言处于非正式的一端。与XML等正式标记相比,轻量级标记使用简单的语法,并且设计为便于人类使用基本文本编辑器输入。Markdown是本文档的主题,是一种/非正式/纯文本格式语法,专门针对使用非专业工具(即文本框)的非技术用户(即几乎没有技能发展的用户)。Jeff Atwood曾将这些非正式标记语言描述为“人道的”[人道的]。
Markdown specifically is a family of syntaxes that are based on the original work of John Gruber with substantial contributions from Aaron Swartz, released in 2004 [MARKDOWN]. Since its release, a number of web or web-facing applications have incorporated Markdown into their text-entry systems, frequently with custom extensions. Fed up with the complexity and security pitfalls of formal markup languages (e.g., HTML5) and proprietary binary formats (e.g., commercial word-processing software), yet unwilling to be confined to the restrictions of plain text, many users have turned to Markdown for document processing. Whole toolchains now exist to support Markdown for online and offline projects.
Markdown是一个特别的语法家族,它基于John Gruber的原著,由Aaron Swartz在2004年发布的大量贡献[Markdown]。自发布以来,许多web或面向web的应用程序已将降价纳入其文本输入系统,通常带有自定义扩展。受够了形式化标记语言(如HTML5)和专有二进制格式(如商业文字处理软件)的复杂性和安全隐患,但又不愿意局限于纯文本的限制,许多用户已转向使用标记进行文档处理。整个工具链现在已经存在,以支持在线和离线项目的降价。
Informality is a bedrock premise of Gruber's design. Gruber created Markdown after disastrous experiences with strict XML and XHTML processing of syndicated feeds. In Mark Pilgrim's "thought experiment", several websites went down because one site included invalid XHTML in a blog post, which was automatically copied via trackbacks across other sites [DIN2MD]. These scenarios led Gruber to believe that clients (e.g., web browsers) SHOULD try to make sense of data that they receive, rather than rejecting data simply because it fails to adhere to strict, unforgiving standards. (In [DIN2MD], Gruber compared Postel's Law [RFC793] with the XML standard, which says: "Once a fatal error is detected [...] the processor MUST NOT continue normal processing" [XML1.0-5].) As a result, there is no such thing as "invalid" Markdown, there is no standard demanding adherence to the Markdown syntax, and there is no governing body that guides or impedes its development. If the Markdown syntax does not result in the "right" output (defined as output that the author wants, not output that adheres to some dictated system of rules), Gruber's view is that the author either should keep on experimenting or should change the processor to address the author's particular needs (see [MARKDOWN] Readme and [MD102b8] perldoc; see also [CATPICS]).
非正式是格鲁伯设计的基本前提。格鲁伯在经历了对联合提要进行严格的XML和XHTML处理的灾难性经历后,创造了降价。在MarkPilgrim的“思维实验”中,有几个网站因为一个网站在一篇博文中包含无效的XHTML而倒闭,而该博文是通过其他网站的trackback自动复制的[DIN2MD]。这些场景使Gruber相信客户端(例如web浏览器)应该尝试理解他们接收的数据,而不是仅仅因为数据没有遵守严格、不可原谅的标准而拒绝数据。(在[DIN2MD]中,Gruber将Postel定律[RFC793]与XML标准进行了比较,XML标准规定:“一旦检测到致命错误[…]处理器不得继续正常处理”[XML1.0-5])因此,不存在“无效”标记,也不存在要求遵守标记语法的标准,也没有任何管理机构指导或阻碍其发展。如果Markdown语法没有产生“正确”的输出(定义为作者想要的输出,而不是遵循某些规定的规则系统的输出),Gruber的观点是,作者应该继续试验,或者应该更改处理器以满足作者的特殊需要(参见[Markdown]自述和[MD102b8]perldoc;另见[CATPICS])。
Since its introduction in 2004, Markdown has enjoyed remarkable success. Markdown works for users for three key reasons. First, the markup instructions (in text) look similar to the markup that they represent; therefore, the cognitive burden to learn the syntax is low. Second, the primary arbiter of the syntax's success is *running code*. The tool that converts the Markdown to a presentable format, and not a series of formal pronouncements by a standards body, is the basis for whether syntactic elements matter. Third, Markdown has become something of an Internet meme [INETMEME], in that Markdown gets received, reinterpreted, and reworked as additional communities encounter it. There are communities that are using Markdown for scholarly writing [OCCASION], for screenplays [FOUNTAIN], and even for mathematical formulae [MATHDOWN]. Clearly, a screenwriter has no use for specialized Markdown syntax for mathematicians; likewise, mathematicians do not need to identify characters or props in common ways. The overall gist is that all of these communities can take the common elements of Markdown (which are rooted in the common elements of HTML circa 2004) and build on them in ways that best fit their needs.
自2004年推出以来,Markdown取得了显著的成功。降价对用户有效有三个关键原因。首先,标记指令(文本)看起来与它们所表示的标记相似;因此,学习句法的认知负担较低。其次,语法成功的主要仲裁者是*运行代码*。将标记转换为可呈现格式的工具,而不是标准机构的一系列正式声明,是确定语法元素是否重要的基础。第三,降价已经成为一种互联网模因[INETMEME],在其他社区遇到降价时,降价会被接受、重新解释和修改。有一些社区在学术写作[场合]、剧本[喷泉]甚至数学公式[MATHDOWN]中使用降价。显然,编剧对数学家来说并没有专门的减价语法的用处;同样,数学家也不需要以普通的方式识别角色或道具。总体要点是,所有这些社区都可以采用Markdown的通用元素(大约在2004年的HTML通用元素中扎根),并以最适合其需要的方式在这些元素的基础上进行构建。
The primary purpose of an Internet media type is to label "content" on the Internet, as distinct from "files". Content is any computer-readable format that can be represented as a primary sequence of octets, along with type-specific metadata (parameters) and type-agnostic metadata (protocol dependent). From this description, it is apparent that appending ".markdown" to the end of a filename is not a sufficient means to identify Markdown. Filenames are properties of files in file systems, but Markdown frequently exists in databases or content management systems (CMSes) where the file metaphor does not apply. One CMS [RAILFROG] uses media types to select appropriate processing, so a media type is necessary for the safe and interoperable use of Markdown.
互联网媒体类型的主要目的是标记互联网上的“内容”,区别于“文件”。内容是任何计算机可读的格式,可以表示为八位字节的主要序列,以及特定于类型的元数据(参数)和不可知类型的元数据(依赖于协议)。从这个描述中可以明显看出,在文件名末尾附加“.markdown”并不足以识别标记。文件名是文件系统中文件的属性,但标记通常存在于文件隐喻不适用的数据库或内容管理系统(CMSE)中。一个CMS[RAILFROG]使用媒体类型来选择适当的处理,因此媒体类型对于安全和可互操作地使用降价是必要的。
Unlike complete HTML documents, [MDSYNTAX] provides no means to include metadata in the content stream. Several derivative flavors have invented metadata incorporation schemes (e.g., [MULTIMD]), but these schemes only address specific use cases. In general, the metadata must be supplied via supplementary means in an encapsulating protocol, format, or convention. The relationship between the content and the metadata is not directly addressed here or in [RFC7763]; however, by identifying Markdown with a media type, Markdown content can participate as a first-class citizen with a wide spectrum of metadata schemes.
与完整的HTML文档不同,[MDSYNTAX]没有在内容流中包含元数据的方法。几种衍生风格已经发明了元数据合并方案(例如,[MULTIMD]),但这些方案只针对特定的用例。通常,元数据必须通过封装协议、格式或约定中的补充方式提供。此处或[RFC7763]中未直接说明内容和元数据之间的关系;但是,通过使用媒体类型标识降价,降价内容可以作为一等公民参与,并具有广泛的元数据方案。
Finally, registering a media type through the IETF process is not trivial. Markdown can no longer be considered a "vendor"-specific innovation, but the registration requirements even in the vendor tree have proven to be overly burdensome for most Markdown implementers. Moreover, registering hundreds of Markdown variants with distinct media types would impede interoperability: virtually all Markdown content can be processed by virtually any Markdown processor, with varying degrees of success. The goal of [RFC7763] is to reduce all of these burdens by having one media type that accommodates diversity and eases registration.
最后,通过IETF过程注册媒体类型并非易事。降价不再被视为“特定于供应商”的创新,但事实证明,即使在供应商树中,注册要求对大多数降价实施者来说也过于繁重。此外,注册数百种具有不同媒体类型的降价变体将阻碍互操作性:几乎所有降价内容都可以由几乎任何降价处理器处理,成功程度各不相同。[RFC7763]的目标是通过拥有一种适应多样性并简化注册的媒体类型来减轻所有这些负担。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应”、“不应”、“建议”、“可”和“可选”应按照[RFC2119]中所述进行解释。
Since Markdown signifies a family of related formats with varying degrees of formal documentation and implementation, this specification uses the term "variant" to identify such formats.
由于标记表示一系列具有不同程度的正式文档和实现的相关格式,因此本规范使用术语“变体”来标识此类格式。
The purpose of this document and [RFC7763] is to promote interoperability between different Markdown-related systems, preserving the author's intent. While [MARKDOWN] was designed by Gruber in 2004 as a simple way to write blog posts and comments, as of 2014 Markdown and its derivatives are rapidly becoming the formats of record for many communities and use cases. While an individual member of (or software tool for) a community can probably look at some "Markdown" and declare its meaning intuitively obvious, software systems in different communities (or different times) need help. [MDSYNTAX] does not have a signaling mechanism like <!DOCTYPE>, so tagging Markdown internally is simply out of the question. Once tags or metadata are introduced, the content is no longer "just" Markdown.
本文件和[RFC7763]的目的是促进不同降价相关系统之间的互操作性,保留作者的意图。尽管[MARKDOWN]是Gruber在2004年设计的一种简单的博客帖子和评论撰写方式,但截至2014年,MARKDOWN及其衍生产品正迅速成为许多社区和用例的记录格式。虽然社区的单个成员(或软件工具)可能会看到一些“降价”并直观地表明其含义,但不同社区(或不同时期)的软件系统需要帮助。[MDSYNTAX]没有像<<这样的信号机制!DOCTYPE>,所以在内部标记标记是不可能的。一旦引入了标记或元数据,内容就不再是“仅仅”标记了。
Some commentators have suggested that an in-band signaling mechanism, such as in Markdown link definitions at the top of the content, could be used to signal the variant. Unfortunately, this signaling mechanism is incompatible with other Markdown variants (e.g., [PANDOC]) that expect their own kinds of metadata at the top of the file. Markdown content is just a stream of text; the semantics of that text can only be furnished by context.
一些评论员建议,可以使用带内信令机制(如内容顶部的降价链接定义)来向变体发送信号。不幸的是,这种信号机制与其他标记变体(例如,[PANDOC])不兼容,这些变体希望在文件顶部有自己的元数据。降价内容只是一个文本流;该文本的语义只能由上下文提供。
The media type and variant parameter in [RFC7763] furnish this missing context, while allowing for additional extensibility. This section covers strategies for how an application might preserve metadata when it leaves the domain of IETF protocols.
[RFC7763]中的媒体类型和变量参数提供了缺少的上下文,同时允许额外的扩展性。本节介绍应用程序离开IETF协议域时如何保存元数据的策略。
[RFC7763] only defines two parameters: the charset parameter (required for all text/* media types) and the variant parameter. [RFC6657] provides guidance on character-set parameter handling. The variant parameter provides a simple identifier -- nothing less or more. Variants are allowed to define additional parameters when sent with the text/markdown media type; the variant can also introduce control information into the textual content stream (such as via a metadata block). Neither [RFC7763] nor this specification recommend any particular approach. However, the philosophy behind [RFC7763] is to preserve formats rather than create new ones, since supporting existing toolchains is more realistic than creating novel ones that lack traction in the Markdown community.
[RFC7763] only defines two parameters: the charset parameter (required for all text/* media types) and the variant parameter. [RFC6657] provides guidance on character-set parameter handling. The variant parameter provides a simple identifier -- nothing less or more. Variants are allowed to define additional parameters when sent with the text/markdown media type; the variant can also introduce control information into the textual content stream (such as via a metadata block). Neither [RFC7763] nor this specification recommend any particular approach. However, the philosophy behind [RFC7763] is to preserve formats rather than create new ones, since supporting existing toolchains is more realistic than creating novel ones that lack traction in the Markdown community.
This strategy is to map the media type, variant, and parameters to "attributes" or "forks" in the local convention. Firstly, Markdown content saved to a file should have an appropriate file extension ending in .md or .markdown, which serves to disambiguate it from other kinds of files. The character repertoire of variant
此策略是将媒体类型、变体和参数映射到本地约定中的“属性”或“分叉”。首先,保存到文件中的标记内容应具有以.md或.Markdown结尾的适当文件扩展名,这有助于消除它与其他类型文件之间的歧义。变形金刚的角色剧目
identifiers in [RFC7763] is designed to be compatible with most filename conventions. Therefore, a recommended strategy is to record the variant identifier as the prefix to the file extension. For example, for [PANDOC] content, a file could be named "example.pandoc.markdown".
[RFC7763]中的标识符设计为与大多数文件名约定兼容。因此,推荐的策略是将变量标识符记录为文件扩展名的前缀。例如,对于[PANDOC]内容,文件可以命名为“example.PANDOC.markdown”。
Many filesystems are case-sensitive or case-preserving; however, file extensions tend to be all lowercase. This document takes no position on whether variant identifiers should be case-preserved or all lowercase when Markdown content is written to a file. However, when the variant identifier is read to influence operational behavior, it needs to be compared case-insensitively.
许多文件系统区分大小写或保留大小写;然而,文件扩展名往往都是小写的。在将标记内容写入文件时,本文档不确定变体标识符是保留大小写还是全部小写。但是,当读取变量标识符以影响操作行为时,需要不区分大小写地对其进行比较。
Many modern filesystems support "extended attributes", "alternate data streams", or "resource forks". Some version control systems support named properties. If the variant defines additional parameters, these parameters should be stored in these resources, where the parameter name includes the name of the resource, and the parameter value is the value of the resource (data in the resource), preferably UTF-8 encoded (unless the parameter definition explicitly defines a different encoding or repertoire). The variant identifier itself should be stored in a resource with a name including the term "variant" (possibly including other decorations to avoid namespace collisions).
许多现代文件系统支持“扩展属性”、“备用数据流”或“资源分叉”。某些版本控制系统支持命名属性。如果变量定义了其他参数,则这些参数应存储在这些资源中,其中参数名称包括资源的名称,参数值是资源的值(资源中的数据),最好是UTF-8编码的(除非参数定义明确定义了不同的编码或曲目). 变量标识符本身应存储在一个资源中,其名称应包括术语“variant”(可能包括其他装饰以避免名称空间冲突)。
This strategy is to save the Markdown content in a first file and to save the metadata (specifically the Content-Type header) in a second file with a filename that is rationally related to the first filename. For example, if the first file is named "readme.markdown", the second file could be named "readme.markdown.headers". (If stored in a database, the analogy would be to store the metadata in a second table with a field that is a key to the first table.) This header file has the media type message/global-headers [RFC6533] (".u8hdr" suggestion notwithstanding).
此策略是将标记内容保存在第一个文件中,并将元数据(特别是内容类型头)保存在第二个文件中,该文件名与第一个文件名合理相关。例如,如果第一个文件名为“readme.markdown”,则第二个文件可能名为“readme.markdown.headers”。(如果存储在数据库中,则类似于将元数据存储在第二个表中,其中的字段是第一个表的键。)此头文件具有媒体类型消息/全局头[RFC6533](“.u8hdr”建议)。
This strategy is to save the Markdown content along with its headers in a file, "arming" the content by prepending the MIME headers (specifically the Content-Type header). It should be appreciated that the file is no longer a "Markdown file"; rather, it is an Internet Message Format file (e.g., [RFC5322]) with a Markdown content part. Therefore, the file should have an Internet message extension (e.g., ".eml", ".msg", or ".u8msg"), not a Markdown extension (e.g., ".md" or ".markdown").
此策略是将标记内容及其标题保存在一个文件中,通过预先添加MIME标题(特别是内容类型标题)来“武装”内容。应该理解的是,该文件不再是“标记文件”;相反,它是一个带有降价内容部分的Internet消息格式文件(例如,[RFC5322])。因此,文件应具有Internet消息扩展名(例如“.eml”、“.msg”或“.u8msg”),而不是标记扩展名(例如“.md”或“.Markdown”)。
This strategy is to translate the processing instructions inferred from the Content-Type and other parameters (e.g., Content-Disposition) into a sequence of commands in the local convention, storing those commands in a batch script. For example, when a MIME-aware client stores some Markdown to disk, the client can save a Makefile in the same directory with commands that are appropriate (and safe) for the local system.
此策略是将从内容类型和其他参数(例如,内容处置)推断出的处理指令转换为本地约定中的命令序列,并将这些命令存储在批处理脚本中。例如,当MIME感知客户端将一些标记存储到磁盘时,该客户端可以使用适合(且安全)本地系统的命令将Makefile保存在同一目录中。
This strategy is to process the Markdown into the formal markup, before a recipient receives it; this eliminates ambiguities. Once the Markdown is processed into (for example) valid XHTML, an application can save a file as "doc.xhtml" or can send MIME content as application/xhtml+xml with no further loss of metadata. While unambiguous, this process may not be reversible.
这种策略是在接收者收到标记之前,将标记处理成正式标记;这消除了歧义。一旦标记被处理成(例如)有效的XHTML,应用程序就可以将文件保存为“doc.XHTML”,或者可以将MIME内容发送为application/XHTML+xml,而不会进一步丢失元数据。这一过程虽然明确,但可能是不可逆的。
This last strategy is to use or create context to determine how to interpret the Markdown. For example, Markdown content that is of the Fountain.io type [FOUNTAIN] could be saved with the filename "script.fountain" instead of "script.markdown". Alternatively, scripts could be stored in a "/screenplays" directory while other kinds of Markdown could be stored elsewhere. For reasons that should be intuitively obvious, this method is the most error-prone. "Context" can be easily lost over time, and the trend of passing Markdown between systems -- taking them *out* of context -- is increasing.
最后一个策略是使用或创建上下文来确定如何解释降价。例如,Fountain.io类型[Fountain]的标记内容可以使用文件名“script.Fountain”而不是“script.Markdown”保存。或者,脚本可以存储在“/剧本”目录中,而其他类型的降价可以存储在其他地方。出于直观上显而易见的原因,这种方法最容易出错。随着时间的推移,“上下文”很容易丢失,系统之间传递降价的趋势——使它们脱离上下文——正在增加。
This subsection covers a preservation strategy in Subversion [SVN], a common client-server version control system.
本小节介绍Subversion[SVN]中的保存策略,这是一种常见的客户机-服务器版本控制系统。
Subversion supports named properties. The "svn:mime-type" property duplicates the entire Content-Type header, so parameters SHOULD be stored there (Section 2.1). The filename SHOULD be consistent with this Content-Type header, i.e., the extension SHOULD be the variant identifier plus ".markdown" (Section 2.1).
Subversion支持命名属性。“svn:mime-type”属性复制整个内容类型头,因此参数应该存储在那里(第2.1节)。文件名应与此内容类型标题一致,即扩展名应为变体标识符加“.markdown”(第2.1节)。
This subsection covers a preservation strategy in Git [GIT], a common distributed version control system.
本小节介绍Git[Git]中的保存策略,Git是一种常见的分布式版本控制系统。
Versions of Git as of the time of this writing do not support arbitrary metadata storage; however, third-party projects add this support.
在撰写本文时,Git的版本不支持任意元数据存储;但是,第三方项目添加了这种支持。
If Git is used without a metadata storage service, then a reasonable strategy is to include the variant identifier in the filename (Section 2.1). The default text encoding SHOULD be UTF-8. For other or different properties, a header file SHOULD be recorded alongside the Markdown file (Section 2.2).
如果使用Git时没有元数据存储服务,那么合理的策略是在文件名中包含变体标识符(第2.1节)。默认文本编码应为UTF-8。对于其他或不同的属性,应在标记文件旁边记录头文件(第2.2节)。
If a metadata storage service is used with Git, then use a convention that is most analogous to the service. For example, the "metastore" project emulates extended attributes (xattrs) of a POSIX-like system, so whatever "xattr" methodology is developed would be usable with metastore and Git.
如果元数据存储服务与Git一起使用,则使用与该服务最相似的约定。例如,“metastore”项目模拟类似POSIX的系统的扩展属性(xattr),因此开发的任何“xattr”方法都可以用于metastore和Git。
The purpose of this section is to register certain syntaxes in the "Markdown Variants" registry [RFC7763] because they illustrate particularly interesting use cases or are broadly applicable to the Internet community; thus, these syntaxes would benefit from the level of review associated with publication as IETF documents.
本节的目的是在“降价变体”注册表[RFC7763]中注册某些语法,因为它们说明了特别有趣的用例或广泛适用于互联网社区;因此,这些语法将受益于与IETF文件发布相关的审查级别。
Identifier: MultiMarkdown
标识符:多重标记
Name: MultiMarkdown
名称:多重减价
Description: MultiMarkdown (MMD) is a superset of "Original". It adds multiple syntax features (tables, footnotes, and citations, to name a few) and is intended to output to various formats. Additionally, it builds in "smart" typography for various languages (proper left-and right-sided quotes, for example).
说明:多重标记(MMD)是“原始”的超集。它添加了多种语法功能(如表格、脚注和引用等),并用于输出各种格式。此外,它还为各种语言构建了“智能”排版(例如,适当的左引号和右引号)。
Additional Parameters: options: String with zero or more of the following tokens delimited by whitespace (WSP):
其他参数:选项:包含以下零个或多个由空格(WSP)分隔的标记的字符串:
"memoir" / "beamer" "full" / "snippet" "process-html" "random-footnote-identifiers" "accept" "reject" "nosmart" "nonotes" "nolabels" "nomask"
"memoir" / "beamer" "full" / "snippet" "process-html" "random-footnote-identifiers" "accept" "reject" "nosmart" "nonotes" "nolabels" "nomask"
The meanings of these tokens are defined in the MultiMarkdown documentation.
这些标记的含义在多重标记文档中定义。
References: <http://fletcher.github.io/MultiMarkdown-4/syntax>
References: <http://fletcher.github.io/MultiMarkdown-4/syntax>
Contact Information: (individual) Fletcher T. Penney <fletcher@fletcherpenney.net> <http://fletcherpenney.net/multimarkdown/>
Contact Information: (individual) Fletcher T. Penney <fletcher@fletcherpenney.net> <http://fletcherpenney.net/multimarkdown/>
Identifier: GFM
识别号码:GFM
Name: GitHub Flavored Markdown
名称:GitHub风味减价
Description: "Original" with the following differences: 1. Multiple underscores in words 2. URL (URI) autolinking 3. Strikethrough 4. Fenced code blocks 5. Syntax highlighting 6. Tables (- for rows; | for columns; : for alignment) 7. Only some HTML allowed; sanitization is integral to the format
描述:“原始”与以下区别:1。单词2中有多个下划线。URL(URI)自动链接3。删除线4。隔离代码块5。语法突出显示6。表格(-用于行;|用于列;:用于对齐)7。只允许一些HTML;净化是格式的一部分
References: <https://help.github.com/articles/github-flavored-markdown/> <https://github.com/github/markup/tree/master#html-sanitization>
References: <https://help.github.com/articles/github-flavored-markdown/> <https://github.com/github/markup/tree/master#html-sanitization>
Contact Information: (corporate) GitHub, Inc. <https://github.com/contact>
Contact Information: (corporate) GitHub, Inc. <https://github.com/contact>
Identifier: pandoc
识别码:潘多克
Name: Pandoc
姓名:潘多克
Description: Markdown is designed to be easy to write and to read: the content should be publishable as-is, as plain text, without looking like it has been marked up with tags or formatting instructions. Yet whereas "Original" has HTML generation in mind, pandoc is designed for multiple output formats. Thus, while pandoc allows the embedding of raw HTML, it discourages it, and provides other, non-HTMLish ways of representing important document elements like definition lists, tables, mathematics, and footnotes.
描述:标记设计为易于书写和阅读:内容应可按原样以纯文本形式发布,而不会看起来像是用标记或格式说明进行了标记。然而,尽管“原始”中考虑了HTML生成,但pandoc是为多种输出格式设计的。因此,尽管pandoc允许嵌入原始HTML,但它不鼓励嵌入原始HTML,并提供其他非HTML的方式来表示重要文档元素,如定义列表、表格、数学和脚注。
Additional Parameters: extensions: String with an optional starting syntax token, followed by a "+" and "-" delimited list of extension tokens. "+" preceding an extension token turns the extension on; "-" turns the extension off. The starting syntax tokens are "markdown", "markdown_strict", "markdown_phpextra", and "markdown_github". If no starting syntax token is given, "markdown" is assumed. The extension tokens include:
附加参数:扩展:字符串,带有可选的起始语法标记,后跟以“+”和“-”分隔的扩展标记列表。扩展令牌前面的“+”打开扩展;“-”关闭分机。起始语法标记是“markdown”、“markdown\u strict”、“markdown\u phpextra”和“markdown\u github”。如果没有给出起始语法标记,则假定为“标记”。扩展令牌包括:
Extensions to turn off (on by default):
要关闭的扩展(默认情况下打开):
escaped_line_breaks blank_before_header header_attributes auto_identifiers implicit_header_references blank_before_blockquote fenced_code_blocks fenced_code_attributes line_blocks fancy_lists startnum definition_lists example_lists table_captions simple_tables multiline_tables grid_tables pipe_tables pandoc_title_block
转义\u行\u断开空白\u在\u标题标题之前\u属性自动\u标识符隐式\u标题\u引用空白\u在\u块引用受保护的\u代码\u块受保护的\u代码\u属性行\u块花式\u列表起始定义\u列表示例\u列表表标题简单\u表多行\u表网格\u表管道\u表pandoc\u标题\u块
yaml_metadata_block all_symbols_escapable intraword_underscores strikeout superscript subscript inline_code_attributes tex_math_dollars raw_html markdown_in_html_blocks native_divs native_spans raw_tex latex_macros implicit_figures footnotes inline_notes citations
yaml\u元数据\u块所有\u符号\u可转义单词内\u下划线删除上标下标内联\u代码\u属性tex\u数学\u美元原始\u html标记\u块本机\u divs本机\u跨度原始\u tex乳胶\u宏隐式\u数字脚注内联\u注释引用
Extensions to turn on (off by default):
要打开的扩展(默认情况下关闭):
lists_without_preceding_blankline hard_line_breaks ignore_line_breaks tex_math_single_backslash tex_match_double_backslash markdown_attribute mmd_title_block abbreviations autolink_bare_uris ascii_identifiers link_attributes mmd_header_identifiers compact_definition_lists
列表\u无前缀\u空白线硬\u线\u中断忽略\u线\u中断tex\u数学\u单次\u反斜杠tex\u匹配\u双次\u反斜杠标记\u属性mmd\u标题\u块缩写自动链接\u裸体\u URI ascii \u标识符链接\u属性mmd\u标题\u标识符压缩\u定义\u列表
Fragment Identifiers: Pandoc defines fragment identifiers using the <id> in the {#<id> .class ...} production (PHP Markdown Extra attribute block). This syntax works for Header Identifiers and Code Block Identifiers.
片段标识符:Pandoc使用{#<id>.class…}产品(PHP标记额外属性块)中的<id>定义片段标识符。此语法适用于标头标识符和代码块标识符。
References: <http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown>
References: <http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown>
Contact Information: (individual) Prof. John MacFarlane <jgm@berkeley.edu> <http://johnmacfarlane.net/>
Contact Information: (individual) Prof. John MacFarlane <jgm@berkeley.edu> <http://johnmacfarlane.net/>
Identifier: Fountain
识别码:喷泉
Name: Fountain
名称:喷泉
Description: Fountain is a simple markup syntax for writing, editing, and sharing screenplays in plain, human-readable text. Fountain allows you to work on your screenplay anywhere, on any computer or tablet, using any software that edits text files.
描述:Fountain是一种简单的标记语法,用于以简单易读的文本编写、编辑和共享剧本。Fountain可以让你在任何地方,任何电脑或平板电脑上,使用任何编辑文本文件的软件来创作剧本。
Fragment Identifiers: See <http://fountain.io/syntax#section-titlepage> and <http://fountain.io/syntax#section-sections>. In the following fragment identifiers, the <key> and <sec*> productions MUST have "/" characters percent-encoded.
片段标识符:参见<http://fountain.io/syntax#section-标题页>和<http://fountain.io/syntax#section-章节>。在以下片段标识符中,<key>和<sec*>产品必须编码“/”字符。
#/ Title Page (acts as metadata). #/<key> Title Page; <key> is the key string. #<sec1> *("/" <secn>) Section or subsection. The <sec1>..<secn> productions are the text of the Section line, with whitespace trimmed from both ends. Subsections (sections with multiple # characters at the beginning of the line in the source) are addressed hierarchically by preceding the subsection with higher-order sections. If the section hierarchy "skips", e.g., # to ###, use a blank section name, e.g., #Section/ACT%20I//PATIO%20SCENE.
#/标题页(充当元数据)#/<键>标题页<key>是键字符串#<第1章*(“/”<secn>)节或小节。<sec1>。<secn>产品是剖面线的文本,从两端修剪空白。子部分(源代码行开头有多个#字符的部分)通过在子部分前面有高阶部分按层次进行处理。如果节层次结构“跳过”,例如#到####,请使用空白节名,例如#节/ACT%20I//PATIO%20SCENE。
References: <http://fountain.io/syntax>
References: <http://fountain.io/syntax>
Contact Information: (individual) Stu Maschwitz <http://prolost.com/> (individual) John August <http://johnaugust.com/>
Contact Information: (individual) Stu Maschwitz <http://prolost.com/> (individual) John August <http://johnaugust.com/>
Identifier: CommonMark
标识符:CommonMark
Name: CommonMark
姓名:CommonMark
Description: CommonMark is a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate
描述:CommonMark是一个标准的、明确的标记语法规范,以及一套用于验证的综合测试
Markdown implementations against this specification. The maintainers believe that CommonMark is necessary, even essential, for the future of Markdown.
针对此规范的降价实现。维护人员认为,CommonMark对于未来的降价是必要的,甚至是必不可少的。
Compared to "Original", CommonMark is much longer and in a few instances contradicts "Original" based on seasoned experience. Although CommonMark specifically does not mandate any particular encoding for the input content, CommonMark draws in more of Unicode, UTF-8, and HTML (including HTML5) than "Original".
与“原创”相比,CommonMark要长得多,并且在少数情况下与基于经验的“原创”相矛盾。尽管CommonMark没有明确要求对输入内容进行任何特定编码,但CommonMark使用的Unicode、UTF-8和HTML(包括HTML5)比“原始”更多。
This registration always refers to the latest version or an unspecified version (receiver's choice). Version 0.13 of the CommonMark specification was released 2014-12-10.
此注册总是指最新版本或未指定版本(接收方选择)。2014年12月10日发布了CommonMark规范的0.13版。
References: <http://spec.commonmark.org/>
References: <http://spec.commonmark.org/>
Contact Information: (individual) John MacFarlane <jgm@berkeley.edu> (individual) David Greenspan <david@meteor.com> (individual) Vicent Marti <vicent@github.com> (individual) Neil Williams <neil@reddit.com> (individual) Benjamin Dumke-von der Ehe <ben@stackexchange.com> (individual) Jeff Atwood <jatwood@codinghorror.com>
Contact Information: (individual) John MacFarlane <jgm@berkeley.edu> (individual) David Greenspan <david@meteor.com> (individual) Vicent Marti <vicent@github.com> (individual) Neil Williams <neil@reddit.com> (individual) Benjamin Dumke-von der Ehe <ben@stackexchange.com> (individual) Jeff Atwood <jatwood@codinghorror.com>
Identifier: kramdown-rfc2629
标识符:kramdown-rfc2629
Name: Markdown for RFCs
名称:RFC降价
Description: kramdown is a markdown parser by Thomas Leitner; it has a number of backends for generating HTML, LaTeX, and Markdown again. kramdown-rfc2629 is an additional backend to that: It allows the generation of XML2RFC XML markup (originally known as markup that is RFC 2629 compliant, now documented in RFC 7749).
描述:kramdown是Thomas Leitner的markdown解析器;它有许多后端用于再次生成HTML、LaTeX和Markdown。kramdown-rfc2629是另一个后端:它允许生成XML2RFC XML标记(最初称为符合RFC 2629的标记,现在记录在RFC 7749中)。
References: <https://github.com/cabo/kramdown-rfc2629>
References: <https://github.com/cabo/kramdown-rfc2629>
Contact Information: (individual) Carsten Bormann <cabo@tzi.org>
Contact Information: (individual) Carsten Bormann <cabo@tzi.org>
Identifier: rfc7328
识别码:rfc7328
Name: Pandoc2rfc
姓名:Pandoc2rfc
Description: Pandoc2rfc allows authors to write in "pandoc" that is then transformed to XML and given to xml2rfc. The conversions are, in a way, amusing, as we start off with (almost) plain text, use elaborate XML, and end up with plain text again.
描述:Pandoc2rfc允许作者在“pandoc”中编写,然后将其转换为XML并提供给xml2rfc。从某种程度上说,转换是有趣的,因为我们从(几乎)纯文本开始,使用复杂的XML,然后又以纯文本结束。
References: RFC 7328 <https://github.com/miekg/pandoc2rfc>
References: RFC 7328 <https://github.com/miekg/pandoc2rfc>
Contact Information: (individual) R. (Miek) Gieben <miek@google.com>
Contact Information: (individual) R. (Miek) Gieben <miek@google.com>
Identifier: Extra
识别码:额外
Name: Markdown Extra
名称:额外减价
Description: Markdown Extra is an extension to PHP Markdown implementing some features currently not available with the plain Markdown syntax. Markdown Extra is available as a separate parser class in PHP Markdown Lib. Other implementations include Maruku (Ruby) and Python Markdown. Markdown Extra is supported in several content management systems, including Drupal, TYPO3, and MediaWiki.
描述:Markdown Extra是PHP Markdown的扩展,实现了一些普通Markdown语法目前不可用的功能。Markdown Extra在PHP Markdown Lib中作为单独的解析器类提供。其他实现包括Maruku(Ruby)和Python Markdown。Markdown Extra在几个内容管理系统中都受支持,包括Drupal、TYPO3和MediaWiki。
Fragment Identifiers: Markdown Extra defines fragment identifiers using the <id> in the {#<id> .class ...} production (attribute block). This syntax works for headers, fenced code blocks, links, and images.
片段标识符:Markdown Extra使用{#<id>.class…}产品(属性块)中的<id>定义片段标识符。此语法适用于标题、受保护的代码块、链接和图像。
References: <https://michelf.ca/projects/php-markdown/extra/>
References: <https://michelf.ca/projects/php-markdown/extra/>
Contact Information: (individual) Michel Fortin <michel.fortin@michelf.ca>
Contact Information: (individual) Michel Fortin <michel.fortin@michelf.ca>
This section provides examples of the variants in Section 3.
本节提供了第3节中的变体示例。
Title: Example of MultiMarkdown Keywords: IETF, example, footnotes
标题:多重标记关键词示例:IETF,示例,脚注
# MultiMarkdown Example #
#多重降价示例#
MultiMarkdown supports several cool features, as well as several output formats: * HTML * PDF * OpenDocument * OPML * LaTeX
MultiMarkdown支持多种很酷的功能,以及多种输出格式:*HTML*PDF*OpenDocument*OPML*LaTeX
## Footnotes ##
## Footnotes ##
Footnotes are described in the MultiMarkdown Syntax Guide.[^somesamplefootnote]
多标记语法指南中介绍了脚注。[^somesamplefootnote]
[^somesamplefootnote]: Here is the text of the footnote itself.
[^somesamplefootnote]:这是脚注本身的文本。
Figure 1: MultiMarkdown Example
图1:多重降价示例
# Start Out #
#出发#
GFM is like regular Markdown with a few extra features. For example, http://www.example.com/ will get auto-linked. ~~This is strike-through text, demarked by the double tildes.~~
GFM is like regular Markdown with a few extra features. For example, http://www.example.com/ will get auto-linked. ~~This is strike-through text, demarked by the double tildes.~~
``` function test() { return "notice this feature?"); } ```
``` function test() { return "notice this feature?"); } ```
# Table Alignments #
#表格对齐#
| Left | Center | Right | |:--------- |:-------:| ------:| | cats | Paxton | $1600 | | dogs | Ruff | $30 | | zebras | Stripes | $20900 |
| Left | Center | Right | |:--------- |:-------:| ------:| | cats | Paxton | $1600 | | dogs | Ruff | $30 | | zebras | Stripes | $20900 |
Figure 2: GitHub Flavored Markdown Example
图2:GitHub风格的降价示例
% Pandoc User's Guide % John MacFarlane % August 30, 2014
%潘多克用户指南%John MacFarlane%2014年8月30日
Synopsis {#syn} ========
Synopsis {#syn} ========
pandoc [*options*] [*input-file*]...
pandoc[*选项*][*输入文件*]。。。
Description {#desc} ===========
Description {#desc} ===========
Pandoc is a [Haskell] library for converting from one markup format to another, and a command-line tool that uses this library.
Pandoc是一个用于从一种标记格式转换为另一种标记格式的[Haskell]库,也是一个使用该库的命令行工具。
#### Extension: `header_attributes` #### {#ext-header-attributes}
#### Extension: `header_attributes` #### {#ext-header-attributes}
Headers can be assigned attributes using this syntax at the end of the line containing the header text:
可以在包含标题文本的行末尾使用以下语法为标题分配属性:
{#identifier .class .class key=value key=value}
{#identifier .class .class key=value key=value}
Thus, for example, the following headers will all be assigned the identifier `foo`:
因此,例如,以下标题都将被分配标识符“foo”:
# My header {#foo}
# My header {#foo}
## My header ## {#foo}
## My header ## {#foo}
My other header {#foo} ---------------
My other header {#foo} ---------------
Figure 3: Pandoc Example
图3:Pandoc示例
INT. BOXCAR - MOVING - DAY ?AGENT MORTIMER lies bleeding in the corner. The car ROCKS gently. Mortimer pulls out his cell phone and dials.
车内-搬家-白天?莫蒂默探员躺在角落里流血。汽车轻轻地摇晃。莫蒂默掏出手机拨号。
MORTIMER? Come on. Pick up.
莫蒂默?来吧拿起
CUT TO:? ext. hotel bar - day? A fiercely gorgeous brunette sips the last of something from a rocks glass. This is REBECCA.
切到:?外线酒店酒吧-白天?一个极其美丽的浅黑色女人从一个石头玻璃杯里啜饮着最后的东西。我是丽贝卡。
Behind her, a dark FIGURE approaches. She seems not to notice.
在她身后,一个黑影走近。她似乎没有注意到。
REBECCA?(to Bartender) Rittenhouse, neat.
丽贝卡?(对酒保)丽腾豪斯,整洁。
FIGURE (O.S.) ^ Ritenhouse, neat.
图(O.S.)^Ritenhouse,整洁。
She turns to find the source of the voice.
她转身寻找声音的来源。
FIGURE Excellent choice.
身材是个不错的选择。
Before she can reply, her phone RINGS.?
她还没来得及回答,电话就响了。?
> INTERCUT WITH:?
>与……互换?
.THE BOXCAR
.棚车
Where MORTIMER is just barely holding on to life.
在那里,莫蒂默几乎无法维持生命。
Figure 4: Fountain Example
图4:喷泉示例
CommonMark is like Markdown.
CommonMark就像Markdown。
Here are some entity names that you can use with CommonMark: ` & © Æ Ď ¾ ℋ ⅆ ∲`
Here are some entity names that you can use with CommonMark: ` & © Æ Ď ¾ ℋ ⅆ ∲`
You can see more at [the CommonMark website](http://commonmark.org/ "CommonMark").
您可以在[CommonMark网站]上查看更多信息(http://commonmark.org/ “普通商标”)。
- foo *** - bar
- foo***-酒吧
Tildes can be used for fenced code blocks:
TILDE可用于防护代码块:
~~~ < > ~~~
~~~ < > ~~~
Figure 5: CommonMark Example
图5:CommonMark示例
--- title: STUN/TURN using PHP in Despair abbrev: STuPiD-excerpt docname: draft-hartke-xmpp-stupid-excerpt-00 date: 2009-07-05 category: info
--- title: STUN/TURN using PHP in Despair abbrev: STuPiD-excerpt docname: draft-hartke-xmpp-stupid-excerpt-00 date: 2009-07-05 category: info
ipr: trust200902 area: General workgroup: XMPP Working Group keyword: Internet-Draft
ipr:trust200902领域:一般工作组:XMPP工作组关键字:Internet草稿
stand_alone: yes pi: [toc, sortrefs, symrefs]
独立:是pi:[toc、sortrefs、symrefs]
author: - ins: K. Hartke name: Klaus Hartke email: example@tzi.org
作者:-ins:K.Hartke姓名:Klaus Hartke电子邮件:example@tzi.org
normative: RFC2119:
规范性文件:RFC2119:
informative: RFC5389: STUNT: target: http://www.example.com/oob title: STUNT & out-of-band channels author: name: Robbie Hanson ins: R. Hanson date: 2007-09-17
informative: RFC5389: STUNT: target: http://www.example.com/oob title: STUNT & out-of-band channels author: name: Robbie Hanson ins: R. Hanson date: 2007-09-17
--- abstract
--- abstract
NAT (Network Address Translator) Traversal may require TURN (Traversal Using Relays around NAT) functionality in certain cases that are not unlikely to occur. There is little incentive to deploy TURN servers, except by those who need them—who may not be in a position to deploy a new protocol on an Internet-connected node, in particular not one with deployment requirements as high as those of TURN.
在某些情况下,NAT(网络地址转换器)遍历可能需要TURN(使用NAT周围的中继进行遍历)功能,但这种情况不太可能发生。除了那些需要TURN服务器的人之外,部署TURN服务器的动机很少;世卫组织可能无法在连接互联网的节点上部署新协议,尤其是部署要求不如TURN高的节点。
--- middle
--- middle
Introduction {#problems} ============
Introduction {#problems} ============
"STUN/TURN using PHP in Despair" is a highly deployable protocol for obtaining TURN-like functionality, while also providing the most important function of STUN {{RFC5389}}.
“STUN/TURN using PHP in Despire”是一个高度可部署的协议,用于获得类似TURN的功能,同时还提供STUN{{RFC5389}最重要的功能。
The Need for Standardization {#need} ----------------------------
The Need for Standardization {#need} ----------------------------
Having one standard form of STuPiD service instead of one specific to each kind of client also creates an incentive for optimized implementations.
拥有一种标准形式的愚蠢服务,而不是针对每种客户机的特定服务,也会鼓励优化实现。
~~~~~~~~~~
~~~~~~~~~~
STuPiD ```````````````````````````````, Script <----------------------------. , | , ^ , | , | , | , (1) | , | , (3) POST | , | , GET | , | , | v | v
STuPiD ```````````````````````````````, Script <----------------------------. , | , ^ , | , | , | , (1) | , | , (3) POST | , | , GET | , | , | v | v
Peer A -----------------------> Peer B (2) out-of-band Notification ~~~~~~~~~~ {: #figops title="STuPiD Protocol Operation"}
Peer A -----------------------> Peer B (2) out-of-band Notification ~~~~~~~~~~ {: #figops title="STuPiD Protocol Operation"}
Terminology {#Terminology} ----------- In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 {{RFC2119}} and indicate requirement levels for compliant STuPiD implementations.
Terminology {#Terminology} ----------- In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 {{RFC2119}} and indicate requirement levels for compliant STuPiD implementations.
--- back
--- back
Sample Implementation {#impl} =====================
Sample Implementation {#impl} =====================
~~~~~~~~~~
~~~~~~~~~~
<?php header("Cache-Control: no-cache, must-revalidate"); header("Expires: Sat, 26 Jul 1997 05:00:00 GMT"); header("Content-Type: application/octet-stream");
<?php header("Cache-Control: no-cache, must-revalidate"); header("Expires: Sat, 26 Jul 1997 05:00:00 GMT"); header("Content-Type: application/octet-stream");
?> ~~~~~~~~~~ {: #figimpl title="STuPiD Sample Implementation"}
?> ~~~~~~~~~~ {: #figimpl title="STuPiD Sample Implementation"}
Figure 6: Markdown for RFCs Example
图6:RFCs示例的降价
Pandoc2rfc expects multiple files as input. The following figure is example of "middle.mkd".
Pandoc2rfc需要多个文件作为输入。下图是“middle.mkd”的示例。
# Introduction
#导言
<?rfc toc="yes"?> <?rfc symrefs="yes"?> <?rfc sortrefs="yes"?> <?rfc subcompact="no"?> <?rfc compact="yes"?> <?rfc comments="yes"?>
<?rfc toc="yes"?> <?rfc symrefs="yes"?> <?rfc sortrefs="yes"?> <?rfc subcompact="no"?> <?rfc compact="yes"?> <?rfc comments="yes"?>
This document presents a technique for using Pandoc syntax as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series.
本文档介绍了一种使用Pandoc语法作为Internet草稿(I-Ds)和征求意见(RFC)系列文档源格式的技术。
This version is adapted to work with `xml2rfc` version 2.x.
此版本适用于'xml2rfc'版本2.x。
Pandoc is an "almost plain text" format and therefore particularly well suited for editing RFC-like documents.
Pandoc是一种“几乎纯文本”格式,因此特别适合编辑类似RFC的文档。
> Note: this document is typeset in Pandoc.
>注:本文件采用Pandoc排版。
> NB: this is mostly text to test Pandoc2rfc, the canonical > documentation is [RFC 7328][p2r].
>注意:这主要是测试Pandoc2rfc的文本,canonical>文档是[rfc7328][p2r]。
[p2r]: http://www.rfc-editor.org/info/rfc7328
[p2r]: http://www.rfc-editor.org/info/rfc7328
# Pandoc to RFC
#Pandoc至RFC
> Pandoc2rfc -- designed to do the right thing, until it doesn't.
>Pandoc2rfc——设计用于做正确的事情,直到它不做。
When writing [](#RFC4641) we directly wrote the XML. Needless to say it was tedious even though the XML of [xml2rfc](http://xml2rfc.ietf.org/) is very "light". The [latest version of xml2rfc version 2 can be found here](http://pypi.python.org/pypi/xml2rfc/).
在编写[](#RFC4641)时,我们直接编写了XML。不用说,尽管[xml2rfc]的XML(http://xml2rfc.ietf.org/)它非常“轻”。[这里可以找到xml2rfc版本2的最新版本](http://pypi.python.org/pypi/xml2rfc/).
Figure 7: Pandoc2rfc Example (middle.mkd)
图7:Pandoc2rfc示例(middle.mkd)
IANA has registered the syntaxes specified in Section 3 in the "Markdown Variants" registry.
IANA已在“降价变体”注册表中注册了第3节中规定的语法。
See the respective syntax descriptions and output media type registrations for their respective security considerations.
有关各自的安全注意事项,请参阅各自的语法说明和输出媒体类型注册。
[MARKDOWN] Gruber, J., "Daring Fireball: Markdown", December 2004, <http://daringfireball.net/projects/markdown/>.
[MARKDOWN]Gruber,J.,“勇敢的火球:MARKDOWN”,2004年12月<http://daringfireball.net/projects/markdown/>.
[MDSYNTAX] Gruber, J., "Daring Fireball: Markdown Syntax Documentation", <http://daringfireball.net/projects/markdown/syntax>.
[MDSYNTAX]Gruber,J.,“大胆的火球:降价语法文档”<http://daringfireball.net/projects/markdown/syntax>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.
[RFC2119]Bradner,S.,“RFC中用于表示需求水平的关键词”,BCP 14,RFC 2119,DOI 10.17487/RFC2119,1997年3月<http://www.rfc-editor.org/info/rfc2119>.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, October 2008, <http://www.rfc-editor.org/info/rfc5322>.
[RFC5322]Resnick,P.,Ed.,“互联网信息格式”,RFC 5322,DOI 10.17487/RFC5322,2008年10月<http://www.rfc-editor.org/info/rfc5322>.
[RFC6657] Melnikov, A. and J. Reschke, "Update to MIME regarding "charset" Parameter Handling in Textual Media Types", RFC 6657, DOI 10.17487/RFC6657, July 2012, <http://www.rfc-editor.org/info/rfc6657>.
[RFC6657]Melnikov,A.和J.Reschke,“关于文本媒体类型中“字符集”参数处理的MIME更新”,RFC 6657,DOI 10.17487/RFC6657,2012年7月<http://www.rfc-editor.org/info/rfc6657>.
[RFC7763] Leonard, S., "The text/markdown Media Type", RFC 7763, DOI 10.17487/RFC7763, March 2016, <http://www.rfc-editor.org/info/rfc7763>.
[RFC7763]Leonard,S.,“文本/降价媒体类型”,RFC 7763,DOI 10.17487/RFC7763,2016年3月<http://www.rfc-editor.org/info/rfc7763>.
[UNICODE] The Unicode Consortium, "The Unicode Standard, Version 8.0", (Mountain View, CA: The Unicode Consortium, 2015. ISBN 978-1-936213-10-8), <http://www.unicode.org/versions/Unicode8.0.0/>.
[UNICODE]UNICODE联盟,“UNICODE标准,8.0版”(加利福尼亚州山景城:UNICODE联盟,2015年,ISBN 978-1-936213-10-8)<http://www.unicode.org/versions/Unicode8.0.0/>.
[HUMANE] Atwood, J., "Is HTML a Humane Markup Language?", May 2008, <http://blog.codinghorror.com/ is-html-a-humane-markup-language/>.
[Humanic]Atwood,J.,“HTML是一种人性化的标记语言吗?”,2008年5月<http://blog.codinghorror.com/ is-html-a-humanic-markup-language/>。
[DIN2MD] Gruber, J., "Dive Into Markdown", March 2004, <http://daringfireball.net/2004/03/dive_into_markdown>.
[DIN2MD]Gruber,J.,“跳入降价”,2004年3月<http://daringfireball.net/2004/03/dive_into_markdown>.
[MD102b8] Gruber, J., "Subject: [ANN] Markdown.pl 1.0.2b8", message to the markdown-discuss mailing list, 9 May 2007, <http://six.pairlist.net/pipermail/markdown-discuss/ 2007-May/000615.html>, <http://daringfireball.net/projects/downloads/ Markdown_1.0.2b8.tbz>.
[MD102b8]Gruber,J.,“主题:[ANN]Markdown.pl 1.0.2b8”,给Markdown讨论邮件列表的信息,2007年5月9日<http://six.pairlist.net/pipermail/markdown-discuss/ 2007年5月/000615.html><http://daringfireball.net/projects/downloads/ Markdown_1.0.2b8.tbz>。
[CATPICS] Gruber, J. and M. Arment, "The Talk Show: Ep. 88: 'Cat Pictures' (Side 1)", July 2014, <http://daringfireball.net/thetalkshow/2014/07/19/ep-088>.
[CATPICS]格鲁伯,J.和M.阿姆特,“脱口秀:Ep.88:‘猫图片’(第1面)”,2014年7月<http://daringfireball.net/thetalkshow/2014/07/19/ep-088>.
[INETMEME] Solon, O., "Richard Dawkins on the internet's hijacking of the word 'meme'", June 2013, <http://www.wired.co.uk/news/archive/2013-06/20/ richard-dawkins-memes>, <http://www.webcitation.org/6HzDGE9Go>.
[INETMEME]Solon,O.,“Richard Dawkins在互联网上劫持‘meme’一词”,2013年6月<http://www.wired.co.uk/news/archive/2013-06/20/ 理查德·道金斯模因><http://www.webcitation.org/6HzDGE9Go>.
[MULTIMD] Penney, F., "MultiMarkdown", <http://fletcherpenney.net/multimarkdown/>.
[MULTIMD]Penney,F.,“多重减价”<http://fletcherpenney.net/multimarkdown/>.
[PANDOC] MacFarlane, J., "Pandoc", <http://johnmacfarlane.net/pandoc/>.
[PANDOC]麦克法兰,J.,“PANDOC”<http://johnmacfarlane.net/pandoc/>.
[RAILFROG] Railfrog Team, "Railfrog", April 2009, <http://railfrog.com/>.
[RAILFROG]RAILFROG团队,“RAILFROG”,2009年4月<http://railfrog.com/>.
[RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, DOI 10.17487/RFC0793, September 1981, <http://www.rfc-editor.org/info/rfc793>.
[RFC793]Postel,J.,“传输控制协议”,标准7,RFC 793,DOI 10.17487/RFC0793,1981年9月<http://www.rfc-editor.org/info/rfc793>.
[RFC6533] Hansen, T., Ed., Newman, C., and A. Melnikov, "Internationalized Delivery Status and Disposition Notifications", RFC 6533, DOI 10.17487/RFC6533, February 2012, <http://www.rfc-editor.org/info/rfc6533>.
[RFC6533]Hansen,T.,Ed.,Newman,C.,和A.Melnikov,“国际化交付状态和处置通知”,RFC 6533,DOI 10.17487/RFC6533,2012年2月<http://www.rfc-editor.org/info/rfc6533>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, <http://www.rfc-editor.org/info/rfc6838>.
[RFC6838]Freed,N.,Klensin,J.和T.Hansen,“介质类型规范和注册程序”,BCP 13,RFC 6838,DOI 10.17487/RFC6838,2013年1月<http://www.rfc-editor.org/info/rfc6838>.
[XML1.0-5] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", W3C Recommendation REC-xml-20081126, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.
[XML1.0-5]Bray,T.,Paoli,J.,Sperberg McQueen,M.,Maler,E.,和F.Yergeau,“可扩展标记语言(XML)1.0(第五版)”,W3C建议REC-XML-20081126,2008年11月<http://www.w3.org/TR/2008/REC-xml-20081126>.
[OCCASION] Shieber, S., "Switching to Markdown for scholarly article production", August 2014, <http://blogs.law.harvard.edu/pamphlet/2014/08/29/ switching-to-markdown-for-scholarly-article-production/>.
[场合]Shieber,S.,“转为降价制作学术文章”,2014年8月<http://blogs.law.harvard.edu/pamphlet/2014/08/29/ 切换到降价制作学术文章/>。
[FOUNTAIN] Maschwitz, S. and J. August, "Fountain | A markup language for screenwriting.", <http://fountain.io/>.
[FOUNTAIN]Maschwitz,S.和J.August,“FOUNTAIN |一种用于剧本创作的标记语言”<http://fountain.io/>.
[MATHDOWN] Cherniavsky-Paskin, B., "math in markdown", <https://github.com/cben/mathdown/wiki/math-in-markdown>.
Cherniavsky Paskin,B.,“markdown中的数学”<https://github.com/cben/mathdown/wiki/math-in-markdown>.
[SVN] Apache Subversion, December 2015, <https://subversion.apache.org/>.
[SVN]Apache Subversion,2015年12月<https://subversion.apache.org/>.
[GIT] Git, <http://git-scm.com/>.
[吉特]吉特<http://git-scm.com/>.
Author's Address
作者地址
Sean Leonard Penango, Inc. 5900 Wilshire Boulevard 21st Floor Los Angeles, CA 90036 United States
Sean Leonard Penango,Inc.美国加利福尼亚州洛杉矶威尔希尔大道21楼5900号,邮编90036
EMail: dev+ietf@seantek.com URI: http://www.penango.com/
EMail: dev+ietf@seantek.com URI: http://www.penango.com/