Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100755 116 lines (70 sloc) 4.514 kb
80c9821 markedown sed script 0.1 added to bin/
hdiedrich authored
1 markedoc 0.1
2 ============
3
4 **markedoc** helps you keep your project's README.md in sync with your
5 overview.edoc.
6
7 Status: alpha. Many things work. Some others do not. See [Status][].
8
9 markedoc translates [Markdown][] formatted texts into [Erlang][] [EDoc][]
10 format, for inclusion into [EDoc][] generated html docs.
11
12 The actual script file is in the bin folder: bin/markedoc.sed.
13
14 markedoc is but a brief [sed][] command file to convert markdown to edoc. Use it
15 to translate your project's README.md into a README.edoc to include in your
16 Erlang project's main overview.edoc file.
17
18 markedoc is part of **[edown][]**.
19
20 You contribution to make markedoc better is highly welcome.
21
22 Use
23 ---
24 At the command line:
25
26 $ sed -E -f markedoc.sed <markdown file> > <edoc file>
27
28 Requirements
29 ------------
30 * **[sed]**: is part of any Linux and Mac OSX distribution. You could get it for [Windows, too][winsed].
31
32 * **[Erlang/OTP][Erlang]**: see below.
33
34 Sample
35 ------
36
37 For your own projects you'd copy markedoc.sed in the right place and do something like:
38
39 $ echo "@doc " > doc/README.edoc
40 $ sed -E -f bin/markedoc.sed README.md >> doc/README.edoc
41 $ erl -noshell -run edoc_run application "'myapp'" '"."' '[{def,{vsn,""}}]'
42
43 And that's it. This could also be part of your Makefile. This way, the
44 README.edoc becomes part of your generated EDoc html pages, you would use a
45 @docfile tag in your overview.edoc file, like so:
46
47 @docfile "doc/README.edoc"
48
49 Status
50 ------
51
52 **Alpha**. You can do nice things but it likes to trip up EDoc, which is kind of easy to do.
53
54 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 the [live sample][sample], it's quite a lot that *does* work and some bits can be worked out. Please experiment and push your fixes.
55
56 **Thanks!**
57
58 Notes
59 -----
60
61 **[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.
62
63 [Erlang]: http://www.erlang.org/doc/
64
65 **[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.
66
67 [EDoc]: http://www.erlang.org/doc/apps/edoc/chapter.html
68
69 **[edown][]** is an EDoc extension for generating Github-flavored Markdown. It uses edoc-style commented Erlang sources to create markdown files from them.
70
71 [edown]: https://github.com/esl/edown
72
73 **[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).
74
75 [Markdown]: http://daringfireball.net/projects/markdown/
76
77 **[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.
78
79 [sed]: http://en.wikipedia.org/wiki/Sed
80
81 [winsed]: http://gnuwin32.sourceforge.net/packages/sed.htm
82
83 [sample]: https://github.com/Eonblast/Emysql/raw/master/README.md "This markdown file is translated alright by markedoc."
84
85
86 Caveats / Todos
87 ---------------
88 * Underlined ("==="/"---") headlines currently don't work, use the '#' variant instead
89 * **'[1]: ...'-style end note references need two spaces at the end of the line**
90 * add two new lines at end of your markdown file to avoid loosing the last line.
91 * Local anchor jumps fail
92
93
94 Not So Bad Todos
95 ----------------
96 * robust alternates not tested for some time
97 * space before javascript links should go
98 * protect ampersands
99
100
101 License
102 -------
103 This script is free software. It comes without any warranty.
104
105
106 Author
107 ------
108 H. Diedrich <hd2010@eonblast.com>
109
110
111 History
112 -------
113 01/31/11 - 0.1 - **first release**
114
115
Something went wrong with that request. Please try again.