Permalink
Browse files

more context-sensitive markup

  • Loading branch information...
1 parent cb07de3 commit 659a33f6b8a8e7492f6c02f2789b70298e80efd2 Ulf Wiger committed Oct 25, 2010
Showing with 255 additions and 82 deletions.
  1. +12 −2 doc/README.md
  2. +85 −34 doc/edown_doclet.md
  3. +77 −25 doc/edown_layout.md
  4. +19 −6 doc/edown_lib.md
  5. +32 −8 doc/edown_xmerl.md
  6. +30 −7 src/edown_layout.erl
View
14 doc/README.md
@@ -1,16 +1,20 @@
-#The edown application#
+<h1>The edown application</h1>
+
The edown application
=====================
Status:
------
More-or-less readable Markdown can be generated.
+
Copyright © 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.
@@ -20,6 +24,7 @@ edoc_doclet creates an index.html and overview.html,
which do not point to the .md files.
+
To generate markdown edoc, run:
@@ -29,13 +34,15 @@ 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
@@ -55,10 +62,13 @@ 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.
-##Modules##
+<h2 class="indextitle">Modules</h2>
+
+
<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_xmerl.md" class="module">edown_xmerl</a></td></tr></table>
+
View
119 doc/edown_doclet.md
@@ -2,38 +2,53 @@ Module edown_doclet
===================
-#Module edown_doclet#
+<h1>Module edown_doclet</h1>
+
* [Description](#description)
* [Function Index](#index)
* [Function Details](#functions)
EDoc Doclet module for producing Github-flavored Markdown.
+
Copyright © 2010 Erlang Solutions Ltd
+
__Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com)).
-##<a name="description">Description</a>##
+<h2><a name="description">Description</a></h2>
+
EDoc Doclet module for producing Github-flavored Markdown.
-##<a name="index">Function Index</a>##
+<h2><a name="index">Function Index</a></h2>
+
+
<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##
+<h2>Function Details</h2>
+
<a name="run-2"></a>
-###run/2##
+<h3>run/2</h3>
+
+
+
+
+
+<tt>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</tt>
+
-`run(Command::[doclet_gen()](#type-doclet_gen) | [doclet_toc()](#type-doclet_toc), Ctxt::[edoc_context()](#type-edoc_context)) -> ok`
Main doclet entry point.
+
Also see [`edoc:layout/2`](edoc.html#layout-2) for layout-related options, and
[`edoc:get_doc/2`](edoc.html#get_doc-2) for options related to reading source
files.
@@ -42,61 +57,97 @@ files.
-###`{file_suffix, string()}`##
+<dt><code>{file_suffix, string()}</code>
+ </dt>
+
-
-Specifies the suffix used for output files. The default value is
- `".md"`.
-
-###`{hidden, bool()}`##
+<dd>Specifies the suffix used for output files. The default value is
+ <code>".md"</code>.
+ </dd>
+
-If the value is `true`, documentation of hidden modules and
- functions will also be included. The default value is `false`.
-
-
-###`{overview, [edoc:filename()](edoc.html#type-filename)}`##
+<dt><code>{hidden, bool()}</code>
+ </dt>
+
-Specifies the name of the overview-file. By default, this doclet
- looks for a file `"overview.edoc"` in the target directory.
+
+<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="edoc.html#type-filename">edoc:filename()</a>}</code>
+ </dt>
+
+
-###`{private, bool()}`##
+<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>
+
-If the value is `true`, documentation of private modules and
- functions will also be included. The default value is `false`.
+
+<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>
+
+
-###`{stylesheet, string()}`##
+<dt><code>{stylesheet, string()}</code>
+ </dt>
+
-Specifies the URI used for referencing the stylesheet. The
- default value is `"stylesheet.css"`. If an empty string is
+
+<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>
+
+
-
-###`{stylesheet_file, [edoc:filename()](edoc.html#type-filename)}`##
+<dt><code>{stylesheet_file, <a href="edoc.html#type-filename">edoc:filename()</a>}</code>
+ </dt>
+
-Specifies the name of the stylesheet file. By default, this
- doclet uses the file `"stylesheet.css"` in the `priv`
+
+<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>
-###`{title, string()}`##
-Specifies the title of the overview-page.
+
+<dt><code>{title, string()}</code>
+ </dt>
+
+
+
+<dd>Specifies the title of the overview-page.
+ </dd>
+
+
-_Generated by EDoc, Oct 23 2010, 20:51:59._
+
+_Generated by EDoc, Oct 25 2010, 17:08:25._
View
102 doc/edown_layout.md
@@ -2,108 +2,160 @@ Module edown_layout
===================
-#Module edown_layout#
+<h1>Module edown_layout</h1>
+
* [Description](#description)
* [Function Index](#index)
* [Function Details](#functions)
Github-flavored Markdown layout module for EDoc.
+
Copyright © 2010 Erlang Solutions Ltd
+
__Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com)).
-##<a name="description">Description</a>##
+<h2><a name="description">Description</a></h2>
+
Github-flavored Markdown layout module for EDoc.
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">Function Index</a>##
+<h2><a name="index">Function Index</a></h2>
+
+
<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##
+<h2>Function Details</h2>
+
<a name="markdown-3"></a>
-###markdown/3##
+<h3>markdown/3</h3>
+
+
+
`markdown(Title, CSS, Body) -> any()`
+
<a name="module-2"></a>
-###module/2##
+<h3>module/2</h3>
+
+
+
`module(Element, Options) -> any()`
+
+
+
The layout function.
Options to the standard layout:
-###`{index_columns, integer()}`##
+<dt><code>{index_columns, integer()}</code>
+ </dt>
+
-Specifies the number of column pairs used for the function
+
+<dd>Specifies the number of column pairs used for the function
index tables. The default value is 1.
-
+ </dd>
+
+
-###`{stylesheet, string()}`##
+<dt><code>{stylesheet, string()}</code>
+ </dt>
+
-Specifies the URI used for referencing the stylesheet. The
- default value is `"stylesheet.css"`. If an empty string is
+
+<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>
+
+
-###`{sort_functions, bool()}`##
+<dt><code>{sort_functions, bool()}</code>
+ </dt>
+
-If `true`, the detailed function descriptions are listed by
+
+<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 `true`.
-
-
+ the source file. The default value is <code>true</code>.
+ </dd>
-###`{xml_export, Module::atom()}`##
-Specifies an [`xmerl`](/Users/uwiger/ETC/git/xmerl/doc/index.html) callback module to be
- used for exporting the documentation. See [`//xmerl/xmerl:export_simple_content/2`](/Users/uwiger/ETC/git/xmerl/doc/xmerl.html#export_simple_content-2) for details.
+
+<dt><code>{xml_export, Module::atom()}</code>
+ </dt>
+
+
+
+<dd>Specifies an <a href="/Users/uwiger/ETC/git/xmerl/doc/index.html" target="_top"><code>xmerl</code></a> callback module to be
+ used for exporting the documentation. See <a href="/Users/uwiger/ETC/git/xmerl/doc/xmerl.html#export_simple_content-2"><code>//xmerl/xmerl:export_simple_content/2</code></a> for details.
+ </dd>
+
+
+
__See also:__ [edoc:layout/2](edoc.html#layout-2).
<a name="overview-2"></a>
-###overview/2##
+<h3>overview/2</h3>
+
+
+
`overview(E, Options) -> any()`
+
<a name="package-2"></a>
-###package/2##
+<h3>package/2</h3>
+
+
+
`package(E, Options) -> any()`
+
<a name="type-1"></a>
-###type/1##
+<h3>type/1</h3>
+
+
+
`type(E) -> any()`
-_Generated by EDoc, Oct 23 2010, 20:51:59._
+
+
+_Generated by EDoc, Oct 25 2010, 17:08:25._
View
25 doc/edown_lib.md
@@ -2,32 +2,45 @@ Module edown_lib
================
-#Module edown_lib#
+<h1>Module edown_lib</h1>
+
* [Description](#description)
* [Function Index](#index)
* [Function Details](#functions)
Github-flavored Markdown for EDoc - common support functions.
+
Copyright © 2010 Erlang Solutions Ltd
+
__Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com)).
-##<a name="description">Description</a>##
+<h2><a name="description">Description</a></h2>
+
Github-flavored Markdown for EDoc - common support functions
-##<a name="index">Function Index</a>##
+<h2><a name="index">Function Index</a></h2>
+
+
<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></table>
+
<a name="functions"></a>
-##Function Details##
+<h2>Function Details</h2>
+
<a name="export-1"></a>
-###export/1##
+<h3>export/1</h3>
+
+
+
`export(Data) -> any()`
-_Generated by EDoc, Oct 23 2010, 20:51:59._
+
+
+_Generated by EDoc, Oct 25 2010, 17:08:25._
View
40 doc/edown_xmerl.md
@@ -2,52 +2,76 @@ Module edown_xmerl
==================
-#Module edown_xmerl#
+<h1>Module edown_xmerl</h1>
+
* [Function Index](#index)
* [Function Details](#functions)
+
Copyright © 2010 Erlang Solutions Ltd
+
__Authors:__ Ulf Wiger ([`ulf.wiger@erlang-solutions.com`](mailto:ulf.wiger@erlang-solutions.com)).
-##<a name="index">Function Index</a>##
+<h2><a name="index">Function Index</a></h2>
+
+
<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##
+<h2>Function Details</h2>
+
<a name="%23element%23-5"></a>
-###'#element#'/5##
+<h3>'#element#'/5</h3>
+
+
+
`#element#(Tag, Data, Attrs, Parents, E) -> any()`
+
<a name="%23root%23-4"></a>
-###'#root#'/4##
+<h3>'#root#'/4</h3>
+
+
+
`#root#(Data, Attrs, X3, E) -> any()`
+
<a name="%23text%23-1"></a>
-###'#text#'/1##
+<h3>'#text#'/1</h3>
+
+
+
`#text#(Text) -> any()`
+
<a name="%23xml-inheritance%23-0"></a>
-###'#xml-inheritance#'/0##
+<h3>'#xml-inheritance#'/0</h3>
+
+
+
`#xml-inheritance#() -> any()`
-_Generated by EDoc, Oct 23 2010, 20:51:59._
+
+
+_Generated by EDoc, Oct 25 2010, 17:08:25._
View
37 src/edown_layout.erl
@@ -202,10 +202,32 @@ layout_module(#xmlElement{name = module, content = Es}=E, Opts) ->
%% io:fwrite("not edown_doclet (~p)~n", [Name])
%% end,
%% xhtml(Title, stylesheet(Opts), Body).
- Res = markdown(Title, stylesheet(Opts), Body),
+ Res = to_simple(markdown(Title, stylesheet(Opts), Body)),
%% io:fwrite("Res = ~p~n", [Res]),
Res.
+%% This function is a workaround for a bug in xmerl_lib:expand_content/1 that
+%% causes it to lose track of the parents if #xmlElement{} records are
+%% encountered in the structure.
+%%
+to_simple([#xmlElement{name = Name, attributes = Attrs, content = Content}|T]) ->
+ [{Name, to_simple_attrs(Attrs), to_simple(Content)} | to_simple(T)];
+to_simple([#xmlText{} = H | T]) ->
+ [H | to_simple(T)];
+to_simple([{N,C} | T]) ->
+ [{N, to_simple(C)} | to_simple(T)];
+to_simple([{N,As,C} | T]) ->
+ [{N, As, to_simple(C)} | to_simple(T)];
+to_simple([[_|_] = L | T]) ->
+ [to_simple(lists:flatten(L)) | to_simple(T)];
+to_simple([H|T]) ->
+ [H | to_simple(T)];
+to_simple([]) ->
+ [].
+
+to_simple_attrs(As) ->
+ [{K,V} || #xmlAttribute{name = K, value = V} <- As].
+
module_params(Es) ->
As = [{get_text(argName, Es1),
get_content(fullDescription, get_content(description, Es1))}
@@ -431,17 +453,18 @@ throws(Es) ->
case get_content(throws, Es) of
[] -> [];
Es1 ->
- [{p, (["throws ", {tt, t_utype(get_elem(type, Es1))}]
- ++ local_defs(get_elem(localdef, Es1)))}]
+ [{p, (["throws ",
+ {'div', [{class,"html"}], {tt, t_utype(get_elem(type, Es1))}}]
+ ++ local_defs(get_elem(localdef, Es1)))}]
end.
%% <!ELEMENT typespec (erlangName, type, localdef*)>
typespec([]) -> [];
typespec(Es) ->
- [{tt, ([t_name(get_elem(erlangName, Es))]
- ++ t_utype(get_elem(type, Es)))}]
- ++ local_defs(get_elem(localdef, Es)).
+ [{'div', [{class,"html"}], [{tt, ([t_name(get_elem(erlangName, Es))]
+ ++ t_utype(get_elem(type, Es)))}]}]
+ ++ local_defs(get_elem(localdef, Es)).
%% <!ELEMENT typedecl (typedef, description?)>
%% <!ELEMENT typedef (erlangName, argtypes, type?, localdef*)>
@@ -456,7 +479,7 @@ typedecl(Name, E=#xmlElement{content = Es}) ->
Lbl = Name ++ "()",
(label_anchor(Lbl, E)
++ [{h3, [{class, "typedecl"}], [Lbl]}]
- ++ [{p, typedef(get_content(typedef, Es))}]
+ ++ [{'div', [{class,"html"}], typedef(get_content(typedef, Es))}]
++ fulldesc(Es)).
type_name(#xmlElement{content = Es}) ->

0 comments on commit 659a33f

Please sign in to comment.