Skip to content
Browse files

integrated bin/markedoc 0.3.2 incl. samples and tests

  • Loading branch information...
1 parent 80c9821 commit 2d7d9147bfd875ab260f9f3f7ba2e20d40eafa50 @Eonblast Eonblast committed Feb 18, 2011
View
17 README.md
@@ -38,4 +38,19 @@ writes the files necessary.
For now, EDown focuses on producing reasonable Markdown, rather
than complying fully with the plugin framework. That is, the
edown_doclet module will not go out of its way to function together
-with any other layout module than edown_layout, and vice versa.
+with any other layout module than edown_layout, and vice versa.
+
+markedoc
+========
+
+The sed script bin/markedoc works in the opposite direction and converts your README.md to an EDoc file.
+
+See bin/MARKEDOC-README.md.
+
+**FreeBSD, Mac OS X**
+ $ sed -E -f markedoc.sed <markdown file> > <edoc file>
+
+**Linux**
+ $ sed -r -f markedoc.sed <markdown file> > <edoc file>
+
+
View
195 bin/MARKEDOC-README.md 100755 → 100644
@@ -1,61 +1,121 @@
-markedoc 0.1
-============
+edown markedoc 0.3.2
+====================
- **markedoc** helps you keep your project's README.md in sync with your
- overview.edoc.
+**markedoc helps you keep your project's README.md in sync with your overview.edoc.**
-Status: alpha. Many things work. Some others do not. See [Status][].
+This is the opposite direction from what **edown** otherwise does.
-markedoc translates [Markdown][] formatted texts into [Erlang][] [EDoc][]
-format, for inclusion into [EDoc][] generated html docs.
+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.
-The actual script file is in the bin folder: bin/markedoc.sed.
+Status: [pre-beta][Status]. Quite stable and usable. See [Status][].
-markedoc is but a brief [sed][] command file to convert markdown to edoc. Use it
-to translate your project's README.md into a README.edoc to include in your
-Erlang project's main overview.edoc file.
+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].
-markedoc is part of **[edown][]**.
+[issues]: https://github.com/hdiedrich/markedoc/issues "Issue tracker"
-You contribution to make markedoc better is highly welcome.
-
-Use
+Use <a name=Use></a>
---
-At the command line:
+At the command line for
+**FreeBSD, Mac OS X**
$ sed -E -f markedoc.sed <markdown file> > <edoc file>
-Requirements
+**Linux**
+ $ sed -r -f markedoc.sed <markdown file> > <edoc file>
+
+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.
+
+Requirements <a name=Requirements></a>
------------
-* **[sed]**: is part of any Linux and Mac OSX distribution. You could get it for [Windows, too][winsed].
+* **[sed][]**: is part of any Linux, FreeBSD and Mac OSX distribution, also see [Notes][].
+
+* **[Erlang/OTP][Erlang]**, see [Notes][].
+
+Test <a name=Test></a>
+----
-* **[Erlang/OTP][Erlang]**: see below.
+ **FreeBSD, Mac OS X**
+ $ samples/markedoc/test-bsd.sh
-Sample
+ **Linux**
+ $ samples/markedoc/test-linux.sh
+
+Then check html files as listed in the output.
+
+Sample <a name=Sample></a>
------
+From edown project root, try out:
+
+ **FreeBSD, Mac OS X**
+ $ sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE1.md > samples/markedoc/doc/SAMPLE.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[]'
+
+ **Linux**
+ $ sed -r -f bin/markedoc.sed samples/markedoc/SAMPLE1.md > samples/markedoc/doc/SAMPLE.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[]'
+
+This creates a SAMPLE.edoc file from SAMPLE1.md, which is then included in the EDoc generation. Point your browser at
+
+ samples/markedoc/doc/overview-summary.html
+
+to see the result. For something only vaguely related but pretty, try:
+
+ $ erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+
+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.
+
For your own projects you'd copy markedoc.sed in the right place and do something like:
- $ echo "@doc " > doc/README.edoc
- $ sed -E -f bin/markedoc.sed README.md >> doc/README.edoc
- $ erl -noshell -run edoc_run application "'myapp'" '"."' '[{def,{vsn,""}}]'
+ **FreeBSD, Mac OS X**
+ $ sed -E -f bin/markedoc.sed README.md > doc/README.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"."' '[]'
+
+ **Linux**
+ $ sed -r -f bin/markedoc.sed README.md > doc/README.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"."' '[]'
-And that's it. This could also be part of your Makefile. This way, the
-README.edoc becomes part of your generated EDoc html pages, you would use a
-@docfile tag in your overview.edoc file, like so:
+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:
@docfile "doc/README.edoc"
-Status
+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.
+
+Accordingly, the sample stub overview.edoc used for the samples here, looks like this:
+
+ @author You
+ @title a markedoc sample doc
+ @version 0.2
+ @docfile "samples/markedoc/doc/SAMPLE.edoc"
+
+Tricks <a name=Tricks></a>
------
- **Alpha**. You can do nice things but it likes to trip up EDoc, which is kind of easy to do.
+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
+both worlds:
+
+ ## Examples <a name=example></a>
+
+ ...
+
+ [sample]: #sample
+
-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.
+This makes a tag `[example][]' into a direct jump to the headline 'Example', in both markdown and edoc.
+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.)
+If you get the reference wrong or forget to make it, the link tag will be displayed in the open, as actual `[example][]'.
+
+
+Status <a name=Status></a>
+------
+
+ **Pre-Beta**. Quite usable, but still likes to trip up EDoc now and then, which is kind of easy to do.
+
+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.
**Thanks!**
-Notes
+Notes <a name=Notes></a>
-----
**[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.
@@ -64,52 +124,73 @@ Notes
**[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.
-[EDoc]: http://www.erlang.org/doc/apps/edoc/chapter.html
+[EDoc]: http://www.erlang.org/doc/apps/edoc/chapter.html
**[edown][]** is an EDoc extension for generating Github-flavored Markdown. It uses edoc-style commented Erlang sources to create markdown files from them.
-[edown]: https://github.com/esl/edown
+[edown]: https://github.com/esl/edown
**[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).
-[Markdown]: http://daringfireball.net/projects/markdown/
+[Markdown]: http://daringfireball.net/projects/markdown/
**[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.
-[sed]: http://en.wikipedia.org/wiki/Sed
-
-[winsed]: http://gnuwin32.sourceforge.net/packages/sed.htm
-
-[sample]: https://github.com/Eonblast/Emysql/raw/master/README.md "This markdown file is translated alright by markedoc."
-
-
-Caveats / Todos
----------------
-* Underlined ("==="/"---") headlines currently don't work, use the '#' variant instead
-* **'[1]: ...'-style end note references need two spaces at the end of the line**
-* add two new lines at end of your markdown file to avoid loosing the last line.
-* Local anchor jumps fail
-
-
-Not So Bad Todos
-----------------
-* robust alternates not tested for some time
-* space before javascript links should go
-* protect ampersands
+[sed]: http://en.wikipedia.org/wiki/Sed
+[winsed]: http://gnuwin32.sourceforge.net/packages/sed.htm
+[sample]: https://github.com/Eonblast/Emysql/raw/master/README.md "This markdown file is translated alright by markedoc."
License
-------
This script is free software. It comes without any warranty.
-
Author
------
H. Diedrich <hd2010@eonblast.com>
-
History
-------
-01/31/11 - 0.1 - **first release**
-
+02/18/11 - 0.3.2 - **edown**
+
+* integrated into edown
+
+02/05/11 - 0.3.1 - **more polish** - Linux, FreeBSD, Mac OS X
+
+* added weeding out of markdown anchor references (an md workaround)
+* added protection for & (but edoc still only accepts number codes)
+* fixed trip up by trailing spaces in underline headline format
+* checked commented out alternate code for code blocks and references.
+
+02/03/11 - 0.3 - **rough edges polished** - Linux, FreeBSD, Mac OS X
+
+* added doc for Linux use
+* added support for multi-line '[..]: ... "..."' references
+* added footnote signs and sepcial chars:
+* dagger, double dagger: (+), (++), stars: (\*), (\*\*), (\*\*\*)
+* superscript 1, 2, 3: (\*1), (\*2), (\*3), copyright (C), (R), (TM),
+* guillemots <<, >> and middle dot ::
+* added test batches etc/test-bsd.sh and etc/test-linux.sh
+* added css sample in samples/markedoc/what-you-could-see/
+* added classes for ``< li >'' list item tags for '[..]:...'-references
+* fixed italic and bold merker interference bullet points
+* eliminated [..]: part of '[..]:...'-references, flipping "..." to lead
+* dev: sample creation batch make_samples.sh added
+
+02/02/11 - 0.2 - **basics complete** - FreeBSD / Mac OS X
+
+* added support for === and --- headline format
+* fixed cutting off of last lines
+* fixed page-local anchor jumps
+* fixed space in javascript links
+* eliminated end-space requirement at end of '[..]:...'-style references.
+* eliminated need for echoing '@doc' first into edoc output file
+* added javascript title tag setting for '[..]:...'-style references.
+
+01/31/11 - 0.1 - **first release:** FreeBSD / Mac OS X
+
+[Requirements]: #Requirements
+[Status]: #Status
+[Notes]: #Notes
+[Test]: #Test
View
293 bin/markedoc.sed 100755 → 100644
@@ -1,103 +1,143 @@
-# markedoc 0.1 - 01/31/11 - H. Diedrich <hd2010@eonblast.com>
+# markedoc 0.3.2 - 02/18/11 H. Diedrich <hd2010@eonblast.com>
# ----------------------------------------------------------
# sed command file to convert markdown format to edoc format
+# Linux, FreeBSD and Mac OS X. Windows must install sed.
# ----------------------------------------------------------
# Use it to make a markdown readme file part of an edoc file:
-# sed -E -f <this file> <markdown file> > <edoc file>
+# FrBSD: sed -E -f <this file> <markdown file> > <edoc file>
+# MacOS: sed -E -f <this file> <markdown file> > <edoc file>
+# Linux: sed -r -f <this file> <markdown file> > <edoc file>
+# As only difference, Linux uses -r where the others use -E.
# ----------------------------------------------------------
-# SAMPLE USE:
+# SAMPLE USE (FreeBSD / Mac OS X):
# sed -E -f markedoc.sed README.markdown > overview.edoc
+# SAMPLE USE (Linux):
+# sed -r -f markedoc.sed README.markdown > overview.edoc
# ----------------------------------------------------------
# SAMPLE FILES:
# https://github.com/hdiedrich/markedoc/tree/master/samples
+# SAMPLE RESULTS:
+# samples/what-you-should-see/ & samples/what-you-could-see/
# ----------------------------------------------------------
-# SAMPLE WORKFLOW:
-# echo '@doc ' > samples/doc/SAMPLE.edoc
-# sed -E -f bin/markedoc.sed samples/SAMPLE1.md >> samples/doc/SAMPLE.edoc
-# erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+# SAMPLE WORKFLOW (change -r to -E for FreeBSD / Mac OS X):
+# sed -r -f markedoc.sed README.md > doc/README.edoc
+# erl -noshell -run edoc_run application "'myapp'" '"."' '[]'
# ----------------------------------------------------------
# REQUIREMENTS: sed, Erlang
+# Windows: http://gnuwin32.sourceforge.net/packages/sed.htm
# ----------------------------------------------------------
-# STATUS: Alpha.
-# You can do nice things but it likes to trip up EDoc.
+# STATUS: Pre-Beta.
+# It can reliably do nice things but likes to trip up EDoc.
# With a bit of patience, and mostly with pretty clean md
# markup, and some blank lines sometimes, most things work.
# ----------------------------------------------------------
# LICENSE: Free software, no warranties.
# ----------------------------------------------------------
-# On edown: http://www.erlang.org/doc/apps/edoc/
+# On edown: https://github.com/esl/edown
# On Markdown: http://daringfireball.net/projects/markdown/
# On Edoc: http://www.erlang.org/doc/apps/edoc/
-# ----------------------------------------------------------
-# There are many ways to create formats that will make the
-# EDoc creator tilt and the errors it throws are not quite
-# illuminating to the reader sometimes. Make an incremental
-# approach and see what works. As you can see from the live
-# sample, it's quite a lot that does work and some bits can
-# be worked out. Please experiment and push your fixes.
-# - Thanks!
+# On sed: http://www.gnu.org/software/sed/manual/sed.html
# ----------------------------------------------------------
# Repository: https://github.com/hdiedrich/markedoc/
-# ----------------------------------------------------------
# Issues: https://github.com/hdiedrich/markedoc/issues
-# ----------------------------------------------------------
-# * Underlined ("==="/"---") headlines currently don't work,
-# use the '#' variant instead
-# * **'[1]: ...'-style end note references need two spaces
-# at the end of the line**
-# * add two new lines at end of your markdown file to avoid
-# loosing the last line.
-# * Local anchor jumps fail
-# * robust alternates not tested for some time
-# * space before javascript links should go
-# * protect ampersands
+# Please experiment and push your fixes. - Thanks!
# ----------------------------------------------------------
# **********************************************************
# SCRIPT
# **********************************************************
-# this is a sed script for -E regex and limited scripting.
+# Ach, da kommt der Meister! Herr, die Not ist gro�! ~~~
+# ~~~ Die ich rief, die Geister, Werd ich nun nicht los.
+# ----------------------------------------------------------
+# This is a sed script for use with -E/-r regexes & NOT -n.
# s/<find>/<replace>/<flag> is the basic sed regex replace
# command. sed normally works strictly line by line. 'N'
-# is used to join lines. 't' is a conditional branch. 'mlc:'
-# is a label. The order of replacement functions matters.
-# See 'man sed' for more info. If you are a sed master,
-# your help making this better is appreciated.
+# is used to join lines. 't' is a conditional branch. ':'
+# is a label. The order of replacement functions matters.
+# There are tabs in some patterns that may look like spaces.
+# See 'man sed' for more info. If you are a sed master,
+# your help making this better is much appreciated.
+# **********************************************************
+
+
+# as first line, make the @doc tag
+# --------------------------------
+1 i\
+@doc\
# code sample blocks, trying to get them into one <pre> block
# -----------------------------------------------------------
# tabs are consumed for 'navigation'. sed is Turing complete.
# inserted space is needed by edocs.
# There are tabs in this pattern.
/^ / {
+ # break ... on last line ('N' would exit)
+ $ b end_collect_with_last_line_hit
+ s/^ (.*)$/ \1/
# do ...
- :mlc
+ : do_collect
# append next line
N
- # does thatline start with a tab, too?
- s/(\n) (.*)$/\1 \2/g
- # while: ... yes, then repeat from :mlc
- t mlc
- # if no, <pre> block is complete, though one line too much, store this.
+ # break ... if we are now into the last line
+ # (or the test below will eat the tab away.)
+ $ b end_collect_with_last_line_hit
+ # does the current last line start with a tab, too?
+ s/(\n) (.*)$/\1 \2/
+ # while: ... yes, then loop
+ t do_collect
+ # normal end of collect: got all indendet lines, plus one too many.
+ # -----------------------------------------------------------------
+ b normal_course
+ #
+ # Run into file end while looping
+ # -------------------------------
+ : end_collect_with_last_line_hit
+ # and does that last line start with a tab, too?
+ s/(\n) (.*)$/\1 \2/
+ s/^ (.*)$/ \1/
+ # yes, then we're done actually
+ t wrap_rest_and_done
+ # else, cut it off and such, as normal
+ # debug i\
+ # debug normal
+ #
+ : normal_course
+ # ... ok, we have multiple lines, and we have one line too much, back it all up.
h
- # Handle the <pre> block to be:
- # -----------------------------
- # cut off the last line, that doesn't belong, and insert newlines
- s/^ (.*)(\n)([^\n]*)$/\2 \1\2/
+ # Handle the <pre> block to be (*):
+ # ---------------------------------
+ # cut off the last line, that doesn't belong and insert newlines
+ s/^(.*)(\n)(.*)$/\2\1\2/
# wrap all in the docs code tags ```...'''
s/^(.*)$/```\1'''/
# protect @ (for edoc related texts that explain @-tags). There is a tab in [].
s/([ \"\'\`]+@)/\1@/g
# send result to stdout
p
- # Now make sure that last line is not lost:
- # -----------------------------------------
+ # Now make sure that that last line is not lost:
+ # ----------------------------------------------
# get stored back
g
# this time discard all but the last line, which is processed further
- s/^ (.*)(\n)([^\n]*)$/\3/
+ s/^.*\n(.*)$/\1/
+ # jump to end
+ b end_of_code_blocks_handling
+ #
+ # File End Remedy: wrap all to end and done.
+ # ------------------------------------------
+ : wrap_rest_and_done
+ # debug i\
+ # debug rest and done
+ # wrap all in the docs code tags ```...'''
+ s/^(.*)$/```\1'''/
+ # protect @ (for edoc related texts that explain @-tags). There is a tab in [].
+ s/([ \"\'\`]+@)/\1@/g
+ b end
+ #
}
+:end_of_code_blocks_handling
+
# robust alternate for code blocks: each tabbed line
# --------------------------------------------------
# If the above keeps being difficult, use this more robust
@@ -107,24 +147,94 @@
# nice results as the above. There are tabs in this pattern.
# s/^ (.+)$/``` \1'''/
-# Erlang comments
-# ---------------
-# doesn't work yet
-# s/(\n\s*)(%[^\n]+)/\1<span class="comment">\2<\/span>/g
+# footnote signs
+# --------------
+# superscript 1
+s/\(\*1\)/\&#185;/g
+# superscript 2
+s/\(\*2\)/\&#178;/g
+# superscript 3
+s/\(\*3\)/\&#179;/g
+# dagger
+s/\(\+\)/\&#134;/g
+# double dagger
+s/\(\+\+\)/\&#135;/g
+# star
+s/\(\*\)/\&#42;/g
+# double star
+s/\(\*\*\)/\&#42;\&#42;/g
+# triple star
+s/\(\*\*\*\)/\&#42;\&#42;\&#42;/g
+
+# special chars
+# -------------
+# middle dot
+s/::/\&#183;/g
+# guillemot
+s/<</\&#171;/g
+s/>>/\&#187;/g
+
+
+# copy right
+# ----------
+s/\(c)/\&#169;/g
+s/\(C)/\&#169;/g
+s/\(R)/\&#174;/g
+s/\(r)/\&#174;/g
+s/\(tm)/\&#153;/g
+s/\(TM)/\&#153;/g
# links
# -----
# external links
s/\[([^]]+)\]\(([^)]+)\)/<a href=\"\2\">\1<\/a>/
-# references - must have trailing double space! (could learn to look at next line for "...")
-s/(\[([^]]+)\]): +\[?(http[s]?:\/\/[^.>" ]+\.[^>" ]+)\]? * *("([^"]+)")? * *$/\1 <a name="\2" id="\2" href="\3" target="_parent">\3<\/a> \5<br \/>/
-s/(\[([^]]+)\]): +<?([^@>" ]+@[^.>" ]+\.[^>" ]+)>? * *("([^"]+)")? * *$/\1 <a name="\2" id="\2" href="mailto:\3">\3<\/a>\5<br \/>/
+# references, '[..]:...'-style
+# ----------------------------
+# urls
+s/(\[([^]]+)\]): +\[?(http[s]?:\/\/[^.>" ]+\.[^>" ]+)\]? * *("([^"]+)") * *$/<li class="ref url"> \5:<a name="\2" id="\2" href="\3" target="_parent">\3<\/a><\/li>/
+# check next line "..." description
+/(\[([^]]+)\]): +\[?(http[s]?:\/\/[^.>" ]+\.[^>" ]+)\]? *$/ {
+ # get next line, if the current is not the last
+ $!N
+ # try two line spanning, or single (last) line
+ s/(\[([^]]+)\]): +\[?(http[s]?:\/\/[^.>" ]+\.[^>" ]+)\]? * *\n * *("([^"]*)") * *$/<li class="ref url"> \5:<a name="\2" id="\2" href="\3" target="_parent">\3<\/a><\/li>/
+ t double_line_url_done
+ # try one line only, rest to be saved
+ s/(\[([^]]+)\]): +\[?(http[s]?:\/\/[^.>" ]+\.[^>" ]+)\]? * *(\n)/<li class="ref url"> <a name="\2" id="\2" href="\3" target="_parent">\3<\/a><\/li>\4/
+ t double_line_url_done
+ # case of last line, single, no "..." description
+ s/(\[([^]]+)\]): +\[?(http[s]?:\/\/[^.>" ]+\.[^>" ]+)\]? * *$/<li class="ref url"> <a name="\2" id="\2" href="\3" target="_parent">\3<\/a><\/li>/
+ : double_line_url_done
+ # print out up to first \n, delete, start from top with the rest
+ P
+ D
+}
+
+# email addresses
+s/(\[([^]]+)\]): +<?([^@>" ]+@[^.>" ]+\.[^>" ]+)>? * *("([^"]+)") * *$/<li class="ref email"> \5:<a name="\2" id="\2" href="mailto:\3">\3<\/a><\/li>/
+# check next line "..." description
+/(\[([^]]+)\]): +<?([^@>" ]+@[^.>" ]+\.[^>" ]+)>? * *("([^"]+)")? * *$/ {
+ # get next line, if the current is not the last
+ $!N
+ # try two line spanning, or single (last) line
+ s/(\[([^]]+)\]): +<?([^@>" ]+@[^.>" ]+\.[^>" ]+)>? * *\n * *("([^"]+)") * *$/<li class="ref email"> \5:<a name="\2" id="\2" href="mailto:\3">\3<\/a><\/li>/
+ t double_line_mail_done
+ # try one line only, rest to be saved
+ s/(\[([^]]+)\]): +<?([^@>" ]+@[^.>" ]+\.[^>" ]+)>? * *(\n)/<li class="ref email"> <a name="\2" id="\2" href="mailto:\3">\3<\/a><\/li>\4/
+ t double_line_mail_done
+ # case of last line, single, no "..." description
+ s/(\[([^]]+)\]): +<?([^@>" ]+@[^.>" ]+\.[^>" ]+)>? * *$/<li class="ref email"> <a name="\2" id="\2" href="mailto:\3">\3<\/a><\/li>/
+ : double_line_mail_done
+ # print out up to first \n, delete, start from top with the rest
+ P
+ D
+}
# smart reference for the [x]: ... format, jumping right to the referenced page.
# ------------------------------------------------------------------------------
-s/\[([^]]+)\]\[\]/<a href="javascript: parent.document.location.href=document.getElementById('\1').href">\1<\/a>/g
-s/\[([^]]+)\]\[([^]]+)\]/<a href="javascript: parent.document.location.href=document.getElementById('\2').href">\1<\/a>/g
+s/\[([^]]+)\]\[\]/<a href="javascript:goto('\1')" onMouseOver="this.title=url('\1')">\1<\/a>/g
+s/\[([^]]+)\]\[([^]]+)\]/<a href="javascript:goto('\2')" onMouseOver="this.title=url('\2')">\1<\/a>/g
# robust alternate reference for the [x]: ... format, jumping to footnote.
# ------------------------------------------------------------------------
@@ -141,6 +251,11 @@ s/^###(.+)$/===\1 ===/
s/^##(.+)$/==\1 ==/
s/^#(.+)$/==\1 ==/
+# italics, bold
+# -------------
+s/\*\*([^*]+)\*\*/<b>\1<\/b>/g
+s/\*([^*]+)\*/<em>\1<\/em>/g
+
# bullet points
# -------------
# edoc must see closing </li>
@@ -155,11 +270,6 @@ s/<(http[s]?:\/\/[^.>]+.[^>]+)>/<a href=\"\1\">\1<\/a>/
# -----------
s/ $/<br \/>/
-# italics, bold
-# -------------
-s/\*\*([^*]+)\*\*/<b>\1<\/b>/
-s/\*([^*]+)\*/<em>\1<\/em>/
-
# single backticks
# ----------------
# make code quotes
@@ -171,15 +281,58 @@ s/`([^`]+)`/<code>\1<\/code>/g
# itself most likely, so escape it.
s/([ \"\'\`]+@)/\1@/g
-# Don't work yet, make every other line not parsed.
# headlines by underline === or ---
# ---------------------------------
# demoted to h2 and h3, as h1 is reserved in edoc
-# /^[^-=]/{
-# N
-# s/^(.+)\n=+ *$/== \1 ==/
-# s/^(.+)\n-+ *$/=== \1 ===/g
-# }
+{
+ # don't check this for the last line ('N' would exit)
+ $ b skip_alt_headlines
+ # get next line
+ N
+ # contract === with previous to headline h2
+ s/^(.+)\n=+ *$/== \1 ==/
+ # if substitution took place, goto ...
+ t substi
+ # contract --- with previous to headline h2
+ s/^(.+)\n-+ *$/=== \1 ===/g
+ # if substitution took place, goto ...
+ t substi
+ # no substitution: print the previous line and start with latest from top
+ # -----------------------------------------------------------------------
+ # store the two lines we have now, one is the one formatting is done with
+ # the next is the fresh one we just pulled.
+ h
+ # cut off the last line, print the ready formatted one
+ P
+ D
+ # and this is the goto for successful headline substitutions above:
+ :substi
+}
-# ----------------------------------------------------------
-# 'powered by Eonblast' http://www.eonblast.com
+:skip_alt_headlines
+:end
+
+# at the bottom, add JS for the 'smart' direct jump
+# -------------------------------------------------
+# to a reference url in trailing '[]:...'-notation
+$ a\
+<script>\
+// Jump directly to a referenced url given in trailing '[]:...'-notation\
+function goto(tag) { parent.document.location.href = url(tag); }\
+function url(tag) { var o=document.getElementById(tag); return o ? o.href : '#'+tag; }\
+</script>
+
+# debugger stable
+# ---------------
+# i\
+# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+# p
+# i\
+# <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+
+# -----------------------------------------------------------------
+# t,b "In most cases, use of these commands indicates that you are
+# probably better off programming in something like awk or Perl."
+# sed manual: http://www.gnu.org/software/sed/manual/sed.html
+# -----------------------------------------------------------------
+# 'powered by Eonblast' http://www.eonblast.com - all the new tech
View
BIN samples/.DS_Store
Binary file not shown.
View
31 samples/.gitignore
@@ -0,0 +1,31 @@
+# ...
+
+# ----------------------------
+# specific markedoc artifacts:
+# ----------------------------
+# some artifacts can be expected to happen from experimenting in the main and samples dir:
+
+doc/
+doc/*
+
+# general intermediary files (relative to sample/)
+SAMPLE.edoc
+edoc-info
+*.dump
+*.beam
+*.log
+
+# specific sample files (relative to sample/)
+markedoc/doc/*.edoc
+markedoc/doc/*.html
+markedoc/doc/edoc-info
+markedoc/doc/stylesheet.css
+markedoc/your-test-results/*.edoc
+markedoc/your-test-results/*.html
+markedoc/your-test-results/edoc-info
+
+# dev (relative to sample/)
+README.html
+markedoc/README.html
+
+# ----------------------------
View
1 samples/README.md
@@ -0,0 +1 @@
+At this point, there are samples in this directory only for the 'markedoc' script, which complements edoc by allowing for converting markdown format to edoc format.
View
BIN samples/markedoc/.DS_Store
Binary file not shown.
View
313 samples/markedoc/SAMPLE1.md
@@ -0,0 +1,313 @@
+# SAMPLE 1: Emysql Readme of Jan 2011
+```
+ --------------------------------------------------------------
+| THIS TEXT IS USED AS A SAMPLE TO ILLUSTRATE MARKEDOC USAGE. |
+| If you see this in your browser, you succeeded compiling it |
+| from markdown into an edoc. As you see it's quite complex |
+| and there is no 'cheating' involved. |
+ --------------------------------------------------------------
+'''
+
+Erlang MySQL driver, based on a rewrite at Electronic Arts(tm). Supports prepared statements and stored procedures. For [samples][] and [docs][] see below.
+
+While you can use mysql via ODBC, using a driver like Emysql should perform better.
+
+This is a continuation fork of [emysql][1] with [fixes][], [updates][], more [docs][] and [samples][]. [emysql][1] is a clean rewrite of [erlang-mysql-driver][2].
+
+<hr/>
+
+ **<<Which fork should I use?>>** See [history][].
+ **<<Who used this fork?>>** Electronic Arts.
+ **<<How do I ...?>>** See [samples][].
+
+ **Download:** <https://github.com/Eonblast/Emysql/archives/master>
+ **Repository:** <https://github.com/Eonblast/Emysql>
+ **Docs:** <http://eonblast.github.com/Emysql/>
+
+<hr/>
+
+## Contents
+
+* [History][]
+* [Usage][]
+* [Samples][]
+* [Links][]
+* [Todo][]
+* [License][]
+
+<hr/>
+
+## History
+
+Open Source Erlang MySQL driver efforts are currently a fractured matter, at least for the higher functionality. There are four main choices:
+
+* **Yxa**: The first Erlang MySQL driver seems to have been written in 2005 by [Magnus Ahltorp][ma] at the [Royal Institute of Technology][3]. It is the basis for the following two. The [original mysql driver source][4] is stable since at least 2007, it is available as part of the SIP proxy [Yxa 1.0][5] (hosted [on github][6]).
+
+* **ejabberd**: Already in 2006, a [fork][7] was created by [Mickael Remond][mr] at [Process One][8] to become part of the successful instant messaging server [ejabberd][9] (also hosted [at github][10]). It can be assumed to be as stable as the Yxa branch, and it didn't change anything in the lowest level, mysql_recv.erl. The differences to the original Yxa branch mainly consists of added inspection functions that help using query results, and an [independent adoption][11] to the MySQL 4.1 client-server protocol. Also, the original Yxa branch has meanwhile adopted edoc comment format. Find a diff [here][12], one ignoring comment lines [here][13].
+
+* **erlang-mysql-driver**: in 2006/07 [Yariv Sadan][ys] created a fork from the ejabberd branch, made it a standalone project, gave it the name that stuck, and hosted it at [Google Code][15]. Before he moved on to work at Facebook, he had added higher level handling of prepared statements and transactions, and stated that he had improved connection pooling and logging. There were changes both in the original Yxa and the ejabberd branch after the forking off that seem to never have made their way into the erlang-mysql-driver branch, which now lies dormant since Oct '07. Docs were somewhat unsatisfying, as much as for the earlier branches. In Feb '10, Dave Smith started making some
+[updates][15] and put them on github, were the driver is now enjoying a couple of [active forks][16] that make for a convincing case in favor of the github Network graph.
+
+* **Emysql** was started from scratch in 2009 by [Jacob Vorreuter][jv] and [Bill Warnecke][bw] at Electronic Arts, who rewrote the erlang-mysql-driver code because they felt it had been touched by so many people that it had become more complicated than necessary. In a way, the third layer module, mysql.erl, had over time started to become badly entangled with the second, mysql_conn.erl. According to Jacob, Emysql is pretty stable and ran without issue in a production environment at Electronic Arts. This fork is a continuation of [their work][1], including all their commits and adding [documentation][docs], [samples], [fixes][] and extensions.
+
+[Vitaliy Batichko][vb] and
+[Chris Rempel][cr] have contributed updates to this branch. Thank you!
+
+[1]: http://github.com/JacobVorreuter/emysql "emysql"
+[2]: http://github.com/dizzyd/erlang-mysql-driver "erlang-mysql-driver"
+[3]: http://www.kth.se/ "Royal Institure of Technology"
+[4]: https://github.com/fredrikt/yxa/tree/master/src/mysql "Yxa mysql driver"
+[5]: http://www.stacken.kth.se/project/yxa/index.html "Yxa Home"
+[6]: https://github.com/fredrikt/yxa "Yxa repository at github"
+[7]: http://svn.process-one.net/ejabberd-modules/mysql/trunk/
+ "ejabberd mysql driver"
+[8]: https://support.process-one.net "Process One Home"
+[9]: http://www.process-one.net/en/ejabberd/ "ejabberd Home"
+[10]: https://github.com/processone/ejabberd/ "ejabberd repository at github"
+[11]: https://support.process-one.net/doc/display/CONTRIBS/Yxa
+ "ejabberd MySQL 4.1. patch"
+[12]: https://github.com/Eonblast/Emysql/tree/master/doc/diff-ejabberd-yxa.txt
+ "Diff of Yxa and ejabberd mysql drivers"
+[13]: https://github.com/Eonblast/Emysql/tree/master/doc/diff-ejabberd-yxa-2.txt
+ "Diff of Yxa and ejabberd mysql drivers ignoring comment changes"
+[14]: http://code.google.com/p/erlang-mysql-driver/
+ "original erlang-mysql-driver"
+[15]: http://github.com/dizzyd/erlang-mysql-driver
+ "Dave Smith's erlang-mysql-driver at github, currently not maintained"
+[16]: https://github.com/dizzyd/erlang-mysql-driver/network
+ "Fork graph of erlang-mysql-driver at github"
+
+[ma]: ahltorp@nada.kth.se "Magnus Ahltorp"
+[ys]: http://yarivsblog.blogspot.com/
+[bw]: bill@rupture.com
+[jv]: https://github.com/JacobVorreuter
+[vb]: https://github.com/bva
+[cr]: https://github.com/csrl "Chris Rempel"
+[hd]: hd2010@eonblast.com "Henning Diedrich"
+[mr]: mickael.remond@process-one.net "Mickael Remond"
+
+[fixes]: https://github.com/Eonblast/Emysql/issues/closed
+ "Emysql fixes"
+[docs]: http://eonblast.github.com/Emysql/
+ "Emysql online docs"
+
+## Usage
+
+#### Start the application
+
+ crypto:start(),
+ application:start(emysql).
+
+#### Add a pool
+ % emysql:add_pool(PoolName, PoolSize, Username, Password, Host, Port, Database, Encoding) ->
+ % ok | {error, pool_already_exists}
+ % PoolName = atom()
+ % PoolSize = integer()
+ % Username = string()
+ % Password = string()
+ % Host = string()
+ % Port = integer()
+ % Database = string()
+ % Encoding = atom()
+
+ emysql:add_pool(mypoolname, 1, "username", "mypassword", "localhost", 3306, "mydatabase", utf8).
+
+#### Record Types
+ -record(ok_packet, {seq_num, affected_rows, insert_id, status, warning_count, msg}).
+ -record(error_packet, {seq_num, code, msg}).
+ -record(result_packet, {seq_num, field_list, rows, extra}).
+
+#### Executing SQL statements
+ % emysql:execute(PoolName, Statement) -> result_packet() | ok_packet() | error_packet()
+ % PoolName = atom()
+ % Statement = string() | binary()
+
+ emysql:execute(mypoolname, <<"SELECT * from mytable">>).
+ #result_packet{field_list=[...], rows=[...]}
+
+ emysql:execute(mypoolname, <<"UPDATE mytable SET bar = 'baz' WHERE id = 1">>).
+ #ok_packet{affected_rows=1}
+
+#### Executing prepared statements
+ % emysql:prepare(StmtName, Statement) -> ok
+ % StmtName = atom()
+ % Statement = binary() | string()
+
+ emysql:prepare(my_stmt, <<"SELECT * from mytable WHERE id = ?">>).
+ ok
+
+ % emysql:execute(PoolName, StmtName, Args) -> result_packet() | ok_packet() | error_packet()
+ % StmtName = atom()
+ % Args = [term()]
+
+ emysql:execute(mypoolname, my_stmt, [1]).
+ #result_packet{field_list=[...], rows=[...]}
+
+#### Executing stored procedures
+
+ % emysql:execute(PoolName, StmtName, Args) -> result_packet() | ok_packet() | error_packet()
+ % StmtName = atom()
+ % Args = [term()]
+
+ emysql:execute(hello_pool,
+ <<"create procedure sp_hello() begin select * from hello_table; end">>).
+ {ok_packet,1,0,0,2,0,[]}
+
+ emysql:execute(hello_pool, <<"call sp_hello();">>).
+ [{result_packet,6,
+ [{field,2,<<"def">>,<<"hello_database">>,<<"hello_table">>,
+ <<"hello_table">>,<<"hello_text">>,<<"hello_text">>,
+ 254,<<>>,33,60,0,0}],
+ [[<<"Hello World!">>],[<<"Hello World!">>]],
+ <<>>},
+ {ok_packet,7,0,0,34,0,[]}]
+
+#### Converting Row Data To Records
+ % emysql_util:as_record(ResultPacket, RecordName, Fields) -> Result
+ % ResultPacket = result_packet()
+ % RecordName = atom() (the name of the record to generate)
+ % Fields = [atom()] (the field names to generate for each record)
+ % Result = [record()]
+
+ -module(fetch_example).
+ -record(foo, {bar, baz, bat}).
+
+ fetch_foo() ->
+ Result = emysql:execute(pool1, <<"select bar, baz, bat from foo">>),
+ Recs = emysql_util:as_record(Result, foo, record_info(fields, foo)),
+ [begin
+ io:format("foo: ~p, ~p, ~p~n", [Foo#foo.bar, Foo#foo.baz, Foo#foo.bat])
+ end || Foo <- Recs].
+
+## Getting Emysql
+
+ $ git clone git://github.com/Eonblast/Emysql.git Emysql
+
+## Samples
+
+#### Hello World(*)
+
+This is a hello world program. Follow the three steps below to try it out.
+
+ -module(a_hello).
+ -export([run/0]).
+
+ run() ->
+
+ crypto:start(),
+ application:start(emysql),
+
+ emysql:add_pool(hello_pool, 1,
+ "hello_username", "hello_password", "localhost", 3306,
+ "hello_database", utf8),
+
+ emysql:execute(hello_pool,
+ <<"INSERT INTO hello_table SET hello_text = 'Hello World!'">>),
+
+ Result = emysql:execute(hello_pool,
+ <<"select hello_text from hello_table">>),
+
+ io:format("~n~p~n", [Result]).
+
+
+We come back to that source, but first:
+
+#### Building Emysql
+
+Build emysql.app, using make:
+
+ $ cd Emysql
+ $ make
+
+
+#### Sample database
+
+For the above sample, create a local mysql database. You should have a mysql server installed and running:
+
+ $ mysql [-u<user> -p]
+ mysql> create database hello_database;
+ mysql> use hello_database;
+ mysql> create table hello_table (hello_text char(20));
+ mysql> grant all privileges on hello_database.* to hello_username@localhost identified by 'hello_password';
+
+#### Run Hello
+
+Be sure to have ./ebin in your Erlang path. Now copy the Hello World source above at '(*)' into a file hello.erl and run it (in the Emysql root directory):
+
+ $ erlc hello.erl
+ $ erl -pa ../ebin -s hello run -s init stop -noshell
+
+See more sample programms, below.
+
+#### Running the Samples
+Sample programs are in ./samples.
+
+* [a_hello](http://github.com/Eonblast/Emysql/blob/master/samples/a_hello.erl) - Hello World
+* [a_hello2](http://github.com/Eonblast/Emysql/blob/master/samples/a_hello2.erl) - Hello World somewhat rawer
+* [b_rows_as_records](http://github.com/Eonblast/Emysql/blob/master/samples/b_rows_as_records.erl) - Using Erlang records to access result rows
+* [c_stored_procedure](http://github.com/Eonblast/Emysql/blob/master/samples/c_stored_procedure.erl) - Using Stored procedures
+
+To run the samples, create the database as listed above at localhost, and:
+
+ $ cd samples
+ $ ./a_hello
+ $ ./b_raw
+ $ ./d_rows_as_records
+ $ ./e_prepared_statement
+ $ ./e_stored_procedure
+
+or make emysql.app and start a_hello etc. manually along these lines (but
+first create the database as listed above):
+
+ $ make
+ $ cd samples
+ $ erlc a_hello.erl
+ $ erl -pa ../ebin -s a_hello run -s init stop -noshell
+
+## Links
+
+* [Emysql on Github](http://github.com/Eonblast/Emysql)
+* [Original Yxa](https://github.com/fredrikt/yxa/tree/master/src/mysql) mysql driver
+* [ejabberd fork](http://svn.process-one.net/ejabberd-modules/mysql/trunk/)
+* ['erlang-mysql-driver'](http://code.google.com/p/erlang-mysql-driver/)
+* [Dave Smith's erlang-mysql-driver fork](http://github.com/dizzyd/erlang-mysql-driver)
+* [A maintained erlang-mysql-driver](https://github.com/JoelPM/erlang-mysql-driver) fork
+* [Another maintained&#134; erlang-mysql-driver](https://github.com/chernomor/erlang-mysql-driver) fork
+* [MySQL Client Server Protocol](http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol)
+* [MySQL 5.5 Source](ftp://ftp.fu-berlin.de/unix/databases/mysql/Downloads/MySQL-5.5/mysql-5.5.8.tar.gz)
+
+&#134;maintained at the time of writing, Jan 2011.
+
+## TODO
+* decrementing pool size could close sockets that are in use
+* spawn individual conn_mgr gen_server processes for each pool
+* allow row results to be returned as binary
+
+## License
+
+Copyright (c) 2009-2011
+Bill Warnecke <bill@rupture.com>,
+Jacob Vorreuter <jacob.vorreuter@gmail.com>,
+Henning Diedrich <hd2010@eonblast.com>,
+Eonblast Corporation [http://www.eonblast.com].
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom
+the Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
View
50 samples/markedoc/SAMPLE2.md
@@ -0,0 +1,50 @@
+SAMPLE 2: EDown Readme of Jan 2011
+==================================
+```
+ --------------------------------------------------------------
+| THIS TEXT IS USED AS A SAMPLE TO ILLUSTRATE MARKEDOC USAGE. |
+| If you see this in your browser, you succeeded compiling it |
+| from markdown into an edoc. |
+ --------------------------------------------------------------
+'''
+
+<ulf.wiger@erlang-solutions.com>
+
+Status:
+-------
+
+More-or-less readable Markdown can be generated.
+A doclet needs to be written that also creates
+a markdown-based index and overview. Currently, the
+edoc_doclet creates an index.html and overview.html,
+which do not point to the .md files.
+
+To generate markdown edoc, run:
+
+`edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).`
+
+The `edown_xmerl` module is used as an xmerl export module.
+It converts xmerl's "simple xml" to Markdown syntax. Note that
+GH-flavored Markdown allows HTML markup (at least common tags),
+but doesn't expand markdown markup inside HTML markup, so the
+`edown_xmerl` module has to know the context in which it operates.
+
+NOTE
+----
+
+EDoc provides a plugin structure, so that one may specify own
+layout modules, export modules, and doclets. However, there is
+some overlap esp. between the layout and doclet modules, and
+several functions are expected to produce files on their own.
+This causes a problem for EDown, since it cannot handle frames.
+Instead, it would probably like to create one overview file with
+different sections. It would have been better to have a framework
+where some plugin functions identify the different files to be
+written, and the outline of each, other plugins convert to suitable
+content representation (e.g. HTML or Markdown), and EDoc then
+writes the files necessary.
+
+For now, EDown focuses on producing reasonable Markdown, rather
+than complying fully with the plugin framework. That is, the
+edown_doclet module will not go out of its way to function together
+with any other layout module than edown_layout, and vice versa.
View
248 samples/markedoc/SAMPLE3.md
@@ -0,0 +1,248 @@
+SAMPLE 3: markedoc 0.3 README of Feb 2011
+=========================================
+
+```
+ --------------------------------------------------------------
+| THIS TEXT IS USED AS A SAMPLE TO ILLUSTRATE MARKEDOC USAGE. |
+| If you see this in your browser, you succeeded compiling it |
+| from markdown into an edoc. As you see it's complex enough. |
+ --------------------------------------------------------------
+'''
+
+ **markedoc helps you keep your project's README.md in sync with your overview.edoc.**
+
+It is for use on Linux, FreeBSD and Mac OS X and any system that you can install **[sed][Requirements]** on.
+
+Status: [pre-beta][Status]. Quite stable and usable. See [Status][].
+
+markedoc translates [Markdown][] formatted texts into [Erlang][] [EDoc][] format, for inclusion into [EDoc][] generated html docs.
+
+The actual script file is in the bin folder: bin/markedoc.sed.
+
+markedoc is a mere [sed][] command file to convert markdown to edoc. It is part of the **[edown][]** project.
+
+Your contribution to make markedoc stable is highly [welcome][issues].
+
+[issues]: https://github.com/hdiedrich/markedoc/issues "Issue tracker"
+
+Use
+---
+At the command line for
+
+**FreeBSD, Mac OS X**
+ $ sed -E -f markedoc.sed <markdown file> > <edoc file>
+
+**Linux**
+ $ sed -r -f markedoc.sed <markdown file> > <edoc file>
+
+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.
+
+Requirements
+------------
+* **[sed][]**: is part of any Linux, FreeBSD and Mac OSX distribution, also see [Notes][].
+
+* **[Erlang/OTP][Erlang]**, see [Notes][].
+
+Test
+----
+
+ **FreeBSD, Mac OS X**
+ $ etc/test-bsd.sh
+
+ **Linux**
+ $ etc/test-linux.sh
+
+Then check html files as listed in the output.
+
+Sample
+------
+
+From project root (were the README.md file is), try out:
+
+ **FreeBSD, Mac OS X**
+ $ sed -E -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+
+ **Linux**
+ $ sed -r -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+
+This creates a SAMPLE.edoc file from SAMPLE1.md, which is then included in the EDoc generation. Point your browser at
+
+ samples/doc/overview-summary.html
+
+to see the result. For something only vaguely related but pretty, try:
+
+ $ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+
+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.
+
+For your own projects you'd copy markedoc.sed in the right place and do something like:
+
+ **FreeBSD, Mac OS X**
+ $ sed -E -f bin/markedoc.sed README.md > doc/README.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"."' '[]'
+
+ **Linux**
+ $ sed -r -f bin/markedoc.sed README.md > doc/README.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"."' '[]'
+
+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:
+
+ @docfile "doc/README.edoc"
+
+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.
+
+Accordingly, the sample stub overview.edoc used for the samples here, looks like this:
+
+ @author You
+ @title a markedoc sample doc
+ @version 0.2
+ @docfile "samples/doc/SAMPLE.edoc"
+
+Status
+------
+
+ **Pre-Beta**. Quite usable, but still likes to trip up EDoc now and then, which is kind of easy to do.
+
+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.
+
+ **Thanks!**
+
+Notes
+-----
+
+ **[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.
+
+[Erlang]: http://www.erlang.org/doc/
+
+ **[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.
+
+[EDoc]: http://www.erlang.org/doc/apps/edoc/chapter.html
+
+ **[edown][]** is an EDoc extension for generating Github-flavored Markdown. It uses edoc-style commented Erlang sources to create markdown files from them.
+
+[edown]: https://github.com/esl/edown
+
+ **[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).
+
+[Markdown]: http://daringfireball.net/projects/markdown/
+
+ **[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.
+
+[sed]: http://en.wikipedia.org/wiki/Sed
+[winsed]: http://gnuwin32.sourceforge.net/packages/sed.htm
+[sample]: https://github.com/Eonblast/Emysql/raw/master/README.md "This markdown file is translated alright by markedoc."
+
+Todo
+----
+* make work with non-FreeBSD sed
+* robust alternates not tested for some time
+* protect ampersands
+
+Development
+-----------
+To test markedoc, see '[Test][]', above. Or use
+
+ **FreeBSD**
+ sed -E -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/your-test-results/sample1.html
+ mv samples/doc/SAMPLE.edoc samples/your-test-results/SAMPLE1.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE2.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+ mv samples/doc/overview-summary.html samples/your-test-results/sample2.html
+ mv samples/doc/SAMPLE.edoc samples/your-test-results/SAMPLE2.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE3.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/your-test-results/sample3.html
+ mv samples/doc/SAMPLE.edoc samples/your-test-results/SAMPLE3.edoc
+
+Then check samples/your-test-results/sample1.html - sample3.html and compare with samples/what-you-should-see/sample1.html, sample2.html and samples/what-you-could-see/sample3.html.
+
+To create the reference samples:
+
+ **FreeBSD**
+ etc/make_samples.sh
+
+or do the following to create six samples and save the results into samples/what-you-should-see/ and samples/what-you-could-see/
+
+ **FreeBSD**
+ sed -E -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample1.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-should-see/SAMPLE1.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE2.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample2.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-should-see/SAMPLE2.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE3.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample3.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-should-see/SAMPLE3.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample1.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-could-see/SAMPLE1.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE2.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample2.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-could-see/SAMPLE2.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE3.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample3.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-could-see/SAMPLE3.edoc
+
+To test this very README.md, use markdown.lua, credit Niklas Frykholm, <niklas@frykholm.se>:
+
+ lua etc/markdown.lua README.md
+
+### HTML Special Signs
+http://www.mountaindragon.com/html/iso.htm
+
+
+License
+-------
+This script is free software. It comes without any warranty.
+
+Author
+------
+H. Diedrich <hd2010@eonblast.com>
+
+History
+-------
+
+02/03/11 - 0.3 - **rough edges polished:** Linux, FreeBSD, Mac OS X
+
+* added doc for Linux use
+* added support for multi-line '[..]: ... "..."' references
+* added footnote signs and sepcial chars:
+* dagger, double dagger: (+), (++), stars: (*), (**), (***)
+* superscript 1, 2, 3: (*1), (*2), (*3), copyright (C), (R), (TM),
+* guillemots <<, >> and middle dot ::
+* added test batches etc/test-bsd.sh and etc/test-linux.sh
+* added css sample in samples/what-you-could-see/
+* added classes for `<li>' list item tags for '[..]:...'-references
+* fixed italic and bold merker interference bullet points
+* eliminated [..]: part of '[..]:...'-references, flipping "..." to lead
+* dev: sample creation batch make_samples.sh added
+
+02/02/11 - 0.2 - **basics complete:** FreeBSD / Mac OS X
+
+* added support for === and --- headline format
+* fixed cutting off of last lines
+* fixed page-local anchor jumps
+* fixed space in javascript links
+* eliminated end-space requirement at end of '[..]:...'-style references.
+* eliminated need for echoing '@doc' first into edoc output file
+* added javascript title tag setting for '[..]:...'-style references.
+
+01/31/11 - 0.1 - **first release:** FreeBSD / Mac OS X
+
View
19 samples/markedoc/make_samples.sh
@@ -0,0 +1,19 @@
+echo "making markedoc samples"
+
+sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE1.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/what-you-should-see/sample1.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/what-you-should-see/SAMPLE1.edoc
+
+sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE2.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/what-you-should-see/sample2.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/what-you-should-see/SAMPLE2.edoc
+
+sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE3.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/what-you-should-see/sample3.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/what-you-should-see/SAMPLE3.edoc
+
+echo "done"
+echo "see samples/markedoc/what-you-should-see/sample1.html - sample3.html"
View
23 samples/markedoc/test-bsd.sh
@@ -0,0 +1,23 @@
+echo -n "testing markedoc - FreeBSD / Mac OS X: "
+
+echo -n "1 ... "
+sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE1.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[{def,{vsn,""}}]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/your-test-results/sample1.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/your-test-results/SAMPLE1.edoc
+
+echo -n "2 ... "
+sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE2.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/your-test-results/sample2.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/your-test-results/SAMPLE2.edoc
+
+echo -n "3 ... "
+sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE3.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/your-test-results/sample3.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/your-test-results/SAMPLE3.edoc
+
+echo "done."
+echo "=> now check samples/markedoc/your-test-results/sample1.html - sample3.html"
+echo "compare with samples/markedoc/what-you-should-see/sample1.html - sample2.html"
View
23 samples/markedoc/test-linux.sh
@@ -0,0 +1,23 @@
+echo -n "testing markedoc - Linux: "
+
+echo -n "1 ... "
+sed -r -f bin/markedoc.sed samples/markedoc/SAMPLE1.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[{def,{vsn,""}}]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/your-test-results/sample1.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/your-test-results/SAMPLE1.edoc
+
+echo -n "2 ... "
+sed -r -f bin/markedoc.sed samples/markedoc/SAMPLE2.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/your-test-results/sample2.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/your-test-results/SAMPLE2.edoc
+
+echo -n "3 ... "
+sed -r -f bin/markedoc.sed samples/markedoc/SAMPLE3.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/your-test-results/sample3.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/your-test-results/SAMPLE3.edoc
+
+echo "done."
+echo "=> now check samples/markedoc/your-test-results/sample1.html - sample3.html"
+echo "compare with samples/markedoc/what-you-should-see/sample1.html - sample2.html"
View
23 samples/markedoc/test-macosx.sh
@@ -0,0 +1,23 @@
+echo -n "testing markedoc - FreeBSD / Mac OS X: "
+
+echo -n "1 ... "
+sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE1.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[{def,{vsn,""}}]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/your-test-results/sample1.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/your-test-results/SAMPLE1.edoc
+
+echo -n "2 ... "
+sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE2.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/your-test-results/sample2.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/your-test-results/SAMPLE2.edoc
+
+echo -n "3 ... "
+sed -E -f bin/markedoc.sed samples/markedoc/SAMPLE3.md > samples/markedoc/doc/SAMPLE.edoc
+erl -noshell -run edoc_run application "'myapp'" '"samples/markedoc"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+mv samples/markedoc/doc/overview-summary.html samples/markedoc/your-test-results/sample3.html
+mv samples/markedoc/doc/SAMPLE.edoc samples/markedoc/your-test-results/SAMPLE3.edoc
+
+echo "done."
+echo "=> now check samples/markedoc/your-test-results/sample1.html - sample3.html"
+echo "compare with samples/markedoc/what-you-should-see/sample1.html - sample2.html"
View
BIN samples/markedoc/what-you-should-see/.DS_Store
Binary file not shown.
View
346 samples/markedoc/what-you-should-see/SAMPLE1.edoc
@@ -0,0 +1,346 @@
+@doc
+== SAMPLE 1: Emysql Readme of Jan 2011 ==
+```
+ --------------------------------------------------------------
+| THIS TEXT IS USED AS A SAMPLE TO ILLUSTRATE MARKEDOC USAGE. |
+| If you see this in your browser, you succeeded compiling it |
+| from markdown into an edoc. As you see it's quite complex |
+| and there is no 'cheating' involved. |
+ --------------------------------------------------------------
+'''
+
+Erlang MySQL driver, based on a rewrite at Electronic Arts&#153;. Supports prepared statements and stored procedures. For <a href="javascript:goto('samples')" onMouseOver="this.title=url('samples')">samples</a> and <a href="javascript:goto('docs')" onMouseOver="this.title=url('docs')">docs</a> see below.
+
+While you can use mysql via ODBC, using a driver like Emysql should perform better.
+
+This is a continuation fork of <a href="javascript:goto('1')" onMouseOver="this.title=url('1')">emysql</a> with <a href="javascript:goto('fixes')" onMouseOver="this.title=url('fixes')">fixes</a>, <a href="javascript:goto('updates')" onMouseOver="this.title=url('updates')">updates</a>, more <a href="javascript:goto('docs')" onMouseOver="this.title=url('docs')">docs</a> and <a href="javascript:goto('samples')" onMouseOver="this.title=url('samples')">samples</a>. <a href="javascript:goto('1')" onMouseOver="this.title=url('1')">emysql</a> is a clean rewrite of <a href="javascript:goto('2')" onMouseOver="this.title=url('2')">erlang-mysql-driver</a>.
+
+<hr/>
+
+ <b>&#171;Which fork should I use?&#187;</b> See <a href="javascript:goto('history')" onMouseOver="this.title=url('history')">history</a>.<br />
+ <b>&#171;Who used this fork?&#187;</b> Electronic Arts.<br />
+ <b>&#171;How do I ...?&#187;</b> See <a href="javascript:goto('samples')" onMouseOver="this.title=url('samples')">samples</a>.<br />
+
+ <b>Download:</b> <a href="https://github.com/Eonblast/Emysql/archives/master">https://github.com/Eonblast/Emysql/archives/master</a><br />
+ <b>Repository:</b> <a href="https://github.com/Eonblast/Emysql">https://github.com/Eonblast/Emysql</a><br />
+ <b>Docs:</b> <a href="http://eonblast.github.com/Emysql/">http://eonblast.github.com/Emysql/</a><br />
+
+<hr/>
+
+== Contents ==
+
+<li> <a href="javascript:goto('History')" onMouseOver="this.title=url('History')">History</a></li>
+<li> <a href="javascript:goto('Usage')" onMouseOver="this.title=url('Usage')">Usage</a></li>
+<li> <a href="javascript:goto('Samples')" onMouseOver="this.title=url('Samples')">Samples</a></li>
+<li> <a href="javascript:goto('Links')" onMouseOver="this.title=url('Links')">Links</a></li>
+<li> <a href="javascript:goto('Todo')" onMouseOver="this.title=url('Todo')">Todo</a></li>
+<li> <a href="javascript:goto('License')" onMouseOver="this.title=url('License')">License</a></li>
+
+<hr/>
+
+== History ==
+
+Open Source Erlang MySQL driver efforts are currently a fractured matter, at least for the higher functionality. There are four main choices:
+
+<li> <b>Yxa</b>: The first Erlang MySQL driver seems to have been written in 2005 by <a href="javascript:goto('ma')" onMouseOver="this.title=url('ma')">Magnus Ahltorp</a> at the <a href="javascript:goto('3')" onMouseOver="this.title=url('3')">Royal Institute of Technology</a>. It is the basis for the following two. The <a href="javascript:goto('4')" onMouseOver="this.title=url('4')">original mysql driver source</a> is stable since at least 2007, it is available as part of the SIP proxy <a href="javascript:goto('5')" onMouseOver="this.title=url('5')">Yxa 1.0</a> (hosted <a href="javascript:goto('6')" onMouseOver="this.title=url('6')">on github</a>).</li>
+
+<li> <b>ejabberd</b>: Already in 2006, a <a href="javascript:goto('7')" onMouseOver="this.title=url('7')">fork</a> was created by <a href="javascript:goto('mr')" onMouseOver="this.title=url('mr')">Mickael Remond</a> at <a href="javascript:goto('8')" onMouseOver="this.title=url('8')">Process One</a> to become part of the successful instant messaging server <a href="javascript:goto('9')" onMouseOver="this.title=url('9')">ejabberd</a> (also hosted <a href="javascript:goto('10')" onMouseOver="this.title=url('10')">at github</a>). It can be assumed to be as stable as the Yxa branch, and it didn't change anything in the lowest level, mysql_recv.erl. The differences to the original Yxa branch mainly consists of added inspection functions that help using query results, and an <a href="javascript:goto('11')" onMouseOver="this.title=url('11')">independent adoption</a> to the MySQL 4.1 client-server protocol. Also, the original Yxa branch has meanwhile adopted edoc comment format. Find a diff <a href="javascript:goto('12')" onMouseOver="this.title=url('12')">here</a>, one ignoring comment lines <a href="javascript:goto('13')" onMouseOver="this.title=url('13')">here</a>.</li>
+
+<li> <b>erlang-mysql-driver</b>: in 2006/07 <a href="javascript:goto('ys')" onMouseOver="this.title=url('ys')">Yariv Sadan</a> created a fork from the ejabberd branch, made it a standalone project, gave it the name that stuck, and hosted it at <a href="javascript:goto('15')" onMouseOver="this.title=url('15')">Google Code</a>. Before he moved on to work at Facebook, he had added higher level handling of prepared statements and transactions, and stated that he had improved connection pooling and logging. There were changes both in the original Yxa and the ejabberd branch after the forking off that seem to never have made their way into the erlang-mysql-driver branch, which now lies dormant since Oct '07. Docs were somewhat unsatisfying, as much as for the earlier branches. In Feb '10, Dave Smith started making some</li>
+<a href="javascript:goto('15')" onMouseOver="this.title=url('15')">updates</a> and put them on github, were the driver is now enjoying a couple of <a href="javascript:goto('16')" onMouseOver="this.title=url('16')">active forks</a> that make for a convincing case in favor of the github Network graph.
+
+<li> <b>Emysql</b> was started from scratch in 2009 by <a href="javascript:goto('jv')" onMouseOver="this.title=url('jv')">Jacob Vorreuter</a> and <a href="javascript:goto('bw')" onMouseOver="this.title=url('bw')">Bill Warnecke</a> at Electronic Arts, who rewrote the erlang-mysql-driver code because they felt it had been touched by so many people that it had become more complicated than necessary. In a way, the third layer module, mysql.erl, had over time started to become badly entangled with the second, mysql_conn.erl. According to Jacob, Emysql is pretty stable and ran without issue in a production environment at Electronic Arts. This fork is a continuation of <a href="javascript:goto('1')" onMouseOver="this.title=url('1')">their work</a>, including all their commits and adding <a href="javascript:goto('docs')" onMouseOver="this.title=url('docs')">documentation</a>, [samples], <a href="javascript:goto('fixes')" onMouseOver="this.title=url('fixes')">fixes</a> and extensions. </li>
+<br />
+<a href="javascript:goto('vb')" onMouseOver="this.title=url('vb')">Vitaliy Batichko</a> and
+<a href="javascript:goto('cr')" onMouseOver="this.title=url('cr')">Chris Rempel</a> have contributed updates to this branch. Thank you!
+
+<li class="ref url"> emysql:<a name="1" id="1" href="http://github.com/JacobVorreuter/emysql" target="_parent">http://github.com/JacobVorreuter/emysql</a></li>
+<li class="ref url"> erlang-mysql-driver:<a name="2" id="2" href="http://github.com/dizzyd/erlang-mysql-driver" target="_parent">http://github.com/dizzyd/erlang-mysql-driver</a></li>
+<li class="ref url"> Royal Institure of Technology:<a name="3" id="3" href="http://www.kth.se/" target="_parent">http://www.kth.se/</a></li>
+<li class="ref url"> Yxa mysql driver:<a name="4" id="4" href="https://github.com/fredrikt/yxa/tree/master/src/mysql" target="_parent">https://github.com/fredrikt/yxa/tree/master/src/mysql</a></li>
+<li class="ref url"> Yxa Home:<a name="5" id="5" href="http://www.stacken.kth.se/project/yxa/index.html" target="_parent">http://www.stacken.kth.se/project/yxa/index.html</a></li>
+<li class="ref url"> Yxa repository at github:<a name="6" id="6" href="https://github.com/fredrikt/yxa" target="_parent">https://github.com/fredrikt/yxa</a></li>
+<li class="ref url"> ejabberd mysql driver:<a name="7" id="7" href="http://svn.process-one.net/ejabberd-modules/mysql/trunk/" target="_parent">http://svn.process-one.net/ejabberd-modules/mysql/trunk/</a></li>
+<li class="ref url"> Process One Home:<a name="8" id="8" href="https://support.process-one.net" target="_parent">https://support.process-one.net</a></li>
+<li class="ref url"> ejabberd Home:<a name="9" id="9" href="http://www.process-one.net/en/ejabberd/" target="_parent">http://www.process-one.net/en/ejabberd/</a></li>
+<li class="ref url"> ejabberd repository at github:<a name="10" id="10" href="https://github.com/processone/ejabberd/" target="_parent">https://github.com/processone/ejabberd/</a></li>
+<li class="ref url"> ejabberd MySQL 4.1. patch:<a name="11" id="11" href="https://support.process-one.net/doc/display/CONTRIBS/Yxa" target="_parent">https://support.process-one.net/doc/display/CONTRIBS/Yxa</a></li>
+<li class="ref url"> Diff of Yxa and ejabberd mysql drivers:<a name="12" id="12" href="https://github.com/Eonblast/Emysql/tree/master/doc/diff-ejabberd-yxa.txt" target="_parent">https://github.com/Eonblast/Emysql/tree/master/doc/diff-ejabberd-yxa.txt</a></li>
+<li class="ref url"> Diff of Yxa and ejabberd mysql drivers ignoring comment changes:<a name="13" id="13" href="https://github.com/Eonblast/Emysql/tree/master/doc/diff-ejabberd-yxa-2.txt" target="_parent">https://github.com/Eonblast/Emysql/tree/master/doc/diff-ejabberd-yxa-2.txt</a></li>
+<li class="ref url"> original erlang-mysql-driver:<a name="14" id="14" href="http://code.google.com/p/erlang-mysql-driver/" target="_parent">http://code.google.com/p/erlang-mysql-driver/</a></li>
+<li class="ref url"> Dave Smith's erlang-mysql-driver at github, currently not maintained:<a name="15" id="15" href="http://github.com/dizzyd/erlang-mysql-driver" target="_parent">http://github.com/dizzyd/erlang-mysql-driver</a></li>
+<li class="ref url"> Fork graph of erlang-mysql-driver at github:<a name="16" id="16" href="https://github.com/dizzyd/erlang-mysql-driver/network" target="_parent">https://github.com/dizzyd/erlang-mysql-driver/network</a></li>
+
+<li class="ref email"> Magnus Ahltorp:<a name="ma" id="ma" href="mailto:ahltorp@nada.kth.se">ahltorp@nada.kth.se</a></li>
+<li class="ref url"> <a name="ys" id="ys" href="http://yarivsblog.blogspot.com/" target="_parent">http://yarivsblog.blogspot.com/</a></li>
+<li class="ref email"> <a name="bw" id="bw" href="mailto:bill@rupture.com">bill@rupture.com</a></li>
+<li class="ref url"> <a name="jv" id="jv" href="https://github.com/JacobVorreuter" target="_parent">https://github.com/JacobVorreuter</a></li>
+<li class="ref url"> <a name="vb" id="vb" href="https://github.com/bva" target="_parent">https://github.com/bva</a></li>
+<li class="ref url"> Chris Rempel:<a name="cr" id="cr" href="https://github.com/csrl" target="_parent">https://github.com/csrl</a></li>
+<li class="ref email"> Henning Diedrich:<a name="hd" id="hd" href="mailto:hd2010@eonblast.com">hd2010@eonblast.com</a></li>
+<li class="ref email"> Mickael Remond:<a name="mr" id="mr" href="mailto:mickael.remond@process-one.net">mickael.remond@process-one.net</a></li>
+
+<li class="ref url"> Emysql fixes:<a name="fixes" id="fixes" href="https://github.com/Eonblast/Emysql/issues/closed" target="_parent">https://github.com/Eonblast/Emysql/issues/closed</a></li>
+<li class="ref url"> Emysql online docs:<a name="docs" id="docs" href="http://eonblast.github.com/Emysql/" target="_parent">http://eonblast.github.com/Emysql/</a></li>
+
+== Usage ==
+
+==== Start the application ====
+
+```
+ crypto:start(),
+ application:start(emysql).
+'''
+
+==== Add a pool ====
+```
+ % emysql:add_pool(PoolName, PoolSize, Username, Password, Host, Port, Database, Encoding) ->
+ % ok | {error, pool_already_exists}
+ % PoolName = atom()
+ % PoolSize = integer()
+ % Username = string()
+ % Password = string()
+ % Host = string()
+ % Port = integer()
+ % Database = string()
+ % Encoding = atom()
+
+ emysql:add_pool(mypoolname, 1, "username", "mypassword", "localhost", 3306, "mydatabase", utf8).
+'''
+
+==== Record Types ====
+```
+ -record(ok_packet, {seq_num, affected_rows, insert_id, status, warning_count, msg}).
+ -record(error_packet, {seq_num, code, msg}).
+ -record(result_packet, {seq_num, field_list, rows, extra}).
+'''
+
+==== Executing SQL statements ====
+```
+ % emysql:execute(PoolName, Statement) -> result_packet() | ok_packet() | error_packet()
+ % PoolName = atom()
+ % Statement = string() | binary()
+
+ emysql:execute(mypoolname, <<"SELECT * from mytable">>).
+ #result_packet{field_list=[...], rows=[...]}
+
+ emysql:execute(mypoolname, <<"UPDATE mytable SET bar = 'baz' WHERE id = 1">>).
+ #ok_packet{affected_rows=1}
+'''
+
+==== Executing prepared statements ====
+```
+ % emysql:prepare(StmtName, Statement) -> ok
+ % StmtName = atom()
+ % Statement = binary() | string()
+'''
+
+```
+ emysql:prepare(my_stmt, <<"SELECT * from mytable WHERE id = ?">>).
+ ok
+
+ % emysql:execute(PoolName, StmtName, Args) -> result_packet() | ok_packet() | error_packet()
+ % StmtName = atom()
+ % Args = [term()]
+'''
+
+```
+ emysql:execute(mypoolname, my_stmt, [1]).
+ #result_packet{field_list=[...], rows=[...]}
+'''
+
+==== Executing stored procedures ====
+
+```
+ % emysql:execute(PoolName, StmtName, Args) -> result_packet() | ok_packet() | error_packet()
+ % StmtName = atom()
+ % Args = [term()]
+'''
+
+```
+ emysql:execute(hello_pool,
+ <<"create procedure sp_hello() begin select * from hello_table; end">>).
+ {ok_packet,1,0,0,2,0,[]}
+'''
+
+```
+ emysql:execute(hello_pool, <<"call sp_hello();">>).
+ [{result_packet,6,
+ [{field,2,<<"def">>,<<"hello_database">>,<<"hello_table">>,
+ <<"hello_table">>,<<"hello_text">>,<<"hello_text">>,
+ 254,<<>>,33,60,0,0}],
+ [[<<"Hello World!">>],[<<"Hello World!">>]],
+ <<>>},
+ {ok_packet,7,0,0,34,0,[]}]
+'''
+
+==== Converting Row Data To Records ====
+```
+ % emysql_util:as_record(ResultPacket, RecordName, Fields) -> Result
+ % ResultPacket = result_packet()
+ % RecordName = atom() (the name of the record to generate)
+ % Fields = [atom()] (the field names to generate for each record)
+ % Result = [record()]
+
+ -module(fetch_example).
+ -record(foo, {bar, baz, bat}).
+
+ fetch_foo() ->
+ Result = emysql:execute(pool1, <<"select bar, baz, bat from foo">>),
+ Recs = emysql_util:as_record(Result, foo, record_info(fields, foo)),
+ [begin
+ io:format("foo: ~p, ~p, ~p~n", [Foo#foo.bar, Foo#foo.baz, Foo#foo.bat])
+ end || Foo <- Recs].
+'''
+
+== Getting Emysql ==
+
+```
+ $ git clone git://github.com/Eonblast/Emysql.git Emysql
+
+'''
+== Samples ==
+
+==== Hello World&#42; ====
+
+This is a hello world program. Follow the three steps below to try it out.
+```
+
+ -module(a_hello).
+ -export([run/0]).
+
+ run() ->
+
+ crypto:start(),
+ application:start(emysql),
+
+ emysql:add_pool(hello_pool, 1,
+ "hello_username", "hello_password", "localhost", 3306,
+ "hello_database", utf8),
+
+ emysql:execute(hello_pool,
+ <<"INSERT INTO hello_table SET hello_text = 'Hello World!'">>),
+
+ Result = emysql:execute(hello_pool,
+ <<"select hello_text from hello_table">>),
+
+ io:format("~n~p~n", [Result]).
+'''
+
+
+We come back to that source, but first:
+
+==== Building Emysql ====
+
+Build emysql.app, using make:
+
+```
+ $ cd Emysql
+ $ make
+'''
+
+
+==== Sample database ====
+
+For the above sample, create a local mysql database. You should have a mysql server installed and running:
+```
+
+ $ mysql [-u<user> -p]
+ mysql> create database hello_database;
+ mysql> use hello_database;
+ mysql> create table hello_table (hello_text char(20));
+ mysql> grant all privileges on hello_database.* to hello_username@localhost identified by 'hello_password';
+'''
+
+==== Run Hello ====
+
+Be sure to have ./ebin in your Erlang path. Now copy the Hello World source above at '&#42;' into a file hello.erl and run it (in the Emysql root directory):
+
+```
+ $ erlc hello.erl
+ $ erl -pa ../ebin -s hello run -s init stop -noshell
+'''
+
+See more sample programms, below.
+
+==== Running the Samples ====
+Sample programs are in ./samples.
+
+<li> <a href="http://github.com/Eonblast/Emysql/blob/master/samples/a_hello.erl">a_hello</a> - Hello World</li>
+<li> <a href="http://github.com/Eonblast/Emysql/blob/master/samples/a_hello2.erl">a_hello2</a> - Hello World somewhat rawer</li>
+<li> <a href="http://github.com/Eonblast/Emysql/blob/master/samples/b_rows_as_records.erl">b_rows_as_records</a> - Using Erlang records to access result rows</li>
+<li> <a href="http://github.com/Eonblast/Emysql/blob/master/samples/c_stored_procedure.erl">c_stored_procedure</a> - Using Stored procedures</li>
+
+To run the samples, create the database as listed above at localhost, and:
+
+```
+ $ cd samples
+ $ ./a_hello
+ $ ./b_raw
+ $ ./d_rows_as_records
+ $ ./e_prepared_statement
+ $ ./e_stored_procedure
+
+'''
+or make emysql.app and start a_hello etc. manually along these lines (but
+first create the database as listed above):
+
+```
+ $ make
+ $ cd samples
+ $ erlc a_hello.erl
+ $ erl -pa ../ebin -s a_hello run -s init stop -noshell
+'''
+
+== Links ==
+
+<li> <a href="http://github.com/Eonblast/Emysql">Emysql on Github</a></li>
+<li> <a href="https://github.com/fredrikt/yxa/tree/master/src/mysql">Original Yxa</a> mysql driver</li>
+<li> <a href="http://svn.process-one.net/ejabberd-modules/mysql/trunk/">ejabberd fork</a></li>
+<li> <a href="http://code.google.com/p/erlang-mysql-driver/">'erlang-mysql-driver'</a></li>
+<li> <a href="http://github.com/dizzyd/erlang-mysql-driver">Dave Smith's erlang-mysql-driver fork</a></li>
+<li> <a href="https://github.com/JoelPM/erlang-mysql-driver">A maintained erlang-mysql-driver</a> fork</li>
+<li> <a href="https://github.com/chernomor/erlang-mysql-driver">Another maintained&#134; erlang-mysql-driver</a> fork</li>
+<li> <a href="http://forge.mysql.com/wiki/MySQL_Internals_ClientServer_Protocol">MySQL Client Server Protocol</a></li>
+<li> <a href="ftp://ftp.fu-berlin.de/unix/databases/mysql/Downloads/MySQL-5.5/mysql-5.5.8.tar.gz">MySQL 5.5 Source</a></li>
+
+&#134;maintained at the time of writing, Jan 2011.
+
+== TODO ==
+<li> decrementing pool size could close sockets that are in use</li>
+<li> spawn individual conn_mgr gen_server processes for each pool</li>
+<li> allow row results to be returned as binary</li>
+
+== License ==
+
+Copyright &#169; 2009-2011
+Bill Warnecke <a href="mailto:bill@rupture.com">bill@rupture.com</a>,
+Jacob Vorreuter <a href="mailto:jacob.vorreuter@gmail.com">jacob.vorreuter@gmail.com</a>,
+Henning Diedrich <a href="mailto:hd2010@eonblast.com">hd2010@eonblast.com</a>,
+Eonblast Corporation [http://www.eonblast.com].
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom
+the Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+<script>
+// Jump directly to a referenced url given in trailing '[]:...'-notation
+function goto(tag) { parent.document.location.href = url(tag); }
+function url(tag) { var o=document.getElementById(tag); return o ? o.href : '#'+tag; }
+</script>
View
53 samples/markedoc/what-you-should-see/SAMPLE2.edoc
@@ -0,0 +1,53 @@
+@doc
+== SAMPLE 2: EDown Readme of Jan 2011 ==
+```
+ --------------------------------------------------------------
+| THIS TEXT IS USED AS A SAMPLE TO ILLUSTRATE MARKEDOC USAGE. |
+| If you see this in your browser, you succeeded compiling it |
+| from markdown into an edoc. |
+ --------------------------------------------------------------
+'''
+
+<a href="mailto:ulf.wiger@erlang-solutions.com">ulf.wiger@erlang-solutions.com</a>
+
+=== Status: ===
+
+More-or-less readable Markdown can be generated.
+A doclet needs to be written that also creates
+a markdown-based index and overview. Currently, the
+edoc_doclet creates an index.html and overview.html,
+which do not point to the .md files.
+
+To generate markdown edoc, run:
+
+<code>edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).</code>
+
+The <code>edown_xmerl</code> module is used as an xmerl export module.
+It converts xmerl's "simple xml" to Markdown syntax. Note that
+GH-flavored Markdown allows HTML markup (at least common tags),
+but doesn't expand markdown markup inside HTML markup, so the
+<code>edown_xmerl</code> module has to know the context in which it operates.
+
+=== NOTE ===
+
+EDoc provides a plugin structure, so that one may specify own
+layout modules, export modules, and doclets. However, there is
+some overlap esp. between the layout and doclet modules, and
+several functions are expected to produce files on their own.
+This causes a problem for EDown, since it cannot handle frames.
+Instead, it would probably like to create one overview file with
+different sections. It would have been better to have a framework
+where some plugin functions identify the different files to be
+written, and the outline of each, other plugins convert to suitable
+content representation (e.g. HTML or Markdown), and EDoc then
+writes the files necessary.
+
+For now, EDown focuses on producing reasonable Markdown, rather
+than complying fully with the plugin framework. That is, the
+edown_doclet module will not go out of its way to function together
+with any other layout module than edown_layout, and vice versa.
+<script>
+// Jump directly to a referenced url given in trailing '[]:...'-notation
+function goto(tag) { parent.document.location.href = url(tag); }
+function url(tag) { var o=document.getElementById(tag); return o ? o.href : '#'+tag; }
+</script>
View
280 samples/markedoc/what-you-should-see/SAMPLE3.edoc
@@ -0,0 +1,280 @@
+@doc
+== SAMPLE 3: markedoc 0.3 README of Feb 2011 ==
+
+```
+ --------------------------------------------------------------
+| THIS TEXT IS USED AS A SAMPLE TO ILLUSTRATE MARKEDOC USAGE. |
+| If you see this in your browser, you succeeded compiling it |
+| from markdown into an edoc. As you see it's complex enough. |
+ --------------------------------------------------------------
+'''
+
+ <b>markedoc helps you keep your project's README.md in sync with your overview.edoc.</b>
+
+It is for use on Linux, FreeBSD and Mac OS X and any system that you can install <b><a href="javascript:goto('Requirements')" onMouseOver="this.title=url('Requirements')">sed</a></b> on.
+
+Status: <a href="javascript:goto('Status')" onMouseOver="this.title=url('Status')">pre-beta</a>. Quite stable and usable. See <a href="javascript:goto('Status')" onMouseOver="this.title=url('Status')">Status</a>.
+
+markedoc translates <a href="javascript:goto('Markdown')" onMouseOver="this.title=url('Markdown')">Markdown</a> formatted texts into <a href="javascript:goto('Erlang')" onMouseOver="this.title=url('Erlang')">Erlang</a> <a href="javascript:goto('EDoc')" onMouseOver="this.title=url('EDoc')">EDoc</a> format, for inclusion into <a href="javascript:goto('EDoc')" onMouseOver="this.title=url('EDoc')">EDoc</a> generated html docs.
+
+The actual script file is in the bin folder: bin/markedoc.sed.
+
+markedoc is a mere <a href="javascript:goto('sed')" onMouseOver="this.title=url('sed')">sed</a> command file to convert markdown to edoc. It is part of the <b><a href="javascript:goto('edown')" onMouseOver="this.title=url('edown')">edown</a></b> project.
+
+Your contribution to make markedoc stable is highly <a href="javascript:goto('issues')" onMouseOver="this.title=url('issues')">welcome</a>.
+
+<li class="ref url"> Issue tracker:<a name="issues" id="issues" href="https://github.com/hdiedrich/markedoc/issues" target="_parent">https://github.com/hdiedrich/markedoc/issues</a></li>
+
+=== Use ===
+At the command line for
+
+<b>FreeBSD, Mac OS X</b>
+```
+ $ sed -E -f markedoc.sed <markdown file> > <edoc file>
+'''
+
+<b>Linux</b>
+```
+ $ sed -r -f markedoc.sed <markdown file> > <edoc file>
+'''
+
+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.
+
+=== Requirements ===
+<li> <b><a href="javascript:goto('sed')" onMouseOver="this.title=url('sed')">sed</a></b>: is part of any Linux, FreeBSD and Mac OSX distribution, also see <a href="javascript:goto('Notes')" onMouseOver="this.title=url('Notes')">Notes</a>.</li>
+
+<li> <b><a href="javascript:goto('Erlang')" onMouseOver="this.title=url('Erlang')">Erlang/OTP</a></b>, see <a href="javascript:goto('Notes')" onMouseOver="this.title=url('Notes')">Notes</a>.</li>
+
+=== Test ===
+
+ <b>FreeBSD, Mac OS X</b>
+```
+ $ etc/test-bsd.sh
+'''
+
+ <b>Linux</b>
+```
+ $ etc/test-linux.sh
+'''
+
+Then check html files as listed in the output.
+
+=== Sample ===
+
+From project root (were the README.md file is), try out:
+
+ <b>FreeBSD, Mac OS X</b>
+```
+ $ sed -E -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+'''
+
+ <b>Linux</b>
+```
+ $ sed -r -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+'''
+
+This creates a SAMPLE.edoc file from SAMPLE1.md, which is then included in the EDoc generation. Point your browser at
+
+```
+ samples/doc/overview-summary.html
+'''
+
+to see the result. For something only vaguely related but pretty, try:
+
+```
+ $ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+'''
+
+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.
+
+For your own projects you'd copy markedoc.sed in the right place and do something like:
+
+ <b>FreeBSD, Mac OS X</b>
+```
+ $ sed -E -f bin/markedoc.sed README.md > doc/README.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"."' '[]'
+'''
+
+ <b>Linux</b>
+```
+ $ sed -r -f bin/markedoc.sed README.md > doc/README.edoc
+ $ erl -noshell -run edoc_run application "'myapp'" '"."' '[]'
+'''
+
+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:
+
+```
+ @@docfile "doc/README.edoc"
+'''
+
+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.
+
+Accordingly, the sample stub overview.edoc used for the samples here, looks like this:
+
+```
+ @@author You
+ @@title a markedoc sample doc
+ @@version 0.2
+ @@docfile "samples/doc/SAMPLE.edoc"
+'''
+
+=== Status ===
+
+ <b>Pre-Beta</b>. Quite usable, but still likes to trip up EDoc now and then, which is kind of easy to do.
+
+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 <a href="javascript:goto('sample')" onMouseOver="this.title=url('sample')">source sample</a>, which works alright, it's quite a lot that <em>does</em> 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.
+
+ <b>Thanks!</b>
+
+=== Notes ===
+
+ <b><a href="javascript:goto('Erlang')" onMouseOver="this.title=url('Erlang')">Erlang</a></b> 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.
+
+<li class="ref url"> <a name="Erlang" id="Erlang" href="http://www.erlang.org/doc/" target="_parent">http://www.erlang.org/doc/</a></li>
+
+ <b><a href="javascript:goto('EDoc')" onMouseOver="this.title=url('EDoc')">EDoc</a></b> 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.
+
+<li class="ref url"> <a name="EDoc" id="EDoc" href="http://www.erlang.org/doc/apps/edoc/chapter.html" target="_parent">http://www.erlang.org/doc/apps/edoc/chapter.html</a></li>
+
+ <b><a href="javascript:goto('edown')" onMouseOver="this.title=url('edown')">edown</a></b> is an EDoc extension for generating Github-flavored Markdown. It uses edoc-style commented Erlang sources to create markdown files from them.
+
+<li class="ref url"> <a name="edown" id="edown" href="https://github.com/esl/edown" target="_parent">https://github.com/esl/edown</a></li>
+
+ <b><a href="javascript:goto('Markdown')" onMouseOver="this.title=url('Markdown')">Markdown</a></b> 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).
+
+<li class="ref url"> <a name="Markdown" id="Markdown" href="http://daringfireball.net/projects/markdown/" target="_parent">http://daringfireball.net/projects/markdown/</a></li>
+
+ <b><a href="javascript:goto('sed')" onMouseOver="this.title=url('sed')">sed</a></b> ('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 <a href="javascript:goto('winsed')" onMouseOver="this.title=url('winsed')">one for Windows</a>, too.
+
+<li class="ref url"> <a name="sed" id="sed" href="http://en.wikipedia.org/wiki/Sed" target="_parent">http://en.wikipedia.org/wiki/Sed</a></li>
+<li class="ref url"> <a name="winsed" id="winsed" href="http://gnuwin32.sourceforge.net/packages/sed.htm" target="_parent">http://gnuwin32.sourceforge.net/packages/sed.htm</a></li>
+<li class="ref url"> This markdown file is translated alright by markedoc.:<a name="sample" id="sample" href="https://github.com/Eonblast/Emysql/raw/master/README.md" target="_parent">https://github.com/Eonblast/Emysql/raw/master/README.md</a></li>
+
+=== Todo ===
+<li> make work with non-FreeBSD sed</li>
+<li> robust alternates not tested for some time</li>
+<li> protect ampersands</li>
+
+=== Development ===
+To test markedoc, see '<a href="javascript:goto('Test')" onMouseOver="this.title=url('Test')">Test</a>', above. Or use
+
+ <b>FreeBSD</b>
+```
+ sed -E -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/your-test-results/sample1.html
+ mv samples/doc/SAMPLE.edoc samples/your-test-results/SAMPLE1.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE2.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+ mv samples/doc/overview-summary.html samples/your-test-results/sample2.html
+ mv samples/doc/SAMPLE.edoc samples/your-test-results/SAMPLE2.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE3.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/your-test-results/sample3.html
+ mv samples/doc/SAMPLE.edoc samples/your-test-results/SAMPLE3.edoc
+
+'''
+Then check samples/your-test-results/sample1.html - sample3.html and compare with samples/what-you-should-see/sample1.html, sample2.html and samples/what-you-could-see/sample3.html.
+
+To create the reference samples:
+
+ <b>FreeBSD</b>
+```
+ etc/make_samples.sh
+'''
+
+or do the following to create six samples and save the results into samples/what-you-should-see/ and samples/what-you-could-see/
+
+ <b>FreeBSD</b>
+```
+ sed -E -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample1.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-should-see/SAMPLE1.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE2.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample2.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-should-see/SAMPLE2.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE3.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample3.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-should-see/SAMPLE3.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE1.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample1.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-could-see/SAMPLE1.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE2.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample2.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-could-see/SAMPLE2.edoc
+
+ sed -E -f bin/markedoc.sed samples/SAMPLE3.md > samples/doc/SAMPLE.edoc
+ erl -noshell -run edoc_run application "'myapp'" '"samples"' '[{def,{vsn,""}},{stylesheet, "markedoc.css"}]'
+ mv samples/doc/overview-summary.html samples/what-you-could-see/sample3.html
+ mv samples/doc/SAMPLE.edoc samples/what-you-could-see/SAMPLE3.edoc
+'''
+
+To test this very README.md, use markdown.lua, credit Niklas Frykholm, <a href="mailto:niklas@frykholm.se">niklas@frykholm.se</a>:
+
+```
+ lua etc/markdown.lua README.md
+
+'''
+=== HTML Special Signs ===
+http://www.mountaindragon.com/html/iso.htm
+
+
+=== License ===
+This script is free software. It comes without any warranty.
+
+=== Author ===
+H. Diedrich <a href="mailto:hd2010@eonblast.com">hd2010@eonblast.com</a>
+
+=== History ===
+```
+
+'''
+02/03/11 - 0.3 - <b>rough edges polished:</b> Linux, FreeBSD, Mac OS X
+
+<li> added doc for Linux use</li>
+<li> added support for multi-line '[..]: ... "..."' references</li>
+<li> added footnote signs and sepcial chars:</li>
+<li> dagger, double dagger: &#134;, &#135;, stars: &#42;, &#42;&#42;, &#42;&#42;&#42; </li>
+<li> superscript 1, 2, 3: &#185;, &#178;, &#179;, copyright &#169;, &#174;, &#153;, </li>
+<li> guillemots &#171;, &#187; and middle dot &#183;</li>
+<li> added test batches etc/test-bsd.sh and etc/test-linux.sh</li>
+<li> added css sample in samples/what-you-could-see/ </li>
+<li> added classes for `<li>' list item tags for '[..]:...'-references</li>
+<li> fixed italic and bold merker interference bullet points</li>
+<li> eliminated [..]: part of '[..]:...'-references, flipping "..." to lead</li>
+<li> dev: sample creation batch make_samples.sh added</li>
+```
+
+'''
+02/02/11 - 0.2 - <b>basics complete:</b> FreeBSD / Mac OS X
+
+<li> added support for === and --- headline format</li>
+<li> fixed cutting off of last lines </li>
+<li> fixed page-local anchor jumps</li>
+<li> fixed space in javascript links</li>
+<li> eliminated end-space requirement at end of '[..]:...'-style references.</li>
+<li> eliminated need for echoing '@@doc' first into edoc output file</li>
+<li> added javascript title tag setting for '[..]:...'-style references.</li>
+```
+
+'''
+01/31/11 - 0.1 - <b>first release:</b> FreeBSD / Mac OS X
+``` '''
+<script>
+// Jump directly to a referenced url given in trailing '[]:...'-notation
+function goto(tag) { parent.document.location.href = url(tag); }
+function url(tag) { var o=document.getElementById(tag); return o ? o.href : '#'+tag; }
+</script>
View
BIN samples/markedoc/what-you-should-see/erlang.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
BIN samples/markedoc/what-you-should-see/markedoc-footer.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
202 samples/markedoc/what-you-should-see/markedoc.css
@@ -0,0 +1,202 @@
+/* standard EDoc style sheet */
+body {
+ font-family: Verdana, Arial, Helvetica, sans-serif;
+ font-size: .9em;
+ margin-left: 2em;
+ margin-right: 2em;
+ margin-top: 2em;
+ margin-bottom: 2em;
+ color: #000000;
+ background-color: #ffffff;
+}
+h1 {
+ margin-left: 0;
+ font-size: 3em;
+}
+h2 {
+ margin-left: -.3em;
+ font-size: 2em;
+}
+
+h2.indextitle {
+
+ font-size: 1em;
+}
+
+h2.indextitle table {
+ border-collapse: separate;
+ border-bottom-right-radius: 1em;
+ border: 1px solid #3070a0;
+ padding: 1em;
+
+ font-size: 0.9em;
+}
+
+h2.indextitle table tr td {
+ background-color: #deeefe;
+ border: 0;
+ border-bottom: 1px solid white;
+}
+
+h3 {
+ margin-left: -.3em;
+ font-size: 1.8em;
+}
+
+h4 {
+ margin-left: -.3em;
+ font-size: 1.5em;
+}
+
+div.navbar {
+ color: white;
+ font-weight: bold;
+ text-size: 0.9em;
+ background-color: #3070a0;
+ padding: 0.2em;
+ border-bottom: 1em solid #f09840;
+ border-top-left-radius: 1em;
+}
+h2.indextitle {
+ color: white;
+ padding: 0.4em;
+ background-color: #3070a0;
+ border-bottom: 10px solid #f09840;
+ border-top-left-radius: 1em;
+}
+
+h3.function,h3.typedecl {
+ color: white;
+ background-color: #3070a0;
+ padding-left: 1em;
+ border-bottom: 5px solid #f09840;
+ border-top-left-radius: 1em;
+}
+
+div.spec {
+ font-weight: bold;
+ margin-left: 0em;
+ padding: .2em 1.1em .2em;
+ background-color: #eeeeee;
+ border-bottom-right-radius: 1em;
+
+}
+a { color: inherit; padding: 2px; text-decoration: none; }
+
+a.module,a.package {
+ text-decoration:none
+}
+a:hover {
+ background-color: #deeefe;
+ color: navy;
+}
+
+a.module:hover,a.package:hover {
+ background-color: #deeefe;
+}
+ul.definitions {
+ list-style-type: none;
+}
+
+ul.index {
+ list-style-type: none;
+ border-collapse: separate;
+ border-bottom-right-radius: 1em;
+ border: 1px solid #3070a0;
+ padding: 1em;
+
+ font-size: 1.1em;
+}
+
+ul.index li {
+ background-color: #feeede;
+ border: 0;
+ border-bottom: 1px solid white;
+ padding: 2px;
+}
+
+ul {
+ list-style-type: square;
+}
+table {
+ border-collapse: collapse;
+}
+
+table.index {
+ border-collapse: separate;
+ border-bottom-right-radius: 1em;
+ border: 1px solid #3070a0;
+ padding: 1em;
+
+ font-size: 0.9em;
+}
+
+table.index td {
+ background-color: #deeefe;
+ border: 0;
+ border-bottom: 1px solid white;
+}
+
+
+table.index td a:hover {
+ background-color: #feeede;
+}
+
+td {
+ padding: 2px;
+}
+
+code {
+ font-size: 1.1em;
+}
+
+div.navbar {
+ background:url("markedoc-footer.png") no-repeat right top;
+}
+
+
+div.navbar a {
+ color: lightblue;
+ font-size: 0.9em;
+ font-weight: bold;
+ margin-left:1em;
+ line-height: 1em;
+}
+
+img {
+ margin-right: 10px;
+
+ }
+
+a {
+ color: navy;
+}
+
+h1 a, h2 a, h3 a, h4 a, h5 a {
+ color: black;
+ }
+
+h3.function a {
+ color: white;
+ }
+
+pre { margin: 0;
+ margin-top: 1em;
+ margin-bottom: 1em;
+ padding: 1.2em;
+ background-color: #f0f4f8;
+ border-radius: 1em;
+ line-height: 1.3em;
+ color: #101000; }
+span.comment {
+ color: dimgrey;
+ }
+
+li.ref {
+ background-color: #fff8e8;
+ padding: 0.1em;
+ margin-left: 0em;
+ padding-left: 1em;
+ list-style-type:square;
+ font-variant: small-caps;
+ }
View
321 samples/markedoc/what-you-should-see/sample1.html
@@ -0,0 +1,321 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<title> A Markedoc Sample Doc</title>
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
+</head>
+<body bgcolor="white">
+<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
+<h1> A Markedoc Sample Doc</h1>
+<p><b>Version:</b> 0.3 / edown</p>
+<p><b>Authors:</b> You!.</p>
+
+<h3><a name="SAMPLE_1:_Emysql_Readme_of_Jan_2011">SAMPLE 1: Emysql Readme of Jan 2011</a></h3>
+<pre> --------------------------------------------------------------
+| THIS TEXT IS USED AS A SAMPLE TO ILLUSTRATE MARKEDOC USAGE. |
+| If you see this in your browser, you succeeded compiling it |
+| from markdown into an edoc. As you see it's quite complex |
+| and there is no 'cheating' involved. |
+ --------------------------------------------------------------</pre>
+
+<p>Erlang MySQL driver, based on a rewrite at Electronic Arts™. Supports prepared statements and stored procedures. For <a href="javascript:goto('samples')" onMouseOver="this.title=url('samples')">samples</a> and <a href="javascript:goto('docs')" onMouseOver="this.title=url('docs')">docs</a> see below.</p>
+
+<p>While you can use mysql via ODBC, using a driver like Emysql should perform better. </p>
+
+<p>This is a continuation fork of <a href="javascript:goto('1')" onMouseOver="this.title=url('1')">emysql</a> with <a href="javascript:goto('fixes')" onMouseOver="this.title=url('fixes')">fixes</a>, <a href="javascript:goto('updates')" onMouseOver="this.title=url('updates')">updates</a>, more <a href="javascript:goto('docs')" onMouseOver="this.title=url('docs')">docs</a> and <a href="javascript:goto('samples')" onMouseOver="this.title=url('samples')">samples</a>. <a href="javascript:goto('1')" onMouseOver="this.title=url('1')">emysql</a> is a clean rewrite of <a href="javascript:goto('2')" onMouseOver="this.title=url('2')">erlang-mysql-driver</a>. </p>
+
+<hr>
+
+ <p><b>«Which fork should I use?»</b> See <a href="javascript:goto('history')" onMouseOver="this.title=url('history')">history</a>.<br>
+ <b>«Who used this fork?»</b> Electronic Arts.<br>
+ <b>«How do I ...?»</b> See <a href="javascript:goto('samples')" onMouseOver="this.title=url('samples')">samples</a>.<br></p>
+
+ <p><b>Download:</b> <a href="https://github.com/Eonblast/Emysql/archives/master">https://github.com/Eonblast/Emysql/archives/master</a><br>
+ <b>Repository:</b> <a href="https://github.com/Eonblast/Emysql">https://github.com/Eonblast/Emysql</a><br>
+ <b>Docs:</b> <a href="http://eonblast.github.com/Emysql/">http://eonblast.github.com/Emysql/</a><br></p>
+
+<hr>
+
+<h3><a name="Contents">Contents</a></h3>
+
+<p><li> <a href="javascript:goto('History')" onMouseOver="this.title=url('History')">History</a></li>
+<li> <a href="javascript:goto('Usage')" onMouseOver="this.title=url('Usage')">Usage</a></li>
+<li> <a href="javascript:goto('Samples')" onMouseOver="this.title=url('Samples')">Samples</a></li>
+<li> <a href="javascript:goto('Links')" onMouseOver="this.title=url('Links')">Links</a></li>
+<li> <a href="javascript:goto('Todo')" onMouseOver="this.title=url('Todo')">Todo</a></li>
+<li> <a href="