diff --git a/README.md b/README.md index 1d3971f..48bb060 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,8 @@ by peg-markdown. [peg]: https://github.com/pointlander/peg [Go]: http://golang.org/ -Support for HTML output is implemented, but Groff and LaTeX -output have not been ported. The output is identical +Support for HTML and groff mm output is implemented, but LaTeX +output has not been ported. The output is identical to that of peg-markdown. I try to keep the grammar in sync with the C version, by diff --git a/cmd/markdown/main.go b/cmd/markdown/main.go index 393160c..f9c4b68 100644 --- a/cmd/markdown/main.go +++ b/cmd/markdown/main.go @@ -9,6 +9,8 @@ import ( "os" ) +var format = flag.String("t", "html", "output format") + func main() { var opt markdown.Extensions flag.BoolVar(&opt.Notes, "notes", false, "turn on footnote syntax") @@ -37,6 +39,12 @@ func main() { defer stopPProf() w := bufio.NewWriter(os.Stdout) - p.Markdown(r, markdown.ToHTML(w)) + + switch *format { + case "groff-mm": + p.Markdown(r, markdown.ToGroffMM(w)) + default: + p.Markdown(r, markdown.ToHTML(w)) + } w.Flush() } diff --git a/markdown_test.go b/markdown_test.go index 72966ab..d864850 100644 --- a/markdown_test.go +++ b/markdown_test.go @@ -25,22 +25,28 @@ func runDirTests(dir string, t *testing.T) { t.Fatal(err) } + var buf bytes.Buffer + fHTML := ToHTML(&buf) + fGroff := ToGroffMM(&buf) p := NewParser(nil) for _, name := range names { if filepath.Ext(name) != ".text" { continue } - if err = compareOutput(filepath.Join(dirPath, name), p); err != nil { + if err = compareOutput(&buf, fHTML, ".html", filepath.Join(dirPath, name), p); err != nil { + t.Error(err) + } + if err = compareOutput(&buf, fGroff, ".mm", filepath.Join(dirPath, name), p); err != nil { t.Error(err) } } } // Compare the output of the C-based peg-markdown, which -// is, for each test, available in a .html file accompanying the -// .text file, with the output of this package's Markdown processor. -func compareOutput(textPath string, p *Parser) (err error) { - var bOrig, bThis bytes.Buffer +// is, for each test, available in either a .html or a .mm file accompanying +// the .text file, with the output of this package's Markdown processor. +func compareOutput(w *bytes.Buffer, f Formatter, ext string, textPath string, p *Parser) (err error) { + var bOrig bytes.Buffer r, err := os.Open(textPath) if err != nil { @@ -48,22 +54,21 @@ func compareOutput(textPath string, p *Parser) (err error) { } defer r.Close() - bThis.Reset() - out := ToHTML(&bThis) - p.Markdown(r, out) + w.Reset() + p.Markdown(r, f) - // replace .text extension by .html + // replace .text extension by `ext' base := textPath[:len(textPath)-len(".text")] - htmlPath := base + ".html" + refPath := base + ext - r, err = os.Open(htmlPath) + r, err = os.Open(refPath) if err != nil { return } defer r.Close() bOrig.ReadFrom(r) - if bytes.Compare(bOrig.Bytes(), bThis.Bytes()) != 0 { - err = fmt.Errorf("test %q failed", base) + if bytes.Compare(bOrig.Bytes(), w.Bytes()) != 0 { + err = fmt.Errorf("test %q failed", refPath) } return } diff --git a/out-groffmm.go b/out-groffmm.go new file mode 100644 index 0000000..4a5ec00 --- /dev/null +++ b/out-groffmm.go @@ -0,0 +1,196 @@ +/* Original C version https://github.com/jgm/peg-markdown/ + * Copyright 2008 John MacFarlane (jgm at berkeley dot edu). + * + * Modifications and translation from C into Go + * based on markdown_output.c + * Copyright 2010 Michael Teichgräber (mt at wmipf dot de) + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License or the MIT + * license. See LICENSE for details. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + */ + +package markdown + +// groff mm output functions + +import ( + "log" + "strings" +) + +type troffOut struct { + baseWriter + inListItem bool + escape *strings.Replacer +} + +// Returns a formatter that writes the document in groff mm format. +func ToGroffMM(w Writer) Formatter { + f := new(troffOut) + f.baseWriter = baseWriter{w, 2} + f.escape = strings.NewReplacer(`\`, `\e`) + return f +} +func (f *troffOut) FormatBlock(tree *element) { + f.elist(tree) +} +func (f *troffOut) Finish() { + f.WriteByte('\n') + f.padded = 2 +} + +func (h *troffOut) sp() *troffOut { + h.pad(2) + return h +} +func (h *troffOut) br() *troffOut { + h.pad(1) + return h +} + +func (h *troffOut) skipPadding() *troffOut { + h.padded = 2 + return h +} + +// write a string +func (w *troffOut) s(s string) *troffOut { + w.WriteString(s) + return w +} + +// write string, escape '\' +func (w *troffOut) str(s string) *troffOut { + w.escape.WriteString(w, s) + return w +} + +func (w *troffOut) children(el *element) *troffOut { + return w.elist(el.children) +} +func (w *troffOut) inline(pfx string, el *element, sfx string) *troffOut { + return w.s(pfx).children(el).s(sfx) +} + +func (w *troffOut) req(name string) *troffOut { + return w.br().s(".").s(name) +} + +// write a list of elements +func (w *troffOut) elist(list *element) *troffOut { + for i := 0; list != nil; i++ { + w.elem(list, i == 0) + list = list.next + } + return w +} + +func (w *troffOut) elem(elt *element, isFirst bool) *troffOut { + var s string + + switch elt.key { + case SPACE: + s = elt.contents.str + case LINEBREAK: + w.req("br\n") + case STR: + w.str(elt.contents.str) + case ELLIPSIS: + s = "..." + case EMDASH: + s = `\[em]` + case ENDASH: + s = `\[en]` + case APOSTROPHE: + s = "'" + case SINGLEQUOTED: + w.inline("`", elt, "'") + case DOUBLEQUOTED: + w.inline(`\[lq]`, elt, `\[rq]`) + case CODE: + w.s(`\fC`).str(elt.contents.str).s(`\fR`) + case HTML: + /* don't print HTML */ + case LINK: + link := elt.contents.link + w.elist(link.label) + w.s(" (").s(link.url).s(")") + case IMAGE: + w.s("[IMAGE: ").elist(elt.contents.link.label).s("]") + /* not supported */ + case EMPH: + w.inline(`\fI`, elt, `\fR`) + case STRONG: + w.inline(`\fB`, elt, `\fR`) + case LIST: + w.children(elt) + case RAW: + /* Shouldn't occur - these are handled by process_raw_blocks() */ + log.Fatalf("RAW") + case H1, H2, H3, H4, H5, H6: + h := ".H " + string('1'+elt.key-H1) + ` "` /* assumes H1 ... H6 are in order */ + w.br().inline(h, elt, `"`) + case PLAIN: + w.br().children(elt) + case PARA: + if !w.inListItem || !isFirst { + w.req("P\n").children(elt) + } else { + w.br().children(elt) + } + case HRULE: + w.br().s(`\l'\n(.lu*8u/10u'`) + case HTMLBLOCK: + /* don't print HTML block */ + case VERBATIM: + w.req("VERBON 2\n") + w.str(elt.contents.str) + w.s(".VERBOFF") + case BULLETLIST: + w.req("BL").children(elt).req("LE 1") + case ORDEREDLIST: + w.req("AL").children(elt).req("LE 1") + case DEFINITIONLIST: + w.req(`BVL \\n(Pin`).children(elt).req("LE 1") + case DEFTITLE: + w.req(`DLI "`).children(elt).s(`"`) + case DEFDATA: + w.children(elt) + w.req("br") + case LISTITEM: + w.req("LI\n") + w.inListItem = true + w.skipPadding() + w.children(elt) + w.inListItem = false + case BLOCKQUOTE: + w.req("DS I\n") + w.skipPadding() + w.children(elt) + w.req("DE") + case NOTE: + /* if contents.str == 0, then print note; else ignore, since this + * is a note block that has been incorporated into the notes list */ + if elt.contents.str == "" { + w.s("\\*F\n") + w.s(".FS\n") + w.skipPadding() + w.children(elt) + w.req("FE") + } + case REFERENCE: + /* Nonprinting */ + default: + log.Fatalf("troffOut.elem encountered unknown element key = %d\n", elt.key) + } + if s != "" { + w.s(s) + } + return w +} diff --git a/tests/gen.rc b/tests/gen.rc index 710ea4d..d9cbeaf 100644 --- a/tests/gen.rc +++ b/tests/gen.rc @@ -3,4 +3,5 @@ pmd=../../,,pmd/markdown for (i in *.text) { stem=`{echo $i | sed 's,.text$,,'} $pmd < $i >$"stem.html + $pmd -t groff-mm < $i >$"stem.mm } diff --git a/tests/md1.0.3/Amps and angle encoding.mm b/tests/md1.0.3/Amps and angle encoding.mm new file mode 100644 index 0000000..13913e9 --- /dev/null +++ b/tests/md1.0.3/Amps and angle encoding.mm @@ -0,0 +1,18 @@ +.P +AT&T has an ampersand in their name. +.P +ATT is another way to write it. +.P +This & that. +.P +4 < 5. +.P +6 > 5. +.P +Here's a link (http://example.com/?foo=1&bar=2) with an ampersand in the URL. +.P +Here's a link with an amersand in the link text: AT&T (http://att.com/). +.P +Here's an inline link (/script?foo=1&bar=2). +.P +Here's an inline link (/script?foo=1&bar=2). diff --git a/tests/md1.0.3/Auto links.mm b/tests/md1.0.3/Auto links.mm new file mode 100644 index 0000000..fcdf6be --- /dev/null +++ b/tests/md1.0.3/Auto links.mm @@ -0,0 +1,21 @@ +.P +Link: http://example.com/ (http://example.com/). +.P +With an ampersand: http://example.com/?foo=1&bar=2 (http://example.com/?foo=1&bar=2) +.BL +.LI +In a list? +.LI +http://example.com/ (http://example.com/) +.LI +It should. +.LE 1 +.DS I +.P +Blockquoted: http://example.com/ (http://example.com/) +.DE +.P +Auto-links should not occur here: \fC\fR +.VERBON 2 +or here: +.VERBOFF diff --git a/tests/md1.0.3/Backslash escapes.mm b/tests/md1.0.3/Backslash escapes.mm new file mode 100644 index 0000000..5429c3c --- /dev/null +++ b/tests/md1.0.3/Backslash escapes.mm @@ -0,0 +1,118 @@ +.P +These should all get escaped: +.P +Backslash: \e +.P +Backtick: ` +.P +Asterisk: * +.P +Underscore: _ +.P +Left brace: { +.P +Right brace: } +.P +Left bracket: [ +.P +Right bracket: ] +.P +Left paren: ( +.P +Right paren: ) +.P +Greater-than: > +.P +Hash: # +.P +Period: . +.P +Bang: ! +.P +Plus: + +.P +Minus: - +.P +These should not, because they occur within a code block: +.VERBON 2 +Backslash: \e\e + +Backtick: \e` + +Asterisk: \e* + +Underscore: \e_ + +Left brace: \e{ + +Right brace: \e} + +Left bracket: \e[ + +Right bracket: \e] + +Left paren: \e( + +Right paren: \e) + +Greater-than: \e> + +Hash: \e# + +Period: \e. + +Bang: \e! + +Plus: \e+ + +Minus: \e- +.VERBOFF +.P +Nor should these, which occur in code spans: +.P +Backslash: \fC\e\e\fR +.P +Backtick: \fC\e`\fR +.P +Asterisk: \fC\e*\fR +.P +Underscore: \fC\e_\fR +.P +Left brace: \fC\e{\fR +.P +Right brace: \fC\e}\fR +.P +Left bracket: \fC\e[\fR +.P +Right bracket: \fC\e]\fR +.P +Left paren: \fC\e(\fR +.P +Right paren: \fC\e)\fR +.P +Greater-than: \fC\e>\fR +.P +Hash: \fC\e#\fR +.P +Period: \fC\e.\fR +.P +Bang: \fC\e!\fR +.P +Plus: \fC\e+\fR +.P +Minus: \fC\e-\fR +.P +These should get escaped, even though they're matching pairs for +other Markdown constructs: +.P +*asterisks* +.P +_underscores_ +.P +`backticks` +.P +This is a code span with a literal backslash-backtick sequence: \fC\e`\fR +.P +This is a tag with unescaped backticks bar. +.P +This is a tag with backslashes bar. diff --git a/tests/md1.0.3/Blockquotes with code blocks.mm b/tests/md1.0.3/Blockquotes with code blocks.mm new file mode 100644 index 0000000..5da20cd --- /dev/null +++ b/tests/md1.0.3/Blockquotes with code blocks.mm @@ -0,0 +1,16 @@ +.DS I +.P +Example: +.VERBON 2 +sub status { + print "working"; +} +.VERBOFF +.P +Or: +.VERBON 2 +sub status { + return "working"; +} +.VERBOFF +.DE diff --git a/tests/md1.0.3/Code Blocks.mm b/tests/md1.0.3/Code Blocks.mm new file mode 100644 index 0000000..9464771 --- /dev/null +++ b/tests/md1.0.3/Code Blocks.mm @@ -0,0 +1,19 @@ +.VERBON 2 +code block on the first line +.VERBOFF +.P +Regular text. +.VERBON 2 +code block indented by spaces +.VERBOFF +.P +Regular text. +.VERBON 2 +the lines in this block +all contain trailing spaces +.VERBOFF +.P +Regular Text. +.VERBON 2 +code block on the last line +.VERBOFF diff --git a/tests/md1.0.3/Code Spans.mm b/tests/md1.0.3/Code Spans.mm new file mode 100644 index 0000000..5a8cc7a --- /dev/null +++ b/tests/md1.0.3/Code Spans.mm @@ -0,0 +1,6 @@ +.P +\fC\fR +.P +Fix for backticks within HTML tag: like this +.P +Here's how you put \fC`backticks`\fR in a code span. diff --git a/tests/md1.0.3/Hard-wrapped paragraphs with list-like lines.mm b/tests/md1.0.3/Hard-wrapped paragraphs with list-like lines.mm new file mode 100644 index 0000000..12cf8cc --- /dev/null +++ b/tests/md1.0.3/Hard-wrapped paragraphs with list-like lines.mm @@ -0,0 +1,9 @@ +.P +In Markdown 1.0.0 and earlier. Version +8. This line turns into a list item. +Because a hard-wrapped line in the +middle of a paragraph looked like a +list item. +.P +Here's one with a bullet. +* criminey. diff --git a/tests/md1.0.3/Horizontal rules.mm b/tests/md1.0.3/Horizontal rules.mm new file mode 100644 index 0000000..25cdc01 --- /dev/null +++ b/tests/md1.0.3/Horizontal rules.mm @@ -0,0 +1,48 @@ +.P +Dashes: +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +.VERBON 2 +--- +.VERBOFF +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +.VERBON 2 +- - - +.VERBOFF +.P +Asterisks: +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +.VERBON 2 +*** +.VERBOFF +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +.VERBON 2 +* * * +.VERBOFF +.P +Underscores: +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +.VERBON 2 +___ +.VERBOFF +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +\l'\n(.lu*8u/10u' +.VERBON 2 +_ _ _ +.VERBOFF diff --git a/tests/md1.0.3/Inline HTML (Advanced).mm b/tests/md1.0.3/Inline HTML (Advanced).mm new file mode 100644 index 0000000..d90670d --- /dev/null +++ b/tests/md1.0.3/Inline HTML (Advanced).mm @@ -0,0 +1,4 @@ +.P +Simple block on one line: +.P +And nested without indentation: diff --git a/tests/md1.0.3/Inline HTML (Simple).mm b/tests/md1.0.3/Inline HTML (Simple).mm new file mode 100644 index 0000000..2656820 --- /dev/null +++ b/tests/md1.0.3/Inline HTML (Simple).mm @@ -0,0 +1,40 @@ +.P +Here's a simple block: +.P +This should be a code block, though: +.VERBON 2 +
+ foo +
+.VERBOFF +.P +As should this: +.VERBON 2 +
foo
+.VERBOFF +.P +Now, nested: +.P +This should just be an HTML comment: +.P +Multiline: +.P +Code block: +.VERBON 2 + +.VERBOFF +.P +Just plain comment, with trailing spaces on the line: +.P +Code: +.VERBON 2 +
+.VERBOFF +.P +Hr's: +.P + +.P + +.P + diff --git a/tests/md1.0.3/Inline HTML comments.mm b/tests/md1.0.3/Inline HTML comments.mm new file mode 100644 index 0000000..6eb63b8 --- /dev/null +++ b/tests/md1.0.3/Inline HTML comments.mm @@ -0,0 +1,6 @@ +.P +Paragraph one. +.P +Paragraph two. +.P +The end. diff --git a/tests/md1.0.3/Links, inline style.mm b/tests/md1.0.3/Links, inline style.mm new file mode 100644 index 0000000..a0ead8d --- /dev/null +++ b/tests/md1.0.3/Links, inline style.mm @@ -0,0 +1,12 @@ +.P +Just a URL (/url/). +.P +URL and title (/url/). +.P +URL and title (/url/). +.P +URL and title (/url/). +.P +URL and title (/url/). +.P +Empty (). diff --git a/tests/md1.0.3/Links, reference style.mm b/tests/md1.0.3/Links, reference style.mm new file mode 100644 index 0000000..2cf1a47 --- /dev/null +++ b/tests/md1.0.3/Links, reference style.mm @@ -0,0 +1,51 @@ +.P +Foo bar (/url/). +.P +Foo bar (/url/). +.P +Foo bar (/url/). +.P +With embedded [brackets] (/url/). +.P +Indented once (/url). +.P +Indented twice (/url). +.P +Indented thrice (/url). +.P +Indented [four][] times. +.VERBON 2 +[four]: /url +.VERBOFF +\l'\n(.lu*8u/10u' +.P +this (foo) should work +.P +So should this (foo). +.P +And this (foo). +.P +And this (foo). +.P +And this (foo). +.P +But not [that] []. +.P +Nor [that][]. +.P +Nor [that]. +.P +[Something in brackets like this (foo) should work] +.P +[Same with this (foo).] +.P +In this case, this (/somethingelse/) points to something else. +.P +Backslashing should suppress [this] and [this]. +\l'\n(.lu*8u/10u' +.P +Here's one where the link +breaks (/url/) across lines. +.P +Here's another where the link +breaks (/url/) across lines, but with a line-ending space. diff --git a/tests/md1.0.3/Links, shortcut references.mm b/tests/md1.0.3/Links, shortcut references.mm new file mode 100644 index 0000000..9f9a466 --- /dev/null +++ b/tests/md1.0.3/Links, shortcut references.mm @@ -0,0 +1,10 @@ +.P +This is the simple case (/simple). +.P +This one has a line +break (/foo). +.P +This one has a line +break (/foo) with a line-ending space. +.P +this (/that) and the other (/other) diff --git a/tests/md1.0.3/Literal quotes in titles.mm b/tests/md1.0.3/Literal quotes in titles.mm new file mode 100644 index 0000000..4510639 --- /dev/null +++ b/tests/md1.0.3/Literal quotes in titles.mm @@ -0,0 +1,4 @@ +.P +Foo bar (/url/). +.P +Foo bar (/url/). diff --git a/tests/md1.0.3/Markdown Documentation - Basics.mm b/tests/md1.0.3/Markdown Documentation - Basics.mm new file mode 100644 index 0000000..cadac2d --- /dev/null +++ b/tests/md1.0.3/Markdown Documentation - Basics.mm @@ -0,0 +1,299 @@ +.H 1 "Markdown: Basics" +.H 2 "Getting the Gist of Markdown's Formatting Syntax" +.P +This page offers a brief overview of what it's like to use Markdown. +The syntax page (/projects/markdown/syntax) provides complete, detailed documentation for +every feature, but Markdown should be very easy to pick up simply by +looking at a few examples of it in action. The examples on this page +are written in a before/after style, showing example syntax and the +HTML output produced by Markdown. +.P +It's also helpful to simply try Markdown out; the Dingus (/projects/markdown/dingus) is a +web application that allows you type your own Markdown-formatted text +and translate it to XHTML. +.P +\fBNote:\fR This document is itself written using Markdown; you +can see the source for it by adding '.text' to the URL (/projects/markdown/basics.text). +.H 2 "Paragraphs, Headers, Blockquotes" +.P +A paragraph is simply one or more consecutive lines of text, separated +by one or more blank lines. (A blank line is any line that looks like a +blank line -- a line containing nothing spaces or tabs is considered +blank.) Normal paragraphs should not be intended with spaces or tabs. +.P +Markdown offers two styles of headers: \fISetext\fR and \fIatx\fR. +Setext-style headers for \fC

\fR and \fC

\fR are created by +"underlining" with equal signs (\fC=\fR) and hyphens (\fC-\fR), respectively. +To create an atx-style header, you put 1-6 hash marks (\fC#\fR) at the +beginning of the line -- the number of hashes equals the resulting +HTML header level. +.P +Blockquotes are indicated using email-style '\fC>\fR' angle brackets. +.P +Markdown: +.VERBON 2 +A First Level Header +==================== + +A Second Level Header +--------------------- + +Now is the time for all good men to come to +the aid of their country. This is just a +regular paragraph. + +The quick brown fox jumped over the lazy +dog's back. + +### Header 3 + +> This is a blockquote. +> +> This is the second paragraph in the blockquote. +> +> ## This is an H2 in a blockquote +.VERBOFF +.P +Output: +.VERBON 2 +

A First Level Header

+ +

A Second Level Header

+ +

Now is the time for all good men to come to +the aid of their country. This is just a +regular paragraph.

+ +

The quick brown fox jumped over the lazy +dog's back.

+ +

Header 3

+ +
+

This is a blockquote.

+ +

This is the second paragraph in the blockquote.

+ +

This is an H2 in a blockquote

+
+.VERBOFF +.H 3 "Phrase Emphasis" +.P +Markdown uses asterisks and underscores to indicate spans of emphasis. +.P +Markdown: +.VERBON 2 +Some of these words *are emphasized*. +Some of these words _are emphasized also_. + +Use two asterisks for **strong emphasis**. +Or, if you prefer, __use two underscores instead__. +.VERBOFF +.P +Output: +.VERBON 2 +

Some of these words are emphasized. +Some of these words are emphasized also.

+ +

Use two asterisks for strong emphasis. +Or, if you prefer, use two underscores instead.

+.VERBOFF +.H 2 "Lists" +.P +Unordered (bulleted) lists use asterisks, pluses, and hyphens (\fC*\fR, +\fC+\fR, and \fC-\fR) as list markers. These three markers are +interchangable; this: +.VERBON 2 +* Candy. +* Gum. +* Booze. +.VERBOFF +.P +this: +.VERBON 2 ++ Candy. ++ Gum. ++ Booze. +.VERBOFF +.P +and this: +.VERBON 2 +- Candy. +- Gum. +- Booze. +.VERBOFF +.P +all produce the same output: +.VERBON 2 +
    +
  • Candy.
  • +
  • Gum.
  • +
  • Booze.
  • +
+.VERBOFF +.P +Ordered (numbered) lists use regular numbers, followed by periods, as +list markers: +.VERBON 2 +1. Red +2. Green +3. Blue +.VERBOFF +.P +Output: +.VERBON 2 +
    +
  1. Red
  2. +
  3. Green
  4. +
  5. Blue
  6. +
+.VERBOFF +.P +If you put blank lines between items, you'll get \fC

\fR tags for the +list item text. You can create multi-paragraph list items by indenting +the paragraphs by 4 spaces or 1 tab: +.VERBON 2 +* A list item. + + With multiple paragraphs. + +* Another item in the list. +.VERBOFF +.P +Output: +.VERBON 2 +

    +
  • A list item.

    +

    With multiple paragraphs.

  • +
  • Another item in the list.

  • +
+.VERBOFF +.H 3 "Links" +.P +Markdown supports two styles for creating links: \fIinline\fR and +\fIreference\fR. With both styles, you use square brackets to delimit the +text you want to turn into a link. +.P +Inline-style links use parentheses immediately after the link text. +For example: +.VERBON 2 +This is an [example link](http://example.com/). +.VERBOFF +.P +Output: +.VERBON 2 +

This is an +example link.

+.VERBOFF +.P +Optionally, you may include a title attribute in the parentheses: +.VERBON 2 +This is an [example link](http://example.com/ "With a Title"). +.VERBOFF +.P +Output: +.VERBON 2 +

This is an +example link.

+.VERBOFF +.P +Reference-style links allow you to refer to your links by names, which +you define elsewhere in your document: +.VERBON 2 +I get 10 times more traffic from [Google][1] than from +[Yahoo][2] or [MSN][3]. + +[1]: http://google.com/ "Google" +[2]: http://search.yahoo.com/ "Yahoo Search" +[3]: http://search.msn.com/ "MSN Search" +.VERBOFF +.P +Output: +.VERBON 2 +

I get 10 times more traffic from Google than from Yahoo or MSN.

+.VERBOFF +.P +The title attribute is optional. Link names may contain letters, +numbers and spaces, but are \fInot\fR case sensitive: +.VERBON 2 +I start my morning with a cup of coffee and +[The New York Times][NY Times]. + +[ny times]: http://www.nytimes.com/ +.VERBOFF +.P +Output: +.VERBON 2 +

I start my morning with a cup of coffee and +The New York Times.

+.VERBOFF +.H 3 "Images" +.P +Image syntax is very much like link syntax. +.P +Inline (titles are optional): +.VERBON 2 +![alt text](/path/to/img.jpg "Title") +.VERBOFF +.P +Reference-style: +.VERBON 2 +![alt text][id] + +[id]: /path/to/img.jpg "Title" +.VERBOFF +.P +Both of the above examples produce the same output: +.VERBON 2 +alt text +.VERBOFF +.H 3 "Code" +.P +In a regular paragraph, you can create code span by wrapping text in +backtick quotes. Any ampersands (\fC&\fR) and angle brackets (\fC<\fR or +\fC>\fR) will automatically be translated into HTML entities. This makes +it easy to use Markdown to write about HTML example code: +.VERBON 2 +I strongly recommend against using any `` tags. + +I wish SmartyPants used named entities like `—` +instead of decimal-encoded entites like `—`. +.VERBOFF +.P +Output: +.VERBON 2 +

I strongly recommend against using any +<blink> tags.

+ +

I wish SmartyPants used named entities like +&mdash; instead of decimal-encoded +entites like &#8212;.

+.VERBOFF +.P +To specify an entire block of pre-formatted code, indent every line of +the block by 4 spaces or 1 tab. Just like with code spans, \fC&\fR, \fC<\fR, +and \fC>\fR characters will be escaped automatically. +.P +Markdown: +.VERBON 2 +If you want your page to validate under XHTML 1.0 Strict, +you've got to put paragraph tags in your blockquotes: + +
+

For example.

+
+.VERBOFF +.P +Output: +.VERBON 2 +

If you want your page to validate under XHTML 1.0 Strict, +you've got to put paragraph tags in your blockquotes:

+ +
<blockquote>
+    <p>For example.</p>
+</blockquote>
+
+.VERBOFF diff --git a/tests/md1.0.3/Markdown Documentation - Syntax.mm b/tests/md1.0.3/Markdown Documentation - Syntax.mm new file mode 100644 index 0000000..0cbef78 --- /dev/null +++ b/tests/md1.0.3/Markdown Documentation - Syntax.mm @@ -0,0 +1,916 @@ +.H 1 "Markdown: Syntax" +.BL +.LI +Overview (#overview) +.BL +.LI +Philosophy (#philosophy) +.LI +Inline HTML (#html) +.LI +Automatic Escaping for Special Characters (#autoescape) +.LE 1 +.LI +Block Elements (#block) +.BL +.LI +Paragraphs and Line Breaks (#p) +.LI +Headers (#header) +.LI +Blockquotes (#blockquote) +.LI +Lists (#list) +.LI +Code Blocks (#precode) +.LI +Horizontal Rules (#hr) +.LE 1 +.LI +Span Elements (#span) +.BL +.LI +Links (#link) +.LI +Emphasis (#em) +.LI +Code (#code) +.LI +Images (#img) +.LE 1 +.LI +Miscellaneous (#misc) +.BL +.LI +Backslash Escapes (#backslash) +.LI +Automatic Links (#autolink) +.LE 1 +.LE 1 +.P +\fBNote:\fR This document is itself written using Markdown; you +can see the source for it by adding '.text' to the URL (/projects/markdown/syntax.text). +\l'\n(.lu*8u/10u' +.P +Markdown is intended to be as easy-to-read and easy-to-write as is feasible. +.P +Readability, however, is emphasized above all else. A Markdown-formatted +document should be publishable as-is, as plain text, without looking +like it's been marked up with tags or formatting instructions. While +Markdown's syntax has been influenced by several existing text-to-HTML +filters -- including Setext (http://docutils.sourceforge.net/mirror/setext.html), atx (http://www.aaronsw.com/2002/atx/), Textile (http://textism.com/tools/textile/), reStructuredText (http://docutils.sourceforge.net/rst.html), +Grutatext (http://www.triptico.com/software/grutatxt.html), and EtText (http://ettext.taint.org/doc/) -- the single biggest source of +inspiration for Markdown's syntax is the format of plain text email. +.P +To this end, Markdown's syntax is comprised entirely of punctuation +characters, which punctuation characters have been carefully chosen so +as to look like what they mean. E.g., asterisks around a word actually +look like *emphasis*. Markdown lists look like, well, lists. Even +blockquotes look like quoted passages of text, assuming you've ever +used email. +.P +Markdown's syntax is intended for one purpose: to be used as a +format for \fIwriting\fR for the web. +.P +Markdown is not a replacement for HTML, or even close to it. Its +syntax is very small, corresponding only to a very small subset of +HTML tags. The idea is \fInot\fR to create a syntax that makes it easier +to insert HTML tags. In my opinion, HTML tags are already easy to +insert. The idea for Markdown is to make it easy to read, write, and +edit prose. HTML is a \fIpublishing\fR format; Markdown is a \fIwriting\fR +format. Thus, Markdown's formatting syntax only addresses issues that +can be conveyed in plain text. +.P +For any markup that is not covered by Markdown's syntax, you simply +use HTML itself. There's no need to preface it or delimit it to +indicate that you're switching from Markdown to HTML; you just use +the tags. +.P +The only restrictions are that block-level HTML elements -- e.g. \fC
\fR, +\fC\fR, \fC
\fR, \fC

\fR, etc. -- must be separated from surrounding +content by blank lines, and the start and end tags of the block should +not be indented with tabs or spaces. Markdown is smart enough not +to add extra (unwanted) \fC

\fR tags around HTML block-level tags. +.P +For example, to add an HTML table to a Markdown article: +.VERBON 2 +This is a regular paragraph. + +

+ + + +
Foo
+ +This is another regular paragraph. +.VERBOFF +.P +Note that Markdown formatting syntax is not processed within block-level +HTML tags. E.g., you can't use Markdown-style \fC*emphasis*\fR inside an +HTML block. +.P +Span-level HTML tags -- e.g. \fC\fR, \fC\fR, or \fC\fR -- can be +used anywhere in a Markdown paragraph, list item, or header. If you +want, you can even use HTML tags instead of Markdown formatting; e.g. if +you'd prefer to use HTML \fC\fR or \fC\fR tags instead of Markdown's +link or image syntax, go right ahead. +.P +Unlike block-level HTML tags, Markdown syntax \fIis\fR processed within +span-level tags. +.P +In HTML, there are two characters that demand special treatment: \fC<\fR +and \fC&\fR. Left angle brackets are used to start tags; ampersands are +used to denote HTML entities. If you want to use them as literal +characters, you must escape them as entities, e.g. \fC<\fR, and +\fC&\fR. +.P +Ampersands in particular are bedeviling for web writers. If you want to +write about 'AT&T', you need to write '\fCAT&T\fR'. You even need to +escape ampersands within URLs. Thus, if you want to link to: +.VERBON 2 +http://images.google.com/images?num=30&q=larry+bird +.VERBOFF +.P +you need to encode the URL as: +.VERBON 2 +http://images.google.com/images?num=30&q=larry+bird +.VERBOFF +.P +in your anchor tag \fChref\fR attribute. Needless to say, this is easy to +forget, and is probably the single most common source of HTML validation +errors in otherwise well-marked-up web sites. +.P +Markdown allows you to use these characters naturally, taking care of +all the necessary escaping for you. If you use an ampersand as part of +an HTML entity, it remains unchanged; otherwise it will be translated +into \fC&\fR. +.P +So, if you want to include a copyright symbol in your article, you can write: +.VERBON 2 +© +.VERBOFF +.P +and Markdown will leave it alone. But if you write: +.VERBON 2 +AT&T +.VERBOFF +.P +Markdown will translate it to: +.VERBON 2 +AT&T +.VERBOFF +.P +Similarly, because Markdown supports inline HTML (#html), if you use +angle brackets as delimiters for HTML tags, Markdown will treat them as +such. But if you write: +.VERBON 2 +4 < 5 +.VERBOFF +.P +Markdown will translate it to: +.VERBON 2 +4 < 5 +.VERBOFF +.P +However, inside Markdown code spans and blocks, angle brackets and +ampersands are \fIalways\fR encoded automatically. This makes it easy to use +Markdown to write about HTML code. (As opposed to raw HTML, which is a +terrible format for writing about HTML syntax, because every single \fC<\fR +and \fC&\fR in your example code needs to be escaped.) +\l'\n(.lu*8u/10u' +.P +A paragraph is simply one or more consecutive lines of text, separated +by one or more blank lines. (A blank line is any line that looks like a +blank line -- a line containing nothing but spaces or tabs is considered +blank.) Normal paragraphs should not be intended with spaces or tabs. +.P +The implication of the "one or more consecutive lines of text" rule is +that Markdown supports "hard-wrapped" text paragraphs. This differs +significantly from most other text-to-HTML formatters (including Movable +Type's "Convert Line Breaks" option) which translate every line break +character in a paragraph into a \fC
\fR tag. +.P +When you \fIdo\fR want to insert a \fC
\fR break tag using Markdown, you +end a line with two or more spaces, then type return. +.P +Yes, this takes a tad more effort to create a \fC
\fR, but a simplistic +"every line break is a \fC
\fR" rule wouldn't work for Markdown. +Markdown's email-style blockquoting (#blockquote) and multi-paragraph list items (#list) +work best -- and look better -- when you format them with hard breaks. +.P +Markdown supports two styles of headers, Setext (http://docutils.sourceforge.net/mirror/setext.html) and atx (http://www.aaronsw.com/2002/atx/). +.P +Setext-style headers are "underlined" using equal signs (for first-level +headers) and dashes (for second-level headers). For example: +.VERBON 2 +This is an H1 +============= + +This is an H2 +------------- +.VERBOFF +.P +Any number of underlining \fC=\fR's or \fC-\fR's will work. +.P +Atx-style headers use 1-6 hash characters at the start of the line, +corresponding to header levels 1-6. For example: +.VERBON 2 +# This is an H1 + +## This is an H2 + +###### This is an H6 +.VERBOFF +.P +Optionally, you may "close" atx-style headers. This is purely +cosmetic -- you can use this if you think it looks better. The +closing hashes don't even need to match the number of hashes +used to open the header. (The number of opening hashes +determines the header level.) : +.VERBON 2 +# This is an H1 # + +## This is an H2 ## + +### This is an H3 ###### +.VERBOFF +.P +Markdown uses email-style \fC>\fR characters for blockquoting. If you're +familiar with quoting passages of text in an email message, then you +know how to create a blockquote in Markdown. It looks best if you hard +wrap the text and put a \fC>\fR before every line: +.VERBON 2 +> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, +> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. +> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. +> +> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse +> id sem consectetuer libero luctus adipiscing. +.VERBOFF +.P +Markdown allows you to be lazy and only put the \fC>\fR before the first +line of a hard-wrapped paragraph: +.VERBON 2 +> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, +consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. +Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. + +> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse +id sem consectetuer libero luctus adipiscing. +.VERBOFF +.P +Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by +adding additional levels of \fC>\fR: +.VERBON 2 +> This is the first level of quoting. +> +> > This is nested blockquote. +> +> Back to the first level. +.VERBOFF +.P +Blockquotes can contain other Markdown elements, including headers, lists, +and code blocks: +.VERBON 2 +> ## This is a header. +> +> 1. This is the first list item. +> 2. This is the second list item. +> +> Here's some example code: +> +> return shell_exec("echo $input | $markdown_script"); +.VERBOFF +.P +Any decent text editor should make email-style quoting easy. For +example, with BBEdit, you can make a selection and choose Increase +Quote Level from the Text menu. +.P +Markdown supports ordered (numbered) and unordered (bulleted) lists. +.P +Unordered lists use asterisks, pluses, and hyphens -- interchangably +-- as list markers: +.VERBON 2 +* Red +* Green +* Blue +.VERBOFF +.P +is equivalent to: +.VERBON 2 ++ Red ++ Green ++ Blue +.VERBOFF +.P +and: +.VERBON 2 +- Red +- Green +- Blue +.VERBOFF +.P +Ordered lists use numbers followed by periods: +.VERBON 2 +1. Bird +2. McHale +3. Parish +.VERBOFF +.P +It's important to note that the actual numbers you use to mark the +list have no effect on the HTML output Markdown produces. The HTML +Markdown produces from the above list is: +.VERBON 2 +
    +
  1. Bird
  2. +
  3. McHale
  4. +
  5. Parish
  6. +
+.VERBOFF +.P +If you instead wrote the list in Markdown like this: +.VERBON 2 +1. Bird +1. McHale +1. Parish +.VERBOFF +.P +or even: +.VERBON 2 +3. Bird +1. McHale +8. Parish +.VERBOFF +.P +you'd get the exact same HTML output. The point is, if you want to, +you can use ordinal numbers in your ordered Markdown lists, so that +the numbers in your source match the numbers in your published HTML. +But if you want to be lazy, you don't have to. +.P +If you do use lazy list numbering, however, you should still start the +list with the number 1. At some point in the future, Markdown may support +starting ordered lists at an arbitrary number. +.P +List markers typically start at the left margin, but may be indented by +up to three spaces. List markers must be followed by one or more spaces +or a tab. +.P +To make lists look nice, you can wrap items with hanging indents: +.VERBON 2 +* Lorem ipsum dolor sit amet, consectetuer adipiscing elit. + Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, + viverra nec, fringilla in, laoreet vitae, risus. +* Donec sit amet nisl. Aliquam semper ipsum sit amet velit. + Suspendisse id sem consectetuer libero luctus adipiscing. +.VERBOFF +.P +But if you want to be lazy, you don't have to: +.VERBON 2 +* Lorem ipsum dolor sit amet, consectetuer adipiscing elit. +Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, +viverra nec, fringilla in, laoreet vitae, risus. +* Donec sit amet nisl. Aliquam semper ipsum sit amet velit. +Suspendisse id sem consectetuer libero luctus adipiscing. +.VERBOFF +.P +If list items are separated by blank lines, Markdown will wrap the +items in \fC

\fR tags in the HTML output. For example, this input: +.VERBON 2 +* Bird +* Magic +.VERBOFF +.P +will turn into: +.VERBON 2 +

    +
  • Bird
  • +
  • Magic
  • +
+.VERBOFF +.P +But this: +.VERBON 2 +* Bird + +* Magic +.VERBOFF +.P +will turn into: +.VERBON 2 +
    +
  • Bird

  • +
  • Magic

  • +
+.VERBOFF +.P +List items may consist of multiple paragraphs. Each subsequent +paragraph in a list item must be intended by either 4 spaces +or one tab: +.VERBON 2 +1. This is a list item with two paragraphs. Lorem ipsum dolor + sit amet, consectetuer adipiscing elit. Aliquam hendrerit + mi posuere lectus. + + Vestibulum enim wisi, viverra nec, fringilla in, laoreet + vitae, risus. Donec sit amet nisl. Aliquam semper ipsum + sit amet velit. + +2. Suspendisse id sem consectetuer libero luctus adipiscing. +.VERBOFF +.P +It looks nice if you indent every line of the subsequent +paragraphs, but here again, Markdown will allow you to be +lazy: +.VERBON 2 +* This is a list item with two paragraphs. + + This is the second paragraph in the list item. You're +only required to indent the first line. Lorem ipsum dolor +sit amet, consectetuer adipiscing elit. + +* Another item in the same list. +.VERBOFF +.P +To put a blockquote within a list item, the blockquote's \fC>\fR +delimiters need to be indented: +.VERBON 2 +* A list item with a blockquote: + + > This is a blockquote + > inside a list item. +.VERBOFF +.P +To put a code block within a list item, the code block needs +to be indented \fItwice\fR -- 8 spaces or two tabs: +.VERBON 2 +* A list item with a code block: + + +.VERBOFF +.P +It's worth noting that it's possible to trigger an ordered list by +accident, by writing something like this: +.VERBON 2 +1986. What a great season. +.VERBOFF +.P +In other words, a \fInumber-period-space\fR sequence at the beginning of a +line. To avoid this, you can backslash-escape the period: +.VERBON 2 +1986\e. What a great season. +.VERBOFF +.P +Pre-formatted code blocks are used for writing about programming or +markup source code. Rather than forming normal paragraphs, the lines +of a code block are interpreted literally. Markdown wraps a code block +in both \fC
\fR and \fC\fR tags.
+.P
+To produce a code block in Markdown, simply indent every line of the
+block by at least 4 spaces or 1 tab. For example, given this input:
+.VERBON 2
+This is a normal paragraph:
+
+    This is a code block.
+.VERBOFF
+.P
+Markdown will generate:
+.VERBON 2
+

This is a normal paragraph:

+ +
This is a code block.
+
+.VERBOFF +.P +One level of indentation -- 4 spaces or 1 tab -- is removed from each +line of the code block. For example, this: +.VERBON 2 +Here is an example of AppleScript: + + tell application "Foo" + beep + end tell +.VERBOFF +.P +will turn into: +.VERBON 2 +

Here is an example of AppleScript:

+ +
tell application "Foo"
+    beep
+end tell
+
+.VERBOFF +.P +A code block continues until it reaches a line that is not indented +(or the end of the article). +.P +Within a code block, ampersands (\fC&\fR) and angle brackets (\fC<\fR and \fC>\fR) +are automatically converted into HTML entities. This makes it very +easy to include example HTML source code using Markdown -- just paste +it and indent it, and Markdown will handle the hassle of encoding the +ampersands and angle brackets. For example, this: +.VERBON 2 + +.VERBOFF +.P +will turn into: +.VERBON 2 +
<div class="footer">
+    &copy; 2004 Foo Corporation
+</div>
+
+.VERBOFF +.P +Regular Markdown syntax is not processed within code blocks. E.g., +asterisks are just literal asterisks within a code block. This means +it's also easy to use Markdown to write about Markdown's own syntax. +.P +You can produce a horizontal rule tag (\fC
\fR) by placing three or +more hyphens, asterisks, or underscores on a line by themselves. If you +wish, you may use spaces between the hyphens or asterisks. Each of the +following lines will produce a horizontal rule: +.VERBON 2 +* * * + +*** + +***** + +- - - + +--------------------------------------- + +_ _ _ +.VERBOFF +\l'\n(.lu*8u/10u' +.P +Markdown supports two style of links: \fIinline\fR and \fIreference\fR. +.P +In both styles, the link text is delimited by [square brackets]. +.P +To create an inline link, use a set of regular parentheses immediately +after the link text's closing square bracket. Inside the parentheses, +put the URL where you want the link to point, along with an \fIoptional\fR +title for the link, surrounded in quotes. For example: +.VERBON 2 +This is [an example](http://example.com/ "Title") inline link. + +[This link](http://example.net/) has no title attribute. +.VERBOFF +.P +Will produce: +.VERBON 2 +

This is +an example inline link.

+ +

This link has no +title attribute.

+.VERBOFF +.P +If you're referring to a local resource on the same server, you can +use relative paths: +.VERBON 2 +See my [About](/about/) page for details. +.VERBOFF +.P +Reference-style links use a second set of square brackets, inside +which you place a label of your choosing to identify the link: +.VERBON 2 +This is [an example][id] reference-style link. +.VERBOFF +.P +You can optionally use a space to separate the sets of brackets: +.VERBON 2 +This is [an example] [id] reference-style link. +.VERBOFF +.P +Then, anywhere in the document, you define your link label like this, +on a line by itself: +.VERBON 2 +[id]: http://example.com/ "Optional Title Here" +.VERBOFF +.P +That is: +.BL +.LI +Square brackets containing the link identifier (optionally +indented from the left margin using up to three spaces); +.LI +followed by a colon; +.LI +followed by one or more spaces (or tabs); +.LI +followed by the URL for the link; +.LI +optionally followed by a title attribute for the link, enclosed +in double or single quotes. +.LE 1 +.P +The link URL may, optionally, be surrounded by angle brackets: +.VERBON 2 +[id]: "Optional Title Here" +.VERBOFF +.P +You can put the title attribute on the next line and use extra spaces +or tabs for padding, which tends to look better with longer URLs: +.VERBON 2 +[id]: http://example.com/longish/path/to/resource/here + "Optional Title Here" +.VERBOFF +.P +Link definitions are only used for creating links during Markdown +processing, and are stripped from your document in the HTML output. +.P +Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are \fInot\fR case sensitive. E.g. these two links: +.VERBON 2 +[link text][a] +[link text][A] +.VERBOFF +.P +are equivalent. +.P +The \fIimplicit link name\fR shortcut allows you to omit the name of the +link, in which case the link text itself is used as the name. +Just use an empty set of square brackets -- e.g., to link the word +"Google" to the google.com web site, you could simply write: +.VERBON 2 +[Google][] +.VERBOFF +.P +And then define the link: +.VERBON 2 +[Google]: http://google.com/ +.VERBOFF +.P +Because link names may contain spaces, this shortcut even works for +multiple words in the link text: +.VERBON 2 +Visit [Daring Fireball][] for more information. +.VERBOFF +.P +And then define the link: +.VERBON 2 +[Daring Fireball]: http://daringfireball.net/ +.VERBOFF +.P +Link definitions can be placed anywhere in your Markdown document. I +tend to put them immediately after each paragraph in which they're +used, but if you want, you can put them all at the end of your +document, sort of like footnotes. +.P +Here's an example of reference links in action: +.VERBON 2 +I get 10 times more traffic from [Google] [1] than from +[Yahoo] [2] or [MSN] [3]. + + [1]: http://google.com/ "Google" + [2]: http://search.yahoo.com/ "Yahoo Search" + [3]: http://search.msn.com/ "MSN Search" +.VERBOFF +.P +Using the implicit link name shortcut, you could instead write: +.VERBON 2 +I get 10 times more traffic from [Google][] than from +[Yahoo][] or [MSN][]. + + [google]: http://google.com/ "Google" + [yahoo]: http://search.yahoo.com/ "Yahoo Search" + [msn]: http://search.msn.com/ "MSN Search" +.VERBOFF +.P +Both of the above examples will produce the following HTML output: +.VERBON 2 +

I get 10 times more traffic from Google than from +Yahoo +or MSN.

+.VERBOFF +.P +For comparison, here is the same paragraph written using +Markdown's inline link style: +.VERBON 2 +I get 10 times more traffic from [Google](http://google.com/ "Google") +than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or +[MSN](http://search.msn.com/ "MSN Search"). +.VERBOFF +.P +The point of reference-style links is not that they're easier to +write. The point is that with reference-style links, your document +source is vastly more readable. Compare the above examples: using +reference-style links, the paragraph itself is only 81 characters +long; with inline-style links, it's 176 characters; and as raw HTML, +it's 234 characters. In the raw HTML, there's more markup than there +is text. +.P +With Markdown's reference-style links, a source document much more +closely resembles the final output, as rendered in a browser. By +allowing you to move the markup-related metadata out of the paragraph, +you can add links without interrupting the narrative flow of your +prose. +.P +Markdown treats asterisks (\fC*\fR) and underscores (\fC_\fR) as indicators of +emphasis. Text wrapped with one \fC*\fR or \fC_\fR will be wrapped with an +HTML \fC\fR tag; double \fC*\fR's or \fC_\fR's will be wrapped with an HTML +\fC\fR tag. E.g., this input: +.VERBON 2 +*single asterisks* + +_single underscores_ + +**double asterisks** + +__double underscores__ +.VERBOFF +.P +will produce: +.VERBON 2 +single asterisks + +single underscores + +double asterisks + +double underscores +.VERBOFF +.P +You can use whichever style you prefer; the lone restriction is that +the same character must be used to open and close an emphasis span. +.P +Emphasis can be used in the middle of a word: +.VERBON 2 +un*fucking*believable +.VERBOFF +.P +But if you surround an \fC*\fR or \fC_\fR with spaces, it'll be treated as a +literal asterisk or underscore. +.P +To produce a literal asterisk or underscore at a position where it +would otherwise be used as an emphasis delimiter, you can backslash +escape it: +.VERBON 2 +\e*this text is surrounded by literal asterisks\e* +.VERBOFF +.P +To indicate a span of code, wrap it with backtick quotes (\fC`\fR). +Unlike a pre-formatted code block, a code span indicates code within a +normal paragraph. For example: +.VERBON 2 +Use the `printf()` function. +.VERBOFF +.P +will produce: +.VERBON 2 +

Use the printf() function.

+.VERBOFF +.P +To include a literal backtick character within a code span, you can use +multiple backticks as the opening and closing delimiters: +.VERBON 2 +``There is a literal backtick (`) here.`` +.VERBOFF +.P +which will produce this: +.VERBON 2 +

There is a literal backtick (`) here.

+.VERBOFF +.P +The backtick delimiters surrounding a code span may include spaces -- +one after the opening, one before the closing. This allows you to place +literal backtick characters at the beginning or end of a code span: +.VERBON 2 +A single backtick in a code span: `` ` `` + +A backtick-delimited string in a code span: `` `foo` `` +.VERBOFF +.P +will produce: +.VERBON 2 +

A single backtick in a code span: `

+ +

A backtick-delimited string in a code span: `foo`

+.VERBOFF +.P +With a code span, ampersands and angle brackets are encoded as HTML +entities automatically, which makes it easy to include example HTML +tags. Markdown will turn this: +.VERBON 2 +Please don't use any `` tags. +.VERBOFF +.P +into: +.VERBON 2 +

Please don't use any <blink> tags.

+.VERBOFF +.P +You can write this: +.VERBON 2 +`—` is the decimal-encoded equivalent of `—`. +.VERBOFF +.P +to produce: +.VERBON 2 +

&#8212; is the decimal-encoded +equivalent of &mdash;.

+.VERBOFF +.P +Admittedly, it's fairly difficult to devise a "natural" syntax for +placing images into a plain text document format. +.P +Markdown uses an image syntax that is intended to resemble the syntax +for links, allowing for two styles: \fIinline\fR and \fIreference\fR. +.P +Inline image syntax looks like this: +.VERBON 2 +![Alt text](/path/to/img.jpg) + +![Alt text](/path/to/img.jpg "Optional title") +.VERBOFF +.P +That is: +.BL +.LI +An exclamation mark: \fC!\fR; +.LI +followed by a set of square brackets, containing the \fCalt\fR +attribute text for the image; +.LI +followed by a set of parentheses, containing the URL or path to +the image, and an optional \fCtitle\fR attribute enclosed in double +or single quotes. +.LE 1 +.P +Reference-style image syntax looks like this: +.VERBON 2 +![Alt text][id] +.VERBOFF +.P +Where "id" is the name of a defined image reference. Image references +are defined using syntax identical to link references: +.VERBON 2 +[id]: url/to/image "Optional title attribute" +.VERBOFF +.P +As of this writing, Markdown has no syntax for specifying the +dimensions of an image; if this is important to you, you can simply +use regular HTML \fC\fR tags. +\l'\n(.lu*8u/10u' +.P +Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this: +.VERBON 2 + +.VERBOFF +.P +Markdown will turn this into: +.VERBON 2 +http://example.com/ +.VERBOFF +.P +Automatic links for email addresses work similarly, except that +Markdown will also perform a bit of randomized decimal and hex +entity-encoding to help obscure your address from address-harvesting +spambots. For example, Markdown will turn this: +.VERBON 2 + +.VERBOFF +.P +into something like this: +.VERBON 2 +address@exa +mple.com +.VERBOFF +.P +which will render in a browser as a clickable link to "address@example.com". +.P +(This sort of entity-encoding trick will indeed fool many, if not +most, address-harvesting bots, but it definitely won't fool all of +them. It's better than nothing, but an address published in this way +will probably eventually start receiving spam.) +.P +Markdown allows you to use backslash escapes to generate literal +characters which would otherwise have special meaning in Markdown's +formatting syntax. For example, if you wanted to surround a word with +literal asterisks (instead of an HTML \fC\fR tag), you can backslashes +before the asterisks, like this: +.VERBON 2 +\e*literal asterisks\e* +.VERBOFF +.P +Markdown provides backslash escapes for the following characters: +.VERBON 2 +\e backslash +` backtick +* asterisk +_ underscore +{} curly braces +[] square brackets +() parentheses +# hash mark ++ plus sign +- minus sign (hyphen) +. dot +! exclamation mark +.VERBOFF diff --git a/tests/md1.0.3/Nested blockquotes.mm b/tests/md1.0.3/Nested blockquotes.mm new file mode 100644 index 0000000..80394ff --- /dev/null +++ b/tests/md1.0.3/Nested blockquotes.mm @@ -0,0 +1,10 @@ +.DS I +.P +foo +.DS I +.P +bar +.DE +.P +foo +.DE diff --git a/tests/md1.0.3/Ordered and unordered lists.mm b/tests/md1.0.3/Ordered and unordered lists.mm new file mode 100644 index 0000000..36467a6 --- /dev/null +++ b/tests/md1.0.3/Ordered and unordered lists.mm @@ -0,0 +1,178 @@ +.H 2 "Unordered" +.P +Asterisks tight: +.BL +.LI +asterisk 1 +.LI +asterisk 2 +.LI +asterisk 3 +.LE 1 +.P +Asterisks loose: +.BL +.LI +asterisk 1 +.LI +asterisk 2 +.LI +asterisk 3 +.LE 1 +\l'\n(.lu*8u/10u' +.P +Pluses tight: +.BL +.LI +Plus 1 +.LI +Plus 2 +.LI +Plus 3 +.LE 1 +.P +Pluses loose: +.BL +.LI +Plus 1 +.LI +Plus 2 +.LI +Plus 3 +.LE 1 +\l'\n(.lu*8u/10u' +.P +Minuses tight: +.BL +.LI +Minus 1 +.LI +Minus 2 +.LI +Minus 3 +.LE 1 +.P +Minuses loose: +.BL +.LI +Minus 1 +.LI +Minus 2 +.LI +Minus 3 +.LE 1 +.H 2 "Ordered" +.P +Tight: +.AL +.LI +First +.LI +Second +.LI +Third +.LE 1 +.P +and: +.AL +.LI +One +.LI +Two +.LI +Three +.LE 1 +.P +Loose using tabs: +.AL +.LI +First +.LI +Second +.LI +Third +.LE 1 +.P +and using spaces: +.AL +.LI +One +.LI +Two +.LI +Three +.LE 1 +.P +Multiple paragraphs: +.AL +.LI +Item 1, graf one. +.P +Item 2. graf two. The quick brown fox jumped over the lazy dog's +back. +.LI +Item 2. +.LI +Item 3. +.LE 1 +.H 2 "Nested" +.BL +.LI +Tab +.BL +.LI +Tab +.BL +.LI +Tab +.LE 1 +.LE 1 +.LE 1 +.P +Here's another: +.AL +.LI +First +.LI +Second: +.BL +.LI +Fee +.LI +Fie +.LI +Foe +.LE 1 +.LI +Third +.LE 1 +.P +Same thing but with paragraphs: +.AL +.LI +First +.LI +Second: +.BL +.LI +Fee +.LI +Fie +.LI +Foe +.LE 1 +.LI +Third +.LE 1 +.P +This was an error in Markdown 1.0.1: +.BL +.LI +this +.BL +.LI +sub +.LE 1 +.P +that +.LE 1 diff --git a/tests/md1.0.3/Strong and em together.mm b/tests/md1.0.3/Strong and em together.mm new file mode 100644 index 0000000..c95e9f1 --- /dev/null +++ b/tests/md1.0.3/Strong and em together.mm @@ -0,0 +1,8 @@ +.P +\fB\fIThis is strong and em.\fR\fR +.P +So is \fB\fIthis\fR\fR word. +.P +\fB\fIThis is strong and em.\fR\fR +.P +So is \fB\fIthis\fR\fR word. diff --git a/tests/md1.0.3/Tabs.mm b/tests/md1.0.3/Tabs.mm new file mode 100644 index 0000000..b810846 --- /dev/null +++ b/tests/md1.0.3/Tabs.mm @@ -0,0 +1,27 @@ +.BL +.LI +this is a list item +indented with tabs +.LI +this is a list item +indented with spaces +.LE 1 +.P +Code: +.VERBON 2 +this code block is indented by one tab +.VERBOFF +.P +And: +.VERBON 2 + this code block is indented by two tabs +.VERBOFF +.P +And: +.VERBON 2 ++ this is an example list item + indented with tabs + ++ this is an example list item + indented with spaces +.VERBOFF diff --git a/tests/md1.0.3/Tidyness.mm b/tests/md1.0.3/Tidyness.mm new file mode 100644 index 0000000..c0c79a3 --- /dev/null +++ b/tests/md1.0.3/Tidyness.mm @@ -0,0 +1,12 @@ +.DS I +.P +A list within a blockquote: +.BL +.LI +asterisk 1 +.LI +asterisk 2 +.LI +asterisk 3 +.LE 1 +.DE