Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

markedown sed script 0.1 added to bin/

  • Loading branch information...
commit 80c9821b647b21d6e396394657d8d99db788c4d8 1 parent 4e8441e
hdiedrich authored
Showing with 300 additions and 0 deletions.
  1. +115 −0 bin/MARKEDOC-README.md
  2. +185 −0 bin/markedoc.sed
View
115 bin/MARKEDOC-README.md
@@ -0,0 +1,115 @@
+markedoc 0.1
+============
+
+ **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][].
+
+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 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 part of **[edown][]**.
+
+You contribution to make markedoc better is highly welcome.
+
+Use
+---
+At the command line:
+
+ $ sed -E -f markedoc.sed <markdown file> > <edoc file>
+
+Requirements
+------------
+* **[sed]**: is part of any Linux and Mac OSX distribution. You could get it for [Windows, too][winsed].
+
+* **[Erlang/OTP][Erlang]**: see below.
+
+Sample
+------
+
+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,""}}]'
+
+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:
+
+ @docfile "doc/README.edoc"
+
+Status
+------
+
+ **Alpha**. You can do nice things but it likes to trip up EDoc, 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 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.
+
+ **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."
+
+
+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
+
+
+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**
+
+
View
185 bin/markedoc.sed
@@ -0,0 +1,185 @@
+# markedoc 0.1 - 01/31/11 - H. Diedrich <hd2010@eonblast.com>
+# ----------------------------------------------------------
+# sed command file to convert markdown format to edoc format
+# ----------------------------------------------------------
+# Use it to make a markdown readme file part of an edoc file:
+# sed -E -f <this file> <markdown file> > <edoc file>
+# ----------------------------------------------------------
+# SAMPLE USE:
+# sed -E -f markedoc.sed README.markdown > overview.edoc
+# ----------------------------------------------------------
+# SAMPLE FILES:
+# https://github.com/hdiedrich/markedoc/tree/master/samples
+# ----------------------------------------------------------
+# 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"' '[]'
+# ----------------------------------------------------------
+# REQUIREMENTS: sed, Erlang
+# ----------------------------------------------------------
+# STATUS: Alpha.
+# You can do nice things but it 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 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!
+# ----------------------------------------------------------
+# 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
+# ----------------------------------------------------------
+
+# **********************************************************
+# SCRIPT
+# **********************************************************
+# this is a sed script for -E regex and limited scripting.
+# 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.
+
+# 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.
+/^ / {
+ # do ...
+ :mlc
+ # 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.
+ 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/
+ # 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:
+ # -----------------------------------------
+ # get stored back
+ g
+ # this time discard all but the last line, which is processed further
+ s/^ (.*)(\n)([^\n]*)$/\3/
+}
+
+# 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'''/
+
+# Erlang comments
+# ---------------
+# doesn't work yet
+# s/(\n\s*)(%[^\n]+)/\1<span class="comment">\2<\/span>/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 \/>/
+
+# 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
+
+# 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 ==/
+
+# 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 \/>/
+
+# italics, bold
+# -------------
+s/\*\*([^*]+)\*\*/<b>\1<\/b>/
+s/\*([^*]+)\*/<em>\1<\/em>/
+
+# 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
+
+# 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
+# }
+
+# ----------------------------------------------------------
+# 'powered by Eonblast' http://www.eonblast.com
Please sign in to comment.
Something went wrong with that request. Please try again.