From 659a33f6b8a8e7492f6c02f2789b70298e80efd2 Mon Sep 17 00:00:00 2001 From: Ulf Wiger Date: Mon, 25 Oct 2010 17:10:05 +0200 Subject: [PATCH] more context-sensitive markup --- doc/README.md | 14 ++++- doc/edown_doclet.md | 119 ++++++++++++++++++++++++++++++------------- doc/edown_layout.md | 102 ++++++++++++++++++++++++++++--------- doc/edown_lib.md | 25 ++++++--- doc/edown_xmerl.md | 40 ++++++++++++--- src/edown_layout.erl | 37 +++++++++++--- 6 files changed, 255 insertions(+), 82 deletions(-) diff --git a/doc/README.md b/doc/README.md index 85e1124..0db6538 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,16 +1,20 @@ -#The edown application# +

The edown application

+ 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,6 +34,7 @@ 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), @@ -36,6 +42,7 @@ 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## +

Modules

+ +
edown_doclet
edown_layout
edown_lib
edown_xmerl
+ diff --git a/doc/edown_doclet.md b/doc/edown_doclet.md index edb158f..4b8692c 100644 --- a/doc/edown_doclet.md +++ b/doc/edown_doclet.md @@ -2,38 +2,53 @@ Module edown_doclet =================== -#Module edown_doclet# +

Module edown_doclet

+ * [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)). -##Description## +

Description

+ EDoc Doclet module for producing Github-flavored Markdown. -##Function Index## +

Function Index

+ +
run/2Main doclet entry point.
+ -##Function Details## +

Function Details

+ -###run/2## +

run/2

+ + + + + +run(Command::doclet_gen() | doclet_toc(), Ctxt::edoc_context()) -> ok + -`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()}`## +
{file_suffix, string()} +
+ - -Specifies the suffix used for output files. The default value is - `".md"`. - -###`{hidden, bool()}`## +
Specifies the suffix used for output files. The default value is + ".md". +
+ -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)}`## +
{hidden, bool()} +
+ -Specifies the name of the overview-file. By default, this doclet - looks for a file `"overview.edoc"` in the target directory. + +
If the value is true, documentation of hidden modules and + functions will also be included. The default value is false. +
+ + + +
{overview, edoc:filename()} +
+ + -###`{private, bool()}`## +
Specifies the name of the overview-file. By default, this doclet + looks for a file "overview.edoc" in the target directory. +
+ -If the value is `true`, documentation of private modules and - functions will also be included. The default value is `false`. + +
{private, bool()} +
+ + + +
If the value is true, documentation of private modules and + functions will also be included. The default value is false. +
+ + -###`{stylesheet, string()}`## +
{stylesheet, string()} +
+ -Specifies the URI used for referencing the stylesheet. The - default value is `"stylesheet.css"`. If an empty string is + +
Specifies the URI used for referencing the stylesheet. The + default value is "stylesheet.css". If an empty string is specified, no stylesheet reference will be generated. +
+ + - -###`{stylesheet_file, [edoc:filename()](edoc.html#type-filename)}`## +
{stylesheet_file, edoc:filename()} +
+ -Specifies the name of the stylesheet file. By default, this - doclet uses the file `"stylesheet.css"` in the `priv` + +
Specifies the name of the stylesheet file. By default, this + doclet uses the file "stylesheet.css" in the priv subdirectory of the EDoc installation directory. The named file will be copied to the target directory. - - +
-###`{title, string()}`## -Specifies the title of the overview-page. + +
{title, string()} +
+ + + +
Specifies the title of the overview-page. +
+ + -_Generated by EDoc, Oct 23 2010, 20:51:59._ \ No newline at end of file + +_Generated by EDoc, Oct 25 2010, 17:08:25._ \ No newline at end of file diff --git a/doc/edown_layout.md b/doc/edown_layout.md index 4237e1f..3b5f8b2 100644 --- a/doc/edown_layout.md +++ b/doc/edown_layout.md @@ -2,108 +2,160 @@ Module edown_layout =================== -#Module edown_layout# +

Module edown_layout

+ * [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)). -##Description## +

Description

+ 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. -##Function Index## +

Function Index

+ +
markdown/3
module/2The layout function.
overview/2
package/2
type/1
+ -##Function Details## +

Function Details

+ -###markdown/3## +

markdown/3

+ + + `markdown(Title, CSS, Body) -> any()` + -###module/2## +

module/2

+ + + `module(Element, Options) -> any()` + + + The layout function. Options to the standard layout: -###`{index_columns, integer()}`## +
{index_columns, integer()} +
+ -Specifies the number of column pairs used for the function + +
Specifies the number of column pairs used for the function index tables. The default value is 1. - +
+ + -###`{stylesheet, string()}`## +
{stylesheet, string()} +
+ -Specifies the URI used for referencing the stylesheet. The - default value is `"stylesheet.css"`. If an empty string is + +
Specifies the URI used for referencing the stylesheet. The + default value is "stylesheet.css". If an empty string is specified, no stylesheet reference will be generated. - +
+ + -###`{sort_functions, bool()}`## +
{sort_functions, bool()} +
+ -If `true`, the detailed function descriptions are listed by + +
If true, 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 true. +
-###`{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. + +
{xml_export, Module::atom()} +
+ + + +
Specifies an xmerl callback module to be + used for exporting the documentation. See //xmerl/xmerl:export_simple_content/2 for details. +
+ + + __See also:__ [edoc:layout/2](edoc.html#layout-2). -###overview/2## +

overview/2

+ + + `overview(E, Options) -> any()` + -###package/2## +

package/2

+ + + `package(E, Options) -> any()` + -###type/1## +

type/1

+ + + `type(E) -> any()` -_Generated by EDoc, Oct 23 2010, 20:51:59._ \ No newline at end of file + + +_Generated by EDoc, Oct 25 2010, 17:08:25._ \ No newline at end of file diff --git a/doc/edown_lib.md b/doc/edown_lib.md index 7caa961..e97a732 100644 --- a/doc/edown_lib.md +++ b/doc/edown_lib.md @@ -2,32 +2,45 @@ Module edown_lib ================ -#Module edown_lib# +

Module edown_lib

+ * [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)). -##Description## +

Description

+ Github-flavored Markdown for EDoc - common support functions -##Function Index## +

Function Index

+ +
export/1
+ -##Function Details## +

Function Details

+ -###export/1## +

export/1

+ + + `export(Data) -> any()` -_Generated by EDoc, Oct 23 2010, 20:51:59._ \ No newline at end of file + + +_Generated by EDoc, Oct 25 2010, 17:08:25._ \ No newline at end of file diff --git a/doc/edown_xmerl.md b/doc/edown_xmerl.md index af81ced..d8e672f 100644 --- a/doc/edown_xmerl.md +++ b/doc/edown_xmerl.md @@ -2,52 +2,76 @@ Module edown_xmerl ================== -#Module edown_xmerl# +

Module edown_xmerl

+ * [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)). -##Function Index## +

Function Index

+ +
'#element#'/5
'#root#'/4
'#text#'/1
'#xml-inheritance#'/0
+ -##Function Details## +

Function Details

+ -###'#element#'/5## +

'#element#'/5

+ + + `#element#(Tag, Data, Attrs, Parents, E) -> any()` + -###'#root#'/4## +

'#root#'/4

+ + + `#root#(Data, Attrs, X3, E) -> any()` + -###'#text#'/1## +

'#text#'/1

+ + + `#text#(Text) -> any()` + -###'#xml-inheritance#'/0## +

'#xml-inheritance#'/0

+ + + `#xml-inheritance#() -> any()` -_Generated by EDoc, Oct 23 2010, 20:51:59._ \ No newline at end of file + + +_Generated by EDoc, Oct 25 2010, 17:08:25._ \ No newline at end of file diff --git a/src/edown_layout.erl b/src/edown_layout.erl index de4d072..2a28831 100644 --- a/src/edown_layout.erl +++ b/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. %% 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)). %% %% @@ -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}) ->