mandown 0.0.7 → 0.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/Manifest.txt +3 -0
- data/README.txt +3 -81
- data/bin/bibdown +2 -520
- data/bin/mandown-sample +124 -0
- data/lib/bibdown_lib.rb +537 -0
- data/lib/mandown/version.rb +1 -1
- data/test/test_bibdown.rb +94 -0
- data/website/index.html +92 -32
- data/website/index.txt +72 -22
- data/website/template.rhtml +1 -1
- metadata +7 -2
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
#################### License ###################################################
|
|
2
|
+
#
|
|
3
|
+
# Copyright (c) 2008 Chris Rose
|
|
4
|
+
#
|
|
5
|
+
# This program is free software: you can redistribute it and/or modify
|
|
6
|
+
# it under the terms of the GNU General Public License as published by
|
|
7
|
+
# the Free Software Foundation, either version 3 of the License, or
|
|
8
|
+
# (at your option) any later version.
|
|
9
|
+
#
|
|
10
|
+
# This program is distributed in the hope that it will be useful,
|
|
11
|
+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
12
|
+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
13
|
+
# GNU General Public License for more details.
|
|
14
|
+
#
|
|
15
|
+
# You should have received a copy of the GNU General Public License
|
|
16
|
+
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
17
|
+
#
|
|
18
|
+
################################################################################
|
|
19
|
+
|
|
20
|
+
require File.dirname(__FILE__) + '/test_helper.rb'
|
|
21
|
+
require File.dirname(__FILE__) + '/../lib/bibdown_lib'
|
|
22
|
+
|
|
23
|
+
class TestBibdown < Test::Unit::TestCase
|
|
24
|
+
|
|
25
|
+
def setup
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
def test_get_keys_in_order
|
|
29
|
+
# Define a simple plaintext containing citations and an array of the
|
|
30
|
+
# expected keys.
|
|
31
|
+
pt = 'A B C cite:R1 D E cite:R2 F G cite:R1 H I cite:R3 J K cite:R2'
|
|
32
|
+
expected = ['R1', 'R2', 'R3']
|
|
33
|
+
assert_equal(expected, get_keys_in_order(pt))
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
def test_r_norm
|
|
37
|
+
assert_equal('Hello', r_norm('Hello'))
|
|
38
|
+
end
|
|
39
|
+
|
|
40
|
+
def test_r_ital
|
|
41
|
+
assert_equal('*Hello*', r_ital('Hello'))
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
def test_get_first_author_surname
|
|
45
|
+
bibentry = {'authors' => 'Jones, A. B. & Jeffries, C. D.'}
|
|
46
|
+
assert_equal('jones', get_first_author_surname(bibentry))
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
def test_make_initials
|
|
50
|
+
assert_equal(['A.', 'G.'], make_initials('Alexander Graham'))
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
def test_make_author_string
|
|
54
|
+
authors = 'Jones, Anthony Bob & Jeffries, Chris David & Jays, Anne May'
|
|
55
|
+
|
|
56
|
+
expected__initials_surname_last =
|
|
57
|
+
'A. B. Jones, C. D. Jeffries and A. M. Jays'
|
|
58
|
+
assert_equal(expected__initials_surname_last,
|
|
59
|
+
make_author_string(authors, use_initials=true, surname_first=false))
|
|
60
|
+
|
|
61
|
+
expected__initials_surname_first =
|
|
62
|
+
'Jones, A. B., Jeffries, C. D. and Jays, A. M.'
|
|
63
|
+
assert_equal(expected__initials_surname_first,
|
|
64
|
+
make_author_string(authors, use_initials=true, surname_first=true))
|
|
65
|
+
|
|
66
|
+
expected__full_surname_last =
|
|
67
|
+
'Anthony Bob Jones, Chris David Jeffries and Anne May Jays'
|
|
68
|
+
assert_equal(expected__full_surname_last,
|
|
69
|
+
make_author_string(authors, use_initials=false, surname_first=false))
|
|
70
|
+
|
|
71
|
+
expected__full_surname_first =
|
|
72
|
+
'Jones, Anthony Bob, Jeffries, Chris David and Jays, Anne May'
|
|
73
|
+
assert_equal(expected__full_surname_first,
|
|
74
|
+
make_author_string(authors, use_initials=false, surname_first=true))
|
|
75
|
+
end
|
|
76
|
+
|
|
77
|
+
def test_check_missing_citations
|
|
78
|
+
none_missing = 'No citations are missing.'
|
|
79
|
+
assert_equal([], check_missing_citations(none_missing))
|
|
80
|
+
|
|
81
|
+
some_missing = 'There are cite:Missing1 two missing citations cite:Missing2'
|
|
82
|
+
assert_equal(
|
|
83
|
+
['The following reference key was undefined: Missing1',
|
|
84
|
+
'The following reference key was undefined: Missing2'],
|
|
85
|
+
check_missing_citations(some_missing))
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
def test_has_key?
|
|
89
|
+
bib_entries = [{:key => 'key1'}]
|
|
90
|
+
assert_equal(true, has_key?('key1', bib_entries))
|
|
91
|
+
assert_equal(false, has_key?('missing_key', bib_entries))
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
end
|
data/website/index.html
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
<link rel="stylesheet" href="stylesheets/screen.css" type="text/css" media="screen" />
|
|
6
6
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
7
7
|
<title>
|
|
8
|
-
|
|
8
|
+
→ ‘mandown’
|
|
9
9
|
</title>
|
|
10
10
|
<script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
|
|
11
11
|
<style>
|
|
@@ -30,75 +30,124 @@
|
|
|
30
30
|
<body>
|
|
31
31
|
<div id="main">
|
|
32
32
|
|
|
33
|
-
<h1
|
|
33
|
+
<h1>→ ‘mandown’</h1>
|
|
34
34
|
<div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/mandown"; return false'>
|
|
35
35
|
<p>Get Version</p>
|
|
36
|
-
<a href="http://rubyforge.org/projects/mandown" class="numbers">0.0.
|
|
36
|
+
<a href="http://rubyforge.org/projects/mandown" class="numbers">0.0.8</a>
|
|
37
37
|
</div>
|
|
38
|
-
<h1
|
|
38
|
+
<h1>Academic writing extensions to Markdown</h1>
|
|
39
39
|
|
|
40
40
|
|
|
41
41
|
<h2>What</h2>
|
|
42
42
|
|
|
43
43
|
|
|
44
|
-
<p>Mandown provides simple extensions to the <a href="http://daringfireball.net/projects/markdown/">Markdown</a>
|
|
44
|
+
<p>Mandown provides simple extensions to the <a href="http://daringfireball.net/projects/markdown/">Markdown</a> syntax that are useful for academic writing.</p>
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
<p>Writing a paper using Mandown is simple: write your paper using standard Markdown syntax and the Mandown extensions where necessary, then process your file using the Mandown tools. These will generate a standard Markdown file containing your citations, bibliography etc. Then process the resulting file using a suitable Markdown processor (I recommend using Pandoc, which will generate <span class="caps">RTF</span> files that can be opened using Microsoft Word).</p>
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
<p>‘Mandown’ is a portmanteau of ‘Markdown’ and ‘manuscript’ which I found appropriately amusing (“Man down!!”).</p>
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
<h2>Why?</h2>
|
|
45
54
|
|
|
46
55
|
|
|
47
56
|
<p>Academics typically write papers using either LaTeX or Microsoft Word. Word is often favoured by the less technically inclined (or those who are simply ignorant of the existence of alternatives). LaTeX is used for some combination of the following reasons: it’s free software; it can produce typographically excellent output; LaTeX documents are plain text files which can be edited using powerful text editors (vi, Emacs, TextMate etc.). Those who would otherwise choose LaTeX are often forced to use Word by their co-authors or the publishers of their work, and would like a way to maintain the benefits of their LaTeX environment while being able to produce Word documents. Mandown provides tools to allow this.</p>
|
|
48
57
|
|
|
49
58
|
|
|
50
|
-
<p>
|
|
59
|
+
<p>Mandown is not attempting to be a document preparation system like LaTeX; if you can use LaTeX you probably should—-it’s far more powerful than Mandown. For example, Mandown will have no support for controlling page layout or inserting and controlling graphics (though it will support the concept of figures).</p>
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
<p>Mandown is implemented as a set of command line tools that can be chained together into a pipeline. At this stage of development, only one component of Mandown has been implemented: bibdown allows one to maintain a bibliography in <span class="caps">YAML</span> format and cite papers from it; bibdown replaces citation keys with citation numbers and renders the bibliography using appropriate Markdown syntax. In future, further extensions to Markdown will be developed and implemented (e.g. figdown will support figures, another tool will support sectioning, labels and referring, etc.). Mandown is distributed as a gem for ease of installation (see the next section).</p>
|
|
51
63
|
|
|
52
64
|
|
|
53
65
|
<h2>Installing</h2>
|
|
54
66
|
|
|
55
67
|
|
|
56
|
-
<p>
|
|
68
|
+
<p>Mandown is distributed as a Ruby gem (so you’ll need Ruby and RubyGems installed already). To install, type something like:</p>
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
<pre>sudo gem install mandown</pre>
|
|
72
|
+
|
|
73
|
+
<p>If you are confused already, read the <a href="http://rubygems.org/read/chapter/1#page1">Really Quick Start guide</a> from the RubyGems user guide and note that you may or may not need the <a href="http://en.wikipedia.org/wiki/Sudo">sudo</a> command (it’s necessary on Mac <span class="caps">OS X</span>).</p>
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
<p>This will add the Mandown executables (executable Ruby scripts) to your $PATH, which include the following: bibdown.</p>
|
|
57
77
|
|
|
58
78
|
|
|
59
79
|
<p>You will also need to install a suitable Markdown processor; I recommend <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> which can convert Markdown to multiple output formats, including <span class="caps">RTF</span> which can be opened using Microsoft Word.</p>
|
|
60
80
|
|
|
61
81
|
|
|
62
|
-
<h2>
|
|
82
|
+
<h2>Usage</h2>
|
|
63
83
|
|
|
64
84
|
|
|
65
|
-
<p>
|
|
66
|
-
|
|
85
|
+
<p>First you need to write a manuscript using a combination of the Markdown and
|
|
86
|
+
Mandown syntaxes, but to get you started Mandown includes a sample Mandown document (see the example, below). Markdown and Mandown are very simple and all you need is a plain text editor.</p>
|
|
67
87
|
|
|
68
88
|
|
|
69
|
-
<
|
|
70
|
-
|
|
89
|
+
<p>To
|
|
90
|
+
learn Markdown, see the <a href="http://daringfireball.net/projects/markdown/syntax">Markdown
|
|
91
|
+
documentation</a> (note that
|
|
92
|
+
<a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> is the recommended Markdown processor
|
|
93
|
+
for academic applications).</p>
|
|
71
94
|
|
|
72
|
-
<p>This assumes that the Mandown tool directory and the Pandoc program are on your system’s $PATH.</p>
|
|
73
95
|
|
|
96
|
+
<p>Each Mandown tool adds one or two simple extensions to Markdown; for example <code>bibdown</code> adds the <code>cite:</code> syntax to cite references and allows you to specify your bibliography in <span class="caps">YAML</span> format.</p>
|
|
74
97
|
|
|
75
|
-
<p>If you are unfamiliar with the <span class="caps">UNIX</span> command line, here’s what’s going on:</p>
|
|
76
98
|
|
|
99
|
+
<p>Each tool provides its own documentation via a <code>--help</code> option, for example type</p>
|
|
77
100
|
|
|
78
|
-
<ol>
|
|
79
|
-
<li>The cat program reads the sample-manuscript.txt and sends it to the standard output device (usually the terminal).</li>
|
|
80
|
-
<li>The contents of sample-manuscript.txt are intercepted by a ‘pipe’ (denoted by the ’|’ character) which sends them to the bibdown program.</li>
|
|
81
|
-
<li>The bibdown program processes the bibliography and sends the resulting manuscript to the standard output device.</li>
|
|
82
|
-
<li>The processed manuscript is intercepted by the ‘>’ operator, which causes standard output to be the file called sample-out.txt. We now have a manuscript with proper citations and a bibliography in Markdown format.</li>
|
|
83
|
-
<li>We then run Pandoc on the result to create an <span class="caps">RTF</span> file.</li>
|
|
84
|
-
</ol>
|
|
85
101
|
|
|
102
|
+
<pre>bibdown --help</pre>
|
|
86
103
|
|
|
87
|
-
<p>
|
|
104
|
+
<p>to learn how to use the bibdown tool and see its syntax.</p>
|
|
88
105
|
|
|
89
106
|
|
|
90
|
-
<
|
|
91
|
-
<pre>pandoc ...</pre>
|
|
107
|
+
<p>Because each Mandown tool does one thing and adds only one or two syntax extensions, you can easily learn just the ones you need and ignore the rest (or perhaps contribute your own).</p>
|
|
92
108
|
|
|
93
|
-
|
|
109
|
+
|
|
110
|
+
<h3>Example</h3>
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
<p>Let’s read an example Mandown manuscript using the <code>less</code> pager:</p>
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
<pre>mandown-sample | less</pre>
|
|
117
|
+
|
|
118
|
+
<p>The <code>mandown-sample</code> program simply outputs the sample manuscript.</p>
|
|
94
119
|
|
|
95
120
|
|
|
96
|
-
<p>
|
|
121
|
+
<p>(Note how papers are cited using the <code>cite:</code> command and have a quick look at the <span class="caps">YAML</span>-format bibliography towards the end of the file.)</p>
|
|
97
122
|
|
|
98
123
|
|
|
99
|
-
<
|
|
100
|
-
|
|
101
|
-
|
|
124
|
+
<p>We want to process this document using Mandown (and then Pandoc), so first save the sample to a file:</p>
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
<pre>mandown-sample > sample-manuscript.txt</pre>
|
|
128
|
+
|
|
129
|
+
<p>Now let’s process this sample manuscript using <code>bibdown</code>:</p>
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
<pre>cat sample-manuscript.txt | bibdown > sample-markdown.txt</pre>
|
|
133
|
+
|
|
134
|
+
<p>This uses the <code>cat</code> program to send the <code>sample-manuscript.txt</code> file to <code>bibdown</code> using a pipe (via the <code>|</code> character), and then saves the result to a file called <code>sample-markdown.txt</code> (via the <code>></code> character):</p>
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
<code>bibdown</code> interprets the bibliographic aspects of the Mandown syntax and renders them using Markdown. The result can then be processed using a Markdown processor such as Pandoc:
|
|
138
|
+
|
|
139
|
+
<pre>pandoc --smart -s sample-markdown.txt -o manuscript.rtf</pre>
|
|
140
|
+
|
|
141
|
+
<p>You could now open the <code>manuscript.rtf</code> file using an application like Microsoft Word or OpenOffice.org.</p>
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
<p>The Mandown tools are designed to be chained together into a pipeline, so for example you might do:</p>
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
<pre>cat my-manu.txt | bibdown | eqndown | secdown > my-manu-out.txt</pre>
|
|
148
|
+
<pre>pandoc ...</pre>
|
|
149
|
+
|
|
150
|
+
<p>Note: only bibdown is currently implemented.</p>
|
|
102
151
|
|
|
103
152
|
|
|
104
153
|
<h2>Help, gotchas and <span class="caps">FAQ</span></h2>
|
|
@@ -125,12 +174,17 @@ in a pipeline. Here is an example of how to process a file containing a bibliogr
|
|
|
125
174
|
<h3>Q4: The tools don’t run.</h3>
|
|
126
175
|
|
|
127
176
|
|
|
128
|
-
<p>Mandown requires Ruby version 1.8.6 or higher
|
|
177
|
+
<p>Mandown requires Ruby version 1.8.6 or higher, and the ruby interpreter program should probably be on your $PATH. If you installed Mandown from the gem, then the tools should be on your system’s $PATH and you should be able to run them. To verify that the tools are on your system’s $PATH, type</p>
|
|
129
178
|
|
|
130
179
|
|
|
131
180
|
<pre>which bibdown</pre>
|
|
132
181
|
|
|
133
|
-
<p>If a path is reported to the bibdown program, then it is on your $PATH
|
|
182
|
+
<p>If a path is reported to the bibdown program, then it is on your $PATH and should be executable; try running</p>
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
<pre>bibdown --help</pre>
|
|
186
|
+
|
|
187
|
+
<p>Otherwise please get in touch with me.</p>
|
|
134
188
|
|
|
135
189
|
|
|
136
190
|
<h2>Please help</h2>
|
|
@@ -142,12 +196,18 @@ in a pipeline. Here is an example of how to process a file containing a bibliogr
|
|
|
142
196
|
<p>The trunk repository is <code>svn://rubyforge.org/var/svn/mandown/trunk</code> for anonymous access.</p>
|
|
143
197
|
|
|
144
198
|
|
|
199
|
+
<h2>Acknowledgements</h2>
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
<p>Mandown would not be possible without the excellent tools provided by the Ruby community. In particular, the Ruby standard library <span class="caps">YAML</span> parser, Nic Williams’ <a href="http://newgem.rubyforge.org/">newgem</a> and the <a href="http://rubyforge.org/">Ruby Forge</a> project have made Mandown much easier to develop and distribute. Thanks!</p>
|
|
203
|
+
|
|
204
|
+
|
|
145
205
|
<h2>License</h2>
|
|
146
206
|
|
|
147
207
|
|
|
148
208
|
<p>This code is distributed according to the terms of the <span class="caps">GNU</span> General Public License; see the file <code>COPYING</code> for full details.</p>
|
|
149
209
|
<p class="coda">
|
|
150
|
-
<a href="
|
|
210
|
+
<a href="mandown@microserf.org.uk">Chris Rose</a>, 15th January 2008<br>
|
|
151
211
|
Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
|
|
152
212
|
</p>
|
|
153
213
|
</div>
|
data/website/index.txt
CHANGED
|
@@ -1,41 +1,84 @@
|
|
|
1
|
-
h1. Academic writing extensions to Markdown
|
|
2
|
-
|
|
3
1
|
h1. → 'mandown'
|
|
4
2
|
|
|
3
|
+
h1. Academic writing extensions to Markdown
|
|
5
4
|
|
|
6
5
|
h2. What
|
|
7
6
|
|
|
8
|
-
Mandown provides simple extensions to the "Markdown":http://daringfireball.net/projects/markdown/
|
|
7
|
+
Mandown provides simple extensions to the "Markdown":http://daringfireball.net/projects/markdown/ syntax that are useful for academic writing.
|
|
8
|
+
|
|
9
|
+
Writing a paper using Mandown is simple: write your paper using standard Markdown syntax and the Mandown extensions where necessary, then process your file using the Mandown tools. These will generate a standard Markdown file containing your citations, bibliography etc. Then process the resulting file using a suitable Markdown processor (I recommend using Pandoc, which will generate RTF files that can be opened using Microsoft Word).
|
|
10
|
+
|
|
11
|
+
'Mandown' is a portmanteau of 'Markdown' and 'manuscript' which I found appropriately amusing ("Man down!!").
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
h2. Why?
|
|
9
15
|
|
|
10
16
|
Academics typically write papers using either LaTeX or Microsoft Word. Word is often favoured by the less technically inclined (or those who are simply ignorant of the existence of alternatives). LaTeX is used for some combination of the following reasons: it's free software; it can produce typographically excellent output; LaTeX documents are plain text files which can be edited using powerful text editors (vi, Emacs, TextMate etc.). Those who would otherwise choose LaTeX are often forced to use Word by their co-authors or the publishers of their work, and would like a way to maintain the benefits of their LaTeX environment while being able to produce Word documents. Mandown provides tools to allow this.
|
|
11
17
|
|
|
12
|
-
|
|
18
|
+
Mandown is not attempting to be a document preparation system like LaTeX; if you can use LaTeX you probably should---it's far more powerful than Mandown. For example, Mandown will have no support for controlling page layout or inserting and controlling graphics (though it will support the concept of figures).
|
|
19
|
+
|
|
20
|
+
Mandown is implemented as a set of command line tools that can be chained together into a pipeline. At this stage of development, only one component of Mandown has been implemented: bibdown allows one to maintain a bibliography in YAML format and cite papers from it; bibdown replaces citation keys with citation numbers and renders the bibliography using appropriate Markdown syntax. In future, further extensions to Markdown will be developed and implemented (e.g. figdown will support figures, another tool will support sectioning, labels and referring, etc.). Mandown is distributed as a gem for ease of installation (see the next section).
|
|
13
21
|
|
|
14
22
|
|
|
15
23
|
h2. Installing
|
|
16
24
|
|
|
17
|
-
|
|
25
|
+
Mandown is distributed as a Ruby gem (so you'll need Ruby and RubyGems installed already). To install, type something like:
|
|
26
|
+
|
|
27
|
+
<pre>sudo gem install mandown</pre>
|
|
28
|
+
|
|
29
|
+
If you are confused already, read the "Really Quick Start guide":http://rubygems.org/read/chapter/1#page1 from the RubyGems user guide and note that you may or may not need the "sudo":http://en.wikipedia.org/wiki/Sudo command (it's necessary on Mac OS X).
|
|
30
|
+
|
|
31
|
+
This will add the Mandown executables (executable Ruby scripts) to your $PATH, which include the following: bibdown.
|
|
18
32
|
|
|
19
33
|
You will also need to install a suitable Markdown processor; I recommend "Pandoc":http://johnmacfarlane.net/pandoc/ which can convert Markdown to multiple output formats, including RTF which can be opened using Microsoft Word.
|
|
20
34
|
|
|
21
35
|
|
|
22
|
-
h2.
|
|
36
|
+
h2. Usage
|
|
37
|
+
|
|
38
|
+
First you need to write a manuscript using a combination of the Markdown and
|
|
39
|
+
Mandown syntaxes, but to get you started Mandown includes a sample Mandown document (see the example, below). Markdown and Mandown are very simple and all you need is a plain text editor.
|
|
40
|
+
|
|
41
|
+
To
|
|
42
|
+
learn Markdown, see the "Markdown
|
|
43
|
+
documentation":http://daringfireball.net/projects/markdown/syntax (note that
|
|
44
|
+
"Pandoc":http://johnmacfarlane.net/pandoc/ is the recommended Markdown processor
|
|
45
|
+
for academic applications).
|
|
46
|
+
|
|
47
|
+
Each Mandown tool adds one or two simple extensions to Markdown; for example <code>bibdown</code> adds the <code>cite:</code> syntax to cite references and allows you to specify your bibliography in YAML format.
|
|
48
|
+
|
|
49
|
+
Each tool provides its own documentation via a <code>--help</code> option, for example type
|
|
50
|
+
|
|
51
|
+
<pre>bibdown --help</pre>
|
|
52
|
+
|
|
53
|
+
to learn how to use the bibdown tool and see its syntax.
|
|
23
54
|
|
|
24
|
-
|
|
25
|
-
in a pipeline. Here is an example of how to process a file containing a bibliography with bibdown and convert the resulting file into an RTF file using Pandoc (the resulting RTF file could then be opened using Word, for example; ignore the initial > characters, which denote the start of a new command):
|
|
55
|
+
Because each Mandown tool does one thing and adds only one or two syntax extensions, you can easily learn just the ones you need and ignore the rest (or perhaps contribute your own).
|
|
26
56
|
|
|
27
|
-
|
|
28
|
-
<pre>pandoc --smart -s sample-out.txt -o sample.rtf</pre>
|
|
57
|
+
h3. Example
|
|
29
58
|
|
|
30
|
-
|
|
59
|
+
Let's read an example Mandown manuscript using the <code>less</code> pager:
|
|
31
60
|
|
|
32
|
-
|
|
61
|
+
<pre>mandown-sample | less</pre>
|
|
33
62
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
63
|
+
The <code>mandown-sample</code> program simply outputs the sample manuscript.
|
|
64
|
+
|
|
65
|
+
(Note how papers are cited using the <code>cite:</code> command and have a quick look at the YAML-format bibliography towards the end of the file.)
|
|
66
|
+
|
|
67
|
+
We want to process this document using Mandown (and then Pandoc), so first save the sample to a file:
|
|
68
|
+
|
|
69
|
+
<pre>mandown-sample > sample-manuscript.txt</pre>
|
|
70
|
+
|
|
71
|
+
Now let's process this sample manuscript using <code>bibdown</code>:
|
|
72
|
+
|
|
73
|
+
<pre>cat sample-manuscript.txt | bibdown > sample-markdown.txt</pre>
|
|
74
|
+
|
|
75
|
+
This uses the <code>cat</code> program to send the <code>sample-manuscript.txt</code> file to <code>bibdown</code> using a pipe (via the <code>|</code> character), and then saves the result to a file called <code>sample-markdown.txt</code> (via the <code>></code> character):
|
|
76
|
+
|
|
77
|
+
<code>bibdown</code> interprets the bibliographic aspects of the Mandown syntax and renders them using Markdown. The result can then be processed using a Markdown processor such as Pandoc:
|
|
78
|
+
|
|
79
|
+
<pre>pandoc --smart -s sample-markdown.txt -o manuscript.rtf</pre>
|
|
80
|
+
|
|
81
|
+
You could now open the <code>manuscript.rtf</code> file using an application like Microsoft Word or OpenOffice.org.
|
|
39
82
|
|
|
40
83
|
The Mandown tools are designed to be chained together into a pipeline, so for example you might do:
|
|
41
84
|
|
|
@@ -44,9 +87,6 @@ The Mandown tools are designed to be chained together into a pipeline, so for ex
|
|
|
44
87
|
|
|
45
88
|
Note: only bibdown is currently implemented.
|
|
46
89
|
|
|
47
|
-
Once Mandown is installed, you can find out how to use the various tools using the --help option, e.g.
|
|
48
|
-
|
|
49
|
-
* <pre>bibdown --help</pre>
|
|
50
90
|
|
|
51
91
|
|
|
52
92
|
h2. Help, gotchas and FAQ
|
|
@@ -65,11 +105,15 @@ Surround the title in quotes; these will be ignored, but fix the problem. I thin
|
|
|
65
105
|
|
|
66
106
|
h3. Q4: The tools don't run.
|
|
67
107
|
|
|
68
|
-
Mandown requires Ruby version 1.8.6 or higher
|
|
108
|
+
Mandown requires Ruby version 1.8.6 or higher, and the ruby interpreter program should probably be on your $PATH. If you installed Mandown from the gem, then the tools should be on your system's $PATH and you should be able to run them. To verify that the tools are on your system's $PATH, type
|
|
69
109
|
|
|
70
110
|
<pre>which bibdown</pre>
|
|
71
111
|
|
|
72
|
-
If a path is reported to the bibdown program, then it is on your $PATH
|
|
112
|
+
If a path is reported to the bibdown program, then it is on your $PATH and should be executable; try running
|
|
113
|
+
|
|
114
|
+
<pre>bibdown --help</pre>
|
|
115
|
+
|
|
116
|
+
Otherwise please get in touch with me.
|
|
73
117
|
|
|
74
118
|
|
|
75
119
|
h2. Please help
|
|
@@ -78,6 +122,12 @@ If you would like to contribute to Mandown, please email "Chris Rose":mailto:man
|
|
|
78
122
|
|
|
79
123
|
The trunk repository is <code>svn://rubyforge.org/var/svn/mandown/trunk</code> for anonymous access.
|
|
80
124
|
|
|
125
|
+
|
|
126
|
+
h2. Acknowledgements
|
|
127
|
+
|
|
128
|
+
Mandown would not be possible without the excellent tools provided by the Ruby community. In particular, the Ruby standard library YAML parser, Nic Williams' "newgem":http://newgem.rubyforge.org/ and the "Ruby Forge":http://rubyforge.org/ project have made Mandown much easier to develop and distribute. Thanks!
|
|
129
|
+
|
|
130
|
+
|
|
81
131
|
h2. License
|
|
82
132
|
|
|
83
133
|
This code is distributed according to the terms of the GNU General Public License; see the file <code>COPYING</code> for full details.
|
data/website/template.rhtml
CHANGED
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
</div>
|
|
38
38
|
<%= body %>
|
|
39
39
|
<p class="coda">
|
|
40
|
-
<a href="
|
|
40
|
+
<a href="mandown@microserf.org.uk">Chris Rose</a>, <%= modified.pretty %><br>
|
|
41
41
|
Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
|
|
42
42
|
</p>
|
|
43
43
|
</div>
|
metadata
CHANGED
|
@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
|
|
|
3
3
|
specification_version: 1
|
|
4
4
|
name: mandown
|
|
5
5
|
version: !ruby/object:Gem::Version
|
|
6
|
-
version: 0.0.
|
|
7
|
-
date: 2008-01-
|
|
6
|
+
version: 0.0.8
|
|
7
|
+
date: 2008-01-15 00:00:00 +00:00
|
|
8
8
|
summary: Provides simple extensions to Markdown that are useful for academic writing
|
|
9
9
|
require_paths:
|
|
10
10
|
- lib
|
|
@@ -35,8 +35,10 @@ files:
|
|
|
35
35
|
- README.txt
|
|
36
36
|
- Rakefile
|
|
37
37
|
- bin/bibdown
|
|
38
|
+
- bin/mandown-sample
|
|
38
39
|
- config/hoe.rb
|
|
39
40
|
- config/requirements.rb
|
|
41
|
+
- lib/bibdown_lib.rb
|
|
40
42
|
- lib/mandown.rb
|
|
41
43
|
- lib/mandown/version.rb
|
|
42
44
|
- log/debug.log
|
|
@@ -49,12 +51,14 @@ files:
|
|
|
49
51
|
- tasks/website.rake
|
|
50
52
|
- test/test_helper.rb
|
|
51
53
|
- test/test_mandown.rb
|
|
54
|
+
- test/test_bibdown.rb
|
|
52
55
|
- website/index.html
|
|
53
56
|
- website/index.txt
|
|
54
57
|
- website/javascripts/rounded_corners_lite.inc.js
|
|
55
58
|
- website/stylesheets/screen.css
|
|
56
59
|
- website/template.rhtml
|
|
57
60
|
test_files:
|
|
61
|
+
- test/test_bibdown.rb
|
|
58
62
|
- test/test_helper.rb
|
|
59
63
|
- test/test_mandown.rb
|
|
60
64
|
rdoc_options:
|
|
@@ -67,6 +71,7 @@ extra_rdoc_files:
|
|
|
67
71
|
- website/index.txt
|
|
68
72
|
executables:
|
|
69
73
|
- bibdown
|
|
74
|
+
- mandown-sample
|
|
70
75
|
extensions: []
|
|
71
76
|
|
|
72
77
|
requirements: []
|