/
sample.html
304 lines (237 loc) · 13 KB
/
sample.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="latexinput" content="mmd-article-header"/>
<title>Sample MultiMarkdown Document</title>
<meta name="latexmode" content="memoir"/>
<meta name="keywords" content="MultiMarkdown, Markdown, XML, XHTML, XSLT, PDF"/>
<link type="text/css" rel="stylesheet" href="http://fletcherpenney.net/css/document.css"/>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
<meta name="copyright" content="2011 Fletcher T. Penney.
This work is licensed under a Creative Commons License.
http://creativecommons.org/licenses/by-nc-sa/3.0/"/>
<meta name="latexinput" content="mmd-natbib-plain"/>
<meta name="latexinput" content="mmd-article-begin-doc"/>
<meta name="latexfooter" content="mmd-memoir-footer"/>
</head>
<body>
<h2 id="introduction">Introduction</h2>
<p>As I add increasing numbers of features to MultiMarkdown, I decided it was
time to create a sample document to show them off. Many of the features are
demonstrated in the <a href="http://fletcherpenney.net/mmd/users_guide/" title="MultiMarkdown User's Guide">MultiMarkdown User’s Guide</a>, but some are not.</p>
<p>Additionally, it’s easy for those features to get lost within all of the
technical documentation. This document is designed to <em>demonstrate</em>, not
describe, most of the features of MultiMarkdown.</p>
<h2 id="howtousethisdocument">How to Use This Document</h2>
<p>I suggest comparing the raw text source with the various final outputs (e.g.
HTML, LaTeX, PDF, OpenDocument) in order to see what can be accomplished.
There will be many similarities between output formats, but also a few
differences. Tables will end up in different places. Paragraphs won’t break in
the same way. But these differences are superficial and are a result of trying
to optimize each format, without regard to identical output across formats
(which would be virtually impossible).</p>
<p>Remember, the main goal of Markdown\MultiMarkdown is to allow you to create a
document in plain text, with minimal distraction from markup, that can be
transformed into a variety of high quality outputs. Or, to quote John Gruber:</p>
<blockquote>
<p>The overriding design goal for Markdown’s formatting syntax is to make it as
readable as possible. The idea is that 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, the single biggest source
of inspiration for Markdown’s syntax is the format of plain text
email.<a class="citation" href="#fn:1" title="Jump to citation">[1]<span class="citekey" style="display:none">Gruber</span></a></p>
</blockquote>
<h2 id="wherecanigetacopy">Where Can I Get a Copy?</h2>
<p>You can download a zipfile containing multiple formats of this document:</p>
<ul>
<li><a href="https://github.com/fletcher/MultiMarkdown-Gallery/releases">MultiMarkdown-Gallery</a></li>
</ul>
<p>This file includes:</p>
<ul>
<li>A plain text file in MultiMarkdown format</li>
<li>A Scrivener file</li>
<li>An HTML file</li>
<li>A PDF</li>
<li>An OpenDocument file</li>
<li>An OPML</li>
<li>A LaTeX file</li>
<li>And the included images</li>
</ul>
<p>All files were generated automatically from the MultiMarkdown source document.</p>
<h2 id="sowhatcanthisdocumentdemonstrate">So, What Can This Document Demonstrate?</h2>
<h3 id="metadata">Metadata</h3>
<p>First, take a look at the overall structure of the document. At the very
beginning is metadata, including a title, author, keywords, copyright
information, etc. Where possible, this metadata is put to appropriate use,
otherwise it is stored in a format designed to be easily read and minimally
distracting:</p>
<ul>
<li><p>In plain text and XHTML snippets<a href="#fn:2" id="fnref:2" title="see footnote" class="footnote">[2]</a>, it is located at the top of the
document.</p></li>
<li><p>In a full XHTML document, is located in the <code><head></code> section, and the title
and CSS metadata, if present, are used appropriately.</p></li>
<li><p>In a PDF generated from my XSLT files, metadata is used to generate the
appropriate fields (title, author, keywords) in the PDF itself. Some PDF
readers will let you examine this data. Additionally, the title, subtitle,
author, and copyright are placed at the beginning of the document.</p></li>
<li><p>In a Scrivener document, you can put the metadata in the first File in the
Binder, but the preferred location is in the “MultiMarkdown Settings…”
pane (in the File Menu.)</p></li>
</ul>
<p>There are a lot of standard metadata keys that can be used, or you can create
your own and use them as you see fit. Definitely a powerful feature.</p>
<h3 id="structure">Structure</h3>
<p>The next thing to look at is the overall structure of the document. You can
visualize a Markdown document as an outline, with different sections and
different levels within those sections. Based on your output format, these can
be used to generate headers, or sections, or even chapters. It’s all based on
what tools you use to process the XHTML output.</p>
<p>Even within the XHTML document, however, you can make use of this structure to
allow easy navigation within the document. You can link directly to the
<a href="#introduction">Introduction</a> (and to <a href="#introduction"></a> when using LaTeX), for instance. And
if you are creating a PDF, it will contain a hierarchy of section names that
you can use to allow easy navigation, if your PDF reader supports this
function.</p>
<h3 id="footnotes">Footnotes</h3>
<p>Footnotes are very easy to implement in MultiMarkdown, as described in the
MultiMarkdown Syntax Guide.<a href="#fn:3" id="fnref:3" title="see footnote" class="footnote">[3]</a></p>
<h3 id="tables">Tables</h3>
<p>Tables can be quite useful for showing data in a meaningful way. As an
example, here is a table comparing <a href="#multimarkdownvs.crayons">MultiMarkdown vs. Crayons</a>.</p>
<table>
<caption id="multimarkdownvs.crayons">This is a caption with <em>italics</em></caption>
<colgroup>
<col style="text-align:left;"/>
<col style="text-align:center;"/>
<col style="text-align:center;"/>
</colgroup>
<thead>
<tr>
<th style="text-align:left;">Features</th>
<th style="text-align:center;">MultiMarkdown</th>
<th style="text-align:center;">Crayons</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:left;">Melts in warm places</td>
<td style="text-align:center;">No</td>
<td style="text-align:center;">Yes</td>
</tr>
<tr>
<td style="text-align:left;">Mistakes can be easily fixed</td>
<td style="text-align:center;">Yes</td>
<td style="text-align:center;">No</td>
</tr>
<tr>
<td style="text-align:left;">Easy to copy documents for friends</td>
<td style="text-align:center;">Yes</td>
<td style="text-align:center;">No</td>
</tr>
<tr>
<td style="text-align:left;">Fun at parties</td>
<td style="text-align:center;">No<a href="#fn:4" id="fnref:4" title="see footnote" class="footnote">[4]</a></td>
<td style="text-align:center;">Why not?</td>
</tr>
</tbody>
<tbody>
<tr>
<td style="text-align:left;">Minimum markup for maximum quality?</td>
<td style="text-align:center;">Yes</td>
<td style="text-align:center;">No</td>
</tr>
</tbody>
</table>
<h3 id="typographicalconventions">Typographical conventions</h3>
<p>By incorporating John Gruber’s <a href="http://daringfireball.net/projects/smartypants/">SmartyPants</a> program into your workflow, you
can generate more “correct” typographic punction in your XHTML pages, and in
your LaTeX source if you are generating PDF’s—this includes en and em
dashes, and ellipses….</p>
<p>Very nice when you want to focus on writing, not grammar.</p>
<h3 id="imagesupport">Image Support</h3>
<p>If you choose to incorporate images in your documents, this can be easily done
as well. MultiMarkdown makes it easier to link to images and include various
attributes.</p>
<p>As an example, here is an image from my website — <a href="#nautilusstar">Nautilus
Star</a>. If you have a local copy of the image, you can include
the image in a pdf.</p>
<figure>
<img src="Nautilus_Star.png" alt="This is a bolded caption" id="nautilusstar" title="Nautilus Star" style="height:2.4in;width:3in;" />
<figcaption>This is a <strong>bolded</strong> caption</figcaption>
</figure>
<h3 id="bibliographysupport">Bibliography Support</h3>
<p>MultiMarkdown offers several mechanisms for managing bibliographies. It has
built-in support for basic citation and bibliography management and
formatting, or you can rely on external tools to handle this for you. There
aren’t many citations in this document, but I think it gets the point
across.<a class="citation" href="#fn:5" title="Jump to citation">[<span class="locator">p. 42</span>, 5]<span class="citekey" style="display:none">fake</span></a></p>
<h3 id="glossarysupport">Glossary Support</h3>
<p>MultiMarkdown has a special format for footnotes that should represent
glossary terms. This doesn’t make much difference in XHTML (because there is
no such thing as a glossary in XHTML), but can be used to generate a glossary
within LaTeX documents.</p>
<p>For example, let’s have an entry for <code>glossary</code>.<a href="#fn:6" id="fnref:6" title="see footnote" class="footnote glossary">[6]</a> And what about
ampersands?<a href="#fn:7" id="fnref:7" title="see footnote" class="footnote glossary">[7]</a></p>
<p>Since we want the ampersand entry to be sorted with the a’s, and not with
symbols, we put in the optional sort key <code>ampersand</code> to control sorting.</p>
<pre><code>[^glossary]: glossary: Glossary
A section at the end ...
[^amp]: glossary: & (ampersand)
A punctuation mark ...
</code></pre>
<h3 id="mathsupport">Math Support</h3>
<p>It’s pretty easy to include mathematical equations:</p>
<p><span class="math">\[ {e}^{i\pi }+1=0 \]</span></p>
<p><span class="math">\[ {x}_{1,2}=\frac{-b\pm \sqrt{{b}^{2}-4ac}}{2a} \]</span></p>
<p>You can also include formulas within a sentence, such as
<span class="math">\({x}^{2}+{y}^{2}=1\)</span>.</p>
<h2 id="nowwhat">Now What?</h2>
<p>Get out there and try it. Let me know what you think. Let me know what doesn’t
work. Let me know what you think is missing.</p>
<p>In other words, help me make it better!</p>
<p>You can get more information on my web site:</p>
<ul>
<li><a href="http://fletcherpenney.net/multimarkdown">http://fletcherpenney.net/multimarkdown</a></li>
</ul>
<p>You can also:</p>
<ul>
<li><p>Email me:<br/>
<a href="mailto:owner@fletcherpenney.net">owner@fletcherpenney.net</a></p></li>
<li><p>Join the MultiMarkdown discussion list:<br/>
<a href="http://groups.google.com/group/multimarkdown">http://groups.google.com/group/multimarkdown</a></p></li>
<li><p>Join the Markdown discussion list:<br/>
<a href="http://six.pairlist.net/mailman/listinfo/markdown-discuss">http://six.pairlist.net/mailman/listinfo/markdown-discuss</a></p></li>
</ul>
<div class="footnotes">
<hr />
<ol>
<li id="fn:1" class="citation"><span class="citekey" style="display:none">Gruber</span><p>John Gruber. Daring Fireball: Markdown. [Cited January 2006].
Available from <a href="http://daringfireball.net/projects/markdown/">http://daringfireball.net/projects/markdown/</a>.</p>
</li>
<li id="fn:2">
<p>An XHTML snippet is my terminology for XHTML code that does not
include the <code><html></code>, <code><head></code>, and <code><body></code> tags. Most browsers will display
it properly, but it is not a complete XHTML document. Without a <code><head></code>
section there is nowhere to put metadata(e.g. there is no <code><title></code>). <a href="#fnref:2" title="return to article" class="reversefootnote"> ↩</a></p>
</li>
<li id="fn:3">
<p>Here is the text of the footnote itself. <a href="#fnref:3" title="return to article" class="reversefootnote"> ↩</a></p>
</li>
<li id="fn:4">
<p>I guess it depends on what kind of parties you go to… <a href="#fnref:4" title="return to article" class="reversefootnote"> ↩</a></p>
</li>
<li id="fn:5" class="citation"><span class="citekey" style="display:none">fake</span><p>John Doe. <em>A Totally Fake Book</em>. Vanity Press, 2006.</p>
</li>
<li id="fn:6">
<span class="glossary name">Glossary </span>: <p>A section at the end … <a href="#fnref:6" title="return to article" class="reversefootnote"> ↩</a></p>
</li>
<li id="fn:7">
<span class="glossary name">& </span><span class="glossary sort" style="display:none">ampersand</span>: <p>A punctuation mark … <a href="#fnref:7" title="return to article" class="reversefootnote"> ↩</a></p>
</li>
</ol>
</div>
</body>
</html>