Skip to content
Browse files

Add 'deps/edown/' from commit 'b390bbdbbe45cba09c7c6f36b04bf5d62b2be405'

git-subtree-dir: deps/edown
git-subtree-mainline: 48fa9fe
git-subtree-split: b390bbd
  • Loading branch information...
2 parents 48fa9fe + b390bbd commit b25021240bc0b6c94b18ecbd5caad3d4e5b5e7d9 Yurii Rashkovskii committed Apr 23, 2012
Showing with 6,446 additions and 0 deletions.
  1. +6 −0 deps/edown/.gitignore
  2. +12 −0 deps/edown/Makefile
  3. +10 −0 deps/edown/NOTICE
  4. +121 −0 deps/edown/README.md
  5. +196 −0 deps/edown/bin/MARKEDOC-README.md
  6. +338 −0 deps/edown/bin/markedoc.sed
  7. +121 −0 deps/edown/doc/README.md
  8. +3 −0 deps/edown/doc/edoc-info
  9. +144 −0 deps/edown/doc/edown_doclet.md
  10. +155 −0 deps/edown/doc/edown_layout.md
  11. +53 −0 deps/edown/doc/edown_lib.md
  12. +88 −0 deps/edown/doc/edown_make.md
  13. +61 −0 deps/edown/doc/edown_xmerl.md
  14. +78 −0 deps/edown/doc/overview.edoc
  15. +42 −0 deps/edown/edown_make
  16. +26 −0 deps/edown/make_doc
  17. BIN deps/edown/rebar
  18. +16 −0 deps/edown/rebar.config
  19. +31 −0 deps/edown/samples/.gitignore
  20. +1 −0 deps/edown/samples/README.md
  21. +313 −0 deps/edown/samples/markedoc/SAMPLE1.md
  22. +50 −0 deps/edown/samples/markedoc/SAMPLE2.md
  23. +248 −0 deps/edown/samples/markedoc/SAMPLE3.md
  24. BIN deps/edown/samples/markedoc/doc/erlang.png
  25. BIN deps/edown/samples/markedoc/doc/markedoc-footer.png
  26. +202 −0 deps/edown/samples/markedoc/doc/markedoc.css
  27. +4 −0 deps/edown/samples/markedoc/doc/overview.edoc
  28. +19 −0 deps/edown/samples/markedoc/make_samples.sh
  29. +23 −0 deps/edown/samples/markedoc/test-bsd.sh
  30. +23 −0 deps/edown/samples/markedoc/test-linux.sh
  31. +23 −0 deps/edown/samples/markedoc/test-macosx.sh
  32. +346 −0 deps/edown/samples/markedoc/what-you-should-see/SAMPLE1.edoc
  33. +53 −0 deps/edown/samples/markedoc/what-you-should-see/SAMPLE2.edoc
  34. +280 −0 deps/edown/samples/markedoc/what-you-should-see/SAMPLE3.edoc
  35. BIN deps/edown/samples/markedoc/what-you-should-see/erlang.png
  36. BIN deps/edown/samples/markedoc/what-you-should-see/markedoc-footer.png
  37. +202 −0 deps/edown/samples/markedoc/what-you-should-see/markedoc.css
  38. +321 −0 deps/edown/samples/markedoc/what-you-should-see/sample1.html
  39. +68 −0 deps/edown/samples/markedoc/what-you-should-see/sample2.html
  40. +255 −0 deps/edown/samples/markedoc/what-you-should-see/sample3.html
  41. +55 −0 deps/edown/samples/markedoc/what-you-should-see/stylesheet.css
  42. BIN deps/edown/samples/markedoc/your-test-results/erlang.png
  43. BIN deps/edown/samples/markedoc/your-test-results/markedoc-footer.png
  44. +202 −0 deps/edown/samples/markedoc/your-test-results/markedoc.css
  45. +55 −0 deps/edown/samples/markedoc/your-test-results/stylesheet.css
  46. +24 −0 deps/edown/src/edown.app.src
  47. +524 −0 deps/edown/src/edown_doclet.erl
  48. +1,274 −0 deps/edown/src/edown_layout.erl
  49. +97 −0 deps/edown/src/edown_lib.erl
  50. +64 −0 deps/edown/src/edown_make.erl
  51. +219 −0 deps/edown/src/edown_xmerl.erl
View
6 deps/edown/.gitignore
@@ -0,0 +1,6 @@
+.eunit/
+ebin/
+*~
+*/*~
+#*#
+*/#*#
View
12 deps/edown/Makefile
@@ -0,0 +1,12 @@
+.PHONY: all compile clean doc
+
+all: compile
+
+compile:
+ ./rebar compile
+
+clean:
+ ./rebar clean
+
+doc: compile
+ ./make_doc
View
10 deps/edown/NOTICE
@@ -0,0 +1,10 @@
+EDown is derived from code in EDoc, and designed to be an extension
+to EDoc.
+
+EDoc was written by Richard Carlsson, (c) 2001-2007 Richard Carlsson.
+It is part of Erlang/OTP (http://www.erlang.org) and available
+via the Erlang Public License (EPL).
+
+Original idea and implementation for EDown: ulf.wiger@erlang-solutions.com
+
+Markedoc contributed by Henning Dietrich <hd2010@eonblast.com>
View
121 deps/edown/README.md
@@ -0,0 +1,121 @@
+
+
+#Edown - Markdown generated from Edoc#
+
+
+Copyright (c) 2010 Erlang Solutions Ltd
+
+
+__Authors:__ [`ulf.wiger@erlang-solutions.com`](mailto: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:
+
+<pre>
+edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).
+</pre>
+
+
+
+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.
+
+
+
+** Special edown option: **
+
+
+
+Using the option `{top_level_readme, {File, BaseHref}}`, a github-friendly
+`README.md` in the top directory can be generated from the `overview.edoc`.
+This file is the same as the `doc/README.md` file already generated,
+but with relative links corrected (using `BaseHref`) so that they actually
+work. This step is needed since Github doesn't support relative paths in
+Markdown links.
+
+
+
+Example:
+
+
+
+`{top_level_readme, {"./README.md", "http://github.com/esl/edown"}}`
+
+
+
+The conversion function will fetch the current branch name from git,
+and fail if it cannot do so.
+
+
+
+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.
+
+
+
+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](http://github.com/esl/gproc/blob/master/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>`
+
+
+
+
+##Modules##
+
+
+<table width="100%" border="0" summary="list of modules">
+<tr><td><a href="http://github.com/esl/gproc/blob/master/doc/edown_doclet.md" class="module">edown_doclet</a></td></tr>
+<tr><td><a href="http://github.com/esl/gproc/blob/master/doc/edown_layout.md" class="module">edown_layout</a></td></tr>
+<tr><td><a href="http://github.com/esl/gproc/blob/master/doc/edown_lib.md" class="module">edown_lib</a></td></tr>
+<tr><td><a href="http://github.com/esl/gproc/blob/master/doc/edown_make.md" class="module">edown_make</a></td></tr>
+<tr><td><a href="http://github.com/esl/gproc/blob/master/doc/edown_xmerl.md" class="module">edown_xmerl</a></td></tr></table>
+
View
196 deps/edown/bin/MARKEDOC-README.md
@@ -0,0 +1,196 @@
+edown markedoc 0.3.2
+====================
+
+**markedoc helps you keep your project's README.md in sync with your overview.edoc.**
+
+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. 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 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].
+
+[issues]: https://github.com/hdiedrich/markedoc/issues "Issue tracker"
+
+Use <a name=Use></a>
+---
+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 <a name=Requirements></a>
+------------
+* **[sed][]**: is part of any Linux, FreeBSD and Mac OSX distribution, also see [Notes][].
+
+* **[Erlang/OTP][Erlang]**, see [Notes][].
+
+Test <a name=Test></a>
+----
+
+ **FreeBSD, Mac OS X**
+ $ samples/markedoc/test-bsd.sh
+
+ **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:
+
+ **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/markedoc/doc/SAMPLE.edoc"
+
+Tricks <a name=Tricks></a>
+------
+
+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
+
+
+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 <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.
+
+[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."
+
+
+License
+-------
+This script is free software. It comes without any warranty.
+
+Author
+------
+H. Diedrich <hd2010@eonblast.com>
+
+History
+-------
+
+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
338 deps/edown/bin/markedoc.sed
@@ -0,0 +1,338 @@
+# 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:
+# 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 (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 (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: 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: https://github.com/esl/edown
+# On Markdown: http://daringfireball.net/projects/markdown/
+# On Edoc: http://www.erlang.org/doc/apps/edoc/
+# On sed: http://www.gnu.org/software/sed/manual/sed.html
+# ----------------------------------------------------------
+# Repository: https://github.com/hdiedrich/markedoc/
+# Issues: https://github.com/hdiedrich/markedoc/issues
+# Please experiment and push your fixes. - Thanks!
+# ----------------------------------------------------------
+
+# **********************************************************
+# SCRIPT
+# **********************************************************
+# 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. ':'
+# 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 ...
+ : do_collect
+ # append next line
+ N
+ # 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)(.*)$/\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 that last line is not lost:
+ # ----------------------------------------------
+ # get stored back
+ g
+ # this time discard all but the last line, which is processed further
+ 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
+# version. The main difference is simply that it will tag each
+# line separately. If you work out the right margins and
+# paddings for <pre> in your css file, that might give just as
+# nice results as the above. There are tabs in this pattern.
+# s/^ (.+)$/``` \1'''/
+
+# 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, '[..]:...'-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: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.
+# ------------------------------------------------------------------------
+# If you don't like the javascript tags, comment out the previous 'smart'
+# reference patterns and uncomment these.
+# s/\[([^]]+)\]\[\]/<a href="#\1">\1<\/a>/g
+# s/\[([^]]+)\]\[([^]]+)\]/<a href="#\2">\1<\/a>/g
+
+# headlines by #
+# --------------
+# h1 demoted to h2 as h1 is reserved in edoc
+s/^####(.+)$/====\1 ====/
+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>
+s/^\*(.+)$/<li>\1<\/li>/
+
+# emails, urls
+# ------------
+s/<([^aA][^@>]+@[^.>]+.[^>]+)>/<a href=\"mailto:\1\">\1<\/a>/
+s/<(http[s]?:\/\/[^.>]+.[^>]+)>/<a href=\"\1\">\1<\/a>/
+
+# line breaks
+# -----------
+s/ $/<br \/>/
+
+# single backticks
+# ----------------
+# make code quotes
+s/`([^`]+)`/<code>\1<\/code>/g
+
+# protect @
+# ---------
+# leading space or tab indicates use as code sample for, well, edoc
+# itself most likely, so escape it.
+s/([ \"\'\`]+@)/\1@/g
+
+# headlines by underline === or ---
+# ---------------------------------
+# demoted to h2 and h3, as h1 is reserved in edoc
+{
+ # 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
+}
+
+: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
121 deps/edown/doc/README.md
@@ -0,0 +1,121 @@
+
+
+#Edown - Markdown generated from Edoc#
+
+
+Copyright (c) 2010 Erlang Solutions Ltd
+
+
+__Authors:__ [`ulf.wiger@erlang-solutions.com`](mailto: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:
+
+<pre>
+edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).
+</pre>
+
+
+
+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.
+
+
+
+** Special edown option: **
+
+
+
+Using the option `{top_level_readme, {File, BaseHref}}`, a github-friendly
+`README.md` in the top directory can be generated from the `overview.edoc`.
+This file is the same as the `doc/README.md` file already generated,
+but with relative links corrected (using `BaseHref`) so that they actually
+work. This step is needed since Github doesn't support relative paths in
+Markdown links.
+
+
+
+Example:
+
+
+
+`{top_level_readme, {"./README.md", "http://github.com/esl/edown"}}`
+
+
+
+The conversion function will fetch the current branch name from git,
+and fail if it cannot do so.
+
+
+
+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.
+
+
+
+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](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>`
+
+
+
+
+##Modules##
+
+
+<table width="100%" border="0" summary="list of modules">
+<tr><td><a href="edown_doclet.md" class="module">edown_doclet</a></td></tr>
+<tr><td><a href="edown_layout.md" class="module">edown_layout</a></td></tr>
+<tr><td><a href="edown_lib.md" class="module">edown_lib</a></td></tr>
+<tr><td><a href="edown_make.md" class="module">edown_make</a></td></tr>
+<tr><td><a href="edown_xmerl.md" class="module">edown_xmerl</a></td></tr></table>
+
View
3 deps/edown/doc/edoc-info
@@ -0,0 +1,3 @@
+{application,edown}.
+{packages,[]}.
+{modules,[edown_doclet,edown_layout,edown_lib,edown_make,edown_xmerl]}.
View
144 deps/edown/doc/edown_doclet.md
@@ -0,0 +1,144 @@
+
+
+#Module edown_doclet#
+* [Description](#description)
+* [Function Index](#index)
+* [Function Details](#functions)
+
+
+EDoc Doclet module for producing Markdown.
+
+
+
+Copyright (c) 2010 Erlang Solutions Ltd
+
+__Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com)).<a name="index"></a>
+
+##Function Index##
+
+
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#run-2">run/2</a></td><td>Main doclet entry point.</td></tr></table>
+
+
+<a name="functions"></a>
+
+##Function Details##
+
+<a name="run-2"></a>
+
+###run/2##
+
+
+
+
+<pre>run(Command::<a href="#type-doclet_gen">doclet_gen()</a> | <a href="#type-doclet_toc">doclet_toc()</a>, Ctxt::<a href="#type-edoc_context">edoc_context()</a>) -> ok</pre>
+<br></br>
+
+
+
+
+
+
+Main doclet entry point.
+
+
+
+Also see [`//edoc/edoc:layout/2`](/Users/uwiger/FL/git/edoc/doc/edoc.md#layout-2) for layout-related options, and
+[`//edoc/edoc:get_doc/2`](/Users/uwiger/FL/git/edoc/doc/edoc.md#get_doc-2) for options related to reading source
+files.
+
+Options:
+
+
+
+<dt><code>{file_suffix, string()}</code>
+</dt>
+
+
+
+
+<dd>Specifies the suffix used for output files. The default value is
+<code>".md"</code>.
+</dd>
+
+
+
+
+<dt><code>{hidden, bool()}</code>
+</dt>
+
+
+
+
+<dd>If the value is <code>true</code>, documentation of hidden modules and
+functions will also be included. The default value is <code>false</code>.
+</dd>
+
+
+
+
+<dt><code>{overview, <a href="/Users/uwiger/FL/git/edoc/doc/edoc.md#type-filename">//edoc/edoc:filename()</a>}</code>
+</dt>
+
+
+
+
+<dd>Specifies the name of the overview-file. By default, this doclet
+looks for a file <code>"overview.edoc"</code> in the target directory.
+</dd>
+
+
+
+
+<dt><code>{private, bool()}</code>
+</dt>
+
+
+
+
+<dd>If the value is <code>true</code>, documentation of private modules and
+functions will also be included. The default value is <code>false</code>.
+</dd>
+
+
+
+
+<dt><code>{stylesheet, string()}</code>
+</dt>
+
+
+
+
+<dd>Specifies the URI used for referencing the stylesheet. The
+default value is <code>"stylesheet.css"</code>. If an empty string is
+specified, no stylesheet reference will be generated.
+</dd>
+
+
+
+
+<dt><code>{stylesheet_file, <a href="/Users/uwiger/FL/git/edoc/doc/edoc.md#type-filename">//edoc/edoc:filename()</a>}</code>
+</dt>
+
+
+
+
+<dd>Specifies the name of the stylesheet file. By default, this
+doclet uses the file <code>"stylesheet.css"</code> in the <code>priv</code>
+subdirectory of the EDoc installation directory. The named file
+will be copied to the target directory.
+</dd>
+
+
+
+
+<dt><code>{title, string()}</code>
+</dt>
+
+
+
+
+<dd>Specifies the title of the overview-page.
+</dd>
+
+
View
155 deps/edown/doc/edown_layout.md
@@ -0,0 +1,155 @@
+
+
+#Module edown_layout#
+* [Description](#description)
+* [Function Index](#index)
+* [Function Details](#functions)
+
+
+Markdown layout module for EDoc.
+
+
+
+Copyright (c) 2010 Erlang Solutions Ltd
+
+__Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com)).<a name="description"></a>
+
+##Description##
+ Derived from `edoc_layout`, which is part of the Erlang/OTP application EDoc.
+The module is intended to be used together with edoc.<a name="index"></a>
+
+##Function Index##
+
+
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#markdown-3">markdown/3</a></td><td></td></tr><tr><td valign="top"><a href="#module-2">module/2</a></td><td>The layout function.</td></tr><tr><td valign="top"><a href="#overview-2">overview/2</a></td><td></td></tr><tr><td valign="top"><a href="#package-2">package/2</a></td><td></td></tr><tr><td valign="top"><a href="#type-1">type/1</a></td><td></td></tr></table>
+
+
+<a name="functions"></a>
+
+##Function Details##
+
+<a name="markdown-3"></a>
+
+###markdown/3##
+
+
+
+
+`markdown(Title, CSS, Body) -> any()`
+
+<a name="module-2"></a>
+
+###module/2##
+
+
+
+
+`module(Element, Options) -> any()`
+
+
+
+
+
+The layout function.
+
+Options to the standard layout:
+
+
+
+<dt><code>{index_columns, integer()}</code>
+</dt>
+
+
+
+
+<dd>Specifies the number of column pairs used for the function
+index tables. The default value is 1.
+</dd>
+
+
+
+
+<dt><code>{pretty_printer, atom()}</code>
+</dt>
+
+
+
+
+<dd>Specifies how types and specifications are pretty printed.
+If the value <code>erl_pp</code> is specified the Erlang pretty printer
+(the module <code>erl_pp</code>) will be used. The default is to do
+no pretty printing which implies that lines can be very long.
+</dd>
+
+
+
+
+<dt><code>{stylesheet, string()}</code>
+</dt>
+
+
+
+
+<dd>Specifies the URI used for referencing the stylesheet. The
+default value is <code>"stylesheet.css"</code>. If an empty string is
+specified, no stylesheet reference will be generated.
+</dd>
+
+
+
+
+<dt><code>{sort_functions, boolean()}</code>
+</dt>
+
+
+
+
+<dd>If <code>true</code>, the detailed function descriptions are listed by
+name, otherwise they are listed in the order of occurrence in
+the source file. The default value is <code>true</code>.
+</dd>
+
+
+
+
+<dt><code>{xml_export, Module::atom()}</code>
+</dt>
+
+
+
+
+<dd>Specifies an <a href="/Users/uwiger/FL/git/xmerl/doc/index.md" target="_top"><code>xmerl</code></a> callback module to be
+used for exporting the documentation. See <a href="/Users/uwiger/FL/git/xmerl/doc/xmerl.md#export_simple_content-2"><code>//xmerl/xmerl:export_simple_content/2</code></a> for details.
+</dd>
+
+
+
+
+
+__See also:__ [//edoc/edoc:layout/2](/Users/uwiger/FL/git/edoc/doc/edoc.md#layout-2), [edown_doclet:layout/2](edown_doclet.md#layout-2).<a name="overview-2"></a>
+
+###overview/2##
+
+
+
+
+`overview(E, Options) -> any()`
+
+<a name="package-2"></a>
+
+###package/2##
+
+
+
+
+`package(E, Options) -> any()`
+
+<a name="type-1"></a>
+
+###type/1##
+
+
+
+
+`type(E) -> any()`
+
View
53 deps/edown/doc/edown_lib.md
@@ -0,0 +1,53 @@
+
+
+#Module edown_lib#
+* [Description](#description)
+* [Function Index](#index)
+* [Function Details](#functions)
+
+
+Markdown for EDoc - common support functions.
+
+
+
+Copyright (c) 2010 Erlang Solutions Ltd
+
+__Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com)).<a name="index"></a>
+
+##Function Index##
+
+
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#export-1">export/1</a></td><td></td></tr><tr><td valign="top"><a href="#get_attrval-2">get_attrval/2</a></td><td></td></tr><tr><td valign="top"><a href="#redirect_uri-1">redirect_uri/1</a></td><td></td></tr></table>
+
+
+<a name="functions"></a>
+
+##Function Details##
+
+<a name="export-1"></a>
+
+###export/1##
+
+
+
+
+`export(Data) -> any()`
+
+<a name="get_attrval-2"></a>
+
+###get_attrval/2##
+
+
+
+
+`get_attrval(Name, XmlElement) -> any()`
+
+<a name="redirect_uri-1"></a>
+
+###redirect_uri/1##
+
+
+
+
+`redirect_uri(XmlElement) -> any()`
+
View
88 deps/edown/doc/edown_make.md
@@ -0,0 +1,88 @@
+
+
+#Module edown_make#
+* [Function Index](#index)
+* [Function Details](#functions)
+
+
+
+
+<a name="index"></a>
+
+##Function Index##
+
+
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#from_script-1">from_script/1</a></td><td>Reads ConfigFile and calls <a href="edoc.md#application-3"><code>edoc:application/3</code></a></td></tr><tr><td valign="top"><a href="#main-1">main/1</a></td><td>Escript entry point for building edown (or edoc) documentation.</td></tr></table>
+
+
+<a name="functions"></a>
+
+##Function Details##
+
+<a name="from_script-1"></a>
+
+###from_script/1##
+
+
+
+
+<pre>from_script(Config::ConfigFile) -&gt; ok | {error, Reason}</pre>
+<br></br>
+
+
+
+
+
+
+Reads ConfigFile and calls [`edoc:application/3`](edoc.md#application-3)
+
+
+
+The ConfigFile will be read using [`file:script/1`](file.md#script-1), and should return
+`{App, Dir, Options}`, as required by [`edoc:application/3`](edoc.md#application-3).
+
+This function does not manage dependencies. It is simply a wrapper around
+[`edoc:application/3`](edoc.md#application-3).<a name="main-1"></a>
+
+###main/1##
+
+
+
+
+<pre>main(Args::[Config]) -&gt; no_return()</pre>
+<br></br>
+
+
+
+
+
+
+Escript entry point for building edown (or edoc) documentation
+
+
+
+Usage: edown_make -config ConfigFile [-pa P] [-pz P]
+
+
+
+Calls [from_script(ConfigFile)](#from_script-1) and then terminates,
+with a normal or non-normal exit code, depending on the outcome.
+
+
+
+Make sure `$EDOWN/edown_make` is runnable, and in the command path, and
+that the edown BEAM files are in the Erlang path (e.g. using $ERL_LIBS).
+The `edown_make` escript also accepts `-pa P` and/or `-pz P` flags as a
+means of locating the edown byte code.
+
+
+
+Note, however, that the function `edoc_make:main/1` only expects the
+config file as an input argument, corresponding to
+
+
+
+`escript edoc_make.beam ConfigFile`
+
+(The reason for this is that if the beam file can be passed directly to
+the escript command, setting the path should also be doable that way).
View
61 deps/edown/doc/edown_xmerl.md
@@ -0,0 +1,61 @@
+
+
+#Module edown_xmerl#
+* [Function Index](#index)
+* [Function Details](#functions)
+
+
+
+
+
+
+Copyright (c) 2010 Erlang Solutions Ltd
+
+__Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com)).<a name="index"></a>
+
+##Function Index##
+
+
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#%23element%23-5">'#element#'/5</a></td><td></td></tr><tr><td valign="top"><a href="#%23root%23-4">'#root#'/4</a></td><td></td></tr><tr><td valign="top"><a href="#%23text%23-1">'#text#'/1</a></td><td></td></tr><tr><td valign="top"><a href="#%23xml-inheritance%23-0">'#xml-inheritance#'/0</a></td><td></td></tr></table>
+
+
+<a name="functions"></a>
+
+##Function Details##
+
+<a name="%23element%23-5"></a>
+
+###'#element#'/5##
+
+
+
+
+`#element#(Tag, Data, Attrs, Parents, E) -> any()`
+
+<a name="%23root%23-4"></a>
+
+###'#root#'/4##
+
+
+
+
+`#root#(Data, Attrs, X3, E) -> any()`
+
+<a name="%23text%23-1"></a>
+
+###'#text#'/1##
+
+
+
+
+`#text#(Text) -> any()`
+
+<a name="%23xml-inheritance%23-0"></a>
+
+###'#xml-inheritance#'/0##
+
+
+
+
+`#xml-inheritance#() -> any()`
+
View
78 deps/edown/doc/overview.edoc
@@ -0,0 +1,78 @@
+@author <ulf.wiger@erlang-solutions.com>
+@copyright 2010 Erlang Solutions Ltd
+
+@title Edown - Markdown generated from Edoc
+
+@doc
+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:
+
+<pre>
+edoc:application(App, [{doclet, edown_doclet} | OtherOpts]).
+</pre>
+
+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.
+
+** Special edown option: **
+
+Using the option `{top_level_readme, {File, BaseHref}}', a github-friendly
+`README.md' in the top directory can be generated from the `overview.edoc'.
+This file is the same as the `doc/README.md' file already generated,
+but with relative links corrected (using `BaseHref') so that they actually
+work. This step is needed since Github doesn't support relative paths in
+Markdown links.
+
+Example:
+
+`{top_level_readme, {"./README.md", "http://github.com/esl/edown"}}'
+
+The conversion function will fetch the current branch name from git,
+and fail if it cannot do so.
+
+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.
+
+markedoc
+========
+
+The sed script bin/markedoc works in the opposite direction and converts
+your `README.md' to an `EDoc' file.
+
+See <a href="bin/MARKEDOC-README.md">bin/MARKEDOC-README.md</a>.
+
+**FreeBSD, Mac OS X**
+ `$ sed -E -f markedoc.sed <markdown file> > <edoc file>'
+
+**Linux**
+ `$ sed -r -f markedoc.sed <markdown file> > <edoc file>'
+
+
+
+@end
View
42 deps/edown/edown_make
@@ -0,0 +1,42 @@
+#!/usr/bin/env escript
+%% -*- erlang -*-
+
+%% @spec main() -> no_return()
+%% @doc Escript for building edown (or edoc) documentation
+%%
+%% Usage: edown_make ConfigFile
+%%
+%% The ConfigFile will be read using {@link file:script/1}, and should return
+%% `{App, Dir, Options}', as required by {@link edoc:application/3}.
+%%
+%% This function does not manage dependencies. It is simply a wrapper around
+%% {@link edoc:application/3}.
+%% @end
+%%
+main(Args) ->
+ Config = parse_args(Args),
+ edown_make:main([Config]).
+
+parse_args(Args) ->
+ parse_args(Args, "edown.config").
+
+parse_args([], Config) ->
+ Config;
+parse_args(["-config", Config|Args], _) ->
+ parse_args(Args, Config);
+parse_args(["-pa", P|Args], Config) ->
+ code:add_patha(P),
+ parse_args(Args, Config);
+parse_args(["-pz", P|Args], Config) ->
+ code:add_pathz(P),
+ parse_args(Args, Config);
+parse_args(Args, _) ->
+ io:fwrite("Unknown options: ~p~n", [Args]),
+ usage(),
+ halt(1).
+
+usage() ->
+ Full = escript:script_name(),
+ Base = filename:basename(Full),
+ io:fwrite("~s~nUsage: ~s -config Config [-pa Path] [-pz Path]~n",
+ [Full, Base]).
View
26 deps/edown/make_doc
@@ -0,0 +1,26 @@
+#!/usr/bin/env escript
+%% -*- erlang -*-
+
+%% edown is designed to work well with rebar, but in order to use edown
+%% to document itself, we need to explicitly set the path to ebin/, so
+%% that we pick up the newly built edown doclet. I haven't found a way
+%% to do this with 'rebar doc'.
+%%
+main([]) ->
+ code:add_patha("ebin"),
+ R = edoc:application(edown, ".",
+ [{doclet, edown_doclet},
+ {source_path, ["src"]},
+ {app_default,"http://www.erlang.org/doc/man"},
+ {stylesheet, ""}, % don't copy stylesheet.css
+ {image, ""}, % don't copy erlang.png
+ {top_level_readme,
+ {"./README.md",
+ "http://github.com/esl/edown"}}]),
+ case R of
+ ok ->
+ halt();
+ Err ->
+ io:fwrite("~p~n", [Err]),
+ halt(1)
+ end.
View
BIN deps/edown/rebar
Binary file not shown.
View
16 deps/edown/rebar.config
@@ -0,0 +1,16 @@
+%% -*- erlang -*-
+{erl_opts, [debug_info]}.
+{xref_checks, [undefined_function_calls]}.
+
+{cover_enabled, true}.
+{eunit_opts, [verbose]}.
+
+{clean_files, ["*~","*/*~","ebin/*.beam"]}.
+
+%% This is a reasonable set of options to use for edown, but edown
+%% doesn't actually use rebar to make its own docs.
+%% {edoc_opts, [{doclet, edown_doclet},
+%% {source_path, ["src", "test"]},
+%% {stylesheet, ""},
+%% {image, ""},
+%% {app_default,"http://www.erlang.org/doc/man"}]}.
View
31 deps/edown/samples/.gitignore
@@ -0,0 +1,31 @@
+.DS_Store
+
+# ----------------------------
+# 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/S*.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 deps/edown/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
313 deps/edown/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 deps/edown/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 deps/edown/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
BIN deps/edown/samples/markedoc/doc/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 deps/edown/samples/markedoc/doc/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 deps/edown/samples/markedoc/doc/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
4 deps/edown/samples/markedoc/doc/overview.edoc
@@ -0,0 +1,4 @@
+@author You
+@title A Markedoc Sample Doc
+@version 0.3 / edown
+@docfile "samples/markedoc/doc/SAMPLE.edoc"
View
19 deps/edown/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 deps/edown/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"}]'