add rebar customization scripts; github URL rewrites

README.md

@@ -42,6 +42,46 @@ Example:
 The conversion function will fetch the current branch name from git,
 and fail if it cannot do so.
 
+Rebar customizations
+====================
+A set of escripts can be found under
+[edown/priv/scripts/](http://github.com/esl/edown/blob/master/priv/scripts/), which
+can be used to customize the `rebar` built process. The
+[rebar.config.script](http://github.com/esl/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.<pre>   {doc_path, ["http://raw.github.com/uwiger/setup/master/doc",
+               "http://raw.github.com/uwiger/gproc/master/doc"]}</pre>
+
+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` 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 
@@ -67,7 +107,7 @@ 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/edown/blob/0.3.1/bin/MARKEDOC-README.md).
+See [bin/MARKEDOC-README.md](http://github.com/esl/edown/blob/master/bin/MARKEDOC-README.md).
 
 **FreeBSD, Mac OS X**`$ sed -E -f markedoc.sed <markdown file> > <edoc file>`
 
@@ -77,9 +117,9 @@ See [bin/MARKEDOC-README.md](http://github.com/esl/edown/blob/0.3.1/bin/MARKEDOC
 
 
 <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>
+<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_doclet.md" class="module">edown_doclet</a></td></tr>
+<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_layout.md" class="module">edown_layout</a></td></tr>
+<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_lib.md" class="module">edown_lib</a></td></tr>
+<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_make.md" class="module">edown_make</a></td></tr>
+<tr><td><a href="http://github.com/esl/edown/blob/master/doc/edown_xmerl.md" class="module">edown_xmerl</a></td></tr></table>
 

doc/README.md

@@ -42,6 +42,46 @@ Example:
 The conversion function will fetch the current branch name from git,
 and fail if it cannot do so.
 
+Rebar customizations
+====================
+A set of escripts can be found under
+[edown/priv/scripts/](priv/scripts/), which
+can be used to customize the `rebar` built process. The
+[rebar.config.script](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.<pre>   {doc_path, ["http://raw.github.com/uwiger/setup/master/doc",
+               "http://raw.github.com/uwiger/gproc/master/doc"]}</pre>
+
+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` 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 

doc/overview.edoc

@@ -40,6 +40,48 @@ Example:
 The conversion function will fetch the current branch name from git,
 and fail if it cannot do so.
 
+Rebar customizations
+====================
+A set of escripts can be found under
+<a href="priv/scripts/">edown/priv/scripts/</a>, which
+can be used to customize the `rebar' built process. The
+<a href="priv/scripts/rebar.config.script">rebar.config.script</a>
+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' 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 

priv/scripts/check_edown.script

@@ -0,0 +1,38 @@
+%% -*- erlang -*-
+%%
+%% This helper script checks if doc is being built, otherwise removes edoc dep.
+%% To build docs, call `rebar get-deps doc`
+%% Assumes that the rebar config is bound to CONFIG
+
+[_|Args] = init:get_plain_arguments().  % rebar 'commands' and options
+case lists:member("doc", Args) of
+    false ->
+	{ok,C1} = file:script(filename:join(filename:dirname(SCRIPT),
+					    "remove_deps.script"),
+			      [{'CONFIG', CONFIG}, {'DEPS', [edown]}]),
+	C1;
+    true ->
+	%% We actually only need to start inets if we have a doc path with http URIS
+	application:start(crypto),
+	application:start(public_key),
+	application:start(ssl),
+	application:start(inets),
+        case code:lib_dir(edown) of
+            {error, bad_name} ->
+                io:fwrite("cannot find edown~n", []),
+                D = {edown, ".*",
+                     {git, "git://github.com/esl/edown.git", "HEAD"}},
+                Deps = case lists:keyfind(deps, 1, CONFIG) of
+                           false -> [D];
+                           {_, Ds} ->
+                               case lists:keymember(edown, 1, Ds) of
+                                   true -> Ds;
+                                   false -> [D|Ds]
+                               end
+                       end,
+                lists:keystore(deps, 1, CONFIG, {deps, Deps});
+            _ ->
+                io:fwrite("edown in path~n", []),
+                CONFIG
+        end
+end.

priv/scripts/remove_deps.script

@@ -0,0 +1,18 @@
+%% -*- erlang -*-
+%%
+%% Assumes the following bound variables:
+%% CONFIG - a rebar.config options list
+%% DEPS :: [atom()]  - a list of deps to remove
+case lists:keyfind(deps, 1, CONFIG) of
+    {_, Deps0} ->
+	Deps1 = lists:filter(
+		  fun(D) when is_atom(D) ->
+			  not lists:member(D, DEPS);
+		     (D) when is_tuple(D) ->
+			  not lists:member(element(1,D), DEPS)
+		  end, Deps0),
+	lists:keyreplace(deps, 1, CONFIG, {deps, Deps1});
+    false ->
+	CONFIG
+end.
+

src/edown_xmerl.erl

@@ -138,7 +138,7 @@ md_elem(a, Data, Attrs, _Parents, _E) ->
     %% io:fwrite("A TAG = ~p~nPs = ~p~n", [_E, _Parents]),
     case lists:keyfind(href, #xmlAttribute.name, Attrs) of
 	#xmlAttribute{value = HRef}  ->
-	    ["[", Data, "](", HRef, ")"];
+	    ["[", Data, "](", rewrite_github_url(HRef), ")"];
 	false ->
 	    case lists:keyfind(name, #xmlAttribute.name, Attrs) of
 		#xmlAttribute{} ->
@@ -229,3 +229,14 @@ no_nl(S) ->
 %%     integer_to_list(V);
 %% a_val(V) ->
 %%     V.
+
+rewrite_github_url("http://raw.github.com" ++ _ = URL) ->
+    case filename:split(URL) of
+	["http:","raw.github.com",User,App,Label,"doc"|Rest] ->
+	    "https://" ++ filename:join(
+			    ["github.com",User,App,"blob",Label,"doc"|Rest]);
+	_ ->
+	    URL
+    end;
+rewrite_github_url(URL) ->
+    URL.