CommonMark
==========
CommonMark is a rationalized version of Markdown syntax,
with a [spec][the spec] and BSD-licensed reference
implementations in C and JavaScript.
[Try it now!](http://try.commonmark.org/)
[the spec]: http://spec.commonmark.org/
For more details, see <http://commonmark.org>.
This repository contains the spec itself, along with tools for
running tests against the spec, and for creating HTML and PDF versions
of the spec.
The reference implementations live in separate repositories:
- <https://github.com/jgm/cmark> (C)
- <https://github.com/jgm/commonmark.js> (JavaScript)
There is a list of third-party libraries
in a dozen different languages
[here](https://github.com/jgm/CommonMark/wiki/List-of-CommonMark-Implementations).
Running tests against the spec
------------------------------
[The spec] contains over 500 embedded examples which serve as conformance
tests. To run the tests using an executable `$PROG`:
python3 test/spec_tests.py --program $PROG
If you want to extract the raw test data from the spec without
actually running the tests, you can do:
python3 test/spec_tests.py --dump-tests
and you'll get all the tests in JSON format.
The spec
--------
The source of [the spec] is `spec.txt`. This is basically a Markdown
file, with code examples written in a shorthand form:
.
Markdown source
.
expected HTML output
.
To build an HTML version of the spec, do `make spec.html`. To build a
PDF version, do `make spec.pdf`. (Creating the HTML version requires
that [cmark](https://github.com/jgm/cmark) and `python3` be installed
and in your path. Creating a PDF also requires [pandoc] and LaTeX.)
The spec is written from the point of view of the human writer, not
the computer reader. It is not an algorithm---an English translation of
a computer program---but a declarative description of what counts as a block
quote, a code block, and each of the other structural elements that can
make up a Markdown document.
Because John Gruber's [canonical syntax
description](http://daringfireball.net/projects/markdown/syntax) leaves
many aspects of the syntax undetermined, writing a precise spec requires
making a large number of decisions, many of them somewhat arbitrary.
In making them, we have appealed to existing conventions and
considerations of simplicity, readability, expressive power, and
consistency. We have tried to ensure that "normal" documents in the many
incompatible existing implementations of Markdown will render, as far as
possible, as their authors intended. And we have tried to make the rules
for different elements work together harmoniously. In places where
different decisions could have been made (for example, the rules
governing list indentation), we have explained the rationale for
our choices. In a few cases, we have departed slightly from the canonical
syntax description, in ways that we think further the goals of Markdown
as stated in that description.
For the most part, we have limited ourselves to the basic elements
described in Gruber's canonical syntax description, eschewing extensions
like footnotes and definition lists. It is important to get the core
right before considering such things. However, we have included a visible
syntax for line breaks and fenced code blocks.
Differences from original Markdown
----------------------------------
There are only a few places where this spec says things that contradict
the canonical syntax description:
- It allows all punctuation symbols to be backslash-escaped,
not just the symbols with special meanings in Markdown. We found
that it was just too hard to remember which symbols could be
escaped.
- It introduces an alternative syntax for hard line
breaks, a backslash at the end of the line, supplementing the
two-spaces-at-the-end-of-line rule. This is motivated by persistent
complaints about the “invisible” nature of the two-space rule.
- Link syntax has been made a bit more predictable (in a
backwards-compatible way). For example, `Markdown.pl` allows single
quotes around a title in inline links, but not in reference links.
This kind of difference is really hard for users to remember, so the
spec allows single quotes in both contexts.
- The rule for HTML blocks differs, though in most real cases it
shouldn't make a difference. (See the section on HTML Blocks
for details.) The spec's proposal makes it easy to include Markdown
inside HTML block-level tags, if you want to, but also allows you to
exclude this. It is also makes parsing much easier, avoiding
expensive backtracking.
- It does not collapse adjacent bird-track blocks into a single
blockquote:
> this is two
> blockquotes
> this is a single
>
> blockquote with two paragraphs
- Rules for content in lists differ in a few respects, though (as with
HTML blocks), most lists in existing documents should render as
intended. There is some discussion of the choice points and
differences in the subsection of List Items entitled Motivation.
We think that the spec's proposal does better than any existing
implementation in rendering lists the way a human writer or reader
would intuitively understand them. (We could give numerous examples
of perfectly natural looking lists that nearly every existing
implementation flubs up.)
- The spec stipulates that two blank lines break out of all list
contexts. This is an attempt to deal with issues that often come up
when someone wants to have two adjacent lists, or a list followed by
an indented code block.
- Changing bullet characters, or changing from bullets to numbers or
vice versa, starts a new list. We think that is almost always going
to be the writer's intent.
- The number that begins an ordered list item may be followed by
either `.` or `)`. Changing the delimiter style starts a new
list.
- The start number of an ordered list is significant.
- Fenced code blocks are supported, delimited by either
backticks (```` ``` ```` or tildes (` ~~~ `).
Contributing
------------
There is a [forum for discussing
CommonMark](http://talk.commonmark.org); you should use it instead of
github issues for questions and possibly open-ended discussions.
Use the [github issue tracker](http://github.com/jgm/CommonMark/issues)
only for simple, clear, actionable issues.
Authors
-------
The spec was written by John MacFarlane, drawing on
- his experience writing and maintaining Markdown implementations in several
languages, including the first Markdown parser not based on regular
expression substitutions ([pandoc](http://github.com/jgm/pandoc)) and
the first markdown parsers based on PEG grammars
([peg-markdown](http://github.com/jgm/peg-markdown),
[lunamark](http://github.com/jgm/lunamark))
- a detailed examination of the differences between existing Markdown
implementations using [BabelMark 2](http://johnmacfarlane.net/babelmark2/),
and
- extensive discussions with David Greenspan, Jeff Atwood, Vicent
Marti, Neil Williams, and Benjamin Dumke-von der Ehe.
Since the first announcement, many people have contributed ideas.
Kārlis Gaņģis was especially helpful in refining the rules for
emphasis, strong emphasis, links, and images.
没有合适的资源?快使用搜索试试~ 我知道了~
Python编写的文档处理工具源码下载.zip
共861个文件
png:193个
py:152个
rst:150个
需积分: 1 1 下载量 196 浏览量
2023-09-10
17:56:47
上传
评论
收藏 6.47MB ZIP 举报
温馨提示
Python编写的文档处理工具源码下载.zip
资源推荐
资源详情
资源评论
收起资源包目录
Python编写的文档处理工具源码下载.zip (861个子文件)
Helvetica-Oblique.afm 76KB
Helvetica.afm 76KB
Helvetica-BoldOblique.afm 71KB
Helvetica-Bold.afm 70KB
Times-Italic.afm 67KB
Times-Bold.afm 65KB
Times-Roman.afm 61KB
Times-BoldItalic.afm 61KB
Courier-Oblique.afm 15KB
Courier-BoldOblique.afm 15KB
Courier.afm 15KB
Courier-Bold.afm 15KB
Symbol.afm 10KB
ZapfDingbats.afm 10KB
make.bat 7KB
catalog 681B
wininst.cfg 745B
setup.cfg 423B
.coveragerc 209B
tweaks.css 317B
hyph_en_US.dic 106KB
docutils.dtd 16KB
soextblx.dtd 12KB
w3centities-f.ent 164KB
htmlmathml-f.ent 155KB
mmlalias.ent 40KB
isoamsr.ent 15KB
isoamsa.ent 13KB
isotech.ent 13KB
isolat2.ent 11KB
isoamsb.ent 10KB
mmlextra.ent 9KB
xhtml1-symbol.ent 9KB
isoamsn.ent 9KB
xhtml1-lat1.ent 8KB
isopub.ent 7KB
isolat1.ent 6KB
isocyr1.ent 6KB
isonum.ent 6KB
isoamso.ent 6KB
isomfrk.ent 5KB
isomscr.ent 5KB
isogrk1.ent 5KB
isobox.ent 5KB
isogrk4.ent 5KB
isogrk3.ent 5KB
w3centities.ent 4KB
isomopf.ent 4KB
htmlmathml.ent 4KB
isocyr2.ent 4KB
xhtml1-special.ent 3KB
isogrk2.ent 3KB
isoamsc.ent 3KB
isodia.ent 2KB
html5-uppercase.ent 2KB
predefined.ent 2KB
.gitattributes 242B
.gitignore 169B
.gitignore 51B
.gitignore 47B
.gitignore 36B
.gitignore 22B
.gitignore 12B
.gitignore 11B
MustRead.html 937B
sRGB_IEC61966-2-1_black_scaled.icc 3KB
rinoh.icns 145KB
rinoh.ico 97KB
python-objects.inv 84KB
sphinx-objects.inv 8KB
carwash.jpg 8KB
lensinfo.jpg 579B
LICENSE 34KB
PngSuite.LICENSE 167B
poetry.lock 67KB
Makefile 7KB
README.md 7KB
05_other.md 142B
texgyretermes-regular.otf 138KB
Puritan2.otf 44KB
Cuprum.otf 43KB
Odpisy.pdf 2.82MB
google_fonts.pdf 886KB
install_resources.pdf 653KB
missing_glyphs.pdf 242KB
sphinx_inline_markup.pdf 233KB
png.pdf 176KB
demo.pdf 54KB
list_of_figures.pdf 37KB
graphviz.pdf 31KB
ref.pdf 31KB
image.pdf 30KB
relativepaths.pdf 21KB
customtemplate.pdf 20KB
citations.pdf 15KB
border_table.pdf 14KB
outoflineflowables.pdf 14KB
table_sideways.pdf 14KB
list_of_tables.pdf 13KB
inline_markup.pdf 12KB
共 861 条
- 1
- 2
- 3
- 4
- 5
- 6
- 9
资源评论
m0_57781768
- 粉丝: 1w+
- 资源: 402
上传资源 快速赚钱
- 我的内容管理 展开
- 我的资源 快来上传第一个资源
- 我的收益 登录查看自己的收益
- 我的积分 登录查看自己的积分
- 我的C币 登录后查看C币余额
- 我的收藏
- 我的下载
- 下载帮助
安全验证
文档复制为VIP权益,开通VIP直接复制
信息提交成功