Merge branch 'upstream-master' into dev

NOTICE

@@ -5,6 +5,6 @@ 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
+Original idea and implementation for EDown: ulf@wiger.net
 
 Markedoc contributed by Henning Dietrich <hd2010@eonblast.com>

README.md

@@ -1,32 +1,35 @@
 
 
-#Edown - Markdown generated from Edoc#
+# Edown - Markdown generated from Edoc #
 
+Copyright (c) 2014 Ulf Wiger
 
-Copyright (c) 2010 Erlang Solutions Ltd
-
-
-__Authors:__ [`ulf.wiger@feuerlabs.com`](mailto:ulf.wiger@feuerlabs.com).
-
+__Authors:__ [`ulf@wiger.net`](mailto:ulf@wiger.net).
 
 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 
+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>
+To generate markdown edoc, run:
+
+```
+
 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.
+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: **
+Top-level README
+----------------
 
 Using the option `{top_level_readme, {File, BaseHref}}`, a github-friendly
 `README.md` in the top directory can be generated from the `overview.edoc`.
@@ -37,49 +40,129 @@ Markdown links.
 
 Example:
 
-`{top_level_readme, {"./README.md", "http://github.com/esl/edown"}}`
+`{top_level_readme, {"./README.md", "http://github.com/uwiger/edown"}}`
 
 The conversion function will fetch the current branch name from git,
 and fail if it cannot do so.
 
+It is also possible to add the branch information specifically:
+`{top_level_readme, {File, BaseHref, Branch}}`, although this shouldn't be
+necessary as long as edown can derive the branch name from git.
+
+Using Atlassian Stash or Gitlab as target
+-----------------------------------------
+
+The option `{edown_target, github | stash | gitlab}` can be used to control
+which is the intended host repository. This affects how links are rewritten in
+order to find related files and stay on the correct branch.
+
+The default value is `github`.
+
+Note that at the moment, the
+[Markdown viewer plugin](https://bitbucket.org/atlassianlabs/stash-markdown-viewer-plugin) will be needed in order to render the generated documentation
+as Markdown on Stash.
+
+Github customizations
+=====================
+`pre` tags are converted into github "fenced" code blocks, i.e.
+
+```
+```...'''
+```
+
+. If language-specific syntax highlighting is desired,
+this can be achieved by adding a 'lang' attribute, e.g.
+
+```
+<pre lang="erlang">
+incr(X) ->
+  %% This should be formatted with Erlang syntax highlighting
+  X + 1.
+</pre>
+```
+
+which should format like this:
+
+```erlang
+
+incr(X) ->
+  %% This should be formatted with Erlang syntax highlighting
+  X + 1.
+
+```
+
+Rebar customizations
+====================
+A set of escripts can be found under
+[edown/priv/scripts/](http://github.com/uwiger/edown/blob/master/priv/scripts/), which
+can be used to customize the `rebar` built process. The
+[rebar.config.script](http://github.com/uwiger/edown/blob/master/priv/scripts/rebar.config.script)
+file should be copied into your application, next to `rebar.config`.
+It will sense if `doc` is a current target, and will then include
+`edown` in the `deps`; otherwise, it removes it. This way, you will
+not have to pull down `edown` unless you really want to build the
+docs. It will also locate edown along your path, in which case
+it doesn't need to pull it down again.
+
+The script will also start the `inets` application, so that you
+can include URLs as part of a `doc_path` option (see below).
+
+Links to other EDown-generated docs
+===================================
+There is a way to configure Edoc/Edown to get URLs right even
+when linking to other Edown-generated docs on Github.
+
+First, you need to specify paths to the `edoc-info` files for
+each repository as part of `edoc_opts` in your rebar.config, e.g.
+
+```
+   {doc_path, ["http://raw.github.com/uwiger/setup/master/doc",
+               "http://raw.github.com/uwiger/gproc/master/doc"]}
+```
+
+Note (1) that we use "http:://...", not "https://...", since
+Edoc doesn't recognize the latter. Also note that we use URLs
+to the raw files. This is for Edoc as it fetches the `edoc-info`
+files. Edown will detect and rewrite such links in the generated
+output, since "raw" links wouldn't work for the markdown files.
+
+The next issue is that Edoc uses httpd_client to fetch the
+`edoc-info` files, which requires `inets` to be started. To
+further complicate matters, `ssl` (and thus `crypto`, 'asn1' and
+`public_key`) must also be started, since Github will
+redirect to https.
+
+One way to solve this is to use the escripts found under
+`edown/priv/scripts`.
+
 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 
+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 
+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 
+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 
+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. 
+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/edown/blob/0.3.1/bin/MARKEDOC-README.md).
+See [bin/MARKEDOC-README.md](http://github.com/uwiger/edown/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/edown/blob/0.3.1/doc/edown_doclet.md" class="module">edown_doclet</a></td></tr>
-<tr><td><a href="http://github.com/esl/edown/blob/0.3.1/doc/edown_layout.md" class="module">edown_layout</a></td></tr>
-<tr><td><a href="http://github.com/esl/edown/blob/0.3.1/doc/edown_lib.md" class="module">edown_lib</a></td></tr>
-<tr><td><a href="http://github.com/esl/edown/blob/0.3.1/doc/edown_make.md" class="module">edown_make</a></td></tr>
-<tr><td><a href="http://github.com/esl/edown/blob/0.3.1/doc/edown_xmerl.md" class="module">edown_xmerl</a></td></tr></table>
-

bin/MARKEDOC-README.md

@@ -63,17 +63,17 @@ 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.		
+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'" '"."' '[]'	
+	$ 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'" '"."' '[]'	
+	$ 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:
 
@@ -83,7 +83,7 @@ By running sed, then edoc, this makes the README.edoc part of the overview page.
 
 Accordingly, the sample stub overview.edoc used for the samples here, looks like this:
 
-	@author You 
+	@author You
 	@title  a markedoc sample doc
 	@version 0.2
 	@docfile "samples/markedoc/doc/SAMPLE.edoc"
@@ -95,21 +95,21 @@ Markdown cannot jump to headlines as anchors, while edoc makes headlines into an
 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.) 
+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. 
+ **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.
 
@@ -120,19 +120,19 @@ 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/  
+[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][]** is an EDoc extension for generating Github-flavored Markdown. It uses edoc-style commented Erlang sources to create markdown files from them.
 
-[edown]: https://github.com/esl/edown
+[edown]: https://github.com/uwiger/edown
 
  **[Markdown][]** is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
 
-[Markdown]: http://daringfireball.net/projects/markdown/ 
+[Markdown]: http://daringfireball.net/projects/markdown/
 
  **[sed][]** ('stream editor') is a Unix utility that parses text files and implements a programming language which can apply textual transformations to such files. It reads input files line by line (sequentially), applying the operation which has been specified via the command line (or a sed script), and then outputs the line. It is available today for most operating systems. There seems to be [one for Windows][winsed], too.
 
@@ -160,36 +160,36 @@ History
 
 * 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 
+* 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),  
+* 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 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 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