ronn-ng 0.7.4 → 0.8.0.SNAPSHOT

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