├── .gitignore
├── CHANGES.md
├── LICENSE
├── Makefile
├── README.md
├── bin
    └── marked-man.js
├── man
    └── marked-man.1
├── package.json
├── src
    ├── extensions.js
    ├── index.js
    ├── renderer.js
    ├── tokenizer.js
    └── utils.js
└── test
    ├── compare.js
    ├── man
        ├── blockquotes.1
        ├── definition_list_syntax.1
        ├── dots_at_line_start_test.1
        ├── ellipses.1
        ├── entity_encoding_test.1
        ├── escapes.1
        ├── graves.1
        ├── links.1
        ├── list.1
        ├── markdown_syntax.1
        ├── nested_list_with_code.1
        ├── noname.1
        ├── pre_block_with_quotes.1
        ├── regressions.1
        ├── simple_table.1
        ├── table.1
        └── underline_spacing_test.1
    ├── md
        ├── blockquotes.md
        ├── definition_list_syntax.md
        ├── dots_at_line_start_test.md
        ├── ellipses.md
        ├── entity_encoding_test.md
        ├── escapes.md
        ├── graves.md
        ├── links.md
        ├── list.md
        ├── markdown_syntax.md
        ├── nested_list_with_code.md
        ├── noname.md
        ├── pre_block_with_quotes.md
        ├── regressions.md
        ├── simple_table.md
        ├── table.md
        └── underline_spacing_test.md
    └── out
        ├── blockquotes.out
        ├── definition_list_syntax.out
        ├── dots_at_line_start_test.out
        ├── ellipses.out
        ├── entity_encoding_test.out
        ├── escapes.out
        ├── graves.out
        ├── links.out
        ├── list.out
        ├── markdown_syntax.out
        ├── nested_list_with_code.out
        ├── noname.out
        ├── pre_block_with_quotes.out
        ├── regressions.out
        ├── simple_table.out
        ├── table.out
        └── underline_spacing_test.out


/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | test/*/*.err
3 | 
4 | 


--------------------------------------------------------------------------------
/CHANGES.md:
--------------------------------------------------------------------------------
 1 | # CHANGES
 2 | 
 3 | ## 0.1.4
 4 | 
 5 | * depends on marked 0.3.2
 6 | * use .nf/.fi instead of .EX/.EE to format blockquotes
 7 | 
 8 | ## 0.1.6
 9 | 
10 | * ensure tests pass
11 | 
12 | ## 0.2.0
13 | 
14 | * add support for gfm table
15 | 
16 | ## 0.2.1
17 | 
18 | * remove useless test files from npm package
19 | 
20 | ## 0.3.0
21 | 
22 | * accept a timestamp in milliseconds as --date argument
23 | 
24 | ## 1.0.0
25 | 
26 | * node >= 12
27 | * --format option is dropped, use directly marked for html output
28 | * other options should work the same
29 | * mostly rewritten
30 | * depends marked >= 4.2
31 | * more groff macros are implemented
32 | 
33 | ## 1.1.0
34 | 
35 | * --breaks is now the default
36 | 
37 | ## 1.2.0
38 | 
39 | * the level-2 NAME section is not generated if it already exists
40 | * --section, if missing from ronn header, is set to 1 by default
41 | * --manual, if missing, is now omitted to let man display a default value
42 | * --description can set the description if not set from ronn header format
43 | * --version, if missing, is read from package.json of target file module, or omitted.
44 | 
45 | ## 1.3.0
46 | 
47 | * fix crash when md has only one token
48 | * better support for stdin, e.g. `cat file.md | marked-man | man /dev/stdin`
49 | * fix blockquote, use a table
50 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | Files:*
 2 | Copyright: 2013-2022 Jérémy Lal <kapouer@melix.org>
 3 | License: MIT
 4 | 
 5 | Files: lib/marked-man.js
 6 | Copyright: 2013 Jérémy Lal <kapouer@melix.org>
 7 |  2011-2013 Christopher Jeffrey (https://github.com/chjj/)
 8 | License: MIT
 9 | 
10 | Files: test/files/*
11 | Copyright: 2013 Jérémy Lal <kapouer@melix.org>
12 |  2009 Ryan Tomayko (http://tomayko.com/about)
13 | License: MIT
14 | 
15 | License: MIT
16 |  Permission is hereby granted, free of charge, to any person
17 |  obtaining a copy of this software and associated documentation files
18 |  (the "Software"), to deal in the Software without restriction,
19 |  including without limitation the rights to use, copy, modify, merge,
20 |  publish, distribute, sublicense, and/or sell copies of the Software,
21 |  and to permit persons to whom the Software is furnished to do so,
22 |  subject to the following conditions:
23 |  .
24 |  The above copyright notice and this permission notice shall be
25 |  included in all copies or substantial portions of the Software.
26 |  .
27 |  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
28 |  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
29 |  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
30 |  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
31 |  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
32 |  ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
33 |  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
34 |  SOFTWARE.
35 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | man/marked-man.1: README.md
2 | 	./bin/marked-man -o $@ $<
3 | 
4 | doc: man/marked-man.1
5 | 
6 | check:
7 | 	node test/compare.js
8 | 
9 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | marked-man(1) -- markdown to roff
 2 | =================================
 3 | 
 4 | SYNOPSIS
 5 | --------
 6 | 
 7 | ```bash
 8 | marked-man README.md > doc/foo.1
 9 | # works too with stdin
10 | cat README.md | marked-man --version 1.0 | man /dev/stdin
11 | ```
12 | 
13 | See also [marked documentation](https://marked.js.org/).
14 | 
15 | DESCRIPTION
16 | -----------
17 | 
18 | `marked-man` wraps `marked` to extend it with groff output support in order to
19 | create Unix manual pages for use with `man`.
20 | 
21 | It follows the `ronn` markdown level-1 header format:
22 |     # name(section) -- short description
23 | 
24 | which populates the *HEADER* section, and the *NAME* section (if none is already written) of the manpage.
25 | 
26 | OPTIONS
27 | -------
28 | 
29 | `marked-man` is a `marked` CLI extension, meaning options can be passed directly to marked.
30 | 
31 | The `--breaks` option, which retains intra-paragraph line breaks, is now true by default. Use `--no-breaks` to disable it.
32 | 
33 | `marked-man` adds some options to `marked`'s existing options, to be able to override the header/footer of generated man pages.
34 | 
35 | * `--name <name>`
36 | Optional, overrides `name` in ronn header.
37 | 
38 | * `--section <section>`
39 | Optional, overrides `section` in ronn header. Defaults to 1.
40 | 
41 | * `--description <description>`
42 | Optional, overrides `description` in ronn header.
43 | 
44 | * `--version <version>`
45 | The version shown in the manpage footer.
46 | Optional, when omitted, defaults to the target node module version, or empty.
47 | 
48 | * `--manual <manual>`
49 | The manual-group name shown in the manpage header.
50 | Optional, when omitted, man displays a value matching the section.
51 | 
52 | * `--date <date>`
53 | The date shown in the manpage header.
54 | Optional, defaults to now.
55 | Must be acceptable to `new Date(string or timestamp)`.
56 | Honors `SOURCE_DATE_EPOCH` environment variable for reproducible builds.
57 | 
58 | INSTALLATION
59 | ------------
60 | 
61 | See your node package manager manual...
62 | 
63 | For example:
64 | 
65 | ```bash
66 | npx marked-man simple.md
67 | ```
68 | 
69 | EXAMPLE
70 | -------
71 | 
72 | To view this README as a man page, run something like the following:
73 | 
74 | ```bash
75 | marked-man README.md | man /dev/stdin
76 | ```
77 | 
78 | AS MARKED EXTENSION
79 | -------------------
80 | 
81 | ```js
82 | import markedMan from 'marked-man';
83 | import marked from 'marked';
84 | 
85 | marked.use(markedMan);
86 | ```
87 | 
88 | SEE ALSO
89 | --------
90 | 
91 | [Ronn](https://github.com/rtomayko/ronn)
92 | [Ronn-NG](https://github.com/apjanke/ronn-ng)
93 | [groff](https://man.cx/groff_man(7))
94 | 
95 | REPORTING BUGS
96 | --------------
97 | 
98 | See [marked-man repository](https://github.com/kapouer/marked-man).
99 | 


--------------------------------------------------------------------------------
/bin/marked-man.js:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env node
 2 | 
 3 | import markedMan from 'marked-man';
 4 | import { marked } from 'marked';
 5 | 
 6 | const { argv } = process;
 7 | argv.forEach((arg, i) => {
 8 | 	if (arg.startsWith("--version")) {
 9 | 		argv[i] = arg.replace(/^--version/, "--man-version");
10 | 	}
11 | });
12 | 
13 | let fileArg = argv.slice(-1)[0];
14 | if (fileArg == argv[1] || fileArg.startsWith('-')) {
15 | 	fileArg = null;
16 | }
17 | markedMan.fileArg = fileArg;
18 | 
19 | marked.use(markedMan);
20 | 
21 | import('marked/bin/marked');
22 | 


--------------------------------------------------------------------------------
/man/marked-man.1:
--------------------------------------------------------------------------------
 1 | .TH "MARKED\-MAN" "1" "January 2014" "" ""
 2 | .SH "NAME"
 3 | \fBmarked-man\fR \- markdown to roff
 4 | .SH SYNOPSIS
 5 | .P
 6 | .RS 2
 7 | .EX
 8 | marked\-man README\.md > doc/marked\-man\.1
 9 | .EE
10 | .RE
11 | .P
12 | See marked README \fIhttps://github\.com/chjj/marked\fR for documentation about how to use marked\.
13 | .P
14 | Note that \fBmarked\-man \-\-format=html\fR is the same as \fBmarked\fR\|\.
15 | .SH DESCRIPTION
16 | .P
17 | \fBmarked\-man\fR wraps \fBmarked\fR to extend it with groff output support\.
18 | .SH OPTIONS
19 | .P
20 | \fBmarked\-man\fR adds some options to \fBmarked\fR existing options:
21 | .RS 0
22 | .IP \(bu 2
23 | format
24 | Sets the output format\. Outputs html if different from \fBroff\fR\|\.
25 | Defaults to \fBroff\fR\|\.
26 | .IP \(bu 2
27 | name
28 | The name shown in the manpage header, if it isn\'t given in the ronn header like in this README\.
29 | Defaults to empty string\.
30 | .IP \(bu 2
31 | section
32 | The section shown in the manpage header, if it isn\'t given in the ronn header like in this README\.
33 | Defaults to empty string\.
34 | .IP \(bu 2
35 | version
36 | The version shown in the manpage header\.
37 | Defaults to empty string\.
38 | .IP \(bu 2
39 | manual
40 | The MANUAL string shown in the manpage header\.
41 | Defaults to empty string\.
42 | .IP \(bu 2
43 | date
44 | The date shown in the manpage header\.
45 | Defaults to now, must be acceptable by new Date(string)\.
46 | 
47 | .RE
48 | .P
49 | \fBmarked\-man\fR invokes \fBmarked \-\-gfm \-\-sanitize\fR\|\.
50 | The \-\-breaks option can be helpful to match default \fBronn\fR behavior\.
51 | .SH SEE ALSO
52 | .P
53 | Ryan Tomayko \fIhttps://github\.com/rtomayko/ronn\fR
54 | .SH REPORTING BUGS
55 | .P
56 | See marked\-man repository \fIhttps://github\.com/kapouer/marked\-man\fR\|\.
57 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "marked-man",
 3 |   "version": "2.1.0",
 4 |   "description": "wrapper adding manpage output to 'marked', inspired by 'ronn'",
 5 |   "type": "module",
 6 |   "main": "./src/index.js",
 7 |   "exports": {
 8 |     ".": "./src/index.js",
 9 |     "./package.json": "./package.json"
10 |   },
11 |   "bin": {
12 |     "marked-man": "./bin/marked-man.js"
13 |   },
14 |   "files": [
15 |     "bin/",
16 |     "src/"
17 |   ],
18 |   "man": [
19 |     "./man/marked-man.1"
20 |   ],
21 |   "scripts": {
22 |     "test": "node ./test/compare"
23 |   },
24 |   "repository": {
25 |     "type": "git",
26 |     "url": "git://github.com/kapouer/marked-man.git"
27 |   },
28 |   "keywords": [
29 |     "markdown",
30 |     "roff",
31 |     "ronn"
32 |   ],
33 |   "author": "Jérémy Lal <kapouer@melix.org>",
34 |   "license": "MIT",
35 |   "dependencies": {
36 |     "marked": "^12.0.1",
37 |     "read-pkg-up": "^11.0.0"
38 |   },
39 |   "devDependencies": {
40 |     "@kapouer/eslint-config": "^2.0.0"
41 |   },
42 |   "eslintConfig": {
43 |     "extends": "@kapouer/eslint-config",
44 |     "overrides": [
45 |       {
46 |         "files": [
47 |           "bin/*.js",
48 |           "src/*.js",
49 |           "test/*.js"
50 |         ],
51 |         "parserOptions": {
52 |           "sourceType": "module"
53 |         }
54 |       }
55 |     ]
56 |   }
57 | }
58 | 


--------------------------------------------------------------------------------
/src/extensions.js:
--------------------------------------------------------------------------------
 1 | const empty = {
 2 | 	name: 'empty',
 3 | 	level: 'inline',
 4 | 	renderer() {
 5 | 		return "";
 6 | 	}
 7 | };
 8 | 
 9 | const link = {
10 | 	name: 'link',
11 | 	level: 'inline',
12 | 	tokenizer(src, tokens) {
13 | 		if (!tokens.length || /^\p{Po}/u.test(src) == false) return;
14 | 		const tok = tokens[tokens.length - 1];
15 | 		if (tok.type == "link") {
16 | 			tok.punctuation = src.charAt(0);
17 | 			return { type: "empty", raw: tok.punctuation };
18 | 		}
19 | 	},
20 | 	renderer({ href, title, text, punctuation }) {
21 | 		if (href.startsWith('#')) {
22 | 			// a local reference, not a link
23 | 			return `\\fI${title || text || href.slice(1)}\\fR`;
24 | 		}
25 | 		const obj = new URL(href, "file://./");
26 | 		const ret = [];
27 | 		if (!this.parser.renderer.jumps) ret.push("");
28 | 
29 | 		const content = title || text || '';
30 | 
31 | 		if (content == href || obj.protocol + content == href) return text;
32 | 
33 | 		if (obj.protocol == "mailto:") {
34 | 			ret.push(".MT " + href, content ? '.I ' + content : '', ".ME");
35 | 		} else {
36 | 			ret.push(".UR " + href, content ? '.I ' + content : '', ".UE");
37 | 		}
38 | 		if (punctuation) ret[ret.length - 1] += " " + punctuation;
39 | 		ret.push("");
40 | 		this.parser.renderer.jumps = true;
41 | 		return ret.join('\n');
42 | 	}
43 | };
44 | 
45 | export default [empty, link];
46 | 


--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
 1 | import { Parser } from 'marked';
 2 | import { readPackageUpSync } from 'read-pkg-up';
 3 | import Path from 'path';
 4 | import * as renderer from './renderer.js';
 5 | import * as tokenizer from './tokenizer.js';
 6 | import extensions from './extensions.js';
 7 | 
 8 | // https://github.com/markedjs/marked/issues/2639
 9 | const defaultParse = Parser.prototype.parse;
10 | Parser.prototype.parse = function (tokens, arg) {
11 | 	if (!this.markedManCheck) {
12 | 		this.markedManCheck = true;
13 | 		const [{ type, depth }, sec] = tokens;
14 | 		if (type != "heading" || depth != 1) {
15 | 			tokens.unshift({
16 | 				type: 'heading',
17 | 				depth: 1,
18 | 				tokens: []
19 | 			});
20 | 		}
21 | 		this.options.disableLevel2Name = sec && sec.type == "heading" && sec.depth == 2 && sec.text && sec.text.toUpperCase() == "NAME";
22 | 	}
23 | 	return defaultParse.call(this, tokens, arg);
24 | };
25 | 
26 | export default {
27 | 	// marked-man defaults
28 | 	date: (() => {
29 | 		if (typeof process == "undefined" || !process.env.SOURCE_DATE_EPOCH) {
30 | 			return Date.now();
31 | 		} else {
32 | 			return parseInt(process.env.SOURCE_DATE_EPOCH) * 1000;
33 | 		}
34 | 	})(),
35 | 	mangle: false,
36 | 	breaks: true,
37 | 	name: null,
38 | 	section: null,
39 | 	manual: null,
40 | 	set manVersion(val) {
41 | 		this.userDefinedVersion = val;
42 | 	},
43 | 	get manVersion() {
44 | 		if (this.userDefinedVersion) {
45 | 			return this.userDefinedVersion;
46 | 		} else if (this.fileArg) {
47 | 			const pkg = readPackageUpSync(Path.dirname(this.fileArg));
48 | 			return pkg ? pkg.packageJson.version : null;
49 | 		} else {
50 | 			return null;
51 | 		}
52 | 	},
53 | 	// output to roff
54 | 	renderer,
55 | 	tokenizer,
56 | 	// custom fixes
57 | 	extensions,
58 | 	headerIds: false // since marked 5
59 | };
60 | 


--------------------------------------------------------------------------------
/src/renderer.js:
--------------------------------------------------------------------------------
  1 | import { htmlEsc, manEsc, parseHeader } from './utils.js';
  2 | 
  3 | export function code(code, infostring, escaped) {
  4 | 	this.jumps = true;
  5 | 	return [
  6 | 		'.RS 2',
  7 | 		'.nf',
  8 | 		manEsc(code),
  9 | 		'.fi',
 10 | 		'.RE',
 11 | 		''
 12 | 	].join('\n');
 13 | }
 14 | 
 15 | export function blockquote(quote) {
 16 | 	this.jumps = true;
 17 | 	return [
 18 | 		'.TS',
 19 | 		'tab(|) nowarn;',
 20 | 		'cx.',
 21 | 		'T{',
 22 | 		quote,
 23 | 		'T}',
 24 | 		'.TE',
 25 | 		''
 26 | 	].join('\n');
 27 | }
 28 | 
 29 | export function html(html) {
 30 | 	return htmlEsc(html);
 31 | }
 32 | 
 33 | 
 34 | export function heading(text, level, raw, slugger) {
 35 | 	this.jumps = true;
 36 | 	let macro;
 37 | 	if (level == 1) {
 38 | 		macro = 'TH';
 39 | 		text = parseHeader(raw || "", this.options);
 40 | 	} else if (level == 2) {
 41 | 		macro = 'SH';
 42 | 	} else {
 43 | 		macro = 'SS';
 44 | 	}
 45 | 	return '.'
 46 | 		+ macro
 47 | 		+ ' '
 48 | 		+ text
 49 | 		+ '\n';
 50 | }
 51 | 
 52 | export function hr() {
 53 | 	this.jumps = true;
 54 | 	return '.HR\n';
 55 | }
 56 | 
 57 | export function list(body) {
 58 | 	return [
 59 | 		'\n.RS 1',
 60 | 		body,
 61 | 		'.RE',
 62 | 		''
 63 | 	].join('\n');
 64 | }
 65 | export function listitem(text) {
 66 | 	// first ^.P
 67 | 	return [
 68 | 		`.IP \\(bu 2`,
 69 | 		text.trim().replace(/^\.P\s/, '').replace(/\.P /, '.br\n'),
 70 | 		''
 71 | 	].join('\n');
 72 | }
 73 | 
 74 | export function checkbox(checked) {
 75 | 
 76 | }
 77 | 
 78 | export function paragraph(text) {
 79 | 	this.jumps = true;
 80 | 	const ret = [
 81 | 		'.P',
 82 | 		text.trim()
 83 | 	];
 84 | 	if (text) ret.push('');
 85 | 	return ret.join('\n');
 86 | }
 87 | 
 88 | export function table(header, body) {
 89 | 	this.jumps = false;
 90 | 	const { tableCols } = this;
 91 | 	delete this.tableCols;
 92 | 	return [
 93 | 		'.TS',
 94 | 		'tab(|) expand nowarn box;',
 95 | 		tableCols.join(' ') + '.',
 96 | 		dropLastRowSep(header.trim()),
 97 | 		'=',
 98 | 		dropLastRowSep(body.trim()),
 99 | 		'.TE',
100 | 		''
101 | 	].join('\n');
102 | }
103 | 
104 | export function tablerow(content) {
105 | 	if (this.tableCols) this.tableCols.done = true;
106 | 	return dropLastCellSep(content) + '\n_\n';
107 | }
108 | 
109 | export function tablecell(content, flags) {
110 | 	if (!this.tableCols) this.tableCols = [];
111 | 	if (!this.tableCols.done) {
112 | 		this.tableCols.push(getCellAlign(flags.align));
113 | 	}
114 | 	return ['T{', content, 'T}|'].join('\n');
115 | }
116 | function dropLastRowSep(str) {
117 | 	return str.replace(/\n_$/, '');
118 | }
119 | function dropLastCellSep(str) {
120 | 	return str.replace(/\|$/, '');
121 | }
122 | function getCellAlign(align) {
123 | 	switch (align) {
124 | 		case "right":
125 | 			return "r";
126 | 		case "center":
127 | 			return "c";
128 | 		default:
129 | 			return "l";
130 | 	}
131 | }
132 | 
133 | export function strong(text) {
134 | 	this.jumps = false;
135 | 	return '\\fB'
136 | 		+ text
137 | 		+ '\\fR';
138 | }
139 | 
140 | export function em(text) {
141 | 	this.jumps = false;
142 | 	return '\\fI'
143 | 		+ text
144 | 		+ '\\fR';
145 | }
146 | 
147 | export function codespan(code) {
148 | 	this.jumps = false;
149 | 	return '\\fB'
150 | 		+ htmlEsc(code, true)
151 | 		+ '\\fP';
152 | }
153 | 
154 | export function br() {
155 | 	this.jumps = true;
156 | 	return '\n.br\n';
157 | }
158 | 
159 | export function del(text) {
160 | 	return "-"
161 | 		+ text
162 | 		+ "-";
163 | }
164 | 
165 | export function image(href, title, text) {
166 | 	if (href == text) {
167 | 		return '\\fI'
168 | 			+ href
169 | 			+ '\\fR';
170 | 	} else {
171 | 		return '\\fI'
172 | 			+ text
173 | 			+ '\\fR[' + href + ']';
174 | 	}
175 | }
176 | 
177 | export function text(text) {
178 | 	if (this.jumps) {
179 | 		text = text.trimStart();
180 | 		this.jumps = false;
181 | 	}
182 | 	return htmlEsc(text);
183 | }
184 | 


--------------------------------------------------------------------------------
/src/tokenizer.js:
--------------------------------------------------------------------------------
 1 | export function inlineText(src) {
 2 | 	const cap = this.rules.inline.text.exec(src);
 3 | 	if (cap) {
 4 | 		return {
 5 | 			type: 'text',
 6 | 			raw: cap[0],
 7 | 			text: cap[0]
 8 | 		};
 9 | 	}
10 | }
11 | 


--------------------------------------------------------------------------------
/src/utils.js:
--------------------------------------------------------------------------------
 1 | export function quote(str) {
 2 | 	return '"' + str + '"';
 3 | }
 4 | 
 5 | export function manEsc(str) {
 6 | 	return str
 7 | 		.replace(/\\/gm, "\\\\")
 8 | 		.replace(/-/gm, "\\-")
 9 | 		.replace(/^\s*\./gm, "\\|.")
10 | 		.replace(/\./gm, "\\.")
11 | 		.replace(/^'/gm, "\\|'");
12 | }
13 | 
14 | export function htmlEsc(str) {
15 | 	return rentities(manEsc(str))
16 | 		.replace(/&gt;/gm, '>')
17 | 		.replace(/&lt;/gm, '<')
18 | 		.replace(/&amp;/gm, '&');
19 | }
20 | 
21 | export function rentities(str) {
22 | 	return str.replace(/&(\w+);/gm, (match, ent) => {
23 | 		const gr = {
24 | 			bull: '[ci]',
25 | 			nbsp: '~',
26 | 			copy: '(co',
27 | 			rdquo: '(rs',
28 | 			mdash: '(em',
29 | 			reg: '(rg',
30 | 			sect: '(sc',
31 | 			ge: '(>=',
32 | 			le: '(<=',
33 | 			ne: '(!=',
34 | 			equiv: '(==',
35 | 			plusmn: '(+-'
36 | 		}[ent];
37 | 		if (gr) return '\\' + gr;
38 | 		else return match;
39 | 	});
40 | }
41 | 
42 | export function parseHeader(str, options) {
43 | 	const {
44 | 		groups: {
45 | 			name = options.name || "",
46 | 			section = options.section || "",
47 | 			last = ""
48 | 		}
49 | 	} = /^(?<name>[\w_.[\]~+=@:-]+)\s*(?:\((?<section>\d\w*)\))?(?:\s*-+\s*(?<last>.*))?$/.exec(str) || { groups: {} };
50 | 
51 | 	let text = last;
52 | 	if (!text) {
53 | 		if (name || section) text = "";
54 | 		else text = str;
55 | 	}
56 | 	if (name && text) text = " - " + text;
57 | 
58 | 	let out = quote(manEsc(name.toUpperCase()))
59 | 		+ " "
60 | 		+ quote(section || "1")
61 | 		+ " "
62 | 		+ quote(manDate(options.date))
63 | 		+ (options.manVersion ? " " + quote(options.manVersion) : "")
64 | 		+ (options.manual ? " " + quote(options.manual) : ""); // use default value
65 | 	if (!options.disableLevel2Name) {
66 | 		out = out
67 | 			+ "\n.SH "
68 | 			+ quote("NAME")
69 | 			+ "\n\\fB"
70 | 			+ name
71 | 			+ "\\fR"
72 | 			+ manEsc(text);
73 | 	} else {
74 | 		delete options.disableLevel2Name;
75 | 	}
76 | 	return out;
77 | }
78 | 
79 | export function manDate(str) {
80 | 	let date;
81 | 	if (typeof str == "string") {
82 | 		const stamp = parseInt(str);
83 | 		if (!Number.isNaN(stamp) && stamp.toString().length == str.length) {
84 | 			date = new Date(stamp);
85 | 		}
86 | 	}
87 | 	if (!date) {
88 | 		date = new Date(str);
89 | 	}
90 | 	if (Number.isNaN(date.getTime())) {
91 | 		throw new Error("Bad date option: " + str);
92 | 	}
93 | 	return date.toLocaleString('en', {
94 | 		month: 'long', year: 'numeric', timeZone: 'UTC'
95 | 	});
96 | }
97 | 
98 | 


--------------------------------------------------------------------------------
/test/compare.js:
--------------------------------------------------------------------------------
  1 | import { promises as fs } from 'fs';
  2 | import * as Path from 'path';
  3 | import { promisify } from 'util';
  4 | import { exec } from 'child_process';
  5 | import { fileURLToPath } from 'url';
  6 | 
  7 | const curDir = Path.dirname(fileURLToPath(import.meta.url));
  8 | const execa = promisify(exec);
  9 | 
 10 | import markedMan from 'marked-man';
 11 | import { marked } from 'marked';
 12 | 
 13 | marked.use(markedMan);
 14 | 
 15 | // params
 16 | const ronnDir = Path.join(curDir, "md");
 17 | const manDir = Path.join(curDir, "man");
 18 | const outDir = Path.join(curDir, "out");
 19 | 
 20 | main(process.argv.slice(2).map(filepath => Path.join('../..', filepath)));
 21 | 
 22 | async function convert(name, str) {
 23 | 	const roff = marked.parse(str, {
 24 | 		name,
 25 | 		date: '1979-01-01',
 26 | 		breaks: true
 27 | 	});
 28 | 	const [status, manPath] = await writeOrCompare(roff, manDir, name + ".1");
 29 | 	const { stdout, stderr } = await execa(`man --warnings --encoding=UTF-8 ${manPath}`, {
 30 | 		env: {
 31 | 			LC_ALL: "C.UTF-8",
 32 | 			MAN_KEEP_FORMATTING: '1',
 33 | 			MANWIDTH: "80"
 34 | 		}
 35 | 	});
 36 | 	if (stderr) console.error(manPath, '\n', stderr);
 37 | 	return [status, stdout];
 38 | }
 39 | 
 40 | async function main(tests) {
 41 | 	const files = tests.length > 0 ? tests : await fs.readdir(ronnDir);
 42 | 	let fails = 0,
 43 | 		works = 0,
 44 | 		news = 0;
 45 | 	try {
 46 | 		await fs.rm(manDir + "-err", { recursive: true });
 47 | 		await fs.rm(outDir + "-err", { recursive: true });
 48 | 	} catch (err) {
 49 | 		// pass
 50 | 	}
 51 | 	await fs.mkdir(manDir + "-err", { recursive: true });
 52 | 	await fs.mkdir(outDir + "-err", { recursive: true });
 53 | 	await Promise.all(files.map(async file => {
 54 | 		const status = await check(file);
 55 | 		switch (status) {
 56 | 			case -1:
 57 | 				fails++;
 58 | 				break;
 59 | 			case 0:
 60 | 				works++;
 61 | 				break;
 62 | 			case 1:
 63 | 				news++;
 64 | 				break;
 65 | 		}
 66 | 	}));
 67 | 	if (fails > 0) console.error("Failed tests: ", fails);
 68 | 	if (works > 0) console.info("Succeeded tests: ", works);
 69 | 	if (news > 0) console.info("New tests: ", news);
 70 | 	if (fails == 0) {
 71 | 		console.info("All tests passed");
 72 | 		await fs.rm(manDir + "-err", { recursive: true });
 73 | 		await fs.rm(outDir + "-err", { recursive: true });
 74 | 	} else {
 75 | 		process.exit(1);
 76 | 	}
 77 | }
 78 | 
 79 | async function writeOrCompare(str, root, name) {
 80 | 	const okpath = Path.join(root, name);
 81 | 	const errpath = Path.join(root + "-err", name);
 82 | 	await fs.writeFile(errpath, str);
 83 | 	let status = 0;
 84 | 	try {
 85 | 		await fs.access(okpath);
 86 | 	} catch (e) {
 87 | 		console.info("Missing test, result written in", okpath);
 88 | 		await fs.writeFile(okpath, str);
 89 | 		status = 1;
 90 | 	}
 91 | 	try {
 92 | 		await execa(
 93 | 			`diff --unified --ignore-space-change ${okpath} ${errpath}`
 94 | 		);
 95 | 		await fs.unlink(errpath);
 96 | 	} catch (e) {
 97 | 		console.error("Test failure");
 98 | 		console.error(e.stdout);
 99 | 		status = -1;
100 | 	}
101 | 	return [status, status >= 0 ? okpath : errpath];
102 | }
103 | 
104 | async function check(filename) {
105 | 	const ronnBuf = await fs.readFile(Path.join(ronnDir, filename));
106 | 	const name = Path.basename(filename, Path.extname(filename));
107 | 	const [statusMan, output] = await convert(name, ronnBuf.toString());
108 | 	if (statusMan != 0) return statusMan;
109 | 	const [statusOut] = await writeOrCompare(output, outDir, name + ".out");
110 | 	return statusOut;
111 | }
112 | 


--------------------------------------------------------------------------------
/test/man/blockquotes.1:
--------------------------------------------------------------------------------
 1 | .TH "T" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBt\fR \- test
 4 | .SH test
 5 | .RS 2
 6 | .nf
 7 | A blockquote here\.
 8 | Continuing on second line\.
 9 | .fi
10 | .RE
11 | .P
12 | Hello\.
13 | .TS
14 | tab(|) nowarn;
15 | cx.
16 | T{
17 | .P
18 | Another block quote\. With a long title\. That will break a line eventually later\.
19 | .br
20 | that continues on second line
21 | .br
22 | continuation
23 | 
24 | T}
25 | .TE
26 | 


--------------------------------------------------------------------------------
/test/man/definition_list_syntax.1:
--------------------------------------------------------------------------------
 1 | .TH "DEFITION_LIST_SYNTAX" "5" "January 1979"
 2 | .SH "NAME"
 3 | \fBdefition_list_syntax\fR \- hiya
 4 | .P
 5 | Definition lists look like unordered lists:
 6 | 
 7 | .RS 1
 8 | .IP \(bu 2
 9 | term:
10 | .br
11 | definition
12 | .IP \(bu 2
13 | another one:
14 | .br
15 | The definition may span
16 | .br
17 | multiple lines and even
18 | .br
19 | start
20 | .br
21 | new paragraphs
22 | .IP \(bu 2
23 | \fB\-\-somearg\fP=<VALUE>:
24 | .br
25 | We can do that too\.
26 | 
27 | .RE
28 | 


--------------------------------------------------------------------------------
/test/man/dots_at_line_start_test.1:
--------------------------------------------------------------------------------
 1 | .TH "DOTS_AT_LINE_START_TEST" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBdots_at_line_start_test\fR
 4 | .P
 5 | There's a weird issue where dots at the beginning of a line
 6 | .br
 7 | generate troff warnings due to escaping\.
 8 | .P
 9 | \|\.\. let's see what happens\.
10 | 


--------------------------------------------------------------------------------
/test/man/ellipses.1:
--------------------------------------------------------------------------------
 1 | .TH "ELLIPSES" "7" "January 1979"
 2 | .SH "NAME"
 3 | \fBellipses\fR \- testing ellipses
 4 | .P
 5 | Ellipses should be replaced\.\.\.
 6 | .P
 7 | \|\.\.\.also, they shouldn't interfere with regular dots at the beginning
 8 | .br
 9 | of a line\.
10 | 


--------------------------------------------------------------------------------
/test/man/entity_encoding_test.1:
--------------------------------------------------------------------------------
 1 | .TH "HELLO" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBhello\fR \- hello world
 4 | .P
 5 | Your output <i>might</i> look like this:
 6 | .RS 2
 7 | .nf
 8 | * Chris
 9 | *
10 | * &lt;b&gt;GitHub&lt;/b&gt;
11 | * <b>GitHub</b>
12 | .fi
13 | .RE
14 | .P
15 | Here's some special entities:
16 | 
17 | .RS 1
18 | .IP \(bu 2
19 | &bull;       \[ci]
20 | .IP \(bu 2
21 | &nbsp;       \~
22 | .IP \(bu 2
23 | &copy;       \(co
24 | .IP \(bu 2
25 | &rdquo;      \(rs
26 | .IP \(bu 2
27 | &mdash;      \(em
28 | .IP \(bu 2
29 | &reg;        \(rg
30 | .IP \(bu 2
31 | &sect;       \(sc
32 | .IP \(bu 2
33 | &ge;         \(>=
34 | .IP \(bu 2
35 | &le;         \(<=
36 | .IP \(bu 2
37 | &ne;         \(!=
38 | .IP \(bu 2
39 | &equiv;      \(==
40 | .IP \(bu 2
41 | &plusmn;     \(+-
42 | 
43 | .RE
44 | .P
45 | Here's a line that uses non\-breaking spaces to force the
46 | .br
47 | last\~few\~words\~to\~wrap\~together\.
48 | 


--------------------------------------------------------------------------------
/test/man/escapes.1:
--------------------------------------------------------------------------------
 1 | .TH "ESCAPES" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBescapes\fR
 4 | .P
 5 | backslashes before the asterisks, like this:
 6 | .RS 2
 7 | .nf
 8 | \\*literal asterisks\\*
 9 | .fi
10 | .RE
11 | .P
12 | Markdown provides backslash escapes for the following characters:
13 | .RS 2
14 | .nf
15 | \\   backslash
16 | `   backtick
17 | *   asterisk
18 | _   underscore
19 | {}  curly braces
20 | []  square brackets
21 | ()  parentheses
22 | #   hash mark
23 | +   plus sign
24 | \-   minus sign (hyphen)
25 | \|\.   dot
26 | !   exclamation mark
27 | .fi
28 | .RE
29 | 


--------------------------------------------------------------------------------
/test/man/graves.1:
--------------------------------------------------------------------------------
1 | .TH "TEST" "1" "January 1979"
2 | .SH "NAME"
3 | \fBtest\fR
4 | .SH this title \fBwill render\fP strangely
5 | .P
6 | This is the body text\.
7 | 


--------------------------------------------------------------------------------
/test/man/links.1:
--------------------------------------------------------------------------------
 1 | .TH "LINKS" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBlinks\fR
 4 | .P
 5 | I get 10 times more traffic from 
 6 | .UR http://google.com/
 7 | .I Google
 8 | .UE
 9 | than from
10 | .br
11 | .UR http://search.yahoo.com/
12 | .I Yahoo Search
13 | .UE
14 | or 
15 | .UR http://search.msn.com/
16 | .I MSN Search
17 | .UE .
18 | .P
19 | This is to test proper escape of html chars and non\-repeating link:
20 | .br
21 | xxxxx@xxxx.xxxx.xxxx.xx
22 | .P
23 | I get 10 times more traffic from 
24 | .UR http://google.com/
25 | .I Google
26 | .UE
27 | than from
28 | .br
29 | .UR http://search.yahoo.com/
30 | .I Yahoo Search
31 | .UE
32 | or 
33 | .UR http://search.msn.com/
34 | .I MSN Search
35 | .UE .
36 | .P
37 | Non\-repeating http link https://example.com/test
38 | .P
39 | Also
40 | .br
41 | .UR http://google.com/
42 | .I Google
43 | .UE
44 | .P
45 | and 
46 | .UR ./table.md
47 | .I local links should not crash
48 | .UE
49 | 


--------------------------------------------------------------------------------
/test/man/list.1:
--------------------------------------------------------------------------------
 1 | .TH "A" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBa\fR
 4 | .P
 5 | This is a tight list:
 6 | 
 7 | .RS 1
 8 | .IP \(bu 2
 9 | \fBtoggle_status\fP: test
10 | .IP \(bu 2
11 | \fBspawn <executable> <additional args>\fP
12 | .br
13 | TODO explain path\-alike expansion,
14 | .br
15 | ability to get a block here\.
16 | 
17 | .RE
18 | .P
19 | This is a loose list:
20 | 
21 | .RS 1
22 | .IP \(bu 2
23 | \fBtoggle_status\fP:
24 | .br
25 | test
26 | .IP \(bu 2
27 | \fBspawn <executable> <additional args>\fP:
28 | .br
29 | TODO explain path\-alike expansion,
30 | .br
31 | ability to get a block here\.
32 | 
33 | .RE
34 | 


--------------------------------------------------------------------------------
/test/man/markdown_syntax.1:
--------------------------------------------------------------------------------
   1 | .TH "MARKDOWN" "5" "January 1979"
   2 | .SH "NAME"
   3 | \fBmarkdown\fR \- humane markup syntax
   4 | .SH SYNOPSIS
   5 | .RS 2
   6 | .nf
   7 | # Header 1 #
   8 | ## Header 2 ##
   9 | ### Header 3 ###             (Hashes on right are optional)
  10 | #### Header 4 ####
  11 | ##### Header 5 #####
  12 | 
  13 | This is a paragraph, which is text surrounded by whitespace\.
  14 | Paragraphs can be on one line (or many), and can drone on for
  15 | hours\.
  16 | 
  17 | [Reference style links][1] and [inline links](http://example\.com)
  18 | [1]: http://example\.com "Title is optional"
  19 | 
  20 | Inline markup like _italics_,  **bold**, and `code()`\.
  21 | 
  22 | ![picture alt](/images/photo\.jpeg "Title is optional")
  23 | 
  24 | > Blockquotes are like quoted text in email replies
  25 | >> And, they can be nested
  26 | 
  27 |     code blocks are for preformatted
  28 |     text and must be indented with four spaces
  29 | 
  30 | * Bullet lists are easy too
  31 |   * You can
  32 |   * even
  33 |   * nest them
  34 | \- Another one
  35 | + Another one
  36 | .fi
  37 | .RE
  38 | .SH DESCRIPTION
  39 | .SS Philosophy
  40 | .P
  41 | Markdown is intended to be as easy\-to\-read and easy\-to\-write as is feasible\.
  42 | .P
  43 | Readability, however, is emphasized above all else\. A Markdown\-formatted
  44 | .br
  45 | document should be publishable as\-is, as plain text, without looking
  46 | .br
  47 | like it's been marked up with tags or formatting instructions\. While
  48 | .br
  49 | Markdown's syntax has been influenced by several existing text\-to\-HTML
  50 | .br
  51 | filters \-\- including 
  52 | .UR http://docutils.sourceforge.net/mirror/setext.html
  53 | .I Setext
  54 | .UE ,
  55 | 
  56 | .UR http://www.aaronsw.com/2002/atx/
  57 | .I atx
  58 | .UE ,
  59 | 
  60 | .UR http://textism.com/tools/textile/
  61 | .I Textile
  62 | .UE ,
  63 | 
  64 | .UR http://docutils.sourceforge.net/rst.html
  65 | .I reStructuredText
  66 | .UE ,
  67 | 
  68 | .br
  69 | .UR http://www.triptico.com/software/grutatxt.html
  70 | .I Grutatext
  71 | .UE ,
  72 | and 
  73 | .UR http://ettext.taint.org/doc/
  74 | .I EtText
  75 | .UE
  76 | \-\- the single biggest source of
  77 | .br
  78 | inspiration for Markdown's syntax is the format of plain text email\.
  79 | .P
  80 | To this end, Markdown's syntax is comprised entirely of punctuation
  81 | .br
  82 | characters, which punctuation characters have been carefully chosen so
  83 | .br
  84 | as to look like what they mean\. E\.g\., asterisks around a word actually
  85 | .br
  86 | look like *emphasis*\|\. Markdown lists look like, well, lists\. Even
  87 | .br
  88 | blockquotes look like quoted passages of text, assuming you've ever
  89 | .br
  90 | used email\.
  91 | .SS Inline HTML
  92 | .P
  93 | Markdown's syntax is intended for one purpose: to be used as a
  94 | .br
  95 | format for \fIwriting\fR for the web\.
  96 | .P
  97 | Markdown is not a replacement for HTML, or even close to it\. Its
  98 | .br
  99 | syntax is very small, corresponding only to a very small subset of
 100 | .br
 101 | HTML tags\. The idea is \fInot\fR to create a syntax that makes it easier
 102 | .br
 103 | to insert HTML tags\. In my opinion, HTML tags are already easy to
 104 | .br
 105 | insert\. The idea for Markdown is to make it easy to read, write, and
 106 | .br
 107 | edit prose\. HTML is a \fIpublishing\fR format; Markdown is a \fIwriting\fR
 108 | .br
 109 | format\. Thus, Markdown's formatting syntax only addresses issues that
 110 | .br
 111 | can be conveyed in plain text\.
 112 | .P
 113 | For any markup that is not covered by Markdown's syntax, you simply
 114 | .br
 115 | use HTML itself\. There's no need to preface it or delimit it to
 116 | .br
 117 | indicate that you're switching from Markdown to HTML; you just use
 118 | .br
 119 | the tags\.
 120 | .P
 121 | The only restrictions are that block\-level HTML elements \-\- e\.g\. \fB<div>\fP,
 122 | .br
 123 | \fB<table>\fP, \fB<pre>\fP, \fB<p>\fP, etc\. \-\- must be separated from surrounding
 124 | .br
 125 | content by blank lines, and the start and end tags of the block should
 126 | .br
 127 | not be indented with tabs or spaces\. Markdown is smart enough not
 128 | .br
 129 | to add extra (unwanted) \fB<p>\fP tags around HTML block\-level tags\.
 130 | .P
 131 | For example, to add an HTML table to a Markdown article:
 132 | .RS 2
 133 | .nf
 134 | This is a regular paragraph\.
 135 | 
 136 | <table>
 137 |     <tr>
 138 |         <td>Foo</td>
 139 |     </tr>
 140 | </table>
 141 | 
 142 | This is another regular paragraph\.
 143 | .fi
 144 | .RE
 145 | .P
 146 | Note that Markdown formatting syntax is not processed within block\-level
 147 | .br
 148 | HTML tags\. E\.g\., you can't use Markdown\-style \fB*emphasis*\fP inside an
 149 | .br
 150 | HTML block\.
 151 | .P
 152 | Span\-level HTML tags \-\- e\.g\. \fB<span>\fP, \fB<cite>\fP, or \fB<del>\fP \-\- can be
 153 | .br
 154 | used anywhere in a Markdown paragraph, list item, or header\. If you
 155 | .br
 156 | want, you can even use HTML tags instead of Markdown formatting; e\.g\. if
 157 | .br
 158 | you'd prefer to use HTML \fB<a>\fP or \fB<img>\fP tags instead of Markdown's
 159 | .br
 160 | link or image syntax, go right ahead\.
 161 | .P
 162 | Unlike block\-level HTML tags, Markdown syntax \fIis\fR processed within
 163 | .br
 164 | span\-level tags\.
 165 | .SS Automatic Escaping for Special Characters
 166 | .P
 167 | In HTML, there are two characters that demand special treatment: \fB<\fP
 168 | .br
 169 | and \fB&\fP\|\. Left angle brackets are used to start tags; ampersands are
 170 | .br
 171 | used to denote HTML entities\. If you want to use them as literal
 172 | .br
 173 | characters, you must escape them as entities, e\.g\. \fB&lt;\fP, and
 174 | .br
 175 | \fB&amp;\fP\|\.
 176 | .P
 177 | Ampersands in particular are bedeviling for web writers\. If you want to
 178 | .br
 179 | write about 'AT&T', you need to write '\fBAT&amp;T\fP\|'\. You even need to
 180 | .br
 181 | escape ampersands within URLs\. Thus, if you want to link to:
 182 | .RS 2
 183 | .nf
 184 | http://images\.google\.com/images?num=30&q=larry+bird
 185 | .fi
 186 | .RE
 187 | .P
 188 | you need to encode the URL as:
 189 | .RS 2
 190 | .nf
 191 | http://images\.google\.com/images?num=30&amp;q=larry+bird
 192 | .fi
 193 | .RE
 194 | .P
 195 | in your anchor tag \fBhref\fP attribute\. Needless to say, this is easy to
 196 | .br
 197 | forget, and is probably the single most common source of HTML validation
 198 | .br
 199 | errors in otherwise well\-marked\-up web sites\.
 200 | .P
 201 | Markdown allows you to use these characters naturally, taking care of
 202 | .br
 203 | all the necessary escaping for you\. If you use an ampersand as part of
 204 | .br
 205 | an HTML entity, it remains unchanged; otherwise it will be translated
 206 | .br
 207 | into \fB&amp;\fP\|\.
 208 | .P
 209 | So, if you want to include a copyright symbol in your article, you can write:
 210 | .RS 2
 211 | .nf
 212 | &copy;
 213 | .fi
 214 | .RE
 215 | .P
 216 | and Markdown will leave it alone\. But if you write:
 217 | .RS 2
 218 | .nf
 219 | AT&T
 220 | .fi
 221 | .RE
 222 | .P
 223 | Markdown will translate it to:
 224 | .RS 2
 225 | .nf
 226 | AT&amp;T
 227 | .fi
 228 | .RE
 229 | .P
 230 | Similarly, because Markdown supports \fIinline HTML\fR if you use
 231 | .br
 232 | angle brackets as delimiters for HTML tags, Markdown will treat them as
 233 | .br
 234 | such\. But if you write:
 235 | .RS 2
 236 | .nf
 237 | 4 < 5
 238 | .fi
 239 | .RE
 240 | .P
 241 | Markdown will translate it to:
 242 | .RS 2
 243 | .nf
 244 | 4 &lt; 5
 245 | .fi
 246 | .RE
 247 | .P
 248 | However, inside Markdown code spans and blocks, angle brackets and
 249 | .br
 250 | ampersands are \fIalways\fR encoded automatically\. This makes it easy to use
 251 | .br
 252 | Markdown to write about HTML code\. (As opposed to raw HTML, which is a
 253 | .br
 254 | terrible format for writing about HTML syntax, because every single \fB<\fP
 255 | .br
 256 | and \fB&\fP in your example code needs to be escaped\.)
 257 | .SH BLOCK ELEMENTS
 258 | .SS Paragraphs and Line Breaks
 259 | .P
 260 | A paragraph is simply one or more consecutive lines of text, separated
 261 | .br
 262 | by one or more blank lines\. (A blank line is any line that looks like a
 263 | .br
 264 | blank line \-\- a line containing nothing but spaces or tabs is considered
 265 | .br
 266 | blank\.) Normal paragraphs should not be indented with spaces or tabs\.
 267 | .P
 268 | The implication of the "one or more consecutive lines of text" rule is
 269 | .br
 270 | that Markdown supports "hard\-wrapped" text paragraphs\. This differs
 271 | .br
 272 | significantly from most other text\-to\-HTML formatters (including Movable
 273 | .br
 274 | Type's "Convert Line Breaks" option) which translate every line break
 275 | .br
 276 | character in a paragraph into a \fB<br />\fP tag\.
 277 | .P
 278 | When you \fIdo\fR want to insert a \fB<br />\fP break tag using Markdown, you
 279 | .br
 280 | end a line with two or more spaces, then type return\.
 281 | .P
 282 | Yes, this takes a tad more effort to create a \fB<br />\fP, but a simplistic
 283 | .br
 284 | "every line break is a \fB<br />\fP" rule wouldn't work for Markdown\.
 285 | .br
 286 | Markdown's email\-style \fIblockquoting\fR and multi\-paragraph \fIlist items\fR
 287 | .br
 288 | work best \-\- and look better \-\- when you format them with hard breaks\.
 289 | .SS Headers
 290 | .P
 291 | Markdown supports two styles of headers, [Setext] 
 292 | .UR http://docutils.sourceforge.net/mirror/setext.html
 293 | .I 1
 294 | .UE
 295 | and [atx] 
 296 | .UR http://www.aaronsw.com/2002/atx/
 297 | .I 2
 298 | .UE .
 299 | .P
 300 | Setext\-style headers are "underlined" using equal signs (for first\-level
 301 | .br
 302 | headers) and dashes (for second\-level headers)\. For example:
 303 | .RS 2
 304 | .nf
 305 | This is an H1
 306 | =============
 307 | 
 308 | This is an H2
 309 | \-\-\-\-\-\-\-\-\-\-\-\-\-
 310 | .fi
 311 | .RE
 312 | .P
 313 | Any number of underlining \fB=\fP\|'s or \fB\-\fP\|'s will work\.
 314 | .P
 315 | Atx\-style headers use 1\-6 hash characters at the start of the line,
 316 | .br
 317 | corresponding to header levels 1\-6\. For example:
 318 | .RS 2
 319 | .nf
 320 | # This is an H1
 321 | 
 322 | ## This is an H2
 323 | 
 324 | ###### This is an H6
 325 | .fi
 326 | .RE
 327 | .P
 328 | Optionally, you may "close" atx\-style headers\. This is purely
 329 | .br
 330 | cosmetic \-\- you can use this if you think it looks better\. The
 331 | .br
 332 | closing hashes don't even need to match the number of hashes
 333 | .br
 334 | used to open the header\. (The number of opening hashes
 335 | .br
 336 | determines the header level\.) :
 337 | .RS 2
 338 | .nf
 339 | # This is an H1 #
 340 | 
 341 | ## This is an H2 ##
 342 | 
 343 | ### This is an H3 ######
 344 | .fi
 345 | .RE
 346 | .SS Blockquotes
 347 | .P
 348 | Markdown uses email\-style \fB>\fP characters for blockquoting\. If you're
 349 | .br
 350 | familiar with quoting passages of text in an email message, then you
 351 | .br
 352 | know how to create a blockquote in Markdown\. It looks best if you hard
 353 | .br
 354 | wrap the text and put a \fB>\fP before every line:
 355 | .RS 2
 356 | .nf
 357 | > This is a blockquote with two paragraphs\. Lorem ipsum dolor sit amet,
 358 | > consectetuer adipiscing elit\. Aliquam hendrerit mi posuere lectus\.
 359 | > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus\.
 360 | >
 361 | > Donec sit amet nisl\. Aliquam semper ipsum sit amet velit\. Suspendisse
 362 | > id sem consectetuer libero luctus adipiscing\.
 363 | .fi
 364 | .RE
 365 | .P
 366 | Markdown allows you to be lazy and only put the \fB>\fP before the first
 367 | .br
 368 | line of a hard\-wrapped paragraph:
 369 | .RS 2
 370 | .nf
 371 | > This is a blockquote with two paragraphs\. Lorem ipsum dolor sit amet,
 372 | consectetuer adipiscing elit\. Aliquam hendrerit mi posuere lectus\.
 373 | Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus\.
 374 | 
 375 | > Donec sit amet nisl\. Aliquam semper ipsum sit amet velit\. Suspendisse
 376 | id sem consectetuer libero luctus adipiscing\.
 377 | .fi
 378 | .RE
 379 | .P
 380 | Blockquotes can be nested (i\.e\. a blockquote\-in\-a\-blockquote) by
 381 | .br
 382 | adding additional levels of \fB>\fP:
 383 | .RS 2
 384 | .nf
 385 | > This is the first level of quoting\.
 386 | >
 387 | > > This is nested blockquote\.
 388 | >
 389 | > Back to the first level\.
 390 | .fi
 391 | .RE
 392 | .P
 393 | Blockquotes can contain other Markdown elements, including headers, lists,
 394 | .br
 395 | and code blocks:
 396 | .RS 2
 397 | .nf
 398 | > ## This is a header\.
 399 | >
 400 | > 1\.   This is the first list item\.
 401 | > 2\.   This is the second list item\.
 402 | >
 403 | > Here's some example code:
 404 | >
 405 | >     return shell_exec("echo $input | $markdown_script");
 406 | .fi
 407 | .RE
 408 | .P
 409 | Any decent text editor should make email\-style quoting easy\. For
 410 | .br
 411 | example, with BBEdit, you can make a selection and choose Increase
 412 | .br
 413 | Quote Level from the Text menu\.
 414 | .SS Lists
 415 | .P
 416 | Markdown supports ordered (numbered) and unordered (bulleted) lists\.
 417 | .P
 418 | Unordered lists use asterisks, pluses, and hyphens \-\- interchangably
 419 | .br
 420 | \-\- as list markers:
 421 | .RS 2
 422 | .nf
 423 | *   Red
 424 | *   Green
 425 | *   Blue
 426 | .fi
 427 | .RE
 428 | .P
 429 | is equivalent to:
 430 | .RS 2
 431 | .nf
 432 | +   Red
 433 | +   Green
 434 | +   Blue
 435 | .fi
 436 | .RE
 437 | .P
 438 | and:
 439 | .RS 2
 440 | .nf
 441 | \-   Red
 442 | \-   Green
 443 | \-   Blue
 444 | .fi
 445 | .RE
 446 | .P
 447 | Ordered lists use numbers followed by periods:
 448 | .RS 2
 449 | .nf
 450 | 1\.  Bird
 451 | 2\.  McHale
 452 | 3\.  Parish
 453 | .fi
 454 | .RE
 455 | .P
 456 | It's important to note that the actual numbers you use to mark the
 457 | .br
 458 | list have no effect on the HTML output Markdown produces\. The HTML
 459 | .br
 460 | Markdown produces from the above list is:
 461 | .RS 2
 462 | .nf
 463 | <ol>
 464 | <li>Bird</li>
 465 | <li>McHale</li>
 466 | <li>Parish</li>
 467 | </ol>
 468 | .fi
 469 | .RE
 470 | .P
 471 | If you instead wrote the list in Markdown like this:
 472 | .RS 2
 473 | .nf
 474 | 1\.  Bird
 475 | 1\.  McHale
 476 | 1\.  Parish
 477 | .fi
 478 | .RE
 479 | .P
 480 | or even:
 481 | .RS 2
 482 | .nf
 483 | 3\. Bird
 484 | 1\. McHale
 485 | 8\. Parish
 486 | .fi
 487 | .RE
 488 | .P
 489 | you'd get the exact same HTML output\. The point is, if you want to,
 490 | .br
 491 | you can use ordinal numbers in your ordered Markdown lists, so that
 492 | .br
 493 | the numbers in your source match the numbers in your published HTML\.
 494 | .br
 495 | But if you want to be lazy, you don't have to\.
 496 | .P
 497 | If you do use lazy list numbering, however, you should still start the
 498 | .br
 499 | list with the number 1\. At some point in the future, Markdown may support
 500 | .br
 501 | starting ordered lists at an arbitrary number\.
 502 | .P
 503 | List markers typically start at the left margin, but may be indented by
 504 | .br
 505 | up to three spaces\. List markers must be followed by one or more spaces
 506 | .br
 507 | or a tab\.
 508 | .P
 509 | To make lists look nice, you can wrap items with hanging indents:
 510 | .RS 2
 511 | .nf
 512 | *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit\.
 513 |     Aliquam hendrerit mi posuere lectus\. Vestibulum enim wisi,
 514 |     viverra nec, fringilla in, laoreet vitae, risus\.
 515 | *   Donec sit amet nisl\. Aliquam semper ipsum sit amet velit\.
 516 |     Suspendisse id sem consectetuer libero luctus adipiscing\.
 517 | .fi
 518 | .RE
 519 | .P
 520 | But if you want to be lazy, you don't have to:
 521 | .RS 2
 522 | .nf
 523 | *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit\.
 524 | Aliquam hendrerit mi posuere lectus\. Vestibulum enim wisi,
 525 | viverra nec, fringilla in, laoreet vitae, risus\.
 526 | *   Donec sit amet nisl\. Aliquam semper ipsum sit amet velit\.
 527 | Suspendisse id sem consectetuer libero luctus adipiscing\.
 528 | .fi
 529 | .RE
 530 | .P
 531 | If list items are separated by blank lines, Markdown will wrap the
 532 | .br
 533 | items in \fB<p>\fP tags in the HTML output\. For example, this input:
 534 | .RS 2
 535 | .nf
 536 | *   Bird
 537 | *   Magic
 538 | .fi
 539 | .RE
 540 | .P
 541 | will turn into:
 542 | .RS 2
 543 | .nf
 544 | <ul>
 545 | <li>Bird</li>
 546 | <li>Magic</li>
 547 | </ul>
 548 | .fi
 549 | .RE
 550 | .P
 551 | But this:
 552 | .RS 2
 553 | .nf
 554 | *   Bird
 555 | 
 556 | *   Magic
 557 | .fi
 558 | .RE
 559 | .P
 560 | will turn into:
 561 | .RS 2
 562 | .nf
 563 | <ul>
 564 | <li><p>Bird</p></li>
 565 | <li><p>Magic</p></li>
 566 | </ul>
 567 | .fi
 568 | .RE
 569 | .P
 570 | List items may consist of multiple paragraphs\. Each subsequent
 571 | .br
 572 | paragraph in a list item must be indented by either 4 spaces
 573 | .br
 574 | or one tab:
 575 | .RS 2
 576 | .nf
 577 | 1\.  This is a list item with two paragraphs\. Lorem ipsum dolor
 578 |     sit amet, consectetuer adipiscing elit\. Aliquam hendrerit
 579 |     mi posuere lectus\.
 580 | 
 581 |     Vestibulum enim wisi, viverra nec, fringilla in, laoreet
 582 |     vitae, risus\. Donec sit amet nisl\. Aliquam semper ipsum
 583 |     sit amet velit\.
 584 | 
 585 | 2\.  Suspendisse id sem consectetuer libero luctus adipiscing\.
 586 | .fi
 587 | .RE
 588 | .P
 589 | It looks nice if you indent every line of the subsequent
 590 | .br
 591 | paragraphs, but here again, Markdown will allow you to be
 592 | .br
 593 | lazy:
 594 | .RS 2
 595 | .nf
 596 | *   This is a list item with two paragraphs\.
 597 | 
 598 |     This is the second paragraph in the list item\. You're
 599 | only required to indent the first line\. Lorem ipsum dolor
 600 | sit amet, consectetuer adipiscing elit\.
 601 | 
 602 | *   Another item in the same list\.
 603 | .fi
 604 | .RE
 605 | .P
 606 | To put a blockquote within a list item, the blockquote's \fB>\fP
 607 | .br
 608 | delimiters need to be indented:
 609 | .RS 2
 610 | .nf
 611 | *   A list item with a blockquote:
 612 | 
 613 |     > This is a blockquote
 614 |     > inside a list item\.
 615 | .fi
 616 | .RE
 617 | .P
 618 | To put a code block within a list item, the code block needs
 619 | .br
 620 | to be indented \fItwice\fR \-\- 8 spaces or two tabs:
 621 | .RS 2
 622 | .nf
 623 | *   A list item with a code block:
 624 | 
 625 |         <code goes here>
 626 | .fi
 627 | .RE
 628 | .P
 629 | It's worth noting that it's possible to trigger an ordered list by
 630 | .br
 631 | accident, by writing something like this:
 632 | .RS 2
 633 | .nf
 634 | 1986\. What a great season\.
 635 | .fi
 636 | .RE
 637 | .P
 638 | In other words, a \fInumber\-period\-space\fR sequence at the beginning of a
 639 | .br
 640 | line\. To avoid this, you can backslash\-escape the period:
 641 | .RS 2
 642 | .nf
 643 | 1986\\\. What a great season\.
 644 | .fi
 645 | .RE
 646 | .SS Code Blocks
 647 | .P
 648 | Pre\-formatted code blocks are used for writing about programming or
 649 | .br
 650 | markup source code\. Rather than forming normal paragraphs, the lines
 651 | .br
 652 | of a code block are interpreted literally\. Markdown wraps a code block
 653 | .br
 654 | in both \fB<pre>\fP and \fB<code>\fP tags\.
 655 | .P
 656 | To produce a code block in Markdown, simply indent every line of the
 657 | .br
 658 | block by at least 4 spaces or 1 tab\. For example, given this input:
 659 | .RS 2
 660 | .nf
 661 | This is a normal paragraph:
 662 | 
 663 |     This is a code block\.
 664 | .fi
 665 | .RE
 666 | .P
 667 | Markdown will generate:
 668 | .RS 2
 669 | .nf
 670 | <p>This is a normal paragraph:</p>
 671 | 
 672 | <pre><code>This is a code block\.
 673 | </code></pre>
 674 | .fi
 675 | .RE
 676 | .P
 677 | One level of indentation \-\- 4 spaces or 1 tab \-\- is removed from each
 678 | .br
 679 | line of the code block\. For example, this:
 680 | .RS 2
 681 | .nf
 682 | Here is an example of AppleScript:
 683 | 
 684 |     tell application "Foo"
 685 |         beep
 686 |     end tell
 687 | .fi
 688 | .RE
 689 | .P
 690 | will turn into:
 691 | .RS 2
 692 | .nf
 693 | <p>Here is an example of AppleScript:</p>
 694 | 
 695 | <pre><code>tell application "Foo"
 696 |     beep
 697 | end tell
 698 | </code></pre>
 699 | .fi
 700 | .RE
 701 | .P
 702 | A code block continues until it reaches a line that is not indented
 703 | .br
 704 | (or the end of the article)\.
 705 | .P
 706 | Within a code block, ampersands (\fB&\fP) and angle brackets (\fB<\fP and \fB>\fP)
 707 | .br
 708 | are automatically converted into HTML entities\. This makes it very
 709 | .br
 710 | easy to include example HTML source code using Markdown \-\- just paste
 711 | .br
 712 | it and indent it, and Markdown will handle the hassle of encoding the
 713 | .br
 714 | ampersands and angle brackets\. For example, this:
 715 | .RS 2
 716 | .nf
 717 |     <div class="footer">
 718 |         &copy; 2004 Foo Corporation
 719 |     </div>
 720 | .fi
 721 | .RE
 722 | .P
 723 | will turn into:
 724 | .RS 2
 725 | .nf
 726 | <pre><code>&lt;div class="footer"&gt;
 727 |     &amp;copy; 2004 Foo Corporation
 728 | &lt;/div&gt;
 729 | </code></pre>
 730 | .fi
 731 | .RE
 732 | .P
 733 | Regular Markdown syntax is not processed within code blocks\. E\.g\.,
 734 | .br
 735 | asterisks are just literal asterisks within a code block\. This means
 736 | .br
 737 | it's also easy to use Markdown to write about Markdown's own syntax\.
 738 | .SS Horizontal Rules
 739 | .P
 740 | You can produce a horizontal rule tag (\fB<hr />\fP) by placing three or
 741 | .br
 742 | more hyphens, asterisks, or underscores on a line by themselves\. If you
 743 | .br
 744 | wish, you may use spaces between the hyphens or asterisks\. Each of the
 745 | .br
 746 | following lines will produce a horizontal rule:
 747 | .RS 2
 748 | .nf
 749 | * * *
 750 | 
 751 | ***
 752 | 
 753 | *****
 754 | 
 755 | \- \- \-
 756 | 
 757 | \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 758 | .fi
 759 | .RE
 760 | .SH SPAN ELEMENTS
 761 | .SS Links
 762 | .P
 763 | Markdown supports two style of links: \fIinline\fR and \fIreference\fR\|\.
 764 | .P
 765 | In both styles, the link text is delimited by [square brackets]\.
 766 | .P
 767 | To create an inline link, use a set of regular parentheses immediately
 768 | .br
 769 | after the link text's closing square bracket\. Inside the parentheses,
 770 | .br
 771 | put the URL where you want the link to point, along with an \fIoptional\fR
 772 | .br
 773 | title for the link, surrounded in quotes\. For example:
 774 | .RS 2
 775 | .nf
 776 | This is [an example](http://example\.com/ "Title") inline link\.
 777 | 
 778 | [This link](http://example\.net/) has no title attribute\.
 779 | .fi
 780 | .RE
 781 | .P
 782 | Will produce:
 783 | .RS 2
 784 | .nf
 785 | <p>This is <a href="http://example\.com/" title="Title">
 786 | an example</a> inline link\.</p>
 787 | 
 788 | <p><a href="http://example\.net/">This link</a> has no
 789 | title attribute\.</p>
 790 | .fi
 791 | .RE
 792 | .P
 793 | If you're referring to a local resource on the same server, you can
 794 | .br
 795 | use relative paths:
 796 | .RS 2
 797 | .nf
 798 | See my [About](/about/) page for details\.
 799 | .fi
 800 | .RE
 801 | .P
 802 | Reference\-style links use a second set of square brackets, inside
 803 | .br
 804 | which you place a label of your choosing to identify the link:
 805 | .RS 2
 806 | .nf
 807 | This is [an example][id] reference\-style link\.
 808 | .fi
 809 | .RE
 810 | .P
 811 | You can optionally use a space to separate the sets of brackets:
 812 | .RS 2
 813 | .nf
 814 | This is [an example] [id] reference\-style link\.
 815 | .fi
 816 | .RE
 817 | .P
 818 | Then, anywhere in the document, you define your link label like this,
 819 | .br
 820 | on a line by itself:
 821 | .RS 2
 822 | .nf
 823 | [id]: http://example\.com/  "Optional Title Here"
 824 | .fi
 825 | .RE
 826 | .P
 827 | That is:
 828 | 
 829 | .RS 1
 830 | .IP \(bu 2
 831 | Square brackets containing the link identifier (optionally
 832 | .br
 833 | indented from the left margin using up to three spaces);
 834 | .IP \(bu 2
 835 | followed by a colon;
 836 | .IP \(bu 2
 837 | followed by one or more spaces (or tabs);
 838 | .IP \(bu 2
 839 | followed by the URL for the link;
 840 | .IP \(bu 2
 841 | optionally followed by a title attribute for the link, enclosed
 842 | .br
 843 | in double or single quotes, or enclosed in parentheses\.
 844 | 
 845 | .RE
 846 | .P
 847 | The following three link definitions are equivalent:
 848 | .RS 2
 849 | .nf
 850 | [foo]: http://example\.com/  "Optional Title Here"
 851 | [foo]: http://example\.com/  'Optional Title Here'
 852 | [foo]: http://example\.com/  (Optional Title Here)
 853 | .fi
 854 | .RE
 855 | .P
 856 | \fBNote:\fR There is a known bug in Markdown\.pl 1\.0\.1 which prevents
 857 | .br
 858 | single quotes from being used to delimit link titles\.
 859 | .P
 860 | The link URL may, optionally, be surrounded by angle brackets:
 861 | .RS 2
 862 | .nf
 863 | [id]: <http://example\.com/>  "Optional Title Here"
 864 | .fi
 865 | .RE
 866 | .P
 867 | You can put the title attribute on the next line and use extra spaces
 868 | .br
 869 | or tabs for padding, which tends to look better with longer URLs:
 870 | .RS 2
 871 | .nf
 872 | [id]: http://example\.com/longish/path/to/resource/here
 873 |     "Optional Title Here"
 874 | .fi
 875 | .RE
 876 | .P
 877 | Link definitions are only used for creating links during Markdown
 878 | .br
 879 | processing, and are stripped from your document in the HTML output\.
 880 | .P
 881 | Link definition names may consist of letters, numbers, spaces, and
 882 | .br
 883 | punctuation \-\- but they are \fInot\fR case sensitive\. E\.g\. these two
 884 | .br
 885 | links:
 886 | .RS 2
 887 | .nf
 888 | [link text][a]
 889 | [link text][A]
 890 | .fi
 891 | .RE
 892 | .P
 893 | are equivalent\.
 894 | .P
 895 | The \fIimplicit link name\fR shortcut allows you to omit the name of the
 896 | .br
 897 | link, in which case the link text itself is used as the name\.
 898 | .br
 899 | Just use an empty set of square brackets \-\- e\.g\., to link the word
 900 | .br
 901 | "Google" to the google\.com web site, you could simply write:
 902 | .RS 2
 903 | .nf
 904 | [Google][]
 905 | .fi
 906 | .RE
 907 | .P
 908 | And then define the link:
 909 | .RS 2
 910 | .nf
 911 | [Google]: http://google\.com/
 912 | .fi
 913 | .RE
 914 | .P
 915 | Because link names may contain spaces, this shortcut even works for
 916 | .br
 917 | multiple words in the link text:
 918 | .RS 2
 919 | .nf
 920 | Visit [Daring Fireball][] for more information\.
 921 | .fi
 922 | .RE
 923 | .P
 924 | And then define the link:
 925 | .RS 2
 926 | .nf
 927 | [Daring Fireball]: http://daringfireball\.net/
 928 | .fi
 929 | .RE
 930 | .P
 931 | Link definitions can be placed anywhere in your Markdown document\. I
 932 | .br
 933 | tend to put them immediately after each paragraph in which they're
 934 | .br
 935 | used, but if you want, you can put them all at the end of your
 936 | .br
 937 | document, sort of like footnotes\.
 938 | .P
 939 | Here's an example of reference links in action:
 940 | .RS 2
 941 | .nf
 942 | I get 10 times more traffic from [Google] [1] than from
 943 | [Yahoo] [2] or [MSN] [3]\.
 944 | 
 945 |   [1]: http://google\.com/        "Google"
 946 |   [2]: http://search\.yahoo\.com/  "Yahoo Search"
 947 |   [3]: http://search\.msn\.com/    "MSN Search"
 948 | .fi
 949 | .RE
 950 | .P
 951 | Using the implicit link name shortcut, you could instead write:
 952 | .RS 2
 953 | .nf
 954 | I get 10 times more traffic from [Google][] than from
 955 | [Yahoo][] or [MSN][]\.
 956 | 
 957 |   [google]: http://google\.com/        "Google"
 958 |   [yahoo]:  http://search\.yahoo\.com/  "Yahoo Search"
 959 |   [msn]:    http://search\.msn\.com/    "MSN Search"
 960 | .fi
 961 | .RE
 962 | .P
 963 | Both of the above examples will produce the following HTML output:
 964 | .RS 2
 965 | .nf
 966 | <p>I get 10 times more traffic from <a href="http://google\.com/"
 967 | title="Google">Google</a> than from
 968 | <a href="http://search\.yahoo\.com/" title="Yahoo Search">Yahoo</a>
 969 | or <a href="http://search\.msn\.com/" title="MSN Search">MSN</a>\.</p>
 970 | .fi
 971 | .RE
 972 | .P
 973 | For comparison, here is the same paragraph written using
 974 | .br
 975 | Markdown's inline link style:
 976 | .RS 2
 977 | .nf
 978 | I get 10 times more traffic from [Google](http://google\.com/ "Google")
 979 | than from [Yahoo](http://search\.yahoo\.com/ "Yahoo Search") or
 980 | [MSN](http://search\.msn\.com/ "MSN Search")\.
 981 | .fi
 982 | .RE
 983 | .P
 984 | The point of reference\-style links is not that they're easier to
 985 | .br
 986 | write\. The point is that with reference\-style links, your document
 987 | .br
 988 | source is vastly more readable\. Compare the above examples: using
 989 | .br
 990 | reference\-style links, the paragraph itself is only 81 characters
 991 | .br
 992 | long; with inline\-style links, it's 176 characters; and as raw HTML,
 993 | .br
 994 | it's 234 characters\. In the raw HTML, there's more markup than there
 995 | .br
 996 | is text\.
 997 | .P
 998 | With Markdown's reference\-style links, a source document much more
 999 | .br
1000 | closely resembles the final output, as rendered in a browser\. By
1001 | .br
1002 | allowing you to move the markup\-related metadata out of the paragraph,
1003 | .br
1004 | you can add links without interrupting the narrative flow of your
1005 | .br
1006 | prose\.
1007 | .SS Emphasis
1008 | .P
1009 | Markdown treats asterisks (\fB*\fP) and underscores (\fB_\fP) as indicators of
1010 | .br
1011 | emphasis\. Text wrapped with one \fB*\fP or \fB_\fP will be wrapped with an
1012 | .br
1013 | HTML \fB<em>\fP tag; double \fB*\fP\|'s or \fB_\fP\|'s will be wrapped with an HTML
1014 | .br
1015 | \fB<strong>\fP tag\. E\.g\., this input:
1016 | .RS 2
1017 | .nf
1018 | *single asterisks*
1019 | 
1020 | _single underscores_
1021 | 
1022 | **double asterisks**
1023 | 
1024 | __double underscores__
1025 | .fi
1026 | .RE
1027 | .P
1028 | will produce:
1029 | .RS 2
1030 | .nf
1031 | <em>single asterisks</em>
1032 | 
1033 | <em>single underscores</em>
1034 | 
1035 | <strong>double asterisks</strong>
1036 | 
1037 | <strong>double underscores</strong>
1038 | .fi
1039 | .RE
1040 | .P
1041 | You can use whichever style you prefer; the lone restriction is that
1042 | .br
1043 | the same character must be used to open and close an emphasis span\.
1044 | .P
1045 | Emphasis can be used in the middle of a word:
1046 | .RS 2
1047 | .nf
1048 | un*frigging*believable
1049 | .fi
1050 | .RE
1051 | .P
1052 | But if you surround an \fB*\fP or \fB_\fP with spaces, it'll be treated as a
1053 | .br
1054 | literal asterisk or underscore\.
1055 | .P
1056 | To produce a literal asterisk or underscore at a position where it
1057 | .br
1058 | would otherwise be used as an emphasis delimiter, you can backslash
1059 | .br
1060 | escape it:
1061 | .RS 2
1062 | .nf
1063 | \\*this text is surrounded by literal asterisks\\*
1064 | .fi
1065 | .RE
1066 | .SS Code
1067 | .P
1068 | To indicate a span of code, wrap it with backtick quotes (\fB`\fP)\.
1069 | .br
1070 | Unlike a pre\-formatted code block, a code span indicates code within a
1071 | .br
1072 | normal paragraph\. For example:
1073 | .RS 2
1074 | .nf
1075 | Use the `printf()` function\.
1076 | .fi
1077 | .RE
1078 | .P
1079 | will produce:
1080 | .RS 2
1081 | .nf
1082 | <p>Use the <code>printf()</code> function\.</p>
1083 | .fi
1084 | .RE
1085 | .P
1086 | To include a literal backtick character within a code span, you can use
1087 | .br
1088 | multiple backticks as the opening and closing delimiters:
1089 | .RS 2
1090 | .nf
1091 | ``There is a literal backtick (`) here\.``
1092 | .fi
1093 | .RE
1094 | .P
1095 | which will produce this:
1096 | .RS 2
1097 | .nf
1098 | <p><code>There is a literal backtick (`) here\.</code></p>
1099 | .fi
1100 | .RE
1101 | .P
1102 | The backtick delimiters surrounding a code span may include spaces \-\-
1103 | .br
1104 | one after the opening, one before the closing\. This allows you to place
1105 | .br
1106 | literal backtick characters at the beginning or end of a code span:
1107 | .RS 2
1108 | .nf
1109 | A single backtick in a code span: `` ` ``
1110 | 
1111 | A backtick\-delimited string in a code span: `` `foo` ``
1112 | .fi
1113 | .RE
1114 | .P
1115 | will produce:
1116 | .RS 2
1117 | .nf
1118 | <p>A single backtick in a code span: <code>`</code></p>
1119 | 
1120 | <p>A backtick\-delimited string in a code span: <code>`foo`</code></p>
1121 | .fi
1122 | .RE
1123 | .P
1124 | With a code span, ampersands and angle brackets are encoded as HTML
1125 | .br
1126 | entities automatically, which makes it easy to include example HTML
1127 | .br
1128 | tags\. Markdown will turn this:
1129 | .RS 2
1130 | .nf
1131 | Please don't use any `<blink>` tags\.
1132 | .fi
1133 | .RE
1134 | .P
1135 | into:
1136 | .RS 2
1137 | .nf
1138 | <p>Please don't use any <code>&lt;blink&gt;</code> tags\.</p>
1139 | .fi
1140 | .RE
1141 | .P
1142 | You can write this:
1143 | .RS 2
1144 | .nf
1145 | `&#8212;` is the decimal\-encoded equivalent of `&mdash;`\.
1146 | .fi
1147 | .RE
1148 | .P
1149 | to produce:
1150 | .RS 2
1151 | .nf
1152 | <p><code>&amp;#8212;</code> is the decimal\-encoded
1153 | equivalent of <code>&amp;mdash;</code>\.</p>
1154 | .fi
1155 | .RE
1156 | .SS Images
1157 | .P
1158 | Admittedly, it's fairly difficult to devise a "natural" syntax for
1159 | .br
1160 | placing images into a plain text document format\.
1161 | .P
1162 | Markdown uses an image syntax that is intended to resemble the syntax
1163 | .br
1164 | for links, allowing for two styles: \fIinline\fR and \fIreference\fR\|\.
1165 | .P
1166 | Inline image syntax looks like this:
1167 | .RS 2
1168 | .nf
1169 | ![Alt text](/path/to/img\.jpg)
1170 | 
1171 | ![Alt text](/path/to/img\.jpg "Optional title")
1172 | .fi
1173 | .RE
1174 | .P
1175 | That is:
1176 | 
1177 | .RS 1
1178 | .IP \(bu 2
1179 | An exclamation mark: \fB!\fP;
1180 | .IP \(bu 2
1181 | followed by a set of square brackets, containing the \fBalt\fP
1182 | .br
1183 | attribute text for the image;
1184 | .IP \(bu 2
1185 | followed by a set of parentheses, containing the URL or path to
1186 | .br
1187 | the image, and an optional \fBtitle\fP attribute enclosed in double
1188 | .br
1189 | or single quotes\.
1190 | 
1191 | .RE
1192 | .P
1193 | Reference\-style image syntax looks like this:
1194 | .RS 2
1195 | .nf
1196 | ![Alt text][id]
1197 | .fi
1198 | .RE
1199 | .P
1200 | Where "id" is the name of a defined image reference\. Image references
1201 | .br
1202 | are defined using syntax identical to link references:
1203 | .RS 2
1204 | .nf
1205 | [id]: url/to/image  "Optional title attribute"
1206 | .fi
1207 | .RE
1208 | .P
1209 | As of this writing, Markdown has no syntax for specifying the
1210 | .br
1211 | dimensions of an image; if this is important to you, you can simply
1212 | .br
1213 | use regular HTML \fB<img>\fP tags\.
1214 | .SH MISCELLANEOUS
1215 | .SS Automatic Links
1216 | .P
1217 | 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:
1218 | .RS 2
1219 | .nf
1220 | <http://example\.com/>
1221 | .fi
1222 | .RE
1223 | .P
1224 | Markdown will turn this into:
1225 | .RS 2
1226 | .nf
1227 | <a href="http://example\.com/">http://example\.com/</a>
1228 | .fi
1229 | .RE
1230 | .P
1231 | Automatic links for email addresses work similarly, except that
1232 | .br
1233 | Markdown will also perform a bit of randomized decimal and hex
1234 | .br
1235 | entity\-encoding to help obscure your address from address\-harvesting
1236 | .br
1237 | spambots\. For example, Markdown will turn this:
1238 | .RS 2
1239 | .nf
1240 | <address@example\.com>
1241 | .fi
1242 | .RE
1243 | .P
1244 | into something like this:
1245 | .RS 2
1246 | .nf
1247 | <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
1248 | &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
1249 | &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
1250 | &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
1251 | .fi
1252 | .RE
1253 | .P
1254 | which will render in a browser as a clickable link to "address@example.com\|\.
1255 | .P
1256 | (This sort of entity\-encoding trick will indeed fool many, if not
1257 | .br
1258 | most, address\-harvesting bots, but it definitely won't fool all of
1259 | .br
1260 | them\. It's better than nothing, but an address published in this way
1261 | .br
1262 | will probably eventually start receiving spam\.)
1263 | .SS Backslash Escapes
1264 | .P
1265 | Markdown allows you to use backslash escapes to generate literal
1266 | .br
1267 | characters which would otherwise have special meaning in Markdown's
1268 | .br
1269 | formatting syntax\. For example, if you wanted to surround a word
1270 | .br
1271 | with literal asterisks (instead of an HTML \fB<em>\fP tag), you can use
1272 | .br
1273 | backslashes before the asterisks, like this:
1274 | .RS 2
1275 | .nf
1276 | \\*literal asterisks\\*
1277 | .fi
1278 | .RE
1279 | .P
1280 | Markdown provides backslash escapes for the following characters:
1281 | .RS 2
1282 | .nf
1283 | \\   backslash
1284 | `   backtick
1285 | *   asterisk
1286 | _   underscore
1287 | {}  curly braces
1288 | []  square brackets
1289 | ()  parentheses
1290 | #   hash mark
1291 | +   plus sign
1292 | \-   minus sign (hyphen)
1293 | \|\.   dot
1294 | !   exclamation mark
1295 | .fi
1296 | .RE
1297 | .SH AUTHOR
1298 | .P
1299 | Markdown was created by John Gruber\.
1300 | .P
1301 | Manual page by Ryan Tomayko\. It's pretty much a direct copy of the
1302 | .br
1303 | .UR http://daringfireball.net/projects/markdown/syntax
1304 | .I Markdown Syntax Reference
1305 | .UE ,
1306 | 
1307 | .br
1308 | also by John Gruber\.
1309 | .SH SEE ALSO
1310 | .P
1311 | ronn(5)
1312 | .br
1313 | .UR http://daringfireball.net/projects/markdown/
1314 | .I Markdown Syntax Reference
1315 | .UE
1316 | 


--------------------------------------------------------------------------------
/test/man/nested_list_with_code.1:
--------------------------------------------------------------------------------
 1 | .TH "A" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBa\fR
 4 | .P
 5 | Tight list:
 6 | 
 7 | .RS 1
 8 | .IP \(bu 2
 9 | \fBtoggle_status\fP
10 | .RS 1
11 | .IP \(bu 2
12 | Toggle the display of the status bar1
13 | .IP \(bu 2
14 | Toggle the display of the status bar2
15 | 
16 | .RE
17 | .IP \(bu 2
18 | \fBspawn <executable> <additional args>\fP TODO explain path\-alike expansion
19 | 
20 | .RE
21 | .P
22 | Loose list:
23 | 
24 | .RS 1
25 | .IP \(bu 2
26 | \fBtoggle_status\fP
27 | 
28 | .RS 1
29 | .IP \(bu 2
30 | Toggle the display of the status bar1
31 | .IP \(bu 2
32 | Toggle the display of the status bar2
33 | 
34 | .RE
35 | .IP \(bu 2
36 | \fBspawn <executable> <additional args>\fP TODO explain path\-alike expansion
37 | 
38 | .RE
39 | 


--------------------------------------------------------------------------------
/test/man/noname.1:
--------------------------------------------------------------------------------
1 | .TH "TEST" "1" "January 1979"
2 | .SH NAME
3 | .P
4 | test \- a nice test
5 | .SH SYNOPSYS
6 | .P
7 | test is a test
8 | 


--------------------------------------------------------------------------------
/test/man/pre_block_with_quotes.1:
--------------------------------------------------------------------------------
 1 | .TH "T" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBt\fR \- test
 4 | .SH test
 5 | .RS 2
 6 | .nf
 7 | [ "$11" ]
 8 | .fi
 9 | .RE
10 | 


--------------------------------------------------------------------------------
/test/man/regressions.1:
--------------------------------------------------------------------------------
1 | .TH "REGRESSIONS" "7" "January 1979"
2 | .SH "NAME"
3 | \fBregressions\fR \- issues
4 | .SH inlines
5 | .P
6 | This should be  \fI(a \fBb\fP)\fR ok\.
7 | .P
8 | This should not double escape \fBpkg\-js\-tools\fR\|\.
9 | 


--------------------------------------------------------------------------------
/test/man/simple_table.1:
--------------------------------------------------------------------------------
 1 | .TH "SIMPLE_TABLE" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBsimple_table\fR
 4 | .TS
 5 | tab(|) expand nowarn box;
 6 | l c r.
 7 | T{
 8 | Col1
 9 | T}|T{
10 | Col2
11 | T}|T{
12 | Col3
13 | T}
14 | =
15 | T{
16 | A
17 | T}|T{
18 | B
19 | T}|T{
20 | C
21 | T}
22 | _
23 | T{
24 | D
25 | T}|T{
26 | E
27 | T}|T{
28 | F
29 | T}
30 | .TE
31 | 


--------------------------------------------------------------------------------
/test/man/table.1:
--------------------------------------------------------------------------------
  1 | .TH "TABLE" "7" "January 1979"
  2 | .SH "NAME"
  3 | \fBtable\fR \- test data for table format
  4 | .P
  5 | test table copy and paste form www\.
  6 | .SH LARGE TABLE
  7 | .P
  8 | .UR https://en.wikipedia.org/wiki/Comparison_of_file_systems
  9 | .I Comparison of file systems
 10 | .UE
 11 | .TS
 12 | tab(|) expand nowarn box;
 13 | l l l l.
 14 | T{
 15 | File system
 16 | T}|T{
 17 | Creator
 18 | T}|T{
 19 | Year of introduction
 20 | T}|T{
 21 | Original operating system
 22 | T}
 23 | =
 24 | T{
 25 | DECtape
 26 | T}|T{
 27 | DEC
 28 | T}|T{
 29 | 1964
 30 | T}|T{
 31 | PDP\-6 Monitor
 32 | T}
 33 | _
 34 | T{
 35 | DASD
 36 | T}|T{
 37 | IBM
 38 | T}|T{
 39 | 1964
 40 | T}|T{
 41 | OS/360
 42 | T}
 43 | _
 44 | T{
 45 | Level\-D
 46 | T}|T{
 47 | DEC
 48 | T}|T{
 49 | 1968
 50 | T}|T{
 51 | TOPS\-10
 52 | T}
 53 | _
 54 | T{
 55 | George 2
 56 | T}|T{
 57 | ICT (later ICL)
 58 | T}|T{
 59 | 1968
 60 | T}|T{
 61 | George 2
 62 | T}
 63 | _
 64 | T{
 65 | Version 6 Unix file system (V6FS)
 66 | T}|T{
 67 | Bell Labs
 68 | T}|T{
 69 | 1972
 70 | T}|T{
 71 | Version 6 Unix
 72 | T}
 73 | _
 74 | T{
 75 | RT\-11 file system
 76 | T}|T{
 77 | DEC
 78 | T}|T{
 79 | 1973
 80 | T}|T{
 81 | RT\-11
 82 | T}
 83 | _
 84 | T{
 85 | Disk Operating System (GEC DOS)
 86 | T}|T{
 87 | GEC
 88 | T}|T{
 89 | 1973
 90 | T}|T{
 91 | Core Operating System
 92 | T}
 93 | _
 94 | T{
 95 | CP/M file system
 96 | T}|T{
 97 | Digital Research (Gary Kildall)
 98 | T}|T{
 99 | 1974
100 | T}|T{
101 | CP/M[1]
102 | T}
103 | _
104 | T{
105 | ODS\-1
106 | T}|T{
107 | DEC
108 | T}|T{
109 | 1975
110 | T}|T{
111 | RSX\-11
112 | T}
113 | _
114 | T{
115 | GEC DOS filing system extended
116 | T}|T{
117 | GEC
118 | T}|T{
119 | 1977
120 | T}|T{
121 | OS4000
122 | T}
123 | _
124 | T{
125 | FAT (8\-bit)
126 | T}|T{
127 | Microsoft (Marc McDonald) for NCR
128 | T}|T{
129 | 1977
130 | T}|T{
131 | Microsoft Standalone Disk BASIC\-80 (later Microsoft Standalone Disk BASIC\-86)
132 | T}
133 | _
134 | T{
135 | DOS 3\.x
136 | T}|T{
137 | Apple Computer
138 | T}|T{
139 | 1978
140 | T}|T{
141 | Apple DOS
142 | T}
143 | _
144 | T{
145 | Pascal
146 | T}|T{
147 | Apple Computer
148 | T}|T{
149 | 1978
150 | T}|T{
151 | Apple Pascal
152 | T}
153 | _
154 | T{
155 | CBM DOS
156 | T}|T{
157 | Commodore
158 | T}|T{
159 | 1978
160 | T}|T{
161 | Commodore BASIC
162 | T}
163 | _
164 | T{
165 | Version 7 Unix file system (V7FS)
166 | T}|T{
167 | Bell Labs
168 | T}|T{
169 | 1979
170 | T}|T{
171 | Version 7 Unix
172 | T}
173 | _
174 | T{
175 | ODS\-2
176 | T}|T{
177 | DEC
178 | T}|T{
179 | 1979
180 | T}|T{
181 | OpenVMS
182 | T}
183 | .TE
184 | .SH LONG TEXT
185 | .TS
186 | tab(|) expand nowarn box;
187 | l l l.
188 | T{
189 | Person
190 | T}|T{
191 | Work
192 | T}|T{
193 | Quote
194 | T}
195 | =
196 | T{
197 | Sherlock Holmes
198 | T}|T{
199 | The Norwood Builder
200 | T}|T{
201 | You mentioned your name as if I should recognize it, but beyond the obvious facts that you are a bachelor, a solicitor, a freemason, and an asthmatic, I know nothing whatever about you\.
202 | T}
203 | .TE
204 | .SH THING TABLE
205 | .TS
206 | tab(|) expand nowarn box;
207 | l l.
208 | T{
209 | 1
210 | T}|T{
211 | 2
212 | T}
213 | =
214 | T{
215 | 1
216 | T}|T{
217 | 2
218 | T}
219 | _
220 | T{
221 | 1
222 | T}|T{
223 | 2
224 | T}
225 | _
226 | T{
227 | 1
228 | T}|T{
229 | 2
230 | T}
231 | _
232 | T{
233 | 1
234 | T}|T{
235 | 2
236 | T}
237 | _
238 | T{
239 | 1
240 | T}|T{
241 | 2
242 | T}
243 | _
244 | T{
245 | T{1
246 | T}|T{
247 | 2
248 | T}
249 | _
250 | T{
251 | 1
252 | T}|T{
253 | 2
254 | T}
255 | _
256 | T{
257 | 1
258 | T}|T{
259 | 2
260 | T}
261 | _
262 | T{
263 | 1
264 | T}|T{
265 | 2
266 | T}
267 | _
268 | T{
269 | 1
270 | T}|T{
271 | 2
272 | T}
273 | _
274 | T{
275 | 1
276 | T}|T{
277 | 2
278 | T}
279 | _
280 | T{
281 | 1
282 | T}|T{
283 | 2
284 | T}
285 | _
286 | T{
287 | 1
288 | T}|T{
289 | 2
290 | T}
291 | _
292 | T{
293 | 1
294 | T}|T{
295 | 2
296 | T}
297 | _
298 | T{
299 | 1
300 | T}|T{
301 | 2
302 | T}
303 | _
304 | T{
305 | 1
306 | T}|T{
307 | 2
308 | T}
309 | _
310 | T{
311 | 1
312 | T}|T{
313 | 2
314 | T}
315 | _
316 | T{
317 | 1
318 | T}|T{
319 | 2
320 | T}
321 | _
322 | T{
323 | 1
324 | T}|T{
325 | 2
326 | T}
327 | .TE
328 | 


--------------------------------------------------------------------------------
/test/man/underline_spacing_test.1:
--------------------------------------------------------------------------------
 1 | .TH "UNDERLINE_SPACING_TEST" "1" "January 1979"
 2 | .SH "NAME"
 3 | \fBunderline_spacing_test\fR
 4 | 
 5 | .RS 1
 6 | .IP \(bu 2
 7 | \fB\-S\fP \fItext\fR, \fBsearch\fP \fItext\fR:
 8 | .br
 9 | Performs a substring search of formula names for \fItext\fR\|\.
10 | .IP \(bu 2
11 | \fB\-O\fP <text>, \fBother\fP <text>:
12 | .br
13 | Does something else\.
14 | 
15 | .RE
16 | .P
17 | Should space text properly\.
18 | <!\-\- this is a comment \-\->
19 | 


--------------------------------------------------------------------------------
/test/md/blockquotes.md:
--------------------------------------------------------------------------------
 1 | t(1) - test
 2 | ===========
 3 | 
 4 | ## test
 5 | 
 6 |     A blockquote here.
 7 |     Continuing on second line.
 8 | 
 9 | Hello.
10 | 
11 | > Another block quote. With a long title. That will break a line eventually later.
12 | that continues on second line
13 | > continuation
14 | 


--------------------------------------------------------------------------------
/test/md/definition_list_syntax.md:
--------------------------------------------------------------------------------
 1 | defition_list_syntax(5) -- hiya
 2 | ===============================
 3 | 
 4 | Definition lists look like unordered lists:
 5 | 
 6 |   * term:
 7 |     definition
 8 | 
 9 |   * another one:
10 |     The definition may span
11 |     multiple lines and even 
12 |     start 
13 |     new paragraphs
14 | 
15 |   * `--somearg`=<VALUE>:
16 |     We can do that too.
17 | 


--------------------------------------------------------------------------------
/test/md/dots_at_line_start_test.md:
--------------------------------------------------------------------------------
1 | There's a weird issue where dots at the beginning of a line
2 | generate troff warnings due to escaping.
3 | 
4 | .. let's see what happens.
5 | 


--------------------------------------------------------------------------------
/test/md/ellipses.md:
--------------------------------------------------------------------------------
1 | ellipses(7) -- testing ellipses
2 | ===============================
3 | 
4 | Ellipses should be replaced...
5 | 
6 | ...also, they shouldn't interfere with regular dots at the beginning
7 | of a line.
8 | 


--------------------------------------------------------------------------------
/test/md/entity_encoding_test.md:
--------------------------------------------------------------------------------
 1 | # hello(1) -- hello world
 2 | 
 3 | Your output &lt;i&gt;might&lt;/i&gt; look like this:
 4 | 
 5 |     * Chris
 6 |     *
 7 |     * &lt;b&gt;GitHub&lt;/b&gt;
 8 |     * <b>GitHub</b>
 9 | 
10 | Here's some special entities:
11 | 
12 |   * &amp;bull;       &bull;
13 |   * &amp;nbsp;       &nbsp;
14 |   * &amp;copy;       &copy;
15 |   * &amp;rdquo;      &rdquo;
16 |   * &amp;mdash;      &mdash;
17 |   * &amp;reg;        &reg;
18 |   * &amp;sect;       &sect;
19 |   * &amp;ge;         &ge;
20 |   * &amp;le;         &le;
21 |   * &amp;ne;         &ne;
22 |   * &amp;equiv;      &equiv;
23 |   * &amp;plusmn;     &plusmn;
24 | 
25 | Here's a line that uses non-breaking spaces to force the
26 | last&nbsp;few&nbsp;words&nbsp;to&nbsp;wrap&nbsp;together.
27 | 


--------------------------------------------------------------------------------
/test/md/escapes.md:
--------------------------------------------------------------------------------
 1 | # escapes tests
 2 | 
 3 | backslashes before the asterisks, like this:
 4 | 
 5 |     \*literal asterisks\*
 6 | 
 7 | Markdown provides backslash escapes for the following characters:
 8 | 
 9 |     \   backslash
10 |     `   backtick
11 |     *   asterisk
12 |     _   underscore
13 |     {}  curly braces
14 |     []  square brackets
15 |     ()  parentheses
16 |     #   hash mark
17 |     +   plus sign
18 |     -   minus sign (hyphen)
19 |     .   dot
20 |     !   exclamation mark
21 | 


--------------------------------------------------------------------------------
/test/md/graves.md:
--------------------------------------------------------------------------------
1 | test
2 | ====
3 | 
4 | ## this title `will render` strangely
5 | 
6 | This is the body text.
7 | 
8 | 


--------------------------------------------------------------------------------
/test/md/links.md:
--------------------------------------------------------------------------------
 1 | I get 10 times more traffic from [Google][1] than from
 2 | [Yahoo][2] or [MSN][3].
 3 | 
 4 |   [1]: http://google.com/        "Google"
 5 |   [2]: http://search.yahoo.com/  "Yahoo Search"
 6 |   [3]: http://search.msn.com/    "MSN Search"
 7 | 
 8 | This is to test proper escape of html chars and non-repeating link:
 9 | <xxxxx@xxxx.xxxx.xxxx.xx>
10 | 
11 | I get 10 times more traffic from [Google][] than from
12 | [Yahoo][] or [MSN][].
13 | 
14 |   [google]: http://google.com/        "Google"
15 |   [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
16 |   [msn]:    http://search.msn.com/    "MSN Search"
17 | 
18 | Non-repeating http link <https://example.com/test>
19 | 
20 | Also
21 | [Google](http://google.com/ "Google")
22 | 
23 | and [local links should not crash](./table.md)
24 | 


--------------------------------------------------------------------------------
/test/md/list.md:
--------------------------------------------------------------------------------
 1 | a(1)
 2 | ====
 3 | 
 4 | This is a tight list:
 5 | 
 6 | * `toggle_status`: test
 7 | * `spawn <executable> <additional args>`
 8 |   TODO explain path-alike expansion,
 9 |   ability to get a block here.
10 | 
11 | This is a loose list:
12 | 
13 | * `toggle_status`:
14 |   test
15 | 
16 | * `spawn <executable> <additional args>`:
17 |   TODO explain path-alike expansion,
18 |   ability to get a block here.
19 | 


--------------------------------------------------------------------------------
/test/md/markdown_syntax.md:
--------------------------------------------------------------------------------
  1 | markdown(5) -- humane markup syntax
  2 | ===================================
  3 | 
  4 | ## SYNOPSIS
  5 | 
  6 |     # Header 1 #
  7 |     ## Header 2 ##
  8 |     ### Header 3 ###             (Hashes on right are optional)
  9 |     #### Header 4 ####
 10 |     ##### Header 5 #####
 11 | 
 12 |     This is a paragraph, which is text surrounded by whitespace.
 13 |     Paragraphs can be on one line (or many), and can drone on for
 14 |     hours.
 15 | 
 16 |     [Reference style links][1] and [inline links](http://example.com)
 17 |     [1]: http://example.com "Title is optional"
 18 | 
 19 |     Inline markup like _italics_,  **bold**, and `code()`.
 20 | 
 21 |     ![picture alt](/images/photo.jpeg "Title is optional")
 22 | 
 23 |     > Blockquotes are like quoted text in email replies
 24 |     >> And, they can be nested
 25 | 
 26 |         code blocks are for preformatted
 27 |         text and must be indented with four spaces
 28 | 
 29 |     * Bullet lists are easy too
 30 |       * You can
 31 |       * even
 32 |       * nest them
 33 |     - Another one
 34 |     + Another one
 35 | 
 36 | ## DESCRIPTION
 37 | 
 38 | ### Philosophy
 39 | 
 40 | Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
 41 | 
 42 | Readability, however, is emphasized above all else. A Markdown-formatted
 43 | document should be publishable as-is, as plain text, without looking
 44 | like it's been marked up with tags or formatting instructions. While
 45 | Markdown's syntax has been influenced by several existing text-to-HTML
 46 | filters -- including [Setext][1], [atx][2], [Textile][3], [reStructuredText][4],
 47 | [Grutatext][5], and [EtText][6] -- the single biggest source of
 48 | inspiration for Markdown's syntax is the format of plain text email.
 49 | 
 50 |   [1]: http://docutils.sourceforge.net/mirror/setext.html
 51 |   [2]: http://www.aaronsw.com/2002/atx/
 52 |   [3]: http://textism.com/tools/textile/
 53 |   [4]: http://docutils.sourceforge.net/rst.html
 54 |   [5]: http://www.triptico.com/software/grutatxt.html
 55 |   [6]: http://ettext.taint.org/doc/
 56 | 
 57 | To this end, Markdown's syntax is comprised entirely of punctuation
 58 | characters, which punctuation characters have been carefully chosen so
 59 | as to look like what they mean. E.g., asterisks around a word actually
 60 | look like \*emphasis\*. Markdown lists look like, well, lists. Even
 61 | blockquotes look like quoted passages of text, assuming you've ever
 62 | used email.
 63 | 
 64 | ### Inline HTML
 65 | 
 66 | Markdown's syntax is intended for one purpose: to be used as a
 67 | format for *writing* for the web.
 68 | 
 69 | Markdown is not a replacement for HTML, or even close to it. Its
 70 | syntax is very small, corresponding only to a very small subset of
 71 | HTML tags. The idea is *not* to create a syntax that makes it easier
 72 | to insert HTML tags. In my opinion, HTML tags are already easy to
 73 | insert. The idea for Markdown is to make it easy to read, write, and
 74 | edit prose. HTML is a *publishing* format; Markdown is a *writing*
 75 | format. Thus, Markdown's formatting syntax only addresses issues that
 76 | can be conveyed in plain text.
 77 | 
 78 | For any markup that is not covered by Markdown's syntax, you simply
 79 | use HTML itself. There's no need to preface it or delimit it to
 80 | indicate that you're switching from Markdown to HTML; you just use
 81 | the tags.
 82 | 
 83 | The only restrictions are that block-level HTML elements -- e.g. `<div>`,
 84 | `<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
 85 | content by blank lines, and the start and end tags of the block should
 86 | not be indented with tabs or spaces. Markdown is smart enough not
 87 | to add extra (unwanted) `<p>` tags around HTML block-level tags.
 88 | 
 89 | For example, to add an HTML table to a Markdown article:
 90 | 
 91 |     This is a regular paragraph.
 92 | 
 93 |     <table>
 94 |         <tr>
 95 |             <td>Foo</td>
 96 |         </tr>
 97 |     </table>
 98 | 
 99 |     This is another regular paragraph.
100 | 
101 | Note that Markdown formatting syntax is not processed within block-level
102 | HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
103 | HTML block.
104 | 
105 | Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
106 | used anywhere in a Markdown paragraph, list item, or header. If you
107 | want, you can even use HTML tags instead of Markdown formatting; e.g. if
108 | you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
109 | link or image syntax, go right ahead.
110 | 
111 | Unlike block-level HTML tags, Markdown syntax *is* processed within
112 | span-level tags.
113 | 
114 | ### Automatic Escaping for Special Characters
115 | 
116 | In HTML, there are two characters that demand special treatment: `<`
117 | and `&`. Left angle brackets are used to start tags; ampersands are
118 | used to denote HTML entities. If you want to use them as literal
119 | characters, you must escape them as entities, e.g. `&lt;`, and
120 | `&amp;`.
121 | 
122 | Ampersands in particular are bedeviling for web writers. If you want to
123 | write about 'AT&T', you need to write '`AT&amp;T`'. You even need to
124 | escape ampersands within URLs. Thus, if you want to link to:
125 | 
126 |     http://images.google.com/images?num=30&q=larry+bird
127 | 
128 | you need to encode the URL as:
129 | 
130 |     http://images.google.com/images?num=30&amp;q=larry+bird
131 | 
132 | in your anchor tag `href` attribute. Needless to say, this is easy to
133 | forget, and is probably the single most common source of HTML validation
134 | errors in otherwise well-marked-up web sites.
135 | 
136 | Markdown allows you to use these characters naturally, taking care of
137 | all the necessary escaping for you. If you use an ampersand as part of
138 | an HTML entity, it remains unchanged; otherwise it will be translated
139 | into `&amp;`.
140 | 
141 | So, if you want to include a copyright symbol in your article, you can write:
142 | 
143 |     &copy;
144 | 
145 | and Markdown will leave it alone. But if you write:
146 | 
147 |     AT&T
148 | 
149 | Markdown will translate it to:
150 | 
151 |     AT&amp;T
152 | 
153 | Similarly, because Markdown supports [inline HTML](#html), if you use
154 | angle brackets as delimiters for HTML tags, Markdown will treat them as
155 | such. But if you write:
156 | 
157 |     4 < 5
158 | 
159 | Markdown will translate it to:
160 | 
161 |     4 &lt; 5
162 | 
163 | However, inside Markdown code spans and blocks, angle brackets and
164 | ampersands are *always* encoded automatically. This makes it easy to use
165 | Markdown to write about HTML code. (As opposed to raw HTML, which is a
166 | terrible format for writing about HTML syntax, because every single `<`
167 | and `&` in your example code needs to be escaped.)
168 | 
169 | ## BLOCK ELEMENTS
170 | 
171 | ### Paragraphs and Line Breaks
172 | 
173 | A paragraph is simply one or more consecutive lines of text, separated
174 | by one or more blank lines. (A blank line is any line that looks like a
175 | blank line -- a line containing nothing but spaces or tabs is considered
176 | blank.) Normal paragraphs should not be indented with spaces or tabs.
177 | 
178 | The implication of the "one or more consecutive lines of text" rule is
179 | that Markdown supports "hard-wrapped" text paragraphs. This differs
180 | significantly from most other text-to-HTML formatters (including Movable
181 | Type's "Convert Line Breaks" option) which translate every line break
182 | character in a paragraph into a `<br />` tag.
183 | 
184 | When you *do* want to insert a `<br />` break tag using Markdown, you
185 | end a line with two or more spaces, then type return.
186 | 
187 | Yes, this takes a tad more effort to create a `<br />`, but a simplistic
188 | "every line break is a `<br />`" rule wouldn't work for Markdown.
189 | Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
190 | work best -- and look better -- when you format them with hard breaks.
191 | 
192 |   [bq]: #blockquote
193 |   [l]:  #list
194 | 
195 | ### Headers
196 | 
197 | Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
198 | 
199 | Setext-style headers are "underlined" using equal signs (for first-level
200 | headers) and dashes (for second-level headers). For example:
201 | 
202 |     This is an H1
203 |     =============
204 | 
205 |     This is an H2
206 |     -------------
207 | 
208 | Any number of underlining `=`'s or `-`'s will work.
209 | 
210 | Atx-style headers use 1-6 hash characters at the start of the line,
211 | corresponding to header levels 1-6. For example:
212 | 
213 |     # This is an H1
214 | 
215 |     ## This is an H2
216 | 
217 |     ###### This is an H6
218 | 
219 | Optionally, you may "close" atx-style headers. This is purely
220 | cosmetic -- you can use this if you think it looks better. The
221 | closing hashes don't even need to match the number of hashes
222 | used to open the header. (The number of opening hashes
223 | determines the header level.) :
224 | 
225 |     # This is an H1 #
226 | 
227 |     ## This is an H2 ##
228 | 
229 |     ### This is an H3 ######
230 | 
231 | ### Blockquotes
232 | 
233 | Markdown uses email-style `>` characters for blockquoting. If you're
234 | familiar with quoting passages of text in an email message, then you
235 | know how to create a blockquote in Markdown. It looks best if you hard
236 | wrap the text and put a `>` before every line:
237 | 
238 |     > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
239 |     > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
240 |     > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
241 |     >
242 |     > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
243 |     > id sem consectetuer libero luctus adipiscing.
244 | 
245 | Markdown allows you to be lazy and only put the `>` before the first
246 | line of a hard-wrapped paragraph:
247 | 
248 |     > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
249 |     consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
250 |     Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
251 | 
252 |     > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
253 |     id sem consectetuer libero luctus adipiscing.
254 | 
255 | Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
256 | adding additional levels of `>`:
257 | 
258 |     > This is the first level of quoting.
259 |     >
260 |     > > This is nested blockquote.
261 |     >
262 |     > Back to the first level.
263 | 
264 | Blockquotes can contain other Markdown elements, including headers, lists,
265 | and code blocks:
266 | 
267 |     > ## This is a header.
268 |     >
269 |     > 1.   This is the first list item.
270 |     > 2.   This is the second list item.
271 |     >
272 |     > Here's some example code:
273 |     >
274 |     >     return shell_exec("echo $input | $markdown_script");
275 | 
276 | Any decent text editor should make email-style quoting easy. For
277 | example, with BBEdit, you can make a selection and choose Increase
278 | Quote Level from the Text menu.
279 | 
280 | ### Lists
281 | 
282 | Markdown supports ordered (numbered) and unordered (bulleted) lists.
283 | 
284 | Unordered lists use asterisks, pluses, and hyphens -- interchangably
285 | -- as list markers:
286 | 
287 |     *   Red
288 |     *   Green
289 |     *   Blue
290 | 
291 | is equivalent to:
292 | 
293 |     +   Red
294 |     +   Green
295 |     +   Blue
296 | 
297 | and:
298 | 
299 |     -   Red
300 |     -   Green
301 |     -   Blue
302 | 
303 | Ordered lists use numbers followed by periods:
304 | 
305 |     1.  Bird
306 |     2.  McHale
307 |     3.  Parish
308 | 
309 | It's important to note that the actual numbers you use to mark the
310 | list have no effect on the HTML output Markdown produces. The HTML
311 | Markdown produces from the above list is:
312 | 
313 |     <ol>
314 |     <li>Bird</li>
315 |     <li>McHale</li>
316 |     <li>Parish</li>
317 |     </ol>
318 | 
319 | If you instead wrote the list in Markdown like this:
320 | 
321 |     1.  Bird
322 |     1.  McHale
323 |     1.  Parish
324 | 
325 | or even:
326 | 
327 |     3. Bird
328 |     1. McHale
329 |     8. Parish
330 | 
331 | you'd get the exact same HTML output. The point is, if you want to,
332 | you can use ordinal numbers in your ordered Markdown lists, so that
333 | the numbers in your source match the numbers in your published HTML.
334 | But if you want to be lazy, you don't have to.
335 | 
336 | If you do use lazy list numbering, however, you should still start the
337 | list with the number 1. At some point in the future, Markdown may support
338 | starting ordered lists at an arbitrary number.
339 | 
340 | List markers typically start at the left margin, but may be indented by
341 | up to three spaces. List markers must be followed by one or more spaces
342 | or a tab.
343 | 
344 | To make lists look nice, you can wrap items with hanging indents:
345 | 
346 |     *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
347 |         Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
348 |         viverra nec, fringilla in, laoreet vitae, risus.
349 |     *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
350 |         Suspendisse id sem consectetuer libero luctus adipiscing.
351 | 
352 | But if you want to be lazy, you don't have to:
353 | 
354 |     *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
355 |     Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
356 |     viverra nec, fringilla in, laoreet vitae, risus.
357 |     *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
358 |     Suspendisse id sem consectetuer libero luctus adipiscing.
359 | 
360 | If list items are separated by blank lines, Markdown will wrap the
361 | items in `<p>` tags in the HTML output. For example, this input:
362 | 
363 |     *   Bird
364 |     *   Magic
365 | 
366 | will turn into:
367 | 
368 |     <ul>
369 |     <li>Bird</li>
370 |     <li>Magic</li>
371 |     </ul>
372 | 
373 | But this:
374 | 
375 |     *   Bird
376 | 
377 |     *   Magic
378 | 
379 | will turn into:
380 | 
381 |     <ul>
382 |     <li><p>Bird</p></li>
383 |     <li><p>Magic</p></li>
384 |     </ul>
385 | 
386 | List items may consist of multiple paragraphs. Each subsequent
387 | paragraph in a list item must be indented by either 4 spaces
388 | or one tab:
389 | 
390 |     1.  This is a list item with two paragraphs. Lorem ipsum dolor
391 |         sit amet, consectetuer adipiscing elit. Aliquam hendrerit
392 |         mi posuere lectus.
393 | 
394 |         Vestibulum enim wisi, viverra nec, fringilla in, laoreet
395 |         vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
396 |         sit amet velit.
397 | 
398 |     2.  Suspendisse id sem consectetuer libero luctus adipiscing.
399 | 
400 | It looks nice if you indent every line of the subsequent
401 | paragraphs, but here again, Markdown will allow you to be
402 | lazy:
403 | 
404 |     *   This is a list item with two paragraphs.
405 | 
406 |         This is the second paragraph in the list item. You're
407 |     only required to indent the first line. Lorem ipsum dolor
408 |     sit amet, consectetuer adipiscing elit.
409 | 
410 |     *   Another item in the same list.
411 | 
412 | To put a blockquote within a list item, the blockquote's `>`
413 | delimiters need to be indented:
414 | 
415 |     *   A list item with a blockquote:
416 | 
417 |         > This is a blockquote
418 |         > inside a list item.
419 | 
420 | To put a code block within a list item, the code block needs
421 | to be indented *twice* -- 8 spaces or two tabs:
422 | 
423 |     *   A list item with a code block:
424 | 
425 |             <code goes here>
426 | 
427 | 
428 | It's worth noting that it's possible to trigger an ordered list by
429 | accident, by writing something like this:
430 | 
431 |     1986. What a great season.
432 | 
433 | In other words, a *number-period-space* sequence at the beginning of a
434 | line. To avoid this, you can backslash-escape the period:
435 | 
436 |     1986\. What a great season.
437 | 
438 | ### Code Blocks
439 | 
440 | Pre-formatted code blocks are used for writing about programming or
441 | markup source code. Rather than forming normal paragraphs, the lines
442 | of a code block are interpreted literally. Markdown wraps a code block
443 | in both `<pre>` and `<code>` tags.
444 | 
445 | To produce a code block in Markdown, simply indent every line of the
446 | block by at least 4 spaces or 1 tab. For example, given this input:
447 | 
448 |     This is a normal paragraph:
449 | 
450 |         This is a code block.
451 | 
452 | Markdown will generate:
453 | 
454 |     <p>This is a normal paragraph:</p>
455 | 
456 |     <pre><code>This is a code block.
457 |     </code></pre>
458 | 
459 | One level of indentation -- 4 spaces or 1 tab -- is removed from each
460 | line of the code block. For example, this:
461 | 
462 |     Here is an example of AppleScript:
463 | 
464 |         tell application "Foo"
465 |             beep
466 |         end tell
467 | 
468 | will turn into:
469 | 
470 |     <p>Here is an example of AppleScript:</p>
471 | 
472 |     <pre><code>tell application "Foo"
473 |         beep
474 |     end tell
475 |     </code></pre>
476 | 
477 | A code block continues until it reaches a line that is not indented
478 | (or the end of the article).
479 | 
480 | Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
481 | are automatically converted into HTML entities. This makes it very
482 | easy to include example HTML source code using Markdown -- just paste
483 | it and indent it, and Markdown will handle the hassle of encoding the
484 | ampersands and angle brackets. For example, this:
485 | 
486 |         <div class="footer">
487 |             &copy; 2004 Foo Corporation
488 |         </div>
489 | 
490 | will turn into:
491 | 
492 |     <pre><code>&lt;div class="footer"&gt;
493 |         &amp;copy; 2004 Foo Corporation
494 |     &lt;/div&gt;
495 |     </code></pre>
496 | 
497 | Regular Markdown syntax is not processed within code blocks. E.g.,
498 | asterisks are just literal asterisks within a code block. This means
499 | it's also easy to use Markdown to write about Markdown's own syntax.
500 | 
501 | 
502 | 
503 | ### Horizontal Rules
504 | 
505 | You can produce a horizontal rule tag (`<hr />`) by placing three or
506 | more hyphens, asterisks, or underscores on a line by themselves. If you
507 | wish, you may use spaces between the hyphens or asterisks. Each of the
508 | following lines will produce a horizontal rule:
509 | 
510 |     * * *
511 | 
512 |     ***
513 | 
514 |     *****
515 | 
516 |     - - -
517 | 
518 |     ---------------------------------------
519 | 
520 | 
521 | ## SPAN ELEMENTS
522 | 
523 | ### Links
524 | 
525 | Markdown supports two style of links: *inline* and *reference*.
526 | 
527 | In both styles, the link text is delimited by [square brackets].
528 | 
529 | To create an inline link, use a set of regular parentheses immediately
530 | after the link text's closing square bracket. Inside the parentheses,
531 | put the URL where you want the link to point, along with an *optional*
532 | title for the link, surrounded in quotes. For example:
533 | 
534 |     This is [an example](http://example.com/ "Title") inline link.
535 | 
536 |     [This link](http://example.net/) has no title attribute.
537 | 
538 | Will produce:
539 | 
540 |     <p>This is <a href="http://example.com/" title="Title">
541 |     an example</a> inline link.</p>
542 | 
543 |     <p><a href="http://example.net/">This link</a> has no
544 |     title attribute.</p>
545 | 
546 | If you're referring to a local resource on the same server, you can
547 | use relative paths:
548 | 
549 |     See my [About](/about/) page for details.
550 | 
551 | Reference-style links use a second set of square brackets, inside
552 | which you place a label of your choosing to identify the link:
553 | 
554 |     This is [an example][id] reference-style link.
555 | 
556 | You can optionally use a space to separate the sets of brackets:
557 | 
558 |     This is [an example] [id] reference-style link.
559 | 
560 | Then, anywhere in the document, you define your link label like this,
561 | on a line by itself:
562 | 
563 |     [id]: http://example.com/  "Optional Title Here"
564 | 
565 | That is:
566 | 
567 | *   Square brackets containing the link identifier (optionally
568 |     indented from the left margin using up to three spaces);
569 | *   followed by a colon;
570 | *   followed by one or more spaces (or tabs);
571 | *   followed by the URL for the link;
572 | *   optionally followed by a title attribute for the link, enclosed
573 |     in double or single quotes, or enclosed in parentheses.
574 | 
575 | The following three link definitions are equivalent:
576 | 
577 |     [foo]: http://example.com/  "Optional Title Here"
578 |     [foo]: http://example.com/  'Optional Title Here'
579 |     [foo]: http://example.com/  (Optional Title Here)
580 | 
581 | **Note:** There is a known bug in Markdown.pl 1.0.1 which prevents
582 | single quotes from being used to delimit link titles.
583 | 
584 | The link URL may, optionally, be surrounded by angle brackets:
585 | 
586 |     [id]: <http://example.com/>  "Optional Title Here"
587 | 
588 | You can put the title attribute on the next line and use extra spaces
589 | or tabs for padding, which tends to look better with longer URLs:
590 | 
591 |     [id]: http://example.com/longish/path/to/resource/here
592 |         "Optional Title Here"
593 | 
594 | Link definitions are only used for creating links during Markdown
595 | processing, and are stripped from your document in the HTML output.
596 | 
597 | Link definition names may consist of letters, numbers, spaces, and
598 | punctuation -- but they are *not* case sensitive. E.g. these two
599 | links:
600 | 
601 |     [link text][a]
602 |     [link text][A]
603 | 
604 | are equivalent.
605 | 
606 | The *implicit link name* shortcut allows you to omit the name of the
607 | link, in which case the link text itself is used as the name.
608 | Just use an empty set of square brackets -- e.g., to link the word
609 | "Google" to the google.com web site, you could simply write:
610 | 
611 |     [Google][]
612 | 
613 | And then define the link:
614 | 
615 |     [Google]: http://google.com/
616 | 
617 | Because link names may contain spaces, this shortcut even works for
618 | multiple words in the link text:
619 | 
620 |     Visit [Daring Fireball][] for more information.
621 | 
622 | And then define the link:
623 | 
624 |     [Daring Fireball]: http://daringfireball.net/
625 | 
626 | Link definitions can be placed anywhere in your Markdown document. I
627 | tend to put them immediately after each paragraph in which they're
628 | used, but if you want, you can put them all at the end of your
629 | document, sort of like footnotes.
630 | 
631 | Here's an example of reference links in action:
632 | 
633 |     I get 10 times more traffic from [Google] [1] than from
634 |     [Yahoo] [2] or [MSN] [3].
635 | 
636 |       [1]: http://google.com/        "Google"
637 |       [2]: http://search.yahoo.com/  "Yahoo Search"
638 |       [3]: http://search.msn.com/    "MSN Search"
639 | 
640 | Using the implicit link name shortcut, you could instead write:
641 | 
642 |     I get 10 times more traffic from [Google][] than from
643 |     [Yahoo][] or [MSN][].
644 | 
645 |       [google]: http://google.com/        "Google"
646 |       [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
647 |       [msn]:    http://search.msn.com/    "MSN Search"
648 | 
649 | Both of the above examples will produce the following HTML output:
650 | 
651 |     <p>I get 10 times more traffic from <a href="http://google.com/"
652 |     title="Google">Google</a> than from
653 |     <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
654 |     or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
655 | 
656 | For comparison, here is the same paragraph written using
657 | Markdown's inline link style:
658 | 
659 |     I get 10 times more traffic from [Google](http://google.com/ "Google")
660 |     than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
661 |     [MSN](http://search.msn.com/ "MSN Search").
662 | 
663 | The point of reference-style links is not that they're easier to
664 | write. The point is that with reference-style links, your document
665 | source is vastly more readable. Compare the above examples: using
666 | reference-style links, the paragraph itself is only 81 characters
667 | long; with inline-style links, it's 176 characters; and as raw HTML,
668 | it's 234 characters. In the raw HTML, there's more markup than there
669 | is text.
670 | 
671 | With Markdown's reference-style links, a source document much more
672 | closely resembles the final output, as rendered in a browser. By
673 | allowing you to move the markup-related metadata out of the paragraph,
674 | you can add links without interrupting the narrative flow of your
675 | prose.
676 | 
677 | ### Emphasis
678 | 
679 | Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
680 | emphasis. Text wrapped with one `*` or `_` will be wrapped with an
681 | HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
682 | `<strong>` tag. E.g., this input:
683 | 
684 |     *single asterisks*
685 | 
686 |     _single underscores_
687 | 
688 |     **double asterisks**
689 | 
690 |     __double underscores__
691 | 
692 | will produce:
693 | 
694 |     <em>single asterisks</em>
695 | 
696 |     <em>single underscores</em>
697 | 
698 |     <strong>double asterisks</strong>
699 | 
700 |     <strong>double underscores</strong>
701 | 
702 | You can use whichever style you prefer; the lone restriction is that
703 | the same character must be used to open and close an emphasis span.
704 | 
705 | Emphasis can be used in the middle of a word:
706 | 
707 |     un*frigging*believable
708 | 
709 | But if you surround an `*` or `_` with spaces, it'll be treated as a
710 | literal asterisk or underscore.
711 | 
712 | To produce a literal asterisk or underscore at a position where it
713 | would otherwise be used as an emphasis delimiter, you can backslash
714 | escape it:
715 | 
716 |     \*this text is surrounded by literal asterisks\*
717 | 
718 | 
719 | ### Code
720 | 
721 | To indicate a span of code, wrap it with backtick quotes (`` ` ``).
722 | Unlike a pre-formatted code block, a code span indicates code within a
723 | normal paragraph. For example:
724 | 
725 |     Use the `printf()` function.
726 | 
727 | will produce:
728 | 
729 |     <p>Use the <code>printf()</code> function.</p>
730 | 
731 | To include a literal backtick character within a code span, you can use
732 | multiple backticks as the opening and closing delimiters:
733 | 
734 |     ``There is a literal backtick (`) here.``
735 | 
736 | which will produce this:
737 | 
738 |     <p><code>There is a literal backtick (`) here.</code></p>
739 | 
740 | The backtick delimiters surrounding a code span may include spaces --
741 | one after the opening, one before the closing. This allows you to place
742 | literal backtick characters at the beginning or end of a code span:
743 | 
744 |     A single backtick in a code span: `` ` ``
745 | 
746 |     A backtick-delimited string in a code span: `` `foo` ``
747 | 
748 | will produce:
749 | 
750 |     <p>A single backtick in a code span: <code>`</code></p>
751 | 
752 |     <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
753 | 
754 | With a code span, ampersands and angle brackets are encoded as HTML
755 | entities automatically, which makes it easy to include example HTML
756 | tags. Markdown will turn this:
757 | 
758 |     Please don't use any `<blink>` tags.
759 | 
760 | into:
761 | 
762 |     <p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
763 | 
764 | You can write this:
765 | 
766 |     `&#8212;` is the decimal-encoded equivalent of `&mdash;`.
767 | 
768 | to produce:
769 | 
770 |     <p><code>&amp;#8212;</code> is the decimal-encoded
771 |     equivalent of <code>&amp;mdash;</code>.</p>
772 | 
773 | 
774 | ### Images
775 | 
776 | Admittedly, it's fairly difficult to devise a "natural" syntax for
777 | placing images into a plain text document format.
778 | 
779 | Markdown uses an image syntax that is intended to resemble the syntax
780 | for links, allowing for two styles: *inline* and *reference*.
781 | 
782 | Inline image syntax looks like this:
783 | 
784 |     ![Alt text](/path/to/img.jpg)
785 | 
786 |     ![Alt text](/path/to/img.jpg "Optional title")
787 | 
788 | That is:
789 | 
790 | *   An exclamation mark: `!`;
791 | *   followed by a set of square brackets, containing the `alt`
792 |     attribute text for the image;
793 | *   followed by a set of parentheses, containing the URL or path to
794 |     the image, and an optional `title` attribute enclosed in double
795 |     or single quotes.
796 | 
797 | Reference-style image syntax looks like this:
798 | 
799 |     ![Alt text][id]
800 | 
801 | Where "id" is the name of a defined image reference. Image references
802 | are defined using syntax identical to link references:
803 | 
804 |     [id]: url/to/image  "Optional title attribute"
805 | 
806 | As of this writing, Markdown has no syntax for specifying the
807 | dimensions of an image; if this is important to you, you can simply
808 | use regular HTML `<img>` tags.
809 | 
810 | 
811 | ## MISCELLANEOUS
812 | 
813 | ### Automatic Links
814 | 
815 | 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:
816 | 
817 |     <http://example.com/>
818 | 
819 | Markdown will turn this into:
820 | 
821 |     <a href="http://example.com/">http://example.com/</a>
822 | 
823 | Automatic links for email addresses work similarly, except that
824 | Markdown will also perform a bit of randomized decimal and hex
825 | entity-encoding to help obscure your address from address-harvesting
826 | spambots. For example, Markdown will turn this:
827 | 
828 |     <address@example.com>
829 | 
830 | into something like this:
831 | 
832 |     <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
833 |     &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
834 |     &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
835 |     &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
836 | 
837 | which will render in a browser as a clickable link to "address@example.com".
838 | 
839 | (This sort of entity-encoding trick will indeed fool many, if not
840 | most, address-harvesting bots, but it definitely won't fool all of
841 | them. It's better than nothing, but an address published in this way
842 | will probably eventually start receiving spam.)
843 | 
844 | 
845 | ### Backslash Escapes
846 | 
847 | Markdown allows you to use backslash escapes to generate literal
848 | characters which would otherwise have special meaning in Markdown's
849 | formatting syntax. For example, if you wanted to surround a word
850 | with literal asterisks (instead of an HTML `<em>` tag), you can use
851 | backslashes before the asterisks, like this:
852 | 
853 |     \*literal asterisks\*
854 | 
855 | Markdown provides backslash escapes for the following characters:
856 | 
857 |     \   backslash
858 |     `   backtick
859 |     *   asterisk
860 |     _   underscore
861 |     {}  curly braces
862 |     []  square brackets
863 |     ()  parentheses
864 |     #   hash mark
865 |     +   plus sign
866 |     -   minus sign (hyphen)
867 |     .   dot
868 |     !   exclamation mark
869 | 
870 | ## AUTHOR
871 | 
872 | Markdown was created by John Gruber.
873 | 
874 | Manual page by Ryan Tomayko. It's pretty much a direct copy of the
875 | [Markdown Syntax Reference](http://daringfireball.net/projects/markdown/syntax),
876 | also by John Gruber.
877 | 
878 | ## SEE ALSO
879 | 
880 | ronn(5)
881 | [Markdown Syntax Reference](http://daringfireball.net/projects/markdown/)
882 | 


--------------------------------------------------------------------------------
/test/md/nested_list_with_code.md:
--------------------------------------------------------------------------------
 1 | a(1)
 2 | ====
 3 | 
 4 | Tight list:
 5 | 
 6 | * `toggle_status`
 7 |   * Toggle the display of the status bar1
 8 |   * Toggle the display of the status bar2
 9 | * `spawn <executable> <additional args>` TODO explain path-alike expansion
10 | 
11 | Loose list:
12 | 
13 | * `toggle_status`
14 | 
15 |   * Toggle the display of the status bar1
16 |   * Toggle the display of the status bar2
17 | 
18 | * `spawn <executable> <additional args>` TODO explain path-alike expansion
19 | 


--------------------------------------------------------------------------------
/test/md/noname.md:
--------------------------------------------------------------------------------
 1 | # test
 2 | 
 3 | ## NAME
 4 | 
 5 | test - a nice test
 6 | 
 7 | ## SYNOPSYS
 8 | 
 9 | test is a test
10 | 


--------------------------------------------------------------------------------
/test/md/pre_block_with_quotes.md:
--------------------------------------------------------------------------------
1 | t(1) - test
2 | ===========
3 | 
4 | ## test
5 | 
6 |     [ "$11" ]
7 | 


--------------------------------------------------------------------------------
/test/md/regressions.md:
--------------------------------------------------------------------------------
1 | # regressions(7) -- issues
2 | 
3 | ## inlines
4 | 
5 | This should be  _(a `b`)_ ok.
6 | 
7 | This should not double escape **pkg-js-tools**.
8 | 
9 | 


--------------------------------------------------------------------------------
/test/md/simple_table.md:
--------------------------------------------------------------------------------
1 | # simple table
2 | 
3 | Col1|Col2|Col3
4 | ----|:--:|---:
5 | A|B|C
6 | D|E|F
7 | 


--------------------------------------------------------------------------------
/test/md/table.md:
--------------------------------------------------------------------------------
 1 | table(7) -- test data for table format
 2 | ======================================
 3 | 
 4 | test table copy and paste form www.
 5 | 
 6 | LARGE TABLE
 7 | -----------
 8 | 
 9 | [Comparison of file systems](https://en.wikipedia.org/wiki/Comparison_of_file_systems)
10 | 
11 | File system |Creator |Year of introduction |Original operating system
12 | ------------|--------|---------------------|---------------
13 | DECtape |DEC |1964 |PDP-6 Monitor
14 | DASD |IBM |1964 |OS/360
15 | Level-D |DEC |1968 |TOPS-10
16 | George 2 |ICT (later ICL) |1968 |George 2
17 | Version 6 Unix file system (V6FS) |Bell Labs |1972 |Version 6 Unix
18 | RT-11 file system |DEC |1973 |RT-11
19 | Disk Operating System (GEC DOS) |GEC |1973 |Core Operating System
20 | CP/M file system |Digital Research (Gary Kildall) |1974 |CP/M[1]
21 | ODS-1 |DEC |1975 |RSX-11
22 | GEC DOS filing system extended |GEC |1977 |OS4000
23 | FAT (8-bit) |Microsoft (Marc McDonald) for NCR |1977 |Microsoft Standalone Disk BASIC-80 (later Microsoft Standalone Disk BASIC-86)
24 | DOS 3.x |Apple Computer |1978 |Apple DOS
25 | Pascal |Apple Computer |1978 |Apple Pascal
26 | CBM DOS |Commodore |1978 |Commodore BASIC
27 | Version 7 Unix file system (V7FS) |Bell Labs |1979 |Version 7 Unix
28 | ODS-2 |DEC |1979 |OpenVMS
29 | 
30 | LONG TEXT
31 | ---------
32 | 
33 | Person|Work|Quote
34 | -|-|-
35 | Sherlock Holmes|The Norwood Builder| You mentioned your name as if I should recognize it, but beyond the obvious facts that you are a bachelor, a solicitor, a freemason, and an asthmatic, I know nothing whatever about you.
36 | 
37 | THING TABLE
38 | -----------
39 | 
40 | 1|2
41 | -|-
42 | 1|2
43 | 1|2
44 | 1|2
45 | 1|2
46 | 1|2
47 | T{1|2
48 | 1|2
49 | 1|2
50 | 1|2
51 | 1|2
52 | 1|2
53 | 1|2
54 | 1|2
55 | 1|2
56 | 1|2
57 | 1|2
58 | 1|2
59 | 1|2
60 | 1|2
61 | 


--------------------------------------------------------------------------------
/test/md/underline_spacing_test.md:
--------------------------------------------------------------------------------
 1 | # This input
 2 | 
 3 |  * `-S` _text_, `search` _text_:
 4 |     Performs a substring search of formula names for _text_.
 5 | 
 6 |  * `-O` <text>, `other` <text>:
 7 |     Does something else.
 8 | 
 9 | Should space text properly.
10 | 
11 | <!-- this is a comment -->
12 | 


--------------------------------------------------------------------------------
/test/out/blockquotes.out:
--------------------------------------------------------------------------------
 1 | T(1)                        General Commands Manual                       T(1)
 2 | 
 3 | NAME
 4 |        t - test
 5 | 
 6 | test
 7 |          A blockquote here.
 8 |          Continuing on second line.
 9 | 
10 |        Hello.
11 | 
12 |               Another  block  quote. With a long title. That will break a line
13 |               eventually later.
14 |               that continues on second line
15 |               continuation
16 | 
17 |                                  January 1979                             T(1)
18 | 


--------------------------------------------------------------------------------
/test/out/definition_list_syntax.out:
--------------------------------------------------------------------------------
 1 | DEFITION_LIST_SYNTAX(5)       File Formats Manual      DEFITION_LIST_SYNTAX(5)
 2 | 
 3 | NAME
 4 |        defition_list_syntax - hiya
 5 | 
 6 |        Definition lists look like unordered lists:
 7 | 
 8 |         • term:
 9 |           definition
10 | 
11 |         • another one:
12 |           The definition may span
13 |           multiple lines and even
14 |           start
15 |           new paragraphs
16 | 
17 |         • --somearg=<VALUE>:
18 |           We can do that too.
19 | 
20 |                                  January 1979          DEFITION_LIST_SYNTAX(5)
21 | 


--------------------------------------------------------------------------------
/test/out/dots_at_line_start_test.out:
--------------------------------------------------------------------------------
 1 | DOTS_AT_LINE_START_TEST(1)  General Commands Manual DOTS_AT_LINE_START_TEST(1)
 2 | 
 3 | NAME
 4 |        dots_at_line_start_test
 5 | 
 6 |        There's a weird issue where dots at the beginning of a line
 7 |        generate troff warnings due to escaping.
 8 | 
 9 |        .. let's see what happens.
10 | 
11 |                                  January 1979       DOTS_AT_LINE_START_TEST(1)
12 | 


--------------------------------------------------------------------------------
/test/out/ellipses.out:
--------------------------------------------------------------------------------
 1 | ELLIPSES(7)            Miscellaneous Information Manual            ELLIPSES(7)
 2 | 
 3 | NAME
 4 |        ellipses - testing ellipses
 5 | 
 6 |        Ellipses should be replaced...
 7 | 
 8 |        ...also, they shouldn't interfere with regular dots at the beginning
 9 |        of a line.
10 | 
11 |                                  January 1979                      ELLIPSES(7)
12 | 


--------------------------------------------------------------------------------
/test/out/entity_encoding_test.out:
--------------------------------------------------------------------------------
 1 | HELLO(1)                    General Commands Manual                   HELLO(1)
 2 | 
 3 | NAME
 4 |        hello - hello world
 5 | 
 6 |        Your output <i>might</i> look like this:
 7 |          * Chris
 8 |          *
 9 |          * &lt;b&gt;GitHub&lt;/b&gt;
10 |          * <b>GitHub</b>
11 | 
12 |        Here's some special entities:
13 | 
14 |         • &bull;       ○
15 | 
16 |         • &nbsp;
17 | 
18 |         • &copy;       ©
19 | 
20 |         • &rdquo;      \
21 | 
22 |         • &mdash;      —
23 | 
24 |         • &reg;        ®
25 | 
26 |         • &sect;       §
27 | 
28 |         • &ge;         ≥
29 | 
30 |         • &le;         ≤
31 | 
32 |         • &ne;         ≠
33 | 
34 |         • &equiv;      ≡
35 | 
36 |         • &plusmn;     ±
37 | 
38 |        Here's a line that uses non-breaking spaces to force the
39 |        last few words to wrap together.
40 | 
41 |                                  January 1979                         HELLO(1)
42 | 


--------------------------------------------------------------------------------
/test/out/escapes.out:
--------------------------------------------------------------------------------
 1 | ESCAPES(1)                  General Commands Manual                 ESCAPES(1)
 2 | 
 3 | NAME
 4 |        escapes
 5 | 
 6 |        backslashes before the asterisks, like this:
 7 |          \*literal asterisks\*
 8 | 
 9 |        Markdown provides backslash escapes for the following characters:
10 |          \   backslash
11 |          `   backtick
12 |          *   asterisk
13 |          _   underscore
14 |          {}  curly braces
15 |          []  square brackets
16 |          ()  parentheses
17 |          #   hash mark
18 |          +   plus sign
19 |          -   minus sign (hyphen)
20 |          .   dot
21 |          !   exclamation mark
22 | 
23 |                                  January 1979                       ESCAPES(1)
24 | 


--------------------------------------------------------------------------------
/test/out/graves.out:
--------------------------------------------------------------------------------
 1 | TEST(1)                     General Commands Manual                    TEST(1)
 2 | 
 3 | NAME
 4 |        test
 5 | 
 6 | this title will render strangely
 7 |        This is the body text.
 8 | 
 9 |                                  January 1979                          TEST(1)
10 | 


--------------------------------------------------------------------------------
/test/out/links.out:
--------------------------------------------------------------------------------
 1 | LINKS(1)                    General Commands Manual                   LINKS(1)
 2 | 
 3 | NAME
 4 |        links
 5 | 
 6 |        I get 10 times more traffic from ]8;;http://google.com/\Google]8;;\ than from
 7 |        ]8;;http://search.yahoo.com/\Yahoo Search]8;;\ or ]8;;http://search.msn.com/\MSN Search]8;;\.
 8 | 
 9 |        This is to test proper escape of html chars and non-repeating link:
10 |        xxxxx@xxxx.xxxx.xxxx.xx
11 | 
12 |        I get 10 times more traffic from ]8;;http://google.com/\Google]8;;\ than from
13 |        ]8;;http://search.yahoo.com/\Yahoo Search]8;;\ or ]8;;http://search.msn.com/\MSN Search]8;;\.
14 | 
15 |        Non-repeating http link https://example.com/test
16 | 
17 |        Also
18 |        ]8;;http://google.com/\Google]8;;\
19 | 
20 |        and ]8;;./table.md\local links should not crash]8;;\
21 | 
22 |                                  January 1979                         LINKS(1)
23 | 


--------------------------------------------------------------------------------
/test/out/list.out:
--------------------------------------------------------------------------------
 1 | A(1)                        General Commands Manual                       A(1)
 2 | 
 3 | NAME
 4 |        a
 5 | 
 6 |        This is a tight list:
 7 | 
 8 |         • toggle_status: test
 9 | 
10 |         • spawn <executable> <additional args>
11 |           TODO explain path-alike expansion,
12 |           ability to get a block here.
13 | 
14 |        This is a loose list:
15 | 
16 |         • toggle_status:
17 |           test
18 | 
19 |         • spawn <executable> <additional args>:
20 |           TODO explain path-alike expansion,
21 |           ability to get a block here.
22 | 
23 |                                  January 1979                             A(1)
24 | 


--------------------------------------------------------------------------------
/test/out/markdown_syntax.out:
--------------------------------------------------------------------------------
  1 | MARKDOWN(5)                   File Formats Manual                  MARKDOWN(5)
  2 | 
  3 | NAME
  4 |        markdown - humane markup syntax
  5 | 
  6 | SYNOPSIS
  7 |          # Header 1 #
  8 |          ## Header 2 ##
  9 |          ### Header 3 ###             (Hashes on right are optional)
 10 |          #### Header 4 ####
 11 |          ##### Header 5 #####
 12 | 
 13 |          This is a paragraph, which is text surrounded by whitespace.
 14 |          Paragraphs can be on one line (or many), and can drone on for
 15 |          hours.
 16 | 
 17 |          [Reference style links][1] and [inline links](http://example.com)
 18 |          [1]: http://example.com "Title is optional"
 19 | 
 20 |          Inline markup like _italics_,  **bold**, and `code()`.
 21 | 
 22 |          ![picture alt](/images/photo.jpeg "Title is optional")
 23 | 
 24 |          > Blockquotes are like quoted text in email replies
 25 |          >> And, they can be nested
 26 | 
 27 |              code blocks are for preformatted
 28 |              text and must be indented with four spaces
 29 | 
 30 |          * Bullet lists are easy too
 31 |            * You can
 32 |            * even
 33 |            * nest them
 34 |          - Another one
 35 |          + Another one
 36 | 
 37 | DESCRIPTION
 38 |    Philosophy
 39 |        Markdown is intended to be as easy-to-read and easy-to-write as is fea‐
 40 |        sible.
 41 | 
 42 |        Readability,  however, is emphasized above all else. A Markdown-format‐
 43 |        ted
 44 |        document should be publishable as-is, as plain text, without looking
 45 |        like it's been marked up with tags or formatting instructions. While
 46 |        Markdown's syntax has been influenced by several existing text-to-HTML
 47 |        filters -- including ]8;;http://docutils.sourceforge.net/mirror/setext.html\Setext]8;;\,
 48 | 
 49 |        ]8;;http://www.aaronsw.com/2002/atx/\atx]8;;\,
 50 | 
 51 |        ]8;;http://textism.com/tools/textile/\Textile]8;;\,
 52 | 
 53 |        ]8;;http://docutils.sourceforge.net/rst.html\reStructuredText]8;;\,
 54 | 
 55 |        ]8;;http://www.triptico.com/software/grutatxt.html\Grutatext]8;;\, and ]8;;http://ettext.taint.org/doc/\EtText]8;;\ -- the single biggest source of
 56 |        inspiration for Markdown's syntax is the format of plain text email.
 57 | 
 58 |        To this end, Markdown's syntax is comprised entirely of punctuation
 59 |        characters, which punctuation characters have been carefully chosen so
 60 |        as to look like what they mean. E.g., asterisks around a word actually
 61 |        look like *emphasis*. Markdown lists look like, well, lists. Even
 62 |        blockquotes look like quoted passages of text, assuming you've ever
 63 |        used email.
 64 | 
 65 |    Inline HTML
 66 |        Markdown's syntax is intended for one purpose: to be used as a
 67 |        format for writing for the web.
 68 | 
 69 |        Markdown is not a replacement for HTML, or even close to it. Its
 70 |        syntax is very small, corresponding only to a very small subset of
 71 |        HTML tags. The idea is not to create a syntax that makes it easier
 72 |        to insert HTML tags. In my opinion, HTML tags are already easy to
 73 |        insert. The idea for Markdown is to make it easy to read, write, and
 74 |        edit prose. HTML is a publishing format; Markdown is a writing
 75 |        format. Thus, Markdown's formatting syntax only addresses issues that
 76 |        can be conveyed in plain text.
 77 | 
 78 |        For any markup that is not covered by Markdown's syntax, you simply
 79 |        use HTML itself. There's no need to preface it or delimit it to
 80 |        indicate that you're switching from Markdown to HTML; you just use
 81 |        the tags.
 82 | 
 83 |        The only restrictions are that block-level HTML elements -- e.g. <div>,
 84 |        <table>, <pre>, <p>, etc. -- must be separated from surrounding
 85 |        content by blank lines, and the start and end tags of the block should
 86 |        not be indented with tabs or spaces. Markdown is smart enough not
 87 |        to add extra (unwanted) <p> tags around HTML block-level tags.
 88 | 
 89 |        For example, to add an HTML table to a Markdown article:
 90 |          This is a regular paragraph.
 91 | 
 92 |          <table>
 93 |              <tr>
 94 |                  <td>Foo</td>
 95 |              </tr>
 96 |          </table>
 97 | 
 98 |          This is another regular paragraph.
 99 | 
100 |        Note  that  Markdown  formatting  syntax  is   not   processed   within
101 |        block-level
102 |        HTML tags. E.g., you can't use Markdown-style *emphasis* inside an
103 |        HTML block.
104 | 
105 |        Span-level HTML tags -- e.g. <span>, <cite>, or <del> -- can be
106 |        used anywhere in a Markdown paragraph, list item, or header. If you
107 |        want,  you  can even use HTML tags instead of Markdown formatting; e.g.
108 |        if
109 |        you'd prefer to use HTML <a> or <img> tags instead of Markdown's
110 |        link or image syntax, go right ahead.
111 | 
112 |        Unlike block-level HTML tags, Markdown syntax is processed within
113 |        span-level tags.
114 | 
115 |    Automatic Escaping for Special Characters
116 |        In HTML, there are two characters that demand special treatment: <
117 |        and &. Left angle brackets are used to start tags; ampersands are
118 |        used to denote HTML entities. If you want to use them as literal
119 |        characters, you must escape them as entities, e.g. &lt;, and
120 |        &amp;.
121 | 
122 |        Ampersands in particular are bedeviling for web writers. If you want to
123 |        write about 'AT&T', you need to write 'AT&amp;T'. You even need to
124 |        escape ampersands within URLs. Thus, if you want to link to:
125 |          http://images.google.com/images?num=30&q=larry+bird
126 | 
127 |        you need to encode the URL as:
128 |          http://images.google.com/images?num=30&amp;q=larry+bird
129 | 
130 |        in your anchor tag href attribute. Needless to say, this is easy to
131 |        forget, and is probably the single most common source of  HTML  valida‐
132 |        tion
133 |        errors in otherwise well-marked-up web sites.
134 | 
135 |        Markdown allows you to use these characters naturally, taking care of
136 |        all the necessary escaping for you. If you use an ampersand as part of
137 |        an HTML entity, it remains unchanged; otherwise it will be translated
138 |        into &amp;.
139 | 
140 |        So,  if you want to include a copyright symbol in your article, you can
141 |        write:
142 |          &copy;
143 | 
144 |        and Markdown will leave it alone. But if you write:
145 |          AT&T
146 | 
147 |        Markdown will translate it to:
148 |          AT&amp;T
149 | 
150 |        Similarly, because Markdown supports inline HTML if you use
151 |        angle brackets as delimiters for HTML tags, Markdown will treat them as
152 |        such. But if you write:
153 |          4 < 5
154 | 
155 |        Markdown will translate it to:
156 |          4 &lt; 5
157 | 
158 |        However, inside Markdown code spans and blocks, angle brackets and
159 |        ampersands are always encoded automatically. This makes it easy to use
160 |        Markdown to write about HTML code. (As opposed to raw HTML, which is a
161 |        terrible format for writing about HTML syntax, because every single <
162 |        and & in your example code needs to be escaped.)
163 | 
164 | BLOCK ELEMENTS
165 |    Paragraphs and Line Breaks
166 |        A paragraph is simply one or more consecutive lines of text, separated
167 |        by one or more blank lines. (A blank line is any line that looks like a
168 |        blank line -- a line containing nothing but spaces or tabs  is  consid‐
169 |        ered
170 |        blank.) Normal paragraphs should not be indented with spaces or tabs.
171 | 
172 |        The implication of the "one or more consecutive lines of text" rule is
173 |        that Markdown supports "hard-wrapped" text paragraphs. This differs
174 |        significantly  from  most other text-to-HTML formatters (including Mov‐
175 |        able
176 |        Type's "Convert Line Breaks" option) which translate every line break
177 |        character in a paragraph into a <br /> tag.
178 | 
179 |        When you do want to insert a <br /> break tag using Markdown, you
180 |        end a line with two or more spaces, then type return.
181 | 
182 |        Yes, this takes a tad more effort to create a <br />, but a simplistic
183 |        "every line break is a <br />" rule wouldn't work for Markdown.
184 |        Markdown's email-style blockquoting and multi-paragraph list items
185 |        work best -- and look better -- when you format them with hard breaks.
186 | 
187 |    Headers
188 |        Markdown supports two styles of headers, [Setext] ]8;;http://docutils.sourceforge.net/mirror/setext.html\1]8;;\ and [atx] ]8;;http://www.aaronsw.com/2002/atx/\2]8;;\.
189 | 
190 |        Setext-style  headers  are  "underlined"   using   equal   signs   (for
191 |        first-level
192 |        headers) and dashes (for second-level headers). For example:
193 |          This is an H1
194 |          =============
195 | 
196 |          This is an H2
197 |          -------------
198 | 
199 |        Any number of underlining ='s or -'s will work.
200 | 
201 |        Atx-style headers use 1-6 hash characters at the start of the line,
202 |        corresponding to header levels 1-6. For example:
203 |          # This is an H1
204 | 
205 |          ## This is an H2
206 | 
207 |          ###### This is an H6
208 | 
209 |        Optionally, you may "close" atx-style headers. This is purely
210 |        cosmetic -- you can use this if you think it looks better. The
211 |        closing hashes don't even need to match the number of hashes
212 |        used to open the header. (The number of opening hashes
213 |        determines the header level.) :
214 |          # This is an H1 #
215 | 
216 |          ## This is an H2 ##
217 | 
218 |          ### This is an H3 ######
219 | 
220 |    Blockquotes
221 |        Markdown uses email-style > characters for blockquoting. If you're
222 |        familiar with quoting passages of text in an email message, then you
223 |        know how to create a blockquote in Markdown. It looks best if you hard
224 |        wrap the text and put a > before every line:
225 |          > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
226 |          > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
227 |          > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
228 |          >
229 |          > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
230 |          > id sem consectetuer libero luctus adipiscing.
231 | 
232 |        Markdown allows you to be lazy and only put the > before the first
233 |        line of a hard-wrapped paragraph:
234 |          > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
235 |          consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
236 |          Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
237 | 
238 |          > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
239 |          id sem consectetuer libero luctus adipiscing.
240 | 
241 |        Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
242 |        adding additional levels of >:
243 |          > This is the first level of quoting.
244 |          >
245 |          > > This is nested blockquote.
246 |          >
247 |          > Back to the first level.
248 | 
249 |        Blockquotes  can  contain  other  Markdown elements, including headers,
250 |        lists,
251 |        and code blocks:
252 |          > ## This is a header.
253 |          >
254 |          > 1.   This is the first list item.
255 |          > 2.   This is the second list item.
256 |          >
257 |          > Here's some example code:
258 |          >
259 |          >     return shell_exec("echo $input | $markdown_script");
260 | 
261 |        Any decent text editor should make email-style quoting easy. For
262 |        example, with BBEdit, you can make a selection and choose Increase
263 |        Quote Level from the Text menu.
264 | 
265 |    Lists
266 |        Markdown supports ordered (numbered) and unordered (bulleted) lists.
267 | 
268 |        Unordered lists use asterisks, pluses, and hyphens -- interchangably
269 |        -- as list markers:
270 |          *   Red
271 |          *   Green
272 |          *   Blue
273 | 
274 |        is equivalent to:
275 |          +   Red
276 |          +   Green
277 |          +   Blue
278 | 
279 |        and:
280 |          -   Red
281 |          -   Green
282 |          -   Blue
283 | 
284 |        Ordered lists use numbers followed by periods:
285 |          1.  Bird
286 |          2.  McHale
287 |          3.  Parish
288 | 
289 |        It's important to note that the actual numbers you use to mark the
290 |        list have no effect on the HTML output Markdown produces. The HTML
291 |        Markdown produces from the above list is:
292 |          <ol>
293 |          <li>Bird</li>
294 |          <li>McHale</li>
295 |          <li>Parish</li>
296 |          </ol>
297 | 
298 |        If you instead wrote the list in Markdown like this:
299 |          1.  Bird
300 |          1.  McHale
301 |          1.  Parish
302 | 
303 |        or even:
304 |          3. Bird
305 |          1. McHale
306 |          8. Parish
307 | 
308 |        you'd get the exact same HTML output. The point is, if you want to,
309 |        you can use ordinal numbers in your ordered Markdown lists, so that
310 |        the numbers in your source match the numbers in your published HTML.
311 |        But if you want to be lazy, you don't have to.
312 | 
313 |        If you do use lazy list numbering, however, you should still start the
314 |        list with the number 1. At some point in the future, Markdown may  sup‐
315 |        port
316 |        starting ordered lists at an arbitrary number.
317 | 
318 |        List markers typically start at the left margin, but may be indented by
319 |        up to three spaces. List markers must be followed by one or more spaces
320 |        or a tab.
321 | 
322 |        To make lists look nice, you can wrap items with hanging indents:
323 |          *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
324 |              Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
325 |              viverra nec, fringilla in, laoreet vitae, risus.
326 |          *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
327 |              Suspendisse id sem consectetuer libero luctus adipiscing.
328 | 
329 |        But if you want to be lazy, you don't have to:
330 |          *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
331 |          Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
332 |          viverra nec, fringilla in, laoreet vitae, risus.
333 |          *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
334 |          Suspendisse id sem consectetuer libero luctus adipiscing.
335 | 
336 |        If list items are separated by blank lines, Markdown will wrap the
337 |        items in <p> tags in the HTML output. For example, this input:
338 |          *   Bird
339 |          *   Magic
340 | 
341 |        will turn into:
342 |          <ul>
343 |          <li>Bird</li>
344 |          <li>Magic</li>
345 |          </ul>
346 | 
347 |        But this:
348 |          *   Bird
349 | 
350 |          *   Magic
351 | 
352 |        will turn into:
353 |          <ul>
354 |          <li><p>Bird</p></li>
355 |          <li><p>Magic</p></li>
356 |          </ul>
357 | 
358 |        List items may consist of multiple paragraphs. Each subsequent
359 |        paragraph in a list item must be indented by either 4 spaces
360 |        or one tab:
361 |          1.  This is a list item with two paragraphs. Lorem ipsum dolor
362 |              sit amet, consectetuer adipiscing elit. Aliquam hendrerit
363 |              mi posuere lectus.
364 | 
365 |              Vestibulum enim wisi, viverra nec, fringilla in, laoreet
366 |              vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
367 |              sit amet velit.
368 | 
369 |          2.  Suspendisse id sem consectetuer libero luctus adipiscing.
370 | 
371 |        It looks nice if you indent every line of the subsequent
372 |        paragraphs, but here again, Markdown will allow you to be
373 |        lazy:
374 |          *   This is a list item with two paragraphs.
375 | 
376 |              This is the second paragraph in the list item. You're
377 |          only required to indent the first line. Lorem ipsum dolor
378 |          sit amet, consectetuer adipiscing elit.
379 | 
380 |          *   Another item in the same list.
381 | 
382 |        To put a blockquote within a list item, the blockquote's >
383 |        delimiters need to be indented:
384 |          *   A list item with a blockquote:
385 | 
386 |              > This is a blockquote
387 |              > inside a list item.
388 | 
389 |        To put a code block within a list item, the code block needs
390 |        to be indented twice -- 8 spaces or two tabs:
391 |          *   A list item with a code block:
392 | 
393 |                  <code goes here>
394 | 
395 |        It's worth noting that it's possible to trigger an ordered list by
396 |        accident, by writing something like this:
397 |          1986. What a great season.
398 | 
399 |        In other words, a number-period-space sequence at the beginning of a
400 |        line. To avoid this, you can backslash-escape the period:
401 |          1986\. What a great season.
402 | 
403 |    Code Blocks
404 |        Pre-formatted code blocks are used for writing about programming or
405 |        markup source code. Rather than forming normal paragraphs, the lines
406 |        of a code block are interpreted literally. Markdown wraps a code block
407 |        in both <pre> and <code> tags.
408 | 
409 |        To produce a code block in Markdown, simply indent every line of the
410 |        block by at least 4 spaces or 1 tab. For example, given this input:
411 |          This is a normal paragraph:
412 | 
413 |              This is a code block.
414 | 
415 |        Markdown will generate:
416 |          <p>This is a normal paragraph:</p>
417 | 
418 |          <pre><code>This is a code block.
419 |          </code></pre>
420 | 
421 |        One level of indentation -- 4 spaces or 1 tab -- is removed from each
422 |        line of the code block. For example, this:
423 |          Here is an example of AppleScript:
424 | 
425 |              tell application "Foo"
426 |                  beep
427 |              end tell
428 | 
429 |        will turn into:
430 |          <p>Here is an example of AppleScript:</p>
431 | 
432 |          <pre><code>tell application "Foo"
433 |              beep
434 |          end tell
435 |          </code></pre>
436 | 
437 |        A code block continues until it reaches a line that is not indented
438 |        (or the end of the article).
439 | 
440 |        Within a code block, ampersands (&) and angle brackets (< and >)
441 |        are automatically converted into HTML entities. This makes it very
442 |        easy to include example HTML source code using Markdown -- just paste
443 |        it and indent it, and Markdown will handle the hassle of encoding the
444 |        ampersands and angle brackets. For example, this:
445 |              <div class="footer">
446 |                  &copy; 2004 Foo Corporation
447 |              </div>
448 | 
449 |        will turn into:
450 |          <pre><code>&lt;div class="footer"&gt;
451 |              &amp;copy; 2004 Foo Corporation
452 |          &lt;/div&gt;
453 |          </code></pre>
454 | 
455 |        Regular Markdown syntax is not processed within code blocks. E.g.,
456 |        asterisks are just literal asterisks within a code block. This means
457 |        it's also easy to use Markdown to write about Markdown's own syntax.
458 | 
459 |    Horizontal Rules
460 |        You can produce a horizontal rule tag (<hr />) by placing three or
461 |        more hyphens, asterisks, or underscores on a line by themselves. If you
462 |        wish, you may use spaces between the hyphens or asterisks. Each of the
463 |        following lines will produce a horizontal rule:
464 |          * * *
465 | 
466 |          ***
467 | 
468 |          *****
469 | 
470 |          - - -
471 | 
472 |          ---------------------------------------
473 | 
474 | SPAN ELEMENTS
475 |    Links
476 |        Markdown supports two style of links: inline and reference.
477 | 
478 |        In both styles, the link text is delimited by [square brackets].
479 | 
480 |        To create an inline link, use a set of regular parentheses immediately
481 |        after the link text's closing square bracket. Inside the parentheses,
482 |        put the URL where you want the link to point, along with an optional
483 |        title for the link, surrounded in quotes. For example:
484 |          This is [an example](http://example.com/ "Title") inline link.
485 | 
486 |          [This link](http://example.net/) has no title attribute.
487 | 
488 |        Will produce:
489 |          <p>This is <a href="http://example.com/" title="Title">
490 |          an example</a> inline link.</p>
491 | 
492 |          <p><a href="http://example.net/">This link</a> has no
493 |          title attribute.</p>
494 | 
495 |        If you're referring to a local resource on the same server, you can
496 |        use relative paths:
497 |          See my [About](/about/) page for details.
498 | 
499 |        Reference-style links use a second set of square brackets, inside
500 |        which you place a label of your choosing to identify the link:
501 |          This is [an example][id] reference-style link.
502 | 
503 |        You can optionally use a space to separate the sets of brackets:
504 |          This is [an example] [id] reference-style link.
505 | 
506 |        Then, anywhere in the document, you define your link label like this,
507 |        on a line by itself:
508 |          [id]: http://example.com/  "Optional Title Here"
509 | 
510 |        That is:
511 | 
512 |         • Square brackets containing the link identifier (optionally
513 |           indented from the left margin using up to three spaces);
514 | 
515 |         • followed by a colon;
516 | 
517 |         • followed by one or more spaces (or tabs);
518 | 
519 |         • followed by the URL for the link;
520 | 
521 |         • optionally followed by a title attribute for the link, enclosed
522 |           in double or single quotes, or enclosed in parentheses.
523 | 
524 |        The following three link definitions are equivalent:
525 |          [foo]: http://example.com/  "Optional Title Here"
526 |          [foo]: http://example.com/  'Optional Title Here'
527 |          [foo]: http://example.com/  (Optional Title Here)
528 | 
529 |        Note: There is a known bug in Markdown.pl 1.0.1 which prevents
530 |        single quotes from being used to delimit link titles.
531 | 
532 |        The link URL may, optionally, be surrounded by angle brackets:
533 |          [id]: <http://example.com/>  "Optional Title Here"
534 | 
535 |        You can put the title attribute on the next line and use extra spaces
536 |        or tabs for padding, which tends to look better with longer URLs:
537 |          [id]: http://example.com/longish/path/to/resource/here
538 |              "Optional Title Here"
539 | 
540 |        Link definitions are only used for creating links during Markdown
541 |        processing, and are stripped from your document in the HTML output.
542 | 
543 |        Link definition names may consist of letters, numbers, spaces, and
544 |        punctuation -- but they are not case sensitive. E.g. these two
545 |        links:
546 |          [link text][a]
547 |          [link text][A]
548 | 
549 |        are equivalent.
550 | 
551 |        The implicit link name shortcut allows you to omit the name of the
552 |        link, in which case the link text itself is used as the name.
553 |        Just use an empty set of square brackets -- e.g., to link the word
554 |        "Google" to the google.com web site, you could simply write:
555 |          [Google][]
556 | 
557 |        And then define the link:
558 |          [Google]: http://google.com/
559 | 
560 |        Because link names may contain spaces, this shortcut even works for
561 |        multiple words in the link text:
562 |          Visit [Daring Fireball][] for more information.
563 | 
564 |        And then define the link:
565 |          [Daring Fireball]: http://daringfireball.net/
566 | 
567 |        Link definitions can be placed anywhere in your Markdown document. I
568 |        tend to put them immediately after each paragraph in which they're
569 |        used, but if you want, you can put them all at the end of your
570 |        document, sort of like footnotes.
571 | 
572 |        Here's an example of reference links in action:
573 |          I get 10 times more traffic from [Google] [1] than from
574 |          [Yahoo] [2] or [MSN] [3].
575 | 
576 |            [1]: http://google.com/        "Google"
577 |            [2]: http://search.yahoo.com/  "Yahoo Search"
578 |            [3]: http://search.msn.com/    "MSN Search"
579 | 
580 |        Using the implicit link name shortcut, you could instead write:
581 |          I get 10 times more traffic from [Google][] than from
582 |          [Yahoo][] or [MSN][].
583 | 
584 |            [google]: http://google.com/        "Google"
585 |            [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
586 |            [msn]:    http://search.msn.com/    "MSN Search"
587 | 
588 |        Both of the above examples will produce the following HTML output:
589 |          <p>I get 10 times more traffic from <a href="http://google.com/"
590 |          title="Google">Google</a> than from
591 |          <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
592 |          or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
593 | 
594 |        For comparison, here is the same paragraph written using
595 |        Markdown's inline link style:
596 |          I get 10 times more traffic from [Google](http://google.com/ "Google")
597 |          than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
598 |          [MSN](http://search.msn.com/ "MSN Search").
599 | 
600 |        The point of reference-style links is not that they're easier to
601 |        write. The point is that with reference-style links, your document
602 |        source is vastly more readable. Compare the above examples: using
603 |        reference-style links, the paragraph itself is only 81 characters
604 |        long; with inline-style links, it's 176 characters; and as raw HTML,
605 |        it's 234 characters. In the raw HTML, there's more markup than there
606 |        is text.
607 | 
608 |        With Markdown's reference-style links, a source document much more
609 |        closely resembles the final output, as rendered in a browser. By
610 |        allowing you to move the markup-related metadata out of the paragraph,
611 |        you can add links without interrupting the narrative flow of your
612 |        prose.
613 | 
614 |    Emphasis
615 |        Markdown treats asterisks (*) and underscores (_) as indicators of
616 |        emphasis. Text wrapped with one * or _ will be wrapped with an
617 |        HTML <em> tag; double *'s or _'s will be wrapped with an HTML
618 |        <strong> tag. E.g., this input:
619 |          *single asterisks*
620 | 
621 |          _single underscores_
622 | 
623 |          **double asterisks**
624 | 
625 |          __double underscores__
626 | 
627 |        will produce:
628 |          <em>single asterisks</em>
629 | 
630 |          <em>single underscores</em>
631 | 
632 |          <strong>double asterisks</strong>
633 | 
634 |          <strong>double underscores</strong>
635 | 
636 |        You can use whichever style you prefer; the lone restriction is that
637 |        the same character must be used to open and close an emphasis span.
638 | 
639 |        Emphasis can be used in the middle of a word:
640 |          un*frigging*believable
641 | 
642 |        But if you surround an * or _ with spaces, it'll be treated as a
643 |        literal asterisk or underscore.
644 | 
645 |        To produce a literal asterisk or underscore at a position where it
646 |        would otherwise be used as an emphasis delimiter, you can backslash
647 |        escape it:
648 |          \*this text is surrounded by literal asterisks\*
649 | 
650 |    Code
651 |        To indicate a span of code, wrap it with backtick quotes (`).
652 |        Unlike a pre-formatted code block, a code span indicates code within a
653 |        normal paragraph. For example:
654 |          Use the `printf()` function.
655 | 
656 |        will produce:
657 |          <p>Use the <code>printf()</code> function.</p>
658 | 
659 |        To include a literal backtick character within a code span, you can use
660 |        multiple backticks as the opening and closing delimiters:
661 |          ``There is a literal backtick (`) here.``
662 | 
663 |        which will produce this:
664 |          <p><code>There is a literal backtick (`) here.</code></p>
665 | 
666 |        The backtick delimiters surrounding a code span may include spaces --
667 |        one after the opening, one before the closing. This allows you to place
668 |        literal backtick characters at the beginning or end of a code span:
669 |          A single backtick in a code span: `` ` ``
670 | 
671 |          A backtick-delimited string in a code span: `` `foo` ``
672 | 
673 |        will produce:
674 |          <p>A single backtick in a code span: <code>`</code></p>
675 | 
676 |          <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
677 | 
678 |        With a code span, ampersands and angle brackets are encoded as HTML
679 |        entities automatically, which makes it easy to include example HTML
680 |        tags. Markdown will turn this:
681 |          Please don't use any `<blink>` tags.
682 | 
683 |        into:
684 |          <p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
685 | 
686 |        You can write this:
687 |          `&#8212;` is the decimal-encoded equivalent of `&mdash;`.
688 | 
689 |        to produce:
690 |          <p><code>&amp;#8212;</code> is the decimal-encoded
691 |          equivalent of <code>&amp;mdash;</code>.</p>
692 | 
693 |    Images
694 |        Admittedly, it's fairly difficult to devise a "natural" syntax for
695 |        placing images into a plain text document format.
696 | 
697 |        Markdown uses an image syntax that is intended to resemble the syntax
698 |        for links, allowing for two styles: inline and reference.
699 | 
700 |        Inline image syntax looks like this:
701 |          ![Alt text](/path/to/img.jpg)
702 | 
703 |          ![Alt text](/path/to/img.jpg "Optional title")
704 | 
705 |        That is:
706 | 
707 |         • An exclamation mark: !;
708 | 
709 |         • followed by a set of square brackets, containing the alt
710 |           attribute text for the image;
711 | 
712 |         • followed by a set of parentheses, containing the URL or path to
713 |           the image, and an optional title attribute enclosed in double
714 |           or single quotes.
715 | 
716 |        Reference-style image syntax looks like this:
717 |          ![Alt text][id]
718 | 
719 |        Where "id" is the name of a defined image reference. Image references
720 |        are defined using syntax identical to link references:
721 |          [id]: url/to/image  "Optional title attribute"
722 | 
723 |        As of this writing, Markdown has no syntax for specifying the
724 |        dimensions of an image; if this is important to you, you can simply
725 |        use regular HTML <img> tags.
726 | 
727 | MISCELLANEOUS
728 |    Automatic Links
729 |        Markdown  supports  a shortcut style for creating "automatic" links for
730 |        URLs and email addresses: simply surround the URL or email address with
731 |        angle brackets. What this means is that if you want to show the  actual
732 |        text  of  a URL or email address, and also have it be a clickable link,
733 |        you can do this:
734 |          <http://example.com/>
735 | 
736 |        Markdown will turn this into:
737 |          <a href="http://example.com/">http://example.com/</a>
738 | 
739 |        Automatic links for email addresses work similarly, except that
740 |        Markdown will also perform a bit of randomized decimal and hex
741 |        entity-encoding to help obscure your address from address-harvesting
742 |        spambots. For example, Markdown will turn this:
743 |          <address@example.com>
744 | 
745 |        into something like this:
746 |          <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
747 |          &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
748 |          &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
749 |          &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
750 | 
751 |        which will render in a browser as a clickable  link  to  "address@exam‐
752 |        ple.com.
753 | 
754 |        (This sort of entity-encoding trick will indeed fool many, if not
755 |        most, address-harvesting bots, but it definitely won't fool all of
756 |        them. It's better than nothing, but an address published in this way
757 |        will probably eventually start receiving spam.)
758 | 
759 |    Backslash Escapes
760 |        Markdown allows you to use backslash escapes to generate literal
761 |        characters which would otherwise have special meaning in Markdown's
762 |        formatting syntax. For example, if you wanted to surround a word
763 |        with literal asterisks (instead of an HTML <em> tag), you can use
764 |        backslashes before the asterisks, like this:
765 |          \*literal asterisks\*
766 | 
767 |        Markdown provides backslash escapes for the following characters:
768 |          \   backslash
769 |          `   backtick
770 |          *   asterisk
771 |          _   underscore
772 |          {}  curly braces
773 |          []  square brackets
774 |          ()  parentheses
775 |          #   hash mark
776 |          +   plus sign
777 |          -   minus sign (hyphen)
778 |          .   dot
779 |          !   exclamation mark
780 | 
781 | AUTHOR
782 |        Markdown was created by John Gruber.
783 | 
784 |        Manual page by Ryan Tomayko. It's pretty much a direct copy of the
785 |        ]8;;http://daringfireball.net/projects/markdown/syntax\Markdown Syntax Reference]8;;\,
786 | 
787 |        also by John Gruber.
788 | 
789 | SEE ALSO
790 |        ronn(5)
791 |        ]8;;http://daringfireball.net/projects/markdown/\Markdown Syntax Reference]8;;\
792 | 
793 |                                  January 1979                      MARKDOWN(5)
794 | 


--------------------------------------------------------------------------------
/test/out/nested_list_with_code.out:
--------------------------------------------------------------------------------
 1 | A(1)                        General Commands Manual                       A(1)
 2 | 
 3 | NAME
 4 |        a
 5 | 
 6 |        Tight list:
 7 | 
 8 |         • toggle_status
 9 | 
10 |          • Toggle the display of the status bar1
11 | 
12 |          • Toggle the display of the status bar2
13 | 
14 |         • spawn  <executable> <additional args> TODO explain path-alike expan‐
15 |           sion
16 | 
17 |        Loose list:
18 | 
19 |         • toggle_status
20 | 
21 |          • Toggle the display of the status bar1
22 | 
23 |          • Toggle the display of the status bar2
24 | 
25 |         • spawn <executable> <additional args> TODO explain path-alike  expan‐
26 |           sion
27 | 
28 |                                  January 1979                             A(1)
29 | 


--------------------------------------------------------------------------------
/test/out/noname.out:
--------------------------------------------------------------------------------
 1 | TEST(1)                     General Commands Manual                    TEST(1)
 2 | 
 3 | NAME
 4 |        test - a nice test
 5 | 
 6 | SYNOPSYS
 7 |        test is a test
 8 | 
 9 |                                  January 1979                          TEST(1)
10 | 


--------------------------------------------------------------------------------
/test/out/pre_block_with_quotes.out:
--------------------------------------------------------------------------------
 1 | T(1)                        General Commands Manual                       T(1)
 2 | 
 3 | NAME
 4 |        t - test
 5 | 
 6 | test
 7 |          [ "$11" ]
 8 | 
 9 |                                  January 1979                             T(1)
10 | 


--------------------------------------------------------------------------------
/test/out/regressions.out:
--------------------------------------------------------------------------------
 1 | REGRESSIONS(7)         Miscellaneous Information Manual         REGRESSIONS(7)
 2 | 
 3 | NAME
 4 |        regressions - issues
 5 | 
 6 | inlines
 7 |        This should be  (a b) ok.
 8 | 
 9 |        This should not double escape pkg-js-tools.
10 | 
11 |                                  January 1979                   REGRESSIONS(7)
12 | 


--------------------------------------------------------------------------------
/test/out/simple_table.out:
--------------------------------------------------------------------------------
 1 | SIMPLE_TABLE(1)             General Commands Manual            SIMPLE_TABLE(1)
 2 | 
 3 | NAME
 4 |        simple_table
 5 |        ┌──────────────────────────────────────────────────────────┐
 6 |        │ Col1                      Col2                      Col3 │
 7 |        ├──────────────────────────────────────────────────────────┤
 8 |        │ A                           B                          C │
 9 |        ├──────────────────────────────────────────────────────────┤
10 |        │ D                           E                          F │
11 |        └──────────────────────────────────────────────────────────┘
12 | 
13 |                                  January 1979                  SIMPLE_TABLE(1)
14 | 


--------------------------------------------------------------------------------
/test/out/table.out:
--------------------------------------------------------------------------------
  1 | TABLE(7)               Miscellaneous Information Manual               TABLE(7)
  2 | 
  3 | NAME
  4 |        table - test data for table format
  5 | 
  6 |        test table copy and paste form www.
  7 | 
  8 | LARGE TABLE
  9 |        ]8;;https://en.wikipedia.org/wiki/Comparison_of_file_systems\Comparison of file systems]8;;\
 10 |        ┌─────────────────────────────────────────────────────────────────────────┐
 11 |        │ File system       Creator           Year  of  intro‐   Original operat‐ │
 12 |        │                                     duction            ing system       │
 13 |        ├─────────────────────────────────────────────────────────────────────────┤
 14 |        │ DECtape           DEC               1964               PDP-6 Monitor    │
 15 |        ├─────────────────────────────────────────────────────────────────────────┤
 16 |        │ DASD              IBM               1964               OS/360           │
 17 |        ├─────────────────────────────────────────────────────────────────────────┤
 18 |        │ Level-D           DEC               1968               TOPS-10          │
 19 |        ├─────────────────────────────────────────────────────────────────────────┤
 20 |        │ George 2          ICT (later ICL)   1968               George 2         │
 21 |        ├─────────────────────────────────────────────────────────────────────────┤
 22 |        │ Version  6  Unix  Bell Labs         1972               Version 6 Unix   │
 23 |        │ file      system                                                        │
 24 |        │ (V6FS)                                                                  │
 25 |        ├─────────────────────────────────────────────────────────────────────────┤
 26 |        │ RT-11 file  sys‐  DEC               1973               RT-11            │
 27 |        │ tem                                                                     │
 28 |        ├─────────────────────────────────────────────────────────────────────────┤
 29 |        │ Disk   Operating  GEC               1973               Core   Operating │
 30 |        │ System (GEC DOS)                                       System           │
 31 |        ├─────────────────────────────────────────────────────────────────────────┤
 32 |        │ CP/M file system  Digital Research  1974               CP/M[1]          │
 33 |        │                   (Gary Kildall)                                        │
 34 |        ├─────────────────────────────────────────────────────────────────────────┤
 35 |        │ ODS-1             DEC               1975               RSX-11           │
 36 |        ├─────────────────────────────────────────────────────────────────────────┤
 37 |        │ GEC  DOS  filing  GEC               1977               OS4000           │
 38 |        │ system extended                                                         │
 39 |        ├─────────────────────────────────────────────────────────────────────────┤
 40 |        │ FAT (8-bit)       Microsoft  (Marc  1977               Microsoft Stand‐ │
 41 |        │                   McDonald)    for                     alone  Disk  BA‐ │
 42 |        │                   NCR                                  SIC-80    (later │
 43 |        │                                                        Microsoft Stand‐ │
 44 |        │                                                        alone  Disk  BA‐ │
 45 |        │                                                        SIC-86)          │
 46 |        ├─────────────────────────────────────────────────────────────────────────┤
 47 |        │ DOS 3.x           Apple Computer    1978               Apple DOS        │
 48 |        ├─────────────────────────────────────────────────────────────────────────┤
 49 |        │ Pascal            Apple Computer    1978               Apple Pascal     │
 50 |        ├─────────────────────────────────────────────────────────────────────────┤
 51 |        │ CBM DOS           Commodore         1978               Commodore BASIC  │
 52 |        ├─────────────────────────────────────────────────────────────────────────┤
 53 |        │ Version  7  Unix  Bell Labs         1979               Version 7 Unix   │
 54 |        │ file      system                                                        │
 55 |        │ (V7FS)                                                                  │
 56 |        ├─────────────────────────────────────────────────────────────────────────┤
 57 |        │ ODS-2             DEC               1979               OpenVMS          │
 58 |        └─────────────────────────────────────────────────────────────────────────┘
 59 | 
 60 | LONG TEXT
 61 |        ┌────────────────────────────────────────────────────────────────────┐
 62 |        │ Person                Work                     Quote               │
 63 |        ├────────────────────────────────────────────────────────────────────┤
 64 |        │ Sherlock Holmes       The Norwood Builder      You  mentioned your │
 65 |        │                                                name as if I should │
 66 |        │                                                recognize  it,  but │
 67 |        │                                                beyond  the obvious │
 68 |        │                                                facts that you  are │
 69 |        │                                                a  bachelor,  a so‐ │
 70 |        │                                                licitor, a  freema‐ │
 71 |        │                                                son,  and  an asth‐ │
 72 |        │                                                matic, I know noth‐ │
 73 |        │                                                ing whatever  about │
 74 |        │                                                you.                │
 75 |        └────────────────────────────────────────────────────────────────────┘
 76 | 
 77 | THING TABLE
 78 |        ┌──────────────────────────────────────────────┐
 79 |        │ 1                                          2 │
 80 |        ├──────────────────────────────────────────────┤
 81 |        │ 1                                          2 │
 82 |        ├──────────────────────────────────────────────┤
 83 |        │ 1                                          2 │
 84 |        ├──────────────────────────────────────────────┤
 85 |        │ 1                                          2 │
 86 |        ├──────────────────────────────────────────────┤
 87 |        │ 1                                          2 │
 88 |        ├──────────────────────────────────────────────┤
 89 |        │ 1                                          2 │
 90 |        ├──────────────────────────────────────────────┤
 91 |        │ T{1                                        2 │
 92 |        ├──────────────────────────────────────────────┤
 93 |        │ 1                                          2 │
 94 |        ├──────────────────────────────────────────────┤
 95 |        │ 1                                          2 │
 96 |        ├──────────────────────────────────────────────┤
 97 |        │ 1                                          2 │
 98 |        ├──────────────────────────────────────────────┤
 99 |        │ 1                                          2 │
100 |        ├──────────────────────────────────────────────┤
101 |        │ 1                                          2 │
102 |        ├──────────────────────────────────────────────┤
103 |        │ 1                                          2 │
104 |        ├──────────────────────────────────────────────┤
105 |        │ 1                                          2 │
106 |        ├──────────────────────────────────────────────┤
107 |        │ 1                                          2 │
108 |        ├──────────────────────────────────────────────┤
109 |        │ 1                                          2 │
110 |        ├──────────────────────────────────────────────┤
111 |        │ 1                                          2 │
112 |        ├──────────────────────────────────────────────┤
113 |        │ 1                                          2 │
114 |        ├──────────────────────────────────────────────┤
115 |        │ 1                                          2 │
116 |        ├──────────────────────────────────────────────┤
117 |        │ 1                                          2 │
118 |        └──────────────────────────────────────────────┘
119 | 
120 |                                  January 1979                         TABLE(7)
121 | 


--------------------------------------------------------------------------------
/test/out/underline_spacing_test.out:
--------------------------------------------------------------------------------
 1 | UNDERLINE_SPACING_TEST(1)   General Commands Manual  UNDERLINE_SPACING_TEST(1)
 2 | 
 3 | NAME
 4 |        underline_spacing_test
 5 | 
 6 |         • -S text, search text:
 7 |           Performs a substring search of formula names for text.
 8 | 
 9 |         • -O <text>, other <text>:
10 |           Does something else.
11 | 
12 |        Should space text properly.  <!-- this is a comment -->
13 | 
14 |                                  January 1979        UNDERLINE_SPACING_TEST(1)
15 | 


--------------------------------------------------------------------------------