Clean up and document source links mechanics

Bump to 0.12.0 and update docs. Close #17.

README.md

@@ -32,7 +32,7 @@ Finally, add Lodox to your `plugins` list:
  [% ...
   {lodox, ".*",
    {git, "git://github.com/quasiquoting/lodox.git",
-    {tag, "0.11.0"}}}]}.
+    {tag, "0.12.0"}}}]}.
 ```
 
 The recommended place for the Lodox plugin entry is the global [rebar3](https://github.com/rebar/rebar3) config, `~/.config/rebar3/rebar.config`,
@@ -60,7 +60,7 @@ rebar3 do compile, lfe lodox
 
 If all goes well, the output will look something like:
 
-    Generated lodox v0.11.0 docs in /path/to/lodox/doc
+    Generated lodox v0.12.0 docs in /path/to/lodox/doc
 
 And, as promised, [generated documentation](http://quasiquoting.org/lodox/) will be in the `doc` subdirectory of
 your project.
@@ -73,6 +73,61 @@ Optionally, you can add Lodox as a `compile` [post-hook](https://www.rebar3.org/
   {post, [{compile, {lfe, lodox}]}]}.
 ```
 
+## Source Links
+
+*[ Modified from [Codox documentation](https://github.com/weavejester/codox#source-links). ]*
+
+If you have the source available at a URI and would like to have links to the
+function/macro's source file in the documentation, you can set the `​'source-uri'​`
+[configuration parameter](http://www.erlang.org/doc/design_principles/applications.html#id76014) in your [application resource file](http://www.erlang.org/doc/design_principles/applications.html#id75484).
+
+```erlang
+{env,
+ [{'source-uri',
+   "https://github.com/foo/bar/blob/{version}/{filepath}#L{line}"}]}
+```
+
+The URI is a template that may contain the following keys:
+
+<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
+
+
+<colgroup>
+<col  class="org-left" />
+
+<col  class="org-left" />
+</colgroup>
+<thead>
+<tr>
+<th scope="col" class="org-left">Template</th>
+<th scope="col" class="org-left">Description</th>
+</tr>
+</thead>
+
+<tbody>
+<tr>
+<td class="org-left">`{filepath}`</td>
+<td class="org-left">the file path from the root of the repository</td>
+</tr>
+
+
+<tr>
+<td class="org-left">`{line}`</td>
+<td class="org-left">the line number of the source file</td>
+</tr>
+
+
+<tr>
+<td class="org-left">`{version}`</td>
+<td class="org-left">the version of the project</td>
+</tr>
+</tbody>
+</table>
+
+N.B. In order for `{version}` to work properly, you must add the corresponding
+tag. For example, if you `.app` file contains `{vsn, "1.2.3"}` you must add the
+tag, `​"1.2.3"​`, to your repo.
+
 # License
 
 Lodox is licensed under [the MIT License](http://yurrriq.mit-license.org).

org/Lodox.org

@@ -129,7 +129,7 @@ branch = gh-pages
   {applications, [kernel, stdlib]},
   {env,
    [{'source-uri',
-     "https://<<lodox-github()>>/blob/master/{filepath}#L{line}"},
+     "https://<<lodox-github()>>/blob/{version}/{filepath}#L{line}"},
     <<lodox-dependency>>]},
   {links,
    [{"Homepage", "https://<<lodox-github()>>"},
@@ -525,11 +525,14 @@ Use [pandoc] if available, otherwise [erlmarkdown].
   (++ (mod-filename module) "#" (func-id func)))
 
 (defun func-source-uri (source-uri project module func)
-  (let* ((filepath1 (mref module 'filepath))
-         (filepath2 (lists:nthtail (+ 1 (length (mref project 'app-dir))) filepath1))
-         (line      (mref func 'line))
-         (uri1 (re:replace source-uri "{filepath}" filepath2 '(#(return list)))))
-    (re:replace uri1 "{line}" (integer_to_list line) '(#(return list)))))
+  (let* ((offset   (+ 1 (length (mref project 'app-dir))))
+         (filepath (lists:nthtail offset (mref module 'filepath)))
+         (line     (integer_to_list (mref func 'line)))
+         (version  (mref project 'version)))
+    (fold-replace source-uri
+      `[#("{filepath}"  ,filepath)
+        #("{line}"      ,line)
+        #("{version}"   ,version)])))
 
 (defun index-link (project on-index?)
   `(,(h3 '(class "no-link") (span '(class "inner") "Application"))
@@ -837,11 +840,12 @@ Use [pandoc] if available, otherwise [erlmarkdown].
   ([x] (when (is_atom x))
    (escape-html (atom_to_list x)))
   ([text]
-   (fold-replace text '(#("\\&"  "\\&amp;")
-                        #("<"  "\\&lt;")
-                        ;; #(">"  "\\&gt;")
-                        #("\"" "\\&quot;")
-                        #("'"  "\\&apos;")))))
+   (fold-replace text
+     '[#("\\&"  "\\&amp;")
+       #("<"  "\\&lt;")
+       ;; #(">"  "\\&gt;")
+       #("\"" "\\&quot;")
+       #("'"  "\\&apos;")])))
 
 (defun escape (string)
   "Given a string, return a copy with backticks and double quotes escaped."

org/README.md

@@ -109,18 +109,18 @@ branch = gh-pages
 ```erlang
 {application,    'lodox',
  [{description,  "The LFE rebar3 Lodox plugin"},
-  {vsn,          "0.11.0"},
+  {vsn,          "0.12.0"},
   {modules,      [lodox,
                   'lodox-html-writer', 'lodox-p', 'lodox-parse', 'lodox-util',
                   'unit-lodox-tests']},
   {registered,   []},
   {applications, [kernel, stdlib]},
   {env,
    [{'source-uri',
-     "https://github.com/quasiquoting/lodox/blob/master/{filepath}#L{line}"},
+     "https://github.com/quasiquoting/lodox/blob/{version}/{filepath}#L{line}"},
     {dependency, {lodox,
                   {git, "git://github.com/quasiquoting/lodox.git",
-                   {tag, "0.11.0"}}}}]},
+                   {tag, "0.12.0"}}}}]},
   {links,
    [{"Homepage", "https://github.com/quasiquoting/lodox"},
     {"Documentation", "http://quasiquoting.org/lodox"}]}]}.
@@ -459,11 +459,14 @@ Use [pandoc] if available, otherwise [erlmarkdown].
   (++ (mod-filename module) "#" (func-id func)))
 
 (defun func-source-uri (source-uri project module func)
-  (let* ((filepath1 (mref module 'filepath))
-         (filepath2 (lists:nthtail (+ 1 (length (mref project 'app-dir))) filepath1))
-         (line      (mref func 'line))
-         (uri1 (re:replace source-uri "{filepath}" filepath2 '(#(return list)))))
-    (re:replace uri1 "{line}" (integer_to_list line) '(#(return list)))))
+  (let* ((offset   (+ 1 (length (mref project 'app-dir))))
+         (filepath (lists:nthtail offset (mref module 'filepath)))
+         (line     (integer_to_list (mref func 'line)))
+         (version  (mref project 'version)))
+    (fold-replace source-uri
+      `[#("{filepath}"  ,filepath)
+        #("{line}"      ,line)
+        #("{version}"   ,version)])))
 
 (defun index-link (project on-index?)
   `(,(h3 '(class "no-link") (span '(class "inner") "Application"))
@@ -771,11 +774,12 @@ Use [pandoc] if available, otherwise [erlmarkdown].
   ([x] (when (is_atom x))
    (escape-html (atom_to_list x)))
   ([text]
-   (fold-replace text '(#("\\&"  "\\&")
-                        #("<"  "\\&lt;")
-                        ;; #(">"  "\\&gt;")
-                        #("\"" "\\&quot;")
-                        #("'"  "\\&apos;")))))
+   (fold-replace text
+     '[#("\\&"  "\\&amp;")
+       #("<"  "\\&lt;")
+       ;; #(">"  "\\&gt;")
+       #("\"" "\\&quot;")
+       #("'"  "\\&apos;")])))
 
 (defun escape (string)
   "Given a string, return a copy with backticks and double quotes escaped."
@@ -828,7 +832,7 @@ Use [pandoc] if available, otherwise [erlmarkdown].
 
 ```commonlisp
 '#m(name        #\"lodox\"
-    version     \"0.11.0\"
+    version     \"0.12.0\"
     description \"The LFE rebar3 Lodox plugin\"
     documents   ()
     modules     {{list of maps of module metadata}}

org/README.org

@@ -91,7 +91,7 @@ cd .. && <<lodox>> | <<last-line-only>> | <<obfuscate-path>>
 #+END_SRC
 
 #+RESULTS: generate-docs
-: Generated lodox v0.11.0 docs in /path/to/lodox/doc
+: Generated lodox v0.12.0 docs in /path/to/lodox/doc
 
 #+NAME: but-actually-though
 #+BEGIN_SRC sh :exports results :results output silent
@@ -111,4 +111,29 @@ Optionally, you can add Lodox as a =compile= [[https://www.rebar3.org/v3.0/docs/
   {post, [{compile, {lfe, lodox}]}]}.
 #+END_SRC
 
+** Source Links
+/[ Modified from [[https://github.com/weavejester/codox#source-links][Codox documentation]]. ]/
+
+If you have the source available at a URI and would like to have links to the
+function/macro's source file in the documentation, you can set the ~​'source-uri'​~
+[[http://www.erlang.org/doc/design_principles/applications.html#id76014][configuration parameter]] in your [[http://www.erlang.org/doc/design_principles/applications.html#id75484][application resource file]].
+
+#+BEGIN_SRC erlang
+{env,
+ [{'source-uri',
+   "https://github.com/foo/bar/blob/{version}/{filepath}#L{line}"}]}
+#+END_SRC
+
+The URI is a template that may contain the following keys:
+
+| Template     | Description                                   |
+|--------------+-----------------------------------------------|
+| ~{filepath}~ | the file path from the root of the repository |
+| ~{line}~     | the line number of the source file            |
+| ~{version}~  | the version of the project                    |
+
+N.B. In order for ~{version}~ to work properly, you must add the corresponding
+tag. For example, if you =.app= file contains ~{vsn, "1.2.3"}~ you must add the
+tag, =​"1.2.3"​=, to your repo.
+
 #+INCLUDE: LICENSE.org :minlevel 1

org/VERSION

@@ -1 +1 @@
-0.11.0
+0.12.0

src/lodox-html-writer.lfe

@@ -132,11 +132,14 @@ Use [pandoc] if available, otherwise [erlmarkdown].
   (++ (mod-filename module) "#" (func-id func)))
 
 (defun func-source-uri (source-uri project module func)
-  (let* ((filepath1 (mref module 'filepath))
-         (filepath2 (lists:nthtail (+ 1 (length (mref project 'app-dir))) filepath1))
-         (line      (mref func 'line))
-         (uri1 (re:replace source-uri "{filepath}" filepath2 '(#(return list)))))
-    (re:replace uri1 "{line}" (integer_to_list line) '(#(return list)))))
+  (let* ((offset   (+ 1 (length (mref project 'app-dir))))
+         (filepath (lists:nthtail offset (mref module 'filepath)))
+         (line     (integer_to_list (mref func 'line)))
+         (version  (mref project 'version)))
+    (fold-replace source-uri
+      `[#("{filepath}"  ,filepath)
+        #("{line}"      ,line)
+        #("{version}"   ,version)])))
 
 (defun index-link (project on-index?)
   `(,(h3 '(class "no-link") (span '(class "inner") "Application"))
@@ -444,11 +447,12 @@ Use [pandoc] if available, otherwise [erlmarkdown].
   ([x] (when (is_atom x))
    (escape-html (atom_to_list x)))
   ([text]
-   (fold-replace text '(#("\\&"  "\\&")
-                        #("<"  "\\&lt;")
-                        ;; #(">"  "\\&gt;")
-                        #("\"" "\\&quot;")
-                        #("'"  "\\&apos;")))))
+   (fold-replace text
+     '[#("\\&"  "\\&amp;")
+       #("<"  "\\&lt;")
+       ;; #(">"  "\\&gt;")
+       #("\"" "\\&quot;")
+       #("'"  "\\&apos;")])))
 
 (defun escape (string)
   "Given a string, return a copy with backticks and double quotes escaped."

src/lodox-parse.lfe

@@ -33,7 +33,7 @@
 
 ```commonlisp
 '#m(name        #\"lodox\"
-    version     \"0.11.0\"
+    version     \"0.12.0\"
     description \"The LFE rebar3 Lodox plugin\"
     documents   ()
     modules     {{list of maps of module metadata}}

src/lodox.app.src

@@ -5,18 +5,18 @@
 
 {application,    'lodox',
  [{description,  "The LFE rebar3 Lodox plugin"},
-  {vsn,          "0.11.0"},
+  {vsn,          "0.12.0"},
   {modules,      [lodox,
                   'lodox-html-writer', 'lodox-p', 'lodox-parse', 'lodox-util',
                   'unit-lodox-tests']},
   {registered,   []},
   {applications, [kernel, stdlib]},
   {env,
    [{'source-uri',
-     "https://github.com/quasiquoting/lodox/blob/master/{filepath}#L{line}"},
+     "https://github.com/quasiquoting/lodox/blob/{version}/{filepath}#L{line}"},
     {dependency, {lodox,
                   {git, "git://github.com/quasiquoting/lodox.git",
-                   {tag, "0.11.0"}}}}]},
+                   {tag, "0.12.0"}}}}]},
   {links,
    [{"Homepage", "https://github.com/quasiquoting/lodox"},
     {"Documentation", "http://quasiquoting.org/lodox"}]}]}.