Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 197 lines (126 sloc) 9.365 kB
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
1 edown markedoc 0.3.2
2 ====================
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
3
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
4 **markedoc helps you keep your project's README.md in sync with your overview.edoc.**
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
5
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
6 This is the opposite direction from what **edown** otherwise does.
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
7
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
8 markedoc translates [Markdown][] formatted texts into [Erlang][] [EDoc][] format, for inclusion into [EDoc][] generated html docs. It is for use on Linux, FreeBSD and Mac OS X and any system that you can install **[sed][Requirements]** on.
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
9
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
10 Status: [pre-beta][Status]. Quite stable and usable. See [Status][].
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
11
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
12 markedoc is a mere [sed][] command file to convert markdown to edoc. It is part of the **[edown][]** project. The actual script file is in the bin folder: bin/markedoc.sed. Your contribution to make markedoc stable is highly [welcome][issues].
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
13
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
14 [issues]: https://github.com/hdiedrich/markedoc/issues "Issue tracker"
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
15
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
16 Use <a name=Use></a>
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
17 ---
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
18 At the command line for
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
19
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
20 **FreeBSD, Mac OS X**
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
21 $ sed -E -f markedoc.sed <markdown file> > <edoc file>
22
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
23 **Linux**
24 $ sed -r -f markedoc.sed <markdown file> > <edoc file>
25
26 Usage for Linux and FreeBSD and Mac OS X is completely the same, except for the -r instead of the -E parameter. Both mean the same but happen to have a different name. In the examples below, replace -E with -r where necessary.
27
28 Requirements <a name=Requirements></a>
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
29 ------------
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
30 * **[sed][]**: is part of any Linux, FreeBSD and Mac OSX distribution, also see [Notes][].
31
32 * **[Erlang/OTP][Erlang]**, see [Notes][].
33
34 Test <a name=Test></a>
35 ----
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
36
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
37 **FreeBSD, Mac OS X**
38 $ samples/markedoc/test-bsd.sh
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
39
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
40 **Linux**
41 $ samples/markedoc/test-linux.sh
42
43 Then check html files as listed in the output.
44
45 Sample <a name=Sample></a>
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
46 ------
47
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
48 From edown project root, try out:
49
50 **FreeBSD, Mac OS X**
51 $ sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE1.md > samples/markedoc/doc/SAMPLE.edoc
52 $ erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[]'
53
54 **Linux**
55 $ sed -r -f bin/markedoc.sed samples/markedoc/SAMPLE1.md > samples/markedoc/doc/SAMPLE.edoc
56 $ erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[]'
57
58 This creates a SAMPLE.edoc file from SAMPLE1.md, which is then included in the EDoc generation. Point your browser at
59
60 samples/markedoc/doc/overview-summary.html
61
62 to see the result. For something only vaguely related but pretty, try:
63
64 $ erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
65
66 This illustrates the motivation for the markedoc as it is now: to have all code lines in one block in order to be able to address them as one united div from css.
67
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
68 For your own projects you'd copy markedoc.sed in the right place and do something like:
69
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
70 **FreeBSD, Mac OS X**
71 $ sed -E -f bin/markedoc.sed README.md > doc/README.edoc
72 $ erl -noshell -run edoc_run application "'myapp'" '"."' '[]'
73
74 **Linux**
75 $ sed -r -f bin/markedoc.sed README.md > doc/README.edoc
76 $ erl -noshell -run edoc_run application "'myapp'" '"."' '[]'
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
77
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
78 And that's it. This could also be part of your Makefile. For the intermediary README.edoc to automatically become part of your generated EDoc html pages, you would use a @docfile tag in your overview.edoc file, like so:
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
79
80 @docfile "doc/README.edoc"
81
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
82 By running sed, then edoc, this makes the README.edoc part of the overview page. You could also make the README.md straight into an overview.edoc but the way it is allows allows to embedd it into additional context information that should be useful for a proper html doc.
83
84 Accordingly, the sample stub overview.edoc used for the samples here, looks like this:
85
86 @author You
87 @title a markedoc sample doc
88 @version 0.2
89 @docfile "samples/markedoc/doc/SAMPLE.edoc"
90
91 Tricks <a name=Tricks></a>
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
92 ------
93
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
94 Markdown cannot jump to headlines as anchors, while edoc makes headlines into anchors automatically. To allow for meaningful anchor jumps like [sample][] within a page, the following workaround makes sense. It is 'weeded out' by markedoc so that it does not trip up edoc. But it makes for local jumps in
95 both worlds:
96
97 ## Examples <a name=example></a>
98
99 ...
100
101 [sample]: #sample
102
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
103
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
104 This makes a tag `[example][]' into a direct jump to the headline 'Example', in both markdown and edoc.
105 Markdown actually uses the `[sample]: #sample' reference. EDoc, however, automatically inserts an anchor for 'Example' being a headline, and of the same name. (The links are not case sensitive.)
106 If you get the reference wrong or forget to make it, the link tag will be displayed in the open, as actual `[example][]'.
107
108
109 Status <a name=Status></a>
110 ------
111
112 **Pre-Beta**. Quite usable, but still likes to trip up EDoc now and then, which is kind of easy to do.
113
114 There are many ways to create formats that will make the EDoc generator tilt and unfortunately, the errors it throws are sometimes not quite so illuminating to the reader. But why not try an incremental approach and see what works. As you can see from this [source sample][sample], which works alright, it's quite a lot that *does* work and the murky bits can usally be worked out fast. Sometimes an additional line helps, some spaces at the end of a line, general intuitive stuff. Please experiment and push your fixes to me.
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
115
116 **Thanks!**
117
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
118 Notes <a name=Notes></a>
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
119 -----
120
121 **[Erlang][]** is a programming language used to build massively scalable soft real-time systems with requirements on high availability. Some of its uses are in telecom, banking, e-commerce, computer telephony and instant messaging. Erlang's runtime system has built-in support for concurrency, distribution and fault tolerance. Erlang comes bundled with the Open Telecom Platform, OTP.
122
123 [Erlang]: http://www.erlang.org/doc/
124
125 **[EDoc][]** is the Erlang program documentation generator. Inspired by the Javadoc tool for the Java programming language, EDoc is adapted to the conventions of the Erlang world, and has several features not found in Javadoc. Edoc is part of the Erlang/OTP distribution.
126
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
127 [EDoc]: http://www.erlang.org/doc/apps/edoc/chapter.html
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
128
129 **[edown][]** is an EDoc extension for generating Github-flavored Markdown. It uses edoc-style commented Erlang sources to create markdown files from them.
130
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
131 [edown]: https://github.com/esl/edown
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
132
133 **[Markdown][]** is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
134
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
135 [Markdown]: http://daringfireball.net/projects/markdown/
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
136
137 **[sed][]** ('stream editor') is a Unix utility that parses text files and implements a programming language which can apply textual transformations to such files. It reads input files line by line (sequentially), applying the operation which has been specified via the command line (or a sed script), and then outputs the line. It is available today for most operating systems. There seems to be [one for Windows][winsed], too.
138
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
139 [sed]: http://en.wikipedia.org/wiki/Sed
140 [winsed]: http://gnuwin32.sourceforge.net/packages/sed.htm
141 [sample]: https://github.com/Eonblast/Emysql/raw/master/README.md "This markdown file is translated alright by markedoc."
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
142
143
144 License
145 -------
146 This script is free software. It comes without any warranty.
147
148 Author
149 ------
150 H. Diedrich <hd2010@eonblast.com>
151
152 History
153 -------
154
2d7d914 @Eonblast integrated bin/markedoc 0.3.2 incl. samples and tests
Eonblast authored
155 02/18/11 - 0.3.2 - **edown**
156
157 * integrated into edown
158
159 02/05/11 - 0.3.1 - **more polish** - Linux, FreeBSD, Mac OS X
160
161 * added weeding out of markdown anchor references (an md workaround)
162 * added protection for & (but edoc still only accepts number codes)
163 * fixed trip up by trailing spaces in underline headline format
164 * checked commented out alternate code for code blocks and references.
165
166 02/03/11 - 0.3 - **rough edges polished** - Linux, FreeBSD, Mac OS X
167
168 * added doc for Linux use
169 * added support for multi-line '[..]: ... "..."' references
170 * added footnote signs and sepcial chars:
171 * dagger, double dagger: (+), (++), stars: (\*), (\*\*), (\*\*\*)
172 * superscript 1, 2, 3: (\*1), (\*2), (\*3), copyright (C), (R), (TM),
173 * guillemots <<, >> and middle dot ::
174 * added test batches etc/test-bsd.sh and etc/test-linux.sh
175 * added css sample in samples/markedoc/what-you-could-see/
176 * added classes for ``< li >'' list item tags for '[..]:...'-references
177 * fixed italic and bold merker interference bullet points
178 * eliminated [..]: part of '[..]:...'-references, flipping "..." to lead
179 * dev: sample creation batch make_samples.sh added
180
181 02/02/11 - 0.2 - **basics complete** - FreeBSD / Mac OS X
182
183 * added support for === and --- headline format
184 * fixed cutting off of last lines
185 * fixed page-local anchor jumps
186 * fixed space in javascript links
187 * eliminated end-space requirement at end of '[..]:...'-style references.
188 * eliminated need for echoing '@doc' first into edoc output file
189 * added javascript title tag setting for '[..]:...'-style references.
190
191 01/31/11 - 0.1 - **first release:** FreeBSD / Mac OS X
192
193 [Requirements]: #Requirements
194 [Status]: #Status
195 [Notes]: #Notes
196 [Test]: #Test
Something went wrong with that request. Please try again.