diff options
Diffstat (limited to 'lib/erl_docgen')
| -rw-r--r-- | lib/erl_docgen/doc/src/block_tags.xml | 431 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/character_entities.xml | 546 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/docb_xml_check.xml | 59 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/fasc_dtds.xml | 115 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/fascicules.xml | 15 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/gazonk | 17 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/header_tags.xml | 183 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/inline_tags.xml | 257 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/man.gif | bin | 0 -> 6048 bytes | |||
| -rw-r--r-- | lib/erl_docgen/doc/src/overview.xml | 185 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/part.xml | 43 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/refman_dtds.xml | 667 | ||||
| -rw-r--r-- | lib/erl_docgen/doc/src/user_guide_dtds.xml | 181 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/Makefile (renamed from lib/erl_docgen/priv/docbuilder_dtd/Makefile) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/application.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/application.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/appref.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/appref.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/book.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/book.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/bookinsidecover.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/bookinsidecover.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/chapter.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/chapter.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/cites.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/cites.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/common.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/common.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/common.entities.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/common.entities.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/common.header.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/common.header.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/common.image.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/common.image.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/common.refs.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/common.refs.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/common.table.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/common.table.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/comref.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/comref.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/cref.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/cref.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/erlref.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/erlref.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/fascicules.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/fascicules.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/fileref.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/fileref.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/part.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/part.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/report.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/report.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/terms.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/terms.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/xhtml1-frameset.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/xhtml1-frameset.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/xhtml1-strict.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/xhtml1-strict.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/priv/dtd/xhtml1-transitional.dtd (renamed from lib/erl_docgen/priv/docbuilder_dtd/xhtml1-transitional.dtd) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/src/docgen_edoc_xml_cb.erl | 1154 | ||||
| -rw-r--r-- | lib/erl_docgen/src/docgen_otp_specs.erl (renamed from lib/erl_docgen/src/otp_specs.erl) | 0 | ||||
| -rw-r--r-- | lib/erl_docgen/src/docgen_xmerl_xml_cb.erl | 88 | ||||
| -rw-r--r-- | lib/erl_docgen/src/docgen_xml_check.erl | 45 |
41 files changed, 3986 insertions, 0 deletions
diff --git a/lib/erl_docgen/doc/src/block_tags.xml b/lib/erl_docgen/doc/src/block_tags.xml new file mode 100644 index 0000000000..f5ba083f38 --- /dev/null +++ b/lib/erl_docgen/doc/src/block_tags.xml @@ -0,0 +1,431 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Block Tags</title> + <prepared/> + <docno/> + <date/> + <rev/> + <file>block_tags.xml</file> + </header> + + <p>Block tags typically define a separate block of information, such + as a paragraph or a list.</p> + + <p>The following subset of block tags are common for all DTDs in + the DocBuilder DTD suite: + <marker id="block_subset"></marker> + <seealso marker="#pTAG"><p></seealso>, + <seealso marker="#preTAG"><pre></seealso>, + <seealso marker="#codeTAG"><code></seealso>, + <seealso marker="#listTAG"><list></seealso>, + <seealso marker="#taglistTAG"><taglist></seealso>, + <seealso marker="#codeincludeTAG"><codeinclude></seealso> and + <seealso marker="#erlevalTAG"><erleval></seealso>. + </p> + + <section> + <marker id="brTAG"></marker> + <title><br> - Line Break</title> + + <p>Forces a newline. Example:</p> + <pre> +Eat yourself<br/>senseless! + </pre> + <p>results in:</p> + <p>Eat yourself<br/>senseless!</p> + + <p>The <c><![CDATA[<br>]]></c> tag is both a block- and an inline + tag.</p> + </section> + + <section> + <marker id="codeTAG"></marker> + <title><code> - Code Example</title> + + <p>Highlight code examples. Example:</p> + <pre> +<code> +sum([H|T]) -> + H + sum(T); +sum([]) -> + 0. +</code> + </pre> + <p>results in:</p> + <code> +sum([H|T]) -> + H + sum(T); +sum([]) -> + 0. + </code> + + <p>There is an attribute <c>type = "erl" | "c" | "none"</c>, but + currently this attribute is ignored by DocBuilder. Default value + is <c>"none"</c></p> + + <note> + <p>No tags are allowed within the tag and no + <seealso marker="character_entities">character + entities</seealso> are expanded.</p> + </note> + </section> + + <section> + <marker id="codeincludeTAG"></marker> + <title><codeinclude> - Code Inclusion</title> + + <p>Include external code snippets. The attribute <c>file</c> + gives the file name and <c>tag</c> defines a string which + delimits the code snippet. Example:</p> + <pre> +<codeinclude file="gazonk" tag="%% Erlang example"/> + </pre> + <p>results in:</p> + <codeinclude file="gazonk" tag="%% Erlang example"/> + + <p>provided there is a file named <c>gazonk</c> looking like this: + </p> + <code> +... + +%% Erlang example +-module(gazonk). + +start() -> + {error,"Pid required!"}. +start(Pid) -> + spawn(fun() -> init(Pid) end). +%% Erlang example + +... + </code> + + <p>If the <c>tag</c> attribute is omitted, the whole file is + included.</p> + + <p>There is also an attribute <c>type = "erl" | "c" | "none"</c>, but + currently this attribute is ignored by DocBuilder. Default value + is <c>"none"</c></p> + </section> + + <section> + <marker id="erlevalTAG"></marker> + <title><erleval> - Erlang Evaluation</title> + + <p>Include the result from evaluating an Erlang expression. Example: + </p> + <code><![CDATA[ +<erleval expr="{A,b,C}={a,b,c}. "/> + ]]></code> + <p>results in:</p> + <erleval expr="{A,b,C}={a,b,c}. "></erleval> + + <p>Note the '.' and space after the expression.</p> + </section> + + <section> + <marker id="listTAG"></marker> + <title><list> - List</title> + + <p>The attribute <c>type = "ordered"|"bulleted"</c> decides if + the list is numbered or bulleted. Default is <c>"bulleted"</c>. + </p> + + <p>Lists contains list items, tag <c><![CDATA[<item>]]></c>, which + can contain plain text, + the <seealso marker="#block_subset">common subset of block + tags</seealso> and <seealso marker="inline_tags">inline + tags</seealso>. Example:</p> + <pre> +<list type="ordered"> + <item>Askosal: + <list> + <item>Nullalisis</item> + <item>Facilisis</item> + </list> + </item> + <item>Ankara</item> +</list> + </pre> + <p>results in:</p> + <list type="ordered"> + <item> + <p>Askosal:</p> + <list type="bulleted"> + <item>Nullalisis</item> + <item>Facilisis</item> + </list> + </item> + <item>Ankara</item> + </list> + </section> + + <section> + <marker id="markerTAG"></marker> + <title><marker> - Marker</title> + + <p>Used as an anchor for hypertext references. The + <c><![CDATA[<marker>]]></c> tag is both a block- and an inline + tag and is described in + the <seealso marker="inline_tags#markerTAG">Inline Tags</seealso> + section.</p> + </section> + + <section> + <marker id="pTAG"></marker> + <title><p> - Paragraph</title> + + <p>Paragraphs contain plain text and + <seealso marker="inline_tags">inline tags</seealso>. Example:</p> + <pre> +<p>I call specific attention to + the authority given by the <em>21st Amendment</em> + to the Constitution to prohibit transportation + or importation of intoxicating liquors into + any State in violation of the laws of such + State.</p> + </pre> + <p>results in:</p> + <p>I call specific attention to + the authority given by the <em>21st Amendment</em> + to the Constitution to prohibit transportation + or importation of intoxicating liquors into + any State in violation of the laws of such + State.</p> + </section> + + <section> + <marker id="noteTAG"></marker> + <title><note> - Note</title> + + <p>Highlights a note. Can contain block tags except + <c><![CDATA[<note>]]></c>, <c><![CDATA[<warning>]]></c>, + <c><![CDATA[<image>]]></c> and <c><![CDATA[<table>]]></c>. + Example:</p> +<pre> +<note> + <p>This function is mainly intended for debugging.</p> +</note> + </pre> + <p>results in:</p> + <note> + <p>This function is mainly intended for debugging.</p> + </note> + </section> + + <section> + <marker id="preTAG"></marker> + <title><pre> - Pre-formatted Text</title> + + <p>Used for documentation of system interaction. Can contain text, + <seealso marker="inline_tags#seealsoTAG">seealso</seealso>, + <seealso marker="inline_tags#urlTAG">url</seealso> and + <c><![CDATA[<input>]]></c> tags.</p> + + <p>The <c><![CDATA[<input>]]></c> tag is used to highlight user + input. Example:</p> + <pre> +<pre> +$ <input>erl</input> +Erlang (BEAM) emulator version 5.5.3 [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.5.3 (abort with ^G) +1> <input>pwd().</input> +/home/user +2> <input>halt().</input> +</pre> + </pre> + <p> results in:</p> + <pre> +$ <input>erl</input> +Erlang (BEAM) emulator version 5.5.3 [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.5.3 (abort with ^G) +1> <input>pwd().</input> +/home/user +2> <input>halt().</input> + </pre> + + <p>All <seealso marker="character_entities">character + entities</seealso> are expanded.</p> + </section> + + <section> + <marker id="quoteTAG"></marker> + <title><quote> - Quotation</title> + + <p>Highlight quotations from other works, or dialog spoken by + characters in a narrative. Contains one or more + <seealso marker="#pTAG"><p></seealso> tags. Example:</p> + <pre> +<p>Whereas Section 217(a) of the Act of Congress entitled +"An Act ..." approved June 16, 1933, provides as follows:</p> +<quote> + <p>Section 217(a) The President shall proclaim the law.</p> +</quote> + </pre> + <p>results in:</p> + <p>Whereas Section 217(a) of the Act of Congress entitled + "An Act ..." approved June 16, 1933, provides as follows:</p> + <quote> + <p>Section 217(a) The President shall proclaim the law.</p> + </quote> + </section> + + <section> + <marker id="taglistTAG"></marker> + <marker id="tagTAG"></marker> + <title><taglist> - Definition List</title> + + <p>Definition lists contains pairs of tags, + <c><![CDATA[<tag>]]></c>, and list items, + <c><![CDATA[<item>]]></c>.</p> + + <p><c><![CDATA[<tag>]]></c> can contain plain text, + <seealso marker="inline_tags#cTAG"><c></seealso>, + <seealso marker="inline_tags#emTAG"><em></seealso>, + <seealso marker="inline_tags#seealsoTAG"><seealso></seealso> + and <seealso marker="inline_tags#urlTAG"><url></seealso> + tags.</p> + + <p><c><![CDATA[<item>]]></c> can contain plain text, + the <seealso marker="#block_subset">common subset of block + tags</seealso> and <seealso marker="inline_tags">inline + tags</seealso>. Example:</p> + <pre> +<taglist> + <tag><c>eacces</c></tag> + <item>Permission denied.</item> + <tag><c>enoent</c></tag> + <item>No such file or directory.</item> +</taglist> + </pre> + <p>results in:</p> + <taglist> + <tag><c>eacces</c></tag> + <item>Permission denied.</item> + <tag><c>enoent</c></tag> + <item>No such file or directory.</item> + </taglist> + </section> + + <section> + <marker id="warningTAG"></marker> + <title><warning> - Warning</title> + + <p>Highlights a warning. Can contain block tags except + <c><![CDATA[<note>]]></c>, <c><![CDATA[<warning>]]></c>, + <c><![CDATA[<image>]]></c> and <c><![CDATA[<table>]]></c>. + Example:</p> +<pre> +<warning> + <p>This function might be removed in a future version without + prior warning.</p> +</warning> + </pre> + <p>results in:</p> + <warning> + <p>This function might be removed in a future version without + prior warning.</p> + </warning> + </section> + + <section> + <marker id="imageTAG"></marker> + <marker id="icaptionTAG"></marker> + <title><image> - Image</title> + + <p>Graphics is imported using the <c><![CDATA[<image>]]></c> tag. + An image caption <c><![CDATA[<icaption>]]></c>, containing plain + text, must be supplied. Example:</p> + <pre> +<image file="man"> + <icaption>A Silly Man</icaption> +</image> + </pre> + <p>results in:</p> + <image file="man.gif"> + <icaption>A Silly Man</icaption> + </image> + + <p>This assumes that <c>man.gif</c> exists in the current directory. + </p> + </section> + + <section> + <marker id="tableTAG"></marker> + <marker id="rowTAG"></marker> + <marker id="cellTAG"></marker> + <marker id="tcaptionTAG"></marker> + <title><table> - Table</title> + + <p>The table format is similar to how tables are described in HTML + 3.2. A table contains one or more rows, <c><![CDATA[<row>]]></c>, + and a table caption <c><![CDATA[<tcaption>]]></c>, containing + plain text.</p> + + <p>Each row contains one or more cells, <c><![CDATA[<cell>]]></c>. + The attributes <c>align = "left"|"center"|"right"</c> and + <c>valign = "top"|"middle"|"bottom"</c> decides how text is + aligned in the cell horizontally and vertically. Default is + "<c>left</c>" and "<c>middle</c>".</p> + + <p>Each cell contains plain text and + <seealso marker="inline_tags">inline tags</seealso>. Example:</p> + <pre><![CDATA[ + <table> + <row> + <cell align="left" valign="top"><em>Boys</em></cell> + <cell align="center" valign="middle"><em>Girls</em></cell> + </row> + <row> + <cell align="left" valign="middle">Juda</cell> + <cell align="right" valign="bottom">Susy</cell> + </row> + <row> + <cell align="left" valign="middle">Anders</cell> + <cell align="left" valign="middle">Victoria</cell> + </row> + <tcaption>A table caption</tcaption> + </table> + ]]></pre> + <p>results in:</p> + <table> + <row> + <cell align="left" valign="top"><em>Boys</em></cell> + <cell align="center" valign="middle"><em>Girls</em></cell> + </row> + <row> + <cell align="left" valign="middle">Juda</cell> + <cell align="right" valign="bottom">Susy</cell> + </row> + <row> + <cell align="left" valign="middle">Anders</cell> + <cell align="left" valign="middle">Victoria</cell> + </row> + <tcaption>A table caption</tcaption> + </table> + </section> +</chapter> + diff --git a/lib/erl_docgen/doc/src/character_entities.xml b/lib/erl_docgen/doc/src/character_entities.xml new file mode 100644 index 0000000000..0a4ae17fb5 --- /dev/null +++ b/lib/erl_docgen/doc/src/character_entities.xml @@ -0,0 +1,546 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2011</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Character Entities</title> + <prepared/> + <docno/> + <date/> + <rev/> + <file>character_entities.xml</file> + </header> + + <section> + <title>Added Latin 1</title> + + <p>The DocBuilder DTD suite uses the same character entities as + defined in HTML 3.2 + (<c>ISO 8879-1986//ENTITIES Added Latin 1//EN//HTML</c>). That is: + for an & (ampersand), use the entity: <c>&amp;</c>, for + ö use the entity <c>&ouml;</c> and so on.</p> + + <table> + <row> + <cell align="left" valign="middle"><em>Character</em></cell> + <cell align="left" valign="middle"><em>Entity</em></cell> + <cell align="left" valign="middle"><em>Description</em></cell> + </row> + <row> + <cell align="left" valign="middle">&</cell> + <cell align="left" valign="middle">&amp;</cell> + <cell align="left" valign="middle">ampersand</cell> + </row> + <row> + <cell align="left" valign="middle">></cell> + <cell align="left" valign="middle">&gt;</cell> + <cell align="left" valign="middle">greater than</cell> + </row> + <row> + <cell align="left" valign="middle"><</cell> + <cell align="left" valign="middle">&lt;</cell> + <cell align="left" valign="middle">less than</cell> + </row> + <row> + <cell align="left" valign="middle"> </cell> + <cell align="left" valign="middle">&nbsp;</cell> + <cell align="left" valign="middle">no-break space</cell> + </row> + <row> + <cell align="left" valign="middle">¡</cell> + <cell align="left" valign="middle">&iexcl;</cell> + <cell align="left" valign="middle">inverted exclamation mark</cell> + </row> + <row> + <cell align="left" valign="middle">¢</cell> + <cell align="left" valign="middle">&cent;</cell> + <cell align="left" valign="middle">cent sign</cell> + </row> + <row> + <cell align="left" valign="middle">£</cell> + <cell align="left" valign="middle">&pound;</cell> + <cell align="left" valign="middle">pound sterling sign</cell> + </row> + <row> + <cell align="left" valign="middle">¤</cell> + <cell align="left" valign="middle">&curren;</cell> + <cell align="left" valign="middle">general currency sign</cell> + </row> + <row> + <cell align="left" valign="middle">¥</cell> + <cell align="left" valign="middle">&yen;</cell> + <cell align="left" valign="middle">yen sign</cell> + </row> + <row> + <cell align="left" valign="middle">¦</cell> + <cell align="left" valign="middle">&brvbar;</cell> + <cell align="left" valign="middle">broken (vertical) bar</cell> + </row> + <row> + <cell align="left" valign="middle">§</cell> + <cell align="left" valign="middle">&sect;</cell> + <cell align="left" valign="middle">section sign</cell> + </row> + <row> + <cell align="left" valign="middle">¨</cell> + <cell align="left" valign="middle">&uml;</cell> + <cell align="left" valign="middle">umlaut (dieresis)</cell> + </row> + <row> + <cell align="left" valign="middle">©</cell> + <cell align="left" valign="middle">&copy;</cell> + <cell align="left" valign="middle">copyright sign</cell> + </row> + <row> + <cell align="left" valign="middle">ª</cell> + <cell align="left" valign="middle">&ordf;</cell> + <cell align="left" valign="middle">ordinal indicator, feminine</cell> + </row> + <row> + <cell align="left" valign="middle">«</cell> + <cell align="left" valign="middle">&laquo;</cell> + <cell align="left" valign="middle">angle quotation mark, left</cell> + </row> + <row> + <cell align="left" valign="middle">¬</cell> + <cell align="left" valign="middle">&not;</cell> + <cell align="left" valign="middle">not sign</cell> + </row> + <row> + <cell align="left" valign="middle"></cell> <!-- a space is used instead of ­ due to bug in fop 1.0 --> + <cell align="left" valign="middle">&shy;</cell> + <cell align="left" valign="middle">soft hyphen</cell> + </row> + <row> + <cell align="left" valign="middle">®</cell> + <cell align="left" valign="middle">&reg;</cell> + <cell align="left" valign="middle">registered sign</cell> + </row> + <row> + <cell align="left" valign="middle">¯</cell> + <cell align="left" valign="middle">&macr;</cell> + <cell align="left" valign="middle">macron</cell> + </row> + <row> + <cell align="left" valign="middle">°</cell> + <cell align="left" valign="middle">&deg;</cell> + <cell align="left" valign="middle">degree sign</cell> + </row> + <row> + <cell align="left" valign="middle">±</cell> + <cell align="left" valign="middle">&plusmn;</cell> + <cell align="left" valign="middle">plus-or-minus</cell> + </row> + <row> + <cell align="left" valign="middle">²</cell> + <cell align="left" valign="middle">&sup2;</cell> + <cell align="left" valign="middle">superscript two</cell> + </row> + <row> + <cell align="left" valign="middle">³</cell> + <cell align="left" valign="middle">&sup3;</cell> + <cell align="left" valign="middle">superscript three</cell> + </row> + <row> + <cell align="left" valign="middle">´</cell> + <cell align="left" valign="middle">&acute;</cell> + <cell align="left" valign="middle">acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">µ</cell> + <cell align="left" valign="middle">&micro;</cell> + <cell align="left" valign="middle">micro sign</cell> + </row> + <row> + <cell align="left" valign="middle">¶</cell> + <cell align="left" valign="middle">&para;</cell> + <cell align="left" valign="middle">pilcrow (paragraph sign)</cell> + </row> + <row> + <cell align="left" valign="middle">·</cell> + <cell align="left" valign="middle">&middot;</cell> + <cell align="left" valign="middle">middle dot</cell> + </row> + <row> + <cell align="left" valign="middle">¸</cell> + <cell align="left" valign="middle">&cedil;</cell> + <cell align="left" valign="middle">cedilla</cell> + </row> + <row> + <cell align="left" valign="middle">¹</cell> + <cell align="left" valign="middle">&sup1;</cell> + <cell align="left" valign="middle">superscript one</cell> + </row> + <row> + <cell align="left" valign="middle">º</cell> + <cell align="left" valign="middle">&ordm;</cell> + <cell align="left" valign="middle">ordinal indicator, masculine</cell> + </row> + <row> + <cell align="left" valign="middle">»</cell> + <cell align="left" valign="middle">&raquo;</cell> + <cell align="left" valign="middle">angle quotation mark, right</cell> + </row> + <row> + <cell align="left" valign="middle">¼</cell> + <cell align="left" valign="middle">&frac14;</cell> + <cell align="left" valign="middle">fraction one-quarter</cell> + </row> + <row> + <cell align="left" valign="middle">½</cell> + <cell align="left" valign="middle">&frac12;</cell> + <cell align="left" valign="middle">fraction one-half</cell> + </row> + <row> + <cell align="left" valign="middle">¾</cell> + <cell align="left" valign="middle">&frac34;</cell> + <cell align="left" valign="middle">fraction three-quarters</cell> + </row> + <row> + <cell align="left" valign="middle">¿</cell> + <cell align="left" valign="middle">&iquest;</cell> + <cell align="left" valign="middle">inverted question mark</cell> + </row> + <row> + <cell align="left" valign="middle">À</cell> + <cell align="left" valign="middle">&Agrave;</cell> + <cell align="left" valign="middle">capital A, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">Á</cell> + <cell align="left" valign="middle">&Aacute;</cell> + <cell align="left" valign="middle">capital A, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">Â</cell> + <cell align="left" valign="middle">&Acirc;</cell> + <cell align="left" valign="middle">capital A, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">Ã</cell> + <cell align="left" valign="middle">&Atilde;</cell> + <cell align="left" valign="middle">capital A, tilde</cell> + </row> + <row> + <cell align="left" valign="middle">Ä</cell> + <cell align="left" valign="middle">&Auml;</cell> + <cell align="left" valign="middle">capital A, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">Å</cell> + <cell align="left" valign="middle">&Aring;</cell> + <cell align="left" valign="middle">capital A, ring</cell> + </row> + <row> + <cell align="left" valign="middle">Æ</cell> + <cell align="left" valign="middle">&AElig;</cell> + <cell align="left" valign="middle">capital AE diphthong (ligature)</cell> + </row> + <row> + <cell align="left" valign="middle">Ç</cell> + <cell align="left" valign="middle">&Ccedil;</cell> + <cell align="left" valign="middle">capital C, cedilla</cell> + </row> + <row> + <cell align="left" valign="middle">È</cell> + <cell align="left" valign="middle">&Egrave;</cell> + <cell align="left" valign="middle">capital E, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">É</cell> + <cell align="left" valign="middle">&Eacute;</cell> + <cell align="left" valign="middle">capital E, acute accen</cell> + </row> + <row> + <cell align="left" valign="middle">Ê</cell> + <cell align="left" valign="middle">&Ecirc;</cell> + <cell align="left" valign="middle">capital E, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">Ë</cell> + <cell align="left" valign="middle">&Euml;</cell> + <cell align="left" valign="middle">capital E, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">Ì</cell> + <cell align="left" valign="middle">&Igrave;</cell> + <cell align="left" valign="middle">capital I, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">Í</cell> + <cell align="left" valign="middle">&Iacute;</cell> + <cell align="left" valign="middle">capital I, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">Î</cell> + <cell align="left" valign="middle">&Icirc;</cell> + <cell align="left" valign="middle">capital I, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">Ï</cell> + <cell align="left" valign="middle">&Iuml;</cell> + <cell align="left" valign="middle">capital I, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">Ð</cell> + <cell align="left" valign="middle">&ETH;</cell> + <cell align="left" valign="middle">capital Eth, Icelandic</cell> + </row> + <row> + <cell align="left" valign="middle">Ñ</cell> + <cell align="left" valign="middle">&Ntilde;</cell> + <cell align="left" valign="middle">capital N, tilde</cell> + </row> + <row> + <cell align="left" valign="middle">Ò</cell> + <cell align="left" valign="middle">&Ograve;</cell> + <cell align="left" valign="middle">capital O, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">Ó</cell> + <cell align="left" valign="middle">&Oacute;</cell> + <cell align="left" valign="middle">capital O, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">Ô</cell> + <cell align="left" valign="middle">&Ocirc;</cell> + <cell align="left" valign="middle">capital O, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">Õ</cell> + <cell align="left" valign="middle">&Otilde;</cell> + <cell align="left" valign="middle">capital O, tilde</cell> + </row> + <row> + <cell align="left" valign="middle">Ö</cell> + <cell align="left" valign="middle">&Ouml;</cell> + <cell align="left" valign="middle">capital O, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">×</cell> + <cell align="left" valign="middle">&times;</cell> + <cell align="left" valign="middle">multiply sign</cell> + </row> + <row> + <cell align="left" valign="middle">Ø</cell> + <cell align="left" valign="middle">&Oslash;</cell> + <cell align="left" valign="middle">capital O, slash</cell> + </row> + <row> + <cell align="left" valign="middle">Ù</cell> + <cell align="left" valign="middle">&Ugrave;</cell> + <cell align="left" valign="middle">capital U, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">Ú</cell> + <cell align="left" valign="middle">&Uacute;</cell> + <cell align="left" valign="middle">capital U, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">Û</cell> + <cell align="left" valign="middle">&Ucirc;</cell> + <cell align="left" valign="middle">capital U, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">Ü</cell> + <cell align="left" valign="middle">&Uuml;</cell> + <cell align="left" valign="middle">capital U, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">Ý</cell> + <cell align="left" valign="middle">&Yacute;</cell> + <cell align="left" valign="middle">capital Y, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">Þ</cell> + <cell align="left" valign="middle">&THORN;</cell> + <cell align="left" valign="middle">capital THORN, Icelandic</cell> + </row> + <row> + <cell align="left" valign="middle">ß</cell> + <cell align="left" valign="middle">&szlig;</cell> + <cell align="left" valign="middle">small sharp s, German (sz ligature)</cell> + </row> + <row> + <cell align="left" valign="middle">à</cell> + <cell align="left" valign="middle">&agrave;</cell> + <cell align="left" valign="middle">small a, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">á</cell> + <cell align="left" valign="middle">&aacute;</cell> + <cell align="left" valign="middle">small a, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">â</cell> + <cell align="left" valign="middle">&acirc;</cell> + <cell align="left" valign="middle">small a, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">ã</cell> + <cell align="left" valign="middle">&atilde;</cell> + <cell align="left" valign="middle">small a, tilde</cell> + </row> + <row> + <cell align="left" valign="middle">ä</cell> + <cell align="left" valign="middle">&auml;</cell> + <cell align="left" valign="middle">small a, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">å</cell> + <cell align="left" valign="middle">&aring;</cell> + <cell align="left" valign="middle">small a, ring</cell> + </row> + <row> + <cell align="left" valign="middle">æ</cell> + <cell align="left" valign="middle">&aelig;</cell> + <cell align="left" valign="middle">small ae diphthong (ligature)</cell> + </row> + <row> + <cell align="left" valign="middle">ç</cell> + <cell align="left" valign="middle">&ccedil;</cell> + <cell align="left" valign="middle">small c, cedilla</cell> + </row> + <row> + <cell align="left" valign="middle">è</cell> + <cell align="left" valign="middle">&egrave;</cell> + <cell align="left" valign="middle">small e, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">é</cell> + <cell align="left" valign="middle">&eacute;</cell> + <cell align="left" valign="middle">small e, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">ê</cell> + <cell align="left" valign="middle">&ecirc;</cell> + <cell align="left" valign="middle">small e, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">ë</cell> + <cell align="left" valign="middle">&euml;</cell> + <cell align="left" valign="middle">small e, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">ì</cell> + <cell align="left" valign="middle">&igrave;</cell> + <cell align="left" valign="middle">small i, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">í</cell> + <cell align="left" valign="middle">&iacute;</cell> + <cell align="left" valign="middle">small i, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">î</cell> + <cell align="left" valign="middle">&icirc;</cell> + <cell align="left" valign="middle">small i, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">ï</cell> + <cell align="left" valign="middle">&iuml;</cell> + <cell align="left" valign="middle">small i, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">ð</cell> + <cell align="left" valign="middle">&eth;</cell> + <cell align="left" valign="middle">small eth, Icelandic</cell> + </row> + <row> + <cell align="left" valign="middle">ñ</cell> + <cell align="left" valign="middle">&ntilde;</cell> + <cell align="left" valign="middle">small n, tilde</cell> + </row> + <row> + <cell align="left" valign="middle">ò</cell> + <cell align="left" valign="middle">&ograve;</cell> + <cell align="left" valign="middle">small o, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">ó</cell> + <cell align="left" valign="middle">&oacute;</cell> + <cell align="left" valign="middle">small o, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">ô</cell> + <cell align="left" valign="middle">&ocirc;</cell> + <cell align="left" valign="middle">small o, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">õ</cell> + <cell align="left" valign="middle">&otilde;</cell> + <cell align="left" valign="middle">small o, tilde</cell> + </row> + <row> + <cell align="left" valign="middle">ö</cell> + <cell align="left" valign="middle">&ouml;</cell> + <cell align="left" valign="middle">small o, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">÷</cell> + <cell align="left" valign="middle">&divide;</cell> + <cell align="left" valign="middle">divide sign</cell> + </row> + <row> + <cell align="left" valign="middle">ø</cell> + <cell align="left" valign="middle">&oslash;</cell> + <cell align="left" valign="middle">small o, slash</cell> + </row> + <row> + <cell align="left" valign="middle">ù</cell> + <cell align="left" valign="middle">&ugrave;</cell> + <cell align="left" valign="middle">small u, grave accent</cell> + </row> + <row> + <cell align="left" valign="middle">ú</cell> + <cell align="left" valign="middle">&uacute;</cell> + <cell align="left" valign="middle">small u, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">û</cell> + <cell align="left" valign="middle">&ucirc;</cell> + <cell align="left" valign="middle">small u, circumflex accent</cell> + </row> + <row> + <cell align="left" valign="middle">ü</cell> + <cell align="left" valign="middle">&uuml;</cell> + <cell align="left" valign="middle">small u, dieresis or umlaut mark</cell> + </row> + <row> + <cell align="left" valign="middle">ý</cell> + <cell align="left" valign="middle">&yacute;</cell> + <cell align="left" valign="middle">small y, acute accent</cell> + </row> + <row> + <cell align="left" valign="middle">þ</cell> + <cell align="left" valign="middle">&thorn;</cell> + <cell align="left" valign="middle">small thorn, Icelandic</cell> + </row> + <row> + <cell align="left" valign="middle">ÿ</cell> + <cell align="left" valign="middle">&yuml;</cell> + <cell align="left" valign="middle">small y, dieresis or umlaut mark</cell> + </row> + <tcaption>Accented Latin-1 alphabetic characters.</tcaption> + </table> + </section> +</chapter> + diff --git a/lib/erl_docgen/doc/src/docb_xml_check.xml b/lib/erl_docgen/doc/src/docb_xml_check.xml new file mode 100644 index 0000000000..eff4fc4342 --- /dev/null +++ b/lib/erl_docgen/doc/src/docb_xml_check.xml @@ -0,0 +1,59 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2007</year> + <year>2011</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>docb_xml_check</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>docb_xml_check</module> + <modulesummary>Validate XML documentation source code</modulesummary> + <description> + <p><c>docb_xml_check</c> contains functions for validating XML + documentation source code.</p> + </description> + + <funcs> + <func> + <name>validate(File) -> ok | error | {error, badfile}</name> + <fsummary>Validate XML source code.</fsummary> + <type> + <v>File = string()</v> + </type> + <desc> + <p>Validates the XML documentation source code in <c>File</c>. + The <c>.xml</c> extension can be omitted.</p> + + <p>Returns <c>ok</c> if successful, otherwise error information + is printed and the function returns <c>error</c>. + If <c>File</c> does not exist, <c>{error, badfile}</c> is + returned.</p> + </desc> + </func> + </funcs> + +</erlref> + diff --git a/lib/erl_docgen/doc/src/fasc_dtds.xml b/lib/erl_docgen/doc/src/fasc_dtds.xml new file mode 100644 index 0000000000..dec8189b55 --- /dev/null +++ b/lib/erl_docgen/doc/src/fasc_dtds.xml @@ -0,0 +1,115 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2007</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Fascicules DTDs</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>fasc_dtds.xml</file> + </header> + + <section> + <title>The fascicules DTD</title> + + <p>The <c>fascicules</c> DTD is a special kind of DTD which can be + used to specify the different parts of the documentation, and + which one of those should be shown as default.</p> + + <p>Example:</p> + + <pre><![CDATA[ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> +<fascicules> + <fascicule file="part" href="part_frame.html" entry="no"> + User's Guide + </fascicule> + <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> + Reference Manual + </fascicule> + <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> + Release Notes + </fascicule> +</fascicules> + ]]></pre> + + <p>In the example, it is specified that the documentation for this + application consists of three parts: User's Guide, where + the "cover page" (with the two frames) is located in + <c>part_frame.html</c>, Reference Manual with the cover page + <c>ref_man_frame.html</c> and Release Notes with the cover page + <c>part_notes_frame.html</c>.</p> + + <p>As a result, at the top of the left frame in the generated HTML + documentation, there will be corresponding links to User's Guide, + Reference Manual and Release Notes.</p> + + <p>The attribute <c>entry="yes"</c> specifies that it is + the Reference Manual which should be shown as default. This means + that when generating the HTML files, <c>application_frame.html</c> + will be copied to <c>index.html</c>.</p> + + <note> + <p>DocBuilder assumes that the XML file written according to + the <c>fascicules</c> DTD is called <c>fascicules.xml</c>.</p> + </note> + + <p>This file is optional. If it does not exist, there are no links + to other parts of the documentation (as they are not known) in + the left frame, and no <c>index.html</c> is created.</p> + </section> + + <section> + <marker id="fasciculesTAG"></marker> + <title><fascicules></title> + + <p>Top level tag for the <c>fascicules</c> DTD.</p> + + <p>Contains one or more + <seealso marker="#fasciculeTAG"><fascicule></seealso>.</p> + </section> + + <section> + <marker id="fasciculeTAG"></marker> + <title><fascicule></title> + + <p>Specifies properties for one "part" of the documentation for an + application.</p> + + <p>Contains plain text, the name of this part.</p> + + <p>The <c>file</c> attribute should specify the file name for + the corresponding <c>part</c> or <c>application</c>, without + the <c>.xml</c> extension.</p> + + <p>The <c>href</c> attribute should specify the file name for + the corresponding HTML cover page file, without the <c>.html</c> + extension.</p> + + <p>The optional <c>entry="yes"|"no"</c> attribute specifies if + the HTML cover page should be copied to <c>index.html</c> or + not. Default is <c>"no"</c>.</p> + </section> +</chapter> + diff --git a/lib/erl_docgen/doc/src/fascicules.xml b/lib/erl_docgen/doc/src/fascicules.xml new file mode 100644 index 0000000000..1b9d6bc94d --- /dev/null +++ b/lib/erl_docgen/doc/src/fascicules.xml @@ -0,0 +1,15 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> + +<fascicules> + <fascicule file="part" href="part_frame.html" entry="no"> + User's Guide + </fascicule> + <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> + Reference Manual + </fascicule> + <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> + Release Notes + </fascicule> +</fascicules> + diff --git a/lib/erl_docgen/doc/src/gazonk b/lib/erl_docgen/doc/src/gazonk new file mode 100644 index 0000000000..1cf0b8f7bc --- /dev/null +++ b/lib/erl_docgen/doc/src/gazonk @@ -0,0 +1,17 @@ +This example code is used in block_tags.xml. + +%% Erlang example +-module(gazonk). + +start() -> + {error,"Pid required!"}. + +start(Pid) -> + spawn(smalltalk,main,[]). +%% Erlang example + +// A little C example +int main() { + for(;;); +} +// A little C example diff --git a/lib/erl_docgen/doc/src/header_tags.xml b/lib/erl_docgen/doc/src/header_tags.xml new file mode 100644 index 0000000000..b1456d679a --- /dev/null +++ b/lib/erl_docgen/doc/src/header_tags.xml @@ -0,0 +1,183 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Header Tags</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>header_tags.xml</file> + </header> + + <p>Each document begins with a header part, which looks the same for + all DTDs. Here the title of the document is specified, as well as + administrative data like who is responsible for the document, which + version is it, when was it last changed and such.</p> + + <p>An full header looks like:</p> + <pre> +<header> + <copyright>...</copyright> + <legalnotice>...</legalnotice> + <title>...</title> + <prepared>...</prepared> + <responsible>...</responsible> + <docno>...</docno> + <approved>...</approved> + <checked>...</checked> + <date>...</date> + <rev>...</rev> + <file>...</file> +</header> + </pre> + + <section> + <marker id="headerTAG"></marker> + <title><header></title> + + <p>Top level tag for the header part.</p> + </section> + + <section> + <marker id="copyrightTAG"></marker> + <title><copyright></title> + + <p>The <c>copyright</c> element holds information about date(s) and holder(s) of + a document copyright. The <c>copyright</c> element is optional. + The <c>copyright</c> element has an inner structure containing one or + more + <c>year</c> elements followed by zero of more <c>holder</c> elements.<br/> + See example below: + </p> + <code><![CDATA[ + <copyright> + <year>1997</year> + <year>2007</year> + <holder>Ericsson AB</holder> + </copyright> + ]]></code> + </section> + + <section> + <marker id="legalnoticeTAG"></marker> + <title><legalnotice></title> + + <p>The <c>legalnotice</c> element is used to express copyright, trademark, + license, and other legal formalities of a document. The element contains + only PCDATA in the same manner as <c>code</c> and <c>pre</c>. + </p> + </section> + + <section> + <marker id="titleTAG"></marker> + <title><title></title> + + <p>For <c>part</c> and <c>application</c> documents, this will be + the title of the document, visible in the left frame and on + the front page.</p> + + <p>For <c>chapter</c> documents, this will be the chapter name.</p> + + <p>For reference manual documents, this tag is ignored.</p> + </section> + + <section> + <title><shorttitle></title> + + <p>This optional tag is ignored by DocBuilder. It will likely be + removed in the future.</p> + </section> + + <section> + <marker id="preparedTAG"></marker> + <title><prepared></title> + + <p>This tag is intended for administrative use and is ignored by + DocBuilder.</p> + </section> + + <section> + <marker id="responsibleTAG"></marker> + <title><responsible></title> + + <p>This optional tag is intended for administrative use and is + ignored by DocBuilder.</p> + </section> + + <section> + <marker id="docnoTAG"></marker> + <title><docno></title> + + <p>Document number.</p> + + <p>For <c>part</c> and <c>application</c> documents, the document + number is visible in the left frame and on the front page.</p> + + <p>For other types of documents, this tag is ignored.</p> + </section> + + <section> + <marker id="approvedTAG"></marker> + <title><approved></title> + + <p>This optional tag is intended for administrative use and is + ignored by DocBuilder.</p> + </section> + + <section> + <marker id="checkedTAG"></marker> + <title><checked></title> + + <p>This optional tag is intended for administrative use and is + ignored by DocBuilder.</p> + </section> + + <section> + <marker id="dateTAG"></marker> + <title><date></title> + + <p>This tag is intended for administrative use and is ignored by + DocBuilder.</p> + </section> + + <section> + <marker id="revTAG"></marker> + <title><rev></title> + + <p>Document version.</p> + + <p>For <c>part</c> and <c>application</c> documents, the document + version is visible in the left frame and on the front page.</p> + + <p>For other types of documents, this tag is ignored.</p> + </section> + + <section> + <marker id="fileTAG"></marker> + <title><file></title> + + <p>This optional tag is intended for administrative use and is + ignored by DocBuilder.</p> + </section> +</chapter> + diff --git a/lib/erl_docgen/doc/src/inline_tags.xml b/lib/erl_docgen/doc/src/inline_tags.xml new file mode 100644 index 0000000000..5bcca54c05 --- /dev/null +++ b/lib/erl_docgen/doc/src/inline_tags.xml @@ -0,0 +1,257 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2011</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Inline Tags</title> + <prepared/> + <docno/> + <date/> + <rev/> + <file>inline_tags.xml</file> + </header> + + <p>Inline tags are typically used within block tags, for example to + highlight a word within a paragraph.</p> + + <section> + <marker id="brTAG"></marker> + <title><br> - Line Break</title> + + <p>Forces a newline. The <c><![CDATA[<br>]]></c> tag is both a + block- and an inline tag and is described in + the <seealso marker="block_tags#brTAG">Block Tags</seealso> + section.</p> + </section> + + <section> + <marker id="cTAG"></marker> + <title><c> - Code</title> + + <p>Highlights things like variables and file names in a text flow. + Can contain plain text only. Newlines and tabs are ignored as + opposed to the <seealso marker="block_tags#codeTAG">code</seealso> + tag. All <seealso marker="character_entities">character + entities</seealso> are expanded. Example:</p> + <pre> +<p>Returns <c>true</c> if <c>Term</c> is an integer.</p> + </pre> + <p>results in:</p> + <p>Returns <c>true</c> if <c>Term</c> is an integer.</p> + </section> + + <section> + <marker id="emTAG"></marker> + <title><em> - Emphasis</title> + + <p>Highlights words which are important within a text flow. Example: + </p> + <pre> +<p>The application <em>must</em> be up and running.</p> + </pre> + <p>results in:</p> + <p>The application <em>must</em> be up and running.</p> + + <p>Contains plain text or a + <seealso marker="#cTAG"><c></seealso> tag.</p> + </section> + + <section> + <marker id="markerTAG"/> + <title><marker> - Marker</title> + + <p>Used as an anchor for hypertext references. The <c>id</c> + attribute defines the name of the marker. Example:</p> + <marker id="marker_example"/> + <pre> +<marker id="marker_example"/> + </pre> + + <p>The <seealso marker="#seealsoTAG"><seealso></seealso> tag + is used to refer to the marker.</p> + + <p>The <c><![CDATA[<marker>]]></c> tag is both a block- and an + inline tag.</p> + </section> + + <section> + <marker id="pathTAG"></marker> + <title><path> - Path</title> + + <p>Highlights file paths. The attributes <c>unix</c> and + <c>windows</c> makes it possible to specify different paths for + different file path notations. Default for both are "". + Example:</p> + <pre> +<p>Look at the <path unix=".profile" windows="win.ini">start-up file</path> + if you intend to alter the initial behavior.</p> + </pre> + <p>If no <c>ptype</c> option is specified when calling + <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso>, + this simply results in:</p> + <p>"Look at the <path>start-up file</path> + if you intend to alter the initial behavior."</p> + + <p>If both the options <c>{ptype,unix}</c> and + <c>{ptype,windows}</c> are specified, the example instead results + in:</p> + <p>"Look at the <path unix=".profile" windows="win.ini">start-up file</path> + if you intend to alter the initial behavior."</p> + </section> + + <section> + <marker id="seealsoTAG"></marker> + <title><seealso> - Local Cross Reference</title> + + <p>A cross reference (hypertext link) to a marker in the same file, + a marker in another file, or (the top of) another file, given by + the <c>marker</c> attribute. Must contain plain text. Examples: + </p> + + <pre><![CDATA[ + <seealso marker="#marker_example">marker example</seealso> + ]]></pre> + <p>results in: + <seealso marker="#marker_example">marker example</seealso> + (a hypertext link to the marker example above).</p> + + <pre><![CDATA[ + <seealso marker="block_tags#markerTAG">marker tag</seealso> + ]]></pre> + <p>results in: + <seealso marker="block_tags#markerTAG">marker tag</seealso> + (a hypertext link to the marker section in the Block Tags + chapter).</p> + + <pre><![CDATA[ + <seealso marker="overview">Overview</seealso> + ]]></pre> + <p>results in: + <seealso marker="overview">Overview</seealso> + (a hypertext link to the Overview chapter).</p> + + <p>Note the use of "#" before the name of the marker. Note also + that the filename extension <c>.html</c> is omitted. This is + because the default behavior of DocBuilder is to translate + <c><![CDATA[<seealso marker="File#Marker">text</seealso>]]></c> + to <c><![CDATA[<A HREF="File.html#Marker">text</A>]]></c>.</p> + + <p>The default behaviour can be modified by using the callback + module option to <c>docb_transform:file/1,2</c> and defining a + callback function + <seealso marker="docb_transform#Module:seealso-1">Module:seealso/1</seealso>. + This possibility is for example used in OTP to resolve cross + references between applications.</p> + </section> + + <section> + <marker id="urlTAG"></marker> + <title><url> - Non-Local Cross Reference</title> + + <p>A reference to a file outside the documentation, a web address or + similar, given by the <c>href</c> attribute. Must contain plain + text. Example:</p> + <pre><![CDATA[ +<url href="http://www.erlang.org">erlang.org</url> + ]]></pre> + <p>results in: <url href="http://www.erlang.org">erlang.org</url> + </p> + </section> + + <section> + <marker id="termTAG"></marker> + <marker id="termdefTAG"></marker> + <title><term>, <termdef> - Glossary</title> + + <p>Used to highlight a term with a local (for this document only) or + global definition. The identity of the term is given by + the <c>id</c> attribute.</p> + + <p>For a locally defined term, the tag contains a + <c><termdef></c>, which in turn contains an explanation of + the term as plain text. Example:</p> + <pre><![CDATA[ +<term id="HTML"><termdef>Hyper-Text Markup Language</termdef></term> + ]]></pre> + + <p>For a globally defined term, the tag is empty. Example:</p> + <pre><![CDATA[ +<term id="HTML"/> + ]]></pre> + + <p>Global definitions are given to DocBuilder in a file, using the + <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso> + option <c>term_defs</c>. The file should contain a list of tuples, + one for each term definition, on the format + <c>{Id,Name,Definition,Owner}</c>. The <c>Owner</c> part is just + for administration, if there are several people contributing to a + term definition file. Example:</p> + <pre> +[..., + {"HTML", "HTML", "Hyper-Text Markup Language", "Gunilla"}, + ...]. + </pre> + + <p>DocBuilder will collect both local and global definitions in a + glossary, which can be reached from a link in the left frame of + the HTML documentation.</p> + + <p>In the generated HTML, it is the term name which will be visible. + For locally defined terms, the id and the name are the same. + The name has a hypertext link to the definition in the glossary. + Example:</p> + <pre><![CDATA[ +<term id="HTML"><termdef>Hyper-Text Markup Language</termdef></term> + ]]></pre> + <p>results in: <term id="HTML"><termdef>Hyper-Text Markup Language</termdef></term> + </p> + + <p>If a term is defined both locally and globally, the global + definition takes precedence.</p> + </section> + + <section> + <marker id="citeTAG"></marker> + <marker id="citedefTAG"></marker> + <title><cite>, <citedef> - Bibliography</title> + + <p>Works the same way as <c><term></c> and + <c><termdef></c>, but for a bibliography list rather than + a glossary.</p> + + <p>A global bibliography list is given to DocBuilder in a file, + using the <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso> + option <c>cite_defs</c>. The file should contain a list of tuples, + one for each cite, on the format + <c>{Id,Title,Info,Owner}</c>. The <c>Owner</c> part is just + for administration, if there are several people contributing to a + bibliography file. Example:</p> + <pre> +[..., + {"erlbook", + "Concurrent Programming in ERLANG","J. Armstrong, R. Virding, C. Wikström, " + "M. Williams, Concurrent Programming in ERLANG, Prentice Hall, 1996, ISBN 0-13-508301-X", + "jocke"}, + ...]. + </pre> + </section> +</chapter> + diff --git a/lib/erl_docgen/doc/src/man.gif b/lib/erl_docgen/doc/src/man.gif Binary files differnew file mode 100644 index 0000000000..8656c7443d --- /dev/null +++ b/lib/erl_docgen/doc/src/man.gif diff --git a/lib/erl_docgen/doc/src/overview.xml b/lib/erl_docgen/doc/src/overview.xml new file mode 100644 index 0000000000..ca13c5d436 --- /dev/null +++ b/lib/erl_docgen/doc/src/overview.xml @@ -0,0 +1,185 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + <title>Overview</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>overview.xml</file> + </header> + + <section> + <title>Background</title> + + <p>DocBuilder has been used within the OTP project to generate + documentation for Erlang/OTP itself for more than ten years. + It has now been released as a regular Erlang/OTP application.</p> + + <p>The intention with DocBuilder is that it should be as easy to + use and maintain as possible and generate adequate documentation + for OTP's needs. It uses frames, which can probably be regarded as + old-fashioned today. Hopefully, this should be improved in + the future.</p> + + <p>Originally, DocBuilder input was SGML files and external tools + was used for parsing. The internal version used in the OTP + project can generate not only HTML code but also LaTeX (for PDF + and PostScript) and nroff (for UNIX man pages). (Again, using + external tools). Because of this, the parsed source code is + transformed into a tree structure before being transformed again + into the desired format.</p> + </section> + + <section> + <title>DTD Suite</title> + + <p>Input is written as XML according to one of the DTDs and output + is corresponding HTML. Documentation for an Erlang/OTP application + is usually organized as follows:</p> + <taglist> + <tag><em>User's Guide</em></tag> + <item> + <p>(DTD: + <seealso marker="user_guide_dtds#partDTD">part</seealso>) + A collection of chapters + (<seealso marker="user_guide_dtds#chapterDTD">chapter</seealso>). + </p> + </item> + + <tag><em>Reference Manual</em></tag> + <item> + <p>(DTD: + <seealso marker="refman_dtds#applicationDTD">application</seealso> + A collection of manual pages for modules + (<seealso marker="refman_dtds#erlrefDTD">erlref</seealso>), + applications + (<seealso marker="refman_dtds#apprefDTD">appref</seealso>), + commands + (<seealso marker="refman_dtds#comrefDTD">comref</seealso>), + C libraries + (<seealso marker="refman_dtds#crefDTD">cref</seealso>) and + files + (<seealso marker="refman_dtds#filerefDTD">fileref</seealso>). + </p> + </item> + + <tag><em>Release Notes</em></tag> + <item> + <p>Same structure as the User's Guide.</p> + </item> + </taglist> + + <p>In some cases, one or more of the User's Guide, Reference Manual + and Release Notes are omitted. Also, it is possible to use either + the <c>application</c> or <c>part</c> DTD to write other types + of documentation for the application.</p> + + <p>A special kind of DTD, + <seealso marker="fasc_dtds">fascicules</seealso>, can be used to + specify the different parts of the documentation, and which one + of those should be shown as default.</p> + </section> + + <section> + <title>Structure of Generated HTML</title> + + <p>The generated HTML corresponding to a <c>part</c> or + <c>application</c> document is split into a left frame and a right + frame. The left frame contains information about the document + and links to the included files, that is chapters or manual pages. + The right frame is used to display either the front page for + the document, or the selected chapter/manual page.</p> + + <p>The left frame also contains links to a bibliography and a + glossary, which are automatically generated.</p> + + <p>In the case of an <c>application</c> document, the left frame + also contains a link to an automatically generated index.</p> + </section> + + <section> + <title>Basic Tags</title> + + <p>All DTDs in the DocBuilder DTD suite share a basic set of tags. + An author can easily switch from one DTD to another and still use + the same basic tags. It is furthermore easy to copy pieces of + information from one document to another, even though they do not + use the same DTD.</p> + + <p>The basic set of tags are divided into two categories: + <seealso marker="block_tags">block tags</seealso> and + <seealso marker="inline_tags">inline tags</seealso>. Block tags + typically define a separate block of information, like a + paragraph or a list. Inline tags are typically used within block + tags, for example a highlighted word within a paragraph.</p> + </section> + + <section> + <title>About This Document</title> + + <p>In this User's Guide, the structure of the different documents + and the meaning of the tags are explained. There are numerous + examples of documentation source code.</p> + + <p>For readability and simplicity, the examples have been kept as + short as possible. For an example of what the generated HTML + will look like, it is recommended to look at the DocBuilder + documentation itself:</p> + <list> + <item>This User's Guide is written using the <c>part</c> and + <c>chapter</c> DTDs.</item> + + <item>The Reference Manual is written using + the <c>application</c>, <c>appref</c> and <c>erlref</c> DTDs. + </item> + </list> + </section> + + <section> + <title>Usage</title> + + <list type="ordered"> + <item> + <p>Create the relevant XML files.</p> + + <p>If there are EDoc comments in a module, the function + <seealso marker="docb_gen#module/1">docb_gen:module/1,2</seealso> + can be used to generate an XML file according to + the <c>erlref</c> DTD for this module.</p> + </item> + + <item> + <p>The XML files can be validated using + <seealso marker="docb_xml_check#validate/1">docb_xml_check:validate/1</seealso>. + </p> + </item> + + <item> + <p>Generate HTML files by using + <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso>. + </p> + </item> + </list> + </section> +</chapter> + diff --git a/lib/erl_docgen/doc/src/part.xml b/lib/erl_docgen/doc/src/part.xml new file mode 100644 index 0000000000..546c6c612e --- /dev/null +++ b/lib/erl_docgen/doc/src/part.xml @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2007</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + <title>DocBuilder User's Guide</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <description> + <p><em>Docbuilder</em> provides functionality for generating HTML + documentation for Erlang modules and Erlang/OTP applications + from XML source code and/or EDoc comments in Erlang source code.</p> + </description> + <xi:include href="overview.xml"/> + <xi:include href="user_guide_dtds.xml"/> + <xi:include href="refman_dtds.xml"/> + <xi:include href="fasc_dtds.xml"/> + <xi:include href="header_tags.xml"/> + <xi:include href="block_tags.xml"/> + <xi:include href="inline_tags.xml"/> + <xi:include href="character_entities.xml"/> +</part> + diff --git a/lib/erl_docgen/doc/src/refman_dtds.xml b/lib/erl_docgen/doc/src/refman_dtds.xml new file mode 100644 index 0000000000..a7beaed708 --- /dev/null +++ b/lib/erl_docgen/doc/src/refman_dtds.xml @@ -0,0 +1,667 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Reference Manual DTDs</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>refman_dtds.xml</file> + </header> + + <p>There are five DTDs for writing manual pages about applications, + shell commands, C libraries, Erlang modules and files, all with a + similar structure:</p> + + <list type="bulleted"> + <item>A header.</item> + <item>Name of the application/command/library/module/file.</item> + <item>Short summary (one line).</item> + <item>A longer description.</item> + <item>"Formal" definitions of functions or commands.</item> + <item>Optional sections of free text.</item> + <item>Optional section with the name(s) and email(s) of the author(s).</item> + </list> + + <p>The differences between the DTDs are the tags for the name, + the short summary and some tags inside the "formal" definitions.</p> + + <section> + <marker id="applicationDTD"></marker> + <title>The application DTD</title> + + <p>The <c>application</c> DTD is intended for a Reference Manual and + groups a set of manual pages into one unit. The structure is + similar to the part DTD: first an introduction and then the manual + pages, written in separate files with the + <seealso marker="#apprefDTD">appref</seealso>, + <seealso marker="#comrefDTD">comref</seealso>, + <seealso marker="#crefDTD">cref</seealso>, + <seealso marker="#erlrefDTD">erlref</seealso>, or + <seealso marker="#filerefDTD">fileref</seealso> DTD.</p> + + <p>Example:</p> + <pre> +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> +<application> + <header> + <title>Application name</title> + <prepared/> + <docno/> + <date/> + <rev/> + </header> + + <description> + <p>Application description...</p> + </description> + + <include file="module1"> + <include file="module2"> +</application> + </pre> + </section> + + <section> + <marker id="applicationTAG"></marker> + <title><application></title> + + <p>The top level tag of an <c>application</c> DTD.</p> + + <p>Contains a + <seealso marker="header_tags"><header></seealso>, + an optional + <seealso marker="user_guide_dtds#descriptionTAG"><description></seealso>, + followed by one or more + <seealso marker="user_guide_dtds#includeTAG"><include></seealso>. + </p> + </section> + + <section> + <marker id="apprefDTD"></marker> + <title>The appref DTD</title> + + <p>This is the DTD for writing an application manual page.</p> + + <p>Example:</p> + <pre> +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE appref SYSTEM "appref.dtd"> +<appref> + <header> + <title>Application name</title> + <prepared/> + <docno/> + <date/> + <rev/> + </header> + + <app>Application name</app> + + <appsummary>A short application summary.</appsummary> + + <description> + <p>A longer description of the application.</p> + </description> + + <section> + <title>Configuration</title> + + <p>...</p> + </section> + + ... + + <authors> + <aname>Name of author</aname> + <email>Email of author</email> + </authors> +</appref> + </pre> + + <section> + <marker id="apprefTAG"></marker> + <title><appref></title> + + <p>The top level tag of an <c>appref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#appTAG"><app></seealso>, + <seealso marker="#appsummaryTAG"><appsummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, + followed by zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="appTAG"></marker> + <title><app></title> + + <p>The application name. Contains plain text.</p> + </section> + + <section> + <marker id="appsummaryTAG"></marker> + <title><appsummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="comrefDTD"></marker> + <title>The comref DTD</title> + + <p>This is the DTD for writing a command manual page.</p> + + <p>Example:</p> + <pre> +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE comref SYSTEM "comref.dtd"> +<comref> + <header> + <title>Command name</title> + <prepared/> + <docno/> + <date/> + <rev/> + </header> + + <com>Command name</com> + + <comsummary>A short command summary.</comsummary> + + <description> + <p>A long description of the command.</p> + </description> + + <funcs> + <func> + <name>command</name> + <name>command -flag <arg></name> + <fsummary>A short command summary (max 40 characters).</fsummary> + <desc> + <p>An extended command description. + </desc> + </func> + </funcs> + + <section> + <title>Options</title> + + <p>...</p> + </section> + + <authors> + <aname>Name of author</aname> + <email>Email of author</email> + </authors> +</comref> + </pre> + + <section> + <marker id="comrefTAG"></marker> + <title><comref></title> + + <p>The top level tag for a <c>comref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#comTAG"><com></seealso>, + <seealso marker="#comsummaryTAG"><comsummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, + followed by zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="comTAG"></marker> + <title><com></title> + + <p>The command name. Contains plain text.</p> + </section> + + <section> + <marker id="comsummaryTAG"></marker> + + <title><comsummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="crefDTD"></marker> + <title>The cref DTD</title> + + <p>This is the DTD for writing a C library manual page.</p> + + <p>Example:</p> + <pre><![CDATA[ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE cref SYSTEM "cref.dtd"> +<cref> + <header> + <title>C library name</title> + <prepared/> + <docno/> + <date/> + <rev/> + </header> + + <lib>C library name</lib> + + <libsummary>A short C library summary.</libsummary> + + <description> + <p>A longer description of the C library.</p> + </description> + + <funcs> + <func> + <name><ret>void</ret><nametext>start(bar)</nametext></name> + <name><ret>void</ret><nametext>start(foo)</nametext></name> + <fsummary>A short function summary (max 40 characters).</fsummary> + <type> + <v>char bar</v> + <v>int foo</v> + </type> + <desc> + <p>An extended function description.</p> + </desc> + </func> + + ... + </funcs> + + <section> + <title>A title</title> + + <p>Some text...</p> + </section> + + +</cref> + ]]></pre> + + <section> + <marker id="crefTAG"></marker> + <title><cref></title> + + <p>The top level tag for a <c>cref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#libTAG"><lib></seealso>, + <seealso marker="#libsummaryTAG"><libsummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, followed by + zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="libTAG"></marker> + <title><lib></title> + + <p>The C library name or acronym. Contains plain text.</p> + </section> + + <section> + <marker id="libsummaryTAG"></marker> + <title><libsummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="erlrefDTD"></marker> + <title>The erlref DTD</title> + + <p>This is the DTD for writing Erlang module manual pages.</p> + + <p>Example:</p> + <pre> +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> +<erlref> + <header> + <title>Module name</title> + <prepared/> + <docno/> + <date/> + <rev/> + </header> + + <module>Module name</module> + + <modulesummary>A short module summary.</modulesummary> + + <description> + <p>A longer description of the module.</p> + </description> + + <funcs> + <func> + <name>start() -> Result</name> + <name>start(N) -> Result</name> + <fsummary>A short function summary (max 40 characters).</fsummary> + <type> + <v>Pid = pid()</v> + <v>N = int()</v> + <v>Result = {ok, Pid} | {error, Reason}</v> + <v>Reason = term()</v> + <d>A parameter description.</d> + </type> + <desc> + <p>An extended function description.</p> + </desc> + </func> + + ... + </funcs> + + <section> + <title>Some Title</title> + <p>Some text...</p> + </section> + + <authors> + <aname>Name of author</aname> + <email>Email of author</email> + </authors> +</erlref> + </pre> + + <section> + <marker id="erlrefTAG"></marker> + <title><erlref></title> + + <p>The top level tag for an <c>erlref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#moduleTAG"><module></seealso>, + <seealso marker="#modulesummaryTAG"><modulesummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, + followed by zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="moduleTAG"></marker> + <title><module></title> + + <p>The module name. Contains plain text.</p> + </section> + + <section> + <marker id="modulesummaryTAG"></marker> + <title><modulesummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="filerefDTD"></marker> + <title>The fileref DTD</title> + + <p>This is the DTD for writing file manual pages. In OTP, this DTD + is used for defining the format of for example <c>.rel</c> and + <c>.app</c> files.</p> + + <p>Example:</p> + <pre> +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE fileref SYSTEM "fileref.dtd"> +<fileref> + <header> + <title>File name</title> + <prepared/> + <docno/> + <date/> + <rev/> + </header> + + <file>fileref</file> + + <filesummary>A short file summary.</filesummary> + + <description> + <p>A longer description of the file.</p> + </description> + + <section> + <title>File format</title> + + <p>...</p> + </section> + + <authors> + <aname>Name of author</aname> + <email>Email of author</email> + </authors> +</fileref> + </pre> + + <p>The file reference manual can also contain function definitions, + similar to the <c>erlref</c> DTD.</p> + + <section> + <marker id="filerefTAG"></marker> + <title><fileref></title> + + <p>The top level tag for a <c>fileref</c> DTD.</p> + + <p>Contains + <seealso marker="header_tags#headerTAG"><header></seealso>, + <seealso marker="#fileTAG"><file></seealso>, + <seealso marker="#filesummaryTAG"><filesummary></seealso>, + <seealso marker="#descriptionTAG"><description></seealso>, + zero or more + <seealso marker="#sectionTAG"><section></seealso> and + <seealso marker="#funcsTAG"><funcs></seealso>, + followed by zero or more + <seealso marker="#authorsTAG"><authors></seealso>.</p> + </section> + + <section> + <marker id="fileTAG"></marker> + <title><file></title> + + <p>The name of the file or file type. Contains plain text.</p> + </section> + + <section> + <marker id="filesummaryTAG"></marker> + <title><filesummary></title> + + <p>Short summary. Contains plain text.</p> + </section> + </section> + + <section> + <marker id="descriptionTAG"></marker> + <title><description></title> + + <p>The introduction after the title and before sections and + "formal" definitions.</p> + + <p>Contains any combination and any number of + <seealso marker="block_tags">block tags</seealso> except + <c><![CDATA[<image>]]></c> and <c><![CDATA[<table>]]></c>.</p> + </section> + + <section> + <marker id="sectionTAG"></marker> + <title><section></title> + + <p>Subdivisions of the document. Contains an optional + <seealso marker="inline_tags#markerTAG"><marker></seealso>, + a <seealso marker="user_guide_dtds#titleTAG"><title></seealso>, + + followed by any combination and any number of + <seealso marker="block_tags">block tags</seealso> except + <c><![CDATA[<image>]]></c> and <c><![CDATA[<table>]]></c>.</p> + </section> + + <section> + <marker id="funcsTAG"></marker> + <title><funcs></title> + + <p>A group of "formal" function definitions.</p> + + <p>Contains one or more + <seealso marker="#funcTAG"><func></seealso>.</p> + </section> + + <section> + <marker id="funcTAG"></marker> + <title><func></title> + + <p>A "formal" function definition.</p> + + <p>Contains one or more + <seealso marker="#nameTAG"><name></seealso>, followed by + <seealso marker="#fsummaryTAG"><fsummary></seealso>, + <seealso marker="#typeTAG"><type></seealso> (optional) and + <seealso marker="#descTAG"><desc></seealso> (optional).</p> + </section> + + <section> + <marker id="nameTAG"></marker> + <title><name></title> + + <p>Function/command signature with name, arguments and return value. + Contains plain text, except for the <c>cref</c> DTD where it + contains a <c><![CDATA[<ret>]]></c> (return type, plain text) and + a <c><![CDATA[<nametext>]]></c> (function name and arguments, + plain text).</p> + + <p>In the case of an <c>erlref</c> DTD, DocBuilder will + automatically try to add a + <seealso marker="inline_tags#markerTAG">marker</seealso>, + <c><![CDATA[<marker id="Name/Arity">]]></c> or + <c><![CDATA[<marker id="Name">]]></c>, based on the contents of + this tag before the function definition.</p> + + <p>Example: Consider the following name definition</p> + <pre><![CDATA[ +<name>foo(Arg1, Arg2) -> ok | {error, Reason}</name> + ]]></pre> + + <p>DocBuilder will create a marker + <c><![CDATA[<marker id="foo/2">]]></c> before the function + definition in the generated HTML. That is, referring to + the function using + <c><![CDATA[<seealso marker="#foo/2">foo/2</seealso>]]></c> will + automatically work.</p> + </section> + + <section> + <marker id="fsummaryTAG"></marker> + <title><fsummary></title> + + <p>Function/command summary. Contains plain text, + <seealso marker="inline_tags#cTAG"><c></seealso> and + <seealso marker="inline_tags#emTAG"><em></seealso>.</p> + </section> + + <section> + <marker id="typeTAG"></marker> + <title><type></title> + + <p>Type declarations for the function/command.</p> + + <p>Contains one or more pairs of + <seealso marker="#vTAG"><v></seealso> and + <seealso marker="#dTAG"><d></seealso> (optional).</p> + </section> + + <section> + <marker id="vTAG"></marker> + <title><v></title> + + <p>Type declaration for an argument or return value. Contains plain + text.</p> + </section> + + <section> + <marker id="dTAG"></marker> + <title><d></title> + + <p>Description for an argument or return value. Contains plain text, + <seealso marker="inline_tags#cTAG"><c></seealso> and + <seealso marker="inline_tags#emTAG"><em></seealso>.</p> + </section> + + <section> + <marker id="descTAG"></marker> + <title><desc></title> + + <p>Function/command description. Contains + <seealso marker="block_tags">block tags</seealso> except + <c><image></c> and <c><table></c>.</p> + </section> + + <section> + <marker id="authorsTAG"></marker> + <title><authors></title> + + <p>Authors of the manual page. The <c>authors</c> element is optional.</p> + + <p>Contains one or more pairs of + <seealso marker="#anameTAG"><aname></seealso> and + <seealso marker="#emailTAG"><email></seealso>.</p> + </section> + + <section> + <marker id="anameTAG"></marker> + <title><aname></title> + + <p>Author name. Contains plain text.</p> + </section> + + <section> + <marker id="emailTAG"></marker> + <title><email></title> + + <p>Author email address. Contains plain text.</p> + </section> +</chapter> + diff --git a/lib/erl_docgen/doc/src/user_guide_dtds.xml b/lib/erl_docgen/doc/src/user_guide_dtds.xml new file mode 100644 index 0000000000..a2db44f830 --- /dev/null +++ b/lib/erl_docgen/doc/src/user_guide_dtds.xml @@ -0,0 +1,181 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>User's Guide DTDs</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>user_guide_dtds.xml</file> + </header> + + <section> + <marker id="partDTD"></marker> + <title>The part DTD</title> + + <p>The <c>part</c> DTD is intended for a "normal" document, like + the User's Guide or Release Notes. First are some paragraphs + introducing the main contents. After that follows chapters, + written in separate files with + the <seealso marker="#chapterDTD">chapter</seealso> DTD.</p> + + <p>Example:</p> + <pre> +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> +<part> + <header> + <title>The chapter title</title> + <prepared>The author</prepared> + <docno/> + <date/> + <rev/> + </header> + + <description> + <p>Some text..</p> + </description> + + <include file="file1"></include> + <include file="file2"></include> +</part> + </pre> + </section> + + <section> + <marker id="partTAG"></marker> + <title><part></title> + + <p>The top level tag of a <c>part</c> DTD.</p> + + <p>Contains a + <seealso marker="header_tags"><header></seealso>, + an optional + <seealso marker="#descriptionTAG"><description></seealso>, + followed by one or more + <seealso marker="#includeTAG"><include></seealso>.</p> + </section> + + <section> + <marker id="descriptionTAG"/> + <title><description></title> + + <p>The introduction after the title and before the bulk of + included chapters/manual pages.</p> + + <p>Contains any combination and any number + of <seealso marker="block_tags">block tags</seealso> except + <c><![CDATA[<image>]]></c> and <c><![CDATA[<table>]]></c>.</p> + </section> + + <section> + <marker id="includeTAG"></marker> + <title><include></title> + + <p>An empty tag. The attribute <c>file</c> specifies a file to + include. The <c>.xml</c> file extension should be omitted.</p> + + <p>Example:</p> + <pre> +<include file="notes"></include> + </pre> + </section> + + <section> + <marker id="chapterDTD"></marker> + <title>The chapter DTD</title> + + <p>The <c>chapter</c> DTD is intended for a chapter in a User's + Guide or similar with text divided into sections, which can be + nested.</p> + + <p>Example:</p> + <pre> +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> +<chapter> + <header> + <title>Title on first level</title> + <prepared/> + <docno/> + <date/> + <rev/> + </header> + + <p>Introduction...</p> + + <section> + <title>Title on second level</title> + + <p>First paragraph.</p> + + <p>Second paragraph etc.</p> + + <section> + <title>Title on third level</title> + + <p>...</p> + </section> + </section> + + ... +</chapter> + </pre> + </section> + + <section> + <marker id="chapterTAG"></marker> + <title><chapter></title> + + <p>The top level tag of a <c>chapter</c> DTD.</p> + + <p>Contains a + <seealso marker="header_tags"><header></seealso>, + an optional introduction consisting of any combination of + <seealso marker="block_tags">block tags</seealso>, + followed by one or more + <seealso marker="#sectionTAG"><section></seealso>.</p> + </section> + + <section> + <marker id="sectionTAG"></marker> + <title><section></title> + + <p>Subdivision of a chapter.</p> + + <p>Contains an optional + <seealso marker="inline_tags#markerTAG"><marker></seealso>, + a <seealso marker="#titleTAG"><title></seealso>, + followed by any combination and any number of + <seealso marker="block_tags">block tags</seealso> and + <c><![CDATA[<section>]]></c>.</p> + </section> + + <section> + <marker id="titleTAG"></marker> + <title><title></title> + + <p>Section title, contains plain text.</p> + </section> +</chapter> + diff --git a/lib/erl_docgen/priv/docbuilder_dtd/Makefile b/lib/erl_docgen/priv/dtd/Makefile index e2214107cb..e2214107cb 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/Makefile +++ b/lib/erl_docgen/priv/dtd/Makefile diff --git a/lib/erl_docgen/priv/docbuilder_dtd/application.dtd b/lib/erl_docgen/priv/dtd/application.dtd index 8a1e8832ec..8a1e8832ec 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/application.dtd +++ b/lib/erl_docgen/priv/dtd/application.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/appref.dtd b/lib/erl_docgen/priv/dtd/appref.dtd index 70a5ff37af..70a5ff37af 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/appref.dtd +++ b/lib/erl_docgen/priv/dtd/appref.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/book.dtd b/lib/erl_docgen/priv/dtd/book.dtd index bb89a6d255..bb89a6d255 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/book.dtd +++ b/lib/erl_docgen/priv/dtd/book.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/bookinsidecover.dtd b/lib/erl_docgen/priv/dtd/bookinsidecover.dtd index d6efbef6a4..d6efbef6a4 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/bookinsidecover.dtd +++ b/lib/erl_docgen/priv/dtd/bookinsidecover.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/chapter.dtd b/lib/erl_docgen/priv/dtd/chapter.dtd index eb2c96b04f..eb2c96b04f 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/chapter.dtd +++ b/lib/erl_docgen/priv/dtd/chapter.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/cites.dtd b/lib/erl_docgen/priv/dtd/cites.dtd index 334574bff9..334574bff9 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/cites.dtd +++ b/lib/erl_docgen/priv/dtd/cites.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.dtd b/lib/erl_docgen/priv/dtd/common.dtd index fdc02c55a1..fdc02c55a1 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.dtd +++ b/lib/erl_docgen/priv/dtd/common.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.entities.dtd b/lib/erl_docgen/priv/dtd/common.entities.dtd index f893ecd070..f893ecd070 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.entities.dtd +++ b/lib/erl_docgen/priv/dtd/common.entities.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.header.dtd b/lib/erl_docgen/priv/dtd/common.header.dtd index d422a89693..d422a89693 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.header.dtd +++ b/lib/erl_docgen/priv/dtd/common.header.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.image.dtd b/lib/erl_docgen/priv/dtd/common.image.dtd index fc95a669dd..fc95a669dd 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.image.dtd +++ b/lib/erl_docgen/priv/dtd/common.image.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.refs.dtd b/lib/erl_docgen/priv/dtd/common.refs.dtd index c1237766e1..c1237766e1 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.refs.dtd +++ b/lib/erl_docgen/priv/dtd/common.refs.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/common.table.dtd b/lib/erl_docgen/priv/dtd/common.table.dtd index 7741da1018..7741da1018 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/common.table.dtd +++ b/lib/erl_docgen/priv/dtd/common.table.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/comref.dtd b/lib/erl_docgen/priv/dtd/comref.dtd index fcdea625d5..fcdea625d5 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/comref.dtd +++ b/lib/erl_docgen/priv/dtd/comref.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/cref.dtd b/lib/erl_docgen/priv/dtd/cref.dtd index e43bb2bf51..e43bb2bf51 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/cref.dtd +++ b/lib/erl_docgen/priv/dtd/cref.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/erlref.dtd b/lib/erl_docgen/priv/dtd/erlref.dtd index 9905086ff4..9905086ff4 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/erlref.dtd +++ b/lib/erl_docgen/priv/dtd/erlref.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/fascicules.dtd b/lib/erl_docgen/priv/dtd/fascicules.dtd index b14276a2c0..b14276a2c0 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/fascicules.dtd +++ b/lib/erl_docgen/priv/dtd/fascicules.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/fileref.dtd b/lib/erl_docgen/priv/dtd/fileref.dtd index 5a1cc54afe..5a1cc54afe 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/fileref.dtd +++ b/lib/erl_docgen/priv/dtd/fileref.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/part.dtd b/lib/erl_docgen/priv/dtd/part.dtd index 3f97199042..3f97199042 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/part.dtd +++ b/lib/erl_docgen/priv/dtd/part.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/report.dtd b/lib/erl_docgen/priv/dtd/report.dtd index 3d07e6e5a7..3d07e6e5a7 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/report.dtd +++ b/lib/erl_docgen/priv/dtd/report.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/terms.dtd b/lib/erl_docgen/priv/dtd/terms.dtd index 6105ec593e..6105ec593e 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/terms.dtd +++ b/lib/erl_docgen/priv/dtd/terms.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-frameset.dtd b/lib/erl_docgen/priv/dtd/xhtml1-frameset.dtd index d128f2eb7c..d128f2eb7c 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-frameset.dtd +++ b/lib/erl_docgen/priv/dtd/xhtml1-frameset.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-strict.dtd b/lib/erl_docgen/priv/dtd/xhtml1-strict.dtd index 2927b9ece7..2927b9ece7 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-strict.dtd +++ b/lib/erl_docgen/priv/dtd/xhtml1-strict.dtd diff --git a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-transitional.dtd b/lib/erl_docgen/priv/dtd/xhtml1-transitional.dtd index 628f27ac50..628f27ac50 100644 --- a/lib/erl_docgen/priv/docbuilder_dtd/xhtml1-transitional.dtd +++ b/lib/erl_docgen/priv/dtd/xhtml1-transitional.dtd diff --git a/lib/erl_docgen/src/docgen_edoc_xml_cb.erl b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl new file mode 100644 index 0000000000..90491bc007 --- /dev/null +++ b/lib/erl_docgen/src/docgen_edoc_xml_cb.erl @@ -0,0 +1,1154 @@ +%% ``The contents of this file are subject to the Erlang Public License, +%% Version 1.1, (the "License"); you may not use this file except in +%% compliance with the License. You should have received a copy of the +%% Erlang Public License along with this software. If not, it can be +%% retrieved via the world wide web at http://www.erlang.org/. +%% +%% Software distributed under the License is distributed on an "AS IS" +%% basis, WITHOUT WARRANTY OF ANY KIND, either expressed or implied. See +%% the Licence for the specific language governing rights and limitations +%% under the License. +%% +%% The Initial Developer of the Original Code is Ericsson AB. +%% Portions created by Ericsson are Copyright 1999-2006, Ericsson AB. +%% All Rights Reserved.�� +%% +%% $Id$ +%% +-module(docb_edoc_xml_cb). + +%% This is the EDoc callback module for creating DocBuilder erlref +%% documents (man pages) in XML format, and also a DocBuilder chapter +%% document based on "overview.edoc". +%% +%% Usage examples: +%% docb_gen File +%% docb_gen -chapter overview.edoc +%% or (from an Erlang shell) +%% edoc:file(File, [{layout,docb_edoc_xml_cb},{file_suffix,".xml"}, +%% {preprocess,true}]). +%% +%% The origin of this file is the edoc module otpsgml_layout.erl +%% written by Richard Carlsson. + +-export([module/2, overview/2]). + +-include("xmerl.hrl"). + +-define(NL, "\n"). + +%%-User interface------------------------------------------------------- + +%% ERLREF +module(Element, Opts) -> + SortP = proplists:get_value(sort_functions, Opts, true), + XML = layout_module(Element, SortP), + xmerl:export_simple([XML], docb_xmerl_xml_cb, []). + +%% CHAPTER +overview(Element, _Opts) -> + XML = layout_chapter(Element), + xmerl:export_simple([XML], docb_xmerl_xml_cb, []). + +%%--Internal functions-------------------------------------------------- + +layout_module(#xmlElement{name = module, content = Es}=E, SortP) -> + Name = get_attrval(name, E), + Desc = get_content(description, Es), + ShortDesc = text_only(get_content(briefDescription, Desc)), + FullDesc = otp_xmlify(get_content(fullDescription, Desc)), + Types0 = get_content(typedecls, Es), + Types1 = lists:sort([{type_name(Et), Et} || Et <- Types0]), + Functions = + case SortP of + true -> + lists:sort([{function_name(Ef), Ef} || + Ef <- get_content(functions, Es)]); + false -> + [{function_name(Ef), Ef} || + Ef <- get_content(functions, Es)] + end, + Header = {header, [ + ?NL,{title, [Name]}, + ?NL,{prepared, [""]}, + ?NL,{responsible, [""]}, + ?NL,{docno, ["1"]}, + ?NL,{approved, [""]}, + ?NL,{checked, [""]}, + ?NL,{date, [""]}, + ?NL,{rev, ["A"]}, + ?NL,{file, [Name++".xml"]} + ]}, + Module = {module, [Name]}, + ModuleSummary = {modulesummary, ShortDesc}, + Description = {description, [?NL|FullDesc]}, + Types = case Types1 of + [] -> []; + _ -> + [?NL, {section,[{title,["DATA TYPES"]}, + {marker,[{id,"types"}],[]}, + ?NL|types(Types1)]}] + end, + Funcs = functions(Functions), + See = seealso_module(Es), + Authors = {authors, authors(Es)}, + {erlref, + [?NL,Header, + ?NL,Module, + ?NL,ModuleSummary, + ?NL,Description] + ++ Types ++ + [?NL,Funcs, + ?NL,See, + ?NL,Authors] + }. + +layout_chapter(#xmlElement{name=overview, content=Es}) -> + Title = get_text(title, Es), + Header = {header, [ + ?NL,{title,[Title]}, + ?NL,{prepared,[""]}, + ?NL,{docno,[""]}, + ?NL,{date,[""]}, + ?NL,{rev,[""]}, + ?NL,{file, ["chapter.xml"]} + ]}, + DescEs = get_content(description, Es), + FullDescEs = get_content(fullDescription, DescEs), + Sections = chapter_ify(FullDescEs, first), + {chapter, [?NL, Header, ?NL | Sections]}. + +chapter_ify([], _) -> + []; +chapter_ify(Es, first) -> + %% Everything up to the first section should be made into + %% plain paragraphs -- or if no first section is found, everything + %% should be made into one + case find_next(h3, Es) of + {Es, []} -> + SubSections = subchapter_ify(Es, first), + [{section, [?NL,{title,["Overview"]}, + ?NL | SubSections]}]; + {FirstEs, RestEs} -> + otp_xmlify(FirstEs) ++ chapter_ify(RestEs, next) + end; +chapter_ify([#xmlElement{name=h3} = E | Es], next) -> + {SectionEs, RestEs} = find_next(h3, Es), + SubSections = subchapter_ify(SectionEs, first), + {Marker, Title} = chapter_title(E), + [{section, [?NL,{marker,[{id,Marker}],[]}, + ?NL,{title,[Title]}, + ?NL | SubSections]} | chapter_ify(RestEs, next)]. + +subchapter_ify([], _) -> + []; +subchapter_ify(Es, first) -> + %% Everything up to the (possible) first subsection should be + %% made into plain paragraphs + {FirstEs, RestEs} = find_next(h4, Es), + otp_xmlify(FirstEs) ++ subchapter_ify(RestEs, next); +subchapter_ify([#xmlElement{name=h4} = E | Es], next) -> + {SectionEs, RestEs} = find_next(h4, Es), + Elements = otp_xmlify(SectionEs), + {Marker, Title} = chapter_title(E), + [{section, [?NL,{marker,[{id,Marker}],[]}, + ?NL,{title,[Title]}, + ?NL | Elements]} | subchapter_ify(RestEs, next)]. + +chapter_title(#xmlElement{content=Es}) -> % name = h3 | h4 + case Es of + [#xmlElement{name=a} = E] -> + {get_attrval(name, E), get_text(E)} + end. + +%%--XHTML->XML transformation------------------------------------------- + +%% otp_xmlify(Es1) -> Es2 +%% Es1 = Es2 = [#xmlElement{} | #xmlText{}] +%% Fix things that are allowed in XHTML but not in chapter/erlref DTDs. +%% 1) lists (<ul>, <ol>, <dl>) and code snippets (<pre>) can not occur +%% within a <p>, such a <p> must be splitted into a sequence of <p>, +%% <ul>, <ol>, <dl> and <pre>. +%% 2) <a> must only have either a href attribute (corresponds to a +%% <seealso> or <url> in the XML code) in which case its content +%% must be plain text; or a name attribute (<marker>). +%% 3a) <b> content must be plain text. +%% b) <em> content must be plain text (or actually a <code> element +%% as well, but a simplification is used here). +%% c) <pre> content must be plain text (or could actually contain +%% <input> as well, but a simplification is used here). +%% 4) <code> content must be plain text, or the element must be split +%% into a list of elements. +%% 5a) <h1>, <h2> etc is not allowed - replaced by its content within +%% a <b> tag. +%% b) <center> is not allowed - replaced by its content. +%% c) <font> -"- +%% 6) <table> is not allowed in erlref, translated to text instead. +%% Also a <table> in chapter without a border is translated to text. +%% A <table> in chapter with a border must contain a <tcaption>. +%% 7) <sup> is not allowed - is replaced with its text content +%% within parenthesis. +%% 8) <blockquote> contents may need to be made into paragraphs +%% 9) <th> (table header) is not allowed - is replaced by +%% <td><em>...</em></td>. +otp_xmlify([]) -> + []; +otp_xmlify(Es0) -> + Es = case is_paragraph(hd(Es0)) of + + %% If the first element is a <p> xmlElement, then + %% the entire element list is ready to be otp_xmlified. + true -> + Es0; + + %% If the first element is not a <p> xmlElement, then all + %% elements up to the first <p> (or end of list) must be + %% made into a paragraph (using the {p, Es} construction) + %% before the list is otp_xmlified. + false -> + case find_next(p, Es0, []) of + {[#xmlText{value=Str}] = First, Rest} -> + %% Special case: Making a paragraph out of a + %% blank line isn't a great idea. + case is_empty(Str) of + true -> + Rest; + false -> + [{p,First}|Rest] + end; + {First, Rest} -> + [{p,First}|Rest] + end + end, + + %% Fix paragraph breaks not needed in XHTML but in XML + EsFixed = otp_xmlify_fix(Es), + + otp_xmlify_es(EsFixed). + +%% EDoc does not always translate empty lines (with leading "%%") +%% as paragraph break, this is the fix +otp_xmlify_fix(Es) -> + otp_xmlify_fix(Es, []). +otp_xmlify_fix([#xmlText{value="\n \n"++_} = E1, E2 | Es], Res) -> + %% This is how it looks when generating an erlref from a .erl file + case is_paragraph(E2) of + false -> + {P, After} = find_p_ending(Es, []), + otp_xmlify_fix(After, [{p, [E2|P]}, E1 | Res]); + true -> + otp_xmlify_fix([E2|Es], [E1|Res]) + end; +otp_xmlify_fix([#xmlText{value="\n\n"} = E1, E2 | Es], Res) -> + %% This is how it looks when generating a chapter from overview.edoc + case is_paragraph(E2) of + false -> + {P, After} = find_p_ending(Es, []), + otp_xmlify_fix(After, [{p, [E2|P]}, E1 | Res]); + true -> + otp_xmlify_fix([E2|Es], [E1|Res]) + end; +otp_xmlify_fix([E|Es], Res) -> + otp_xmlify_fix(Es, [E|Res]); +otp_xmlify_fix([], Res) -> + lists:reverse(Res). + +otp_xmlify_es([E | Es]) -> + case is_paragraph(E) of + true -> + case otp_xmlify_psplit(E) of + + %% paragraph contained inline tags and text only + nosplit -> + otp_xmlify_e(E) ++ otp_xmlify_es(Es); + + %% paragraph contained dl, ul and/or pre and has been + %% splitted + SubEs -> + lists:flatmap(fun otp_xmlify_e/1, SubEs) ++ + otp_xmlify_es(Es) + end; + false -> + otp_xmlify_e(E) ++ otp_xmlify_es(Es) + end; +otp_xmlify_es([]) -> + []. + +%% otp_xmlify_psplit(P) -> nosplit | [E] +%% Handles case 1) above. +%% Uses the {p, Es} construct, thus replaces an p xmlElement with one +%% or more {p, Es} tuples if splitting the paraghrap is necessary. +otp_xmlify_psplit(P) -> + otp_xmlify_psplit(p_content(P), [], []). +otp_xmlify_psplit([#xmlElement{name=Name}=E | Es], Content, Res) -> + if + Name==blockquote; Name==ul; Name==ol; Name==dl; Name==pre; + Name==table -> + case Content of + [] -> + otp_xmlify_psplit(Es, [], [E|Res]); + [#xmlText{value=Str}] -> + %% Special case: Making a paragraph out of a blank + %% line isn't a great idea. Instead, this can be + %% viewed as the case above, where there is no + %% content to make a paragraph out of + case is_empty(Str) of + true -> + otp_xmlify_psplit(Es, [], [E|Res]); + false -> + Pnew = {p, lists:reverse(Content)}, + otp_xmlify_psplit(Es, [], [E,Pnew|Res]) + end; + _ -> + Pnew = {p, lists:reverse(Content)}, + otp_xmlify_psplit(Es, [], [E,Pnew|Res]) + end; + + true -> + otp_xmlify_psplit(Es, [E|Content], Res) + end; +otp_xmlify_psplit([E | Es], Content, Res) -> + otp_xmlify_psplit(Es, [E|Content], Res); +otp_xmlify_psplit([], _Content, []) -> + nosplit; +otp_xmlify_psplit([], [], Res) -> + lists:reverse(Res); +otp_xmlify_psplit([], [#xmlText{value="\n\n"}], Res) -> + lists:reverse(Res); +otp_xmlify_psplit([], Content, Res) -> + Pnew = {p, lists:reverse(Content)}, + lists:reverse([Pnew|Res]). + +%% otp_xmlify_e(E) -> [E] +%% This is the function which does the actual transformation of +%% single elements, normally by making sure the content corresponds +%% to what is allowed by the OTP DTDs. +%% Returns a list of elements as the xmlification in some cases +%% returns no element or more than one element (although in most cases +%% exactly one element). +otp_xmlify_e(#xmlElement{name=a} = E) -> % 2) above + otp_xmlify_a(E); +otp_xmlify_e(#xmlElement{name=Tag} = E) % 3a-c) + when Tag==b; Tag==em; Tag==pre -> + Content = text_only(E#xmlElement.content), + [E#xmlElement{content=Content}]; +otp_xmlify_e(#xmlElement{name=code} = E) -> % 4) + case catch text_only(E#xmlElement.content) of + {'EXIT', _Error} -> + otp_xmlify_code(E); + Content -> + [E#xmlElement{content=Content}] + end; +otp_xmlify_e(#xmlElement{name=Tag} = E) % 5a + when Tag==h1; Tag==h2; Tag==h3; Tag==h4; Tag==h5 -> + Content = text_only(E#xmlElement.content), + [E#xmlElement{name=b, content=Content}]; +otp_xmlify_e(#xmlElement{name=Tag} = E) % 5b-c) + when Tag==center; + Tag==font -> + otp_xmlify_e(E#xmlElement.content); +otp_xmlify_e(#xmlElement{name=table} = E) -> % 6) + case parent(E) of + module -> + otp_xmlify_table(E#xmlElement.content); + overview -> + Content0 = otp_xmlify_e(E#xmlElement.content), + Summary = #xmlText{value=get_attrval(summary, E)}, + TCaption = E#xmlElement{name=tcaption, + attributes=[], + content=[Summary]}, + Content = Content0 ++ [TCaption], + [E#xmlElement{attributes=[], content=Content}] + end; +otp_xmlify_e(#xmlElement{name=tbody} = E) -> + otp_xmlify_e(E#xmlElement.content); +otp_xmlify_e(#xmlElement{name=sup} = E) -> % 7) + Text = get_text(E), + [#xmlText{parents = E#xmlElement.parents, + pos = E#xmlElement.pos, + language = E#xmlElement.language, + value = "(" ++ Text ++ ")"}]; +otp_xmlify_e(#xmlElement{name=blockquote} = E) -> % 8) + Content = otp_xmlify_blockquote(E#xmlElement.content), + [E#xmlElement{content=Content}]; +otp_xmlify_e(#xmlElement{name=th} = E) -> % 9) + Content = otp_xmlify_e(E#xmlElement.content), + EmE = E#xmlElement{name=em, content=Content}, + [E#xmlElement{name=td, content=[EmE]}]; +otp_xmlify_e(#xmlElement{name=p} = E) -> % recurse + Content = otp_xmlify_e(E#xmlElement.content), + [E#xmlElement{content=Content}]; +otp_xmlify_e({p, Content1}) -> + Content2 = otp_xmlify_e(Content1), + [{p, Content2}]; +otp_xmlify_e(#xmlElement{name=ul} = E) -> + Content = otp_xmlify_e(E#xmlElement.content), + [E#xmlElement{content=Content}]; +otp_xmlify_e(#xmlElement{name=li} = E) -> + %% Content may need to be made into <p>s etc. + Content = otp_xmlify(E#xmlElement.content), + [E#xmlElement{content=Content}]; +otp_xmlify_e(#xmlElement{name=dl} = E) -> + Content0 = otp_xmlify_e(E#xmlElement.content), + Content = otp_xmlify_dl(Content0), + [E#xmlElement{content=Content}]; +otp_xmlify_e(#xmlElement{name=dt} = E) -> + %% Special fix: Markers in <taglist> <tag>s are not allowed, + %% save it using 'put' and place the marker first in the <item> + %% instead + Content = case E#xmlElement.content of + [#xmlElement{name=a} = A] -> + put(dt_marker, otp_xmlify_e(A)), + otp_xmlify_e(A#xmlElement.content); + _ -> + otp_xmlify_e(E#xmlElement.content) + end, + [E#xmlElement{content=Content}]; +otp_xmlify_e(#xmlElement{name=dd} = E) -> + %% Content may need to be made into <p>s etc. + Content0 = otp_xmlify(E#xmlElement.content), + Content = case get(dt_marker) of + undefined -> Content0; + [Marker] -> + put(dt_marker, undefined), + [Marker#xmlElement{content=[]}|Content0] + end, + [E#xmlElement{content=Content}]; +otp_xmlify_e(#xmlElement{name=tr} = E) -> + Content = otp_xmlify_e(E#xmlElement.content), + [E#xmlElement{content=Content}]; +otp_xmlify_e(#xmlElement{name=td} = E) -> + Content = otp_xmlify_e(E#xmlElement.content), + [E#xmlElement{content=Content}]; +otp_xmlify_e([E | Es]) -> + otp_xmlify_e(E) ++ otp_xmlify_e(Es); +otp_xmlify_e([]) -> + []; +otp_xmlify_e(E) -> + [E]. + +%%--Tags with special handling------------------------------------------ + +%% otp_xmlify_a(A1) -> [A2] +%% Takes an <a> element and filters the attributes to decide wheather +%% its a seealso/url or a marker. +%% In the case of a seealso/url, the href part is checked, making +%% sure a .xml/.html file extension is removed (as DocBuilder inserts +%% .html extension when resolving cross references). +%% Also, references to other applications //App has a href attribute +%% value "OTPROOT/..." (due to app_default being set to "OTPROOT" in +%% docb_gen.erl), in this case both href attribute and content must be +%% formatted correctly according to DocBuilder requirements. +otp_xmlify_a(A) -> + [Attr0] = filter_a_attrs(A#xmlElement.attributes), + case Attr0 of + #xmlAttribute{name=href, value=Href0} -> % seealso | url + Content0 = text_only(A#xmlElement.content), + {Href, Content} = otp_xmlify_a_href(Href0, Content0), + [A#xmlElement{attributes=[Attr0#xmlAttribute{value=Href}], + content=Content}]; + #xmlAttribute{name=name} -> % marker + Content = otp_xmlify_e(A#xmlElement.content), + [A#xmlElement{attributes=[Attr0], content=Content}] + end. + +%% filter_a_attrs(Attrs) -> [Attr] +%% Removes all attributes from a <a> element except the href or +%% name attribute. +filter_a_attrs([#xmlAttribute{name=href} = Attr | _Attrs]) -> + [Attr]; +filter_a_attrs([#xmlAttribute{name=name} = Attr | _Attrs]) -> + [Attr]; +filter_a_attrs([_Attr|Attrs]) -> + filter_a_attrs(Attrs); +filter_a_attrs([]) -> + []. + +%% otp_xmlify_a_href(Href0, Es0) -> {Href1, Es1} +%% Href = string() +otp_xmlify_a_href("#"++_ = Marker, Es0) -> % <seealso marker="#what"> + {Marker, Es0}; +otp_xmlify_a_href("http:"++_ = URL, Es0) -> % external URL + {URL, Es0}; +otp_xmlify_a_href("OTPROOT"++AppRef, Es0) -> % <.. marker="App:FileRef + [AppS, "doc", FileRef1] = split(AppRef, "/"), + FileRef = AppS++":"++otp_xmlify_a_fileref(FileRef1, AppS), + [#xmlText{value=Str0} = T] = Es0, + Str = case split(Str0, "/") of + %% //Application + [AppS2] -> + %% AppS2 can differ from AppS + %% Example: xmerl/XMerL + AppS2; + [_AppS,ModRef] -> + case split(ModRef, ":") of + %% //Application/Module + [Module] -> + Module++"(3)"; + %% //Application/Module:Type() + [_Module,_Type] -> + ModRef + end; + %% //Application/Module:Function/Arity + [_AppS,ModFunc,Arity] -> + ModFunc++"/"++Arity + end, + {FileRef, [T#xmlText{value=Str}]}; +otp_xmlify_a_href("../"++File, Es0) -> + %% Special case: This kind of relative path is used on some + %% places within i.e. EDoc and refers to a file within the same + %% application tree. + %% Correct the path according to the OTP directory structure + {"../../"++File, Es0}; +otp_xmlify_a_href(FileRef1, Es0) -> % File within the same application + FileRef2 = otp_xmlify_a_fileref(FileRef1, this), + {FileRef2, Es0}. + +%% otp_xmlify_a_fileref(FileRef1, AppS|this) -> FileRef2 +%% AppS = FileRef = string() +otp_xmlify_a_fileref(FileRef1, AppS) -> + case split(FileRef1, ".#") of + + %% EDoc default name is "overview-summary.html, + %% name of OTP User's Guide chapter is "chapter.xml" + ["overview-summary", _Ext] -> + "chapter"; + ["overview-summary", _Ext, Marker] -> + "chapter#"++Marker; + + [File, Ext] when Ext=="xml"; + Ext=="html", AppS/=this -> + File; + [File, Ext, Marker0] -> + %% Here is an awkward solution to an awkward problem + %% The marker automatically inserted by DocBuilder at + %% each function does not seem to work for EDoc generated + %% ERLREFs. + %% So if the referenced marker is in an ERLREF generated + %% by EDoc, keep it "as is", ie "function-arity". + %% If the referenced marker is NOT in an ERLREF generated + %% by EDoc, the marker should be on the format + %% "function/arity". + %% The awkward part of the solution is to decide wheather + %% the ERLREF is generated by EDoc or not: Here we make + %% the decision based on which application the module + %% belongs to -- which is ok when the module was written + %% but probably not in the future... + EDocApps = ["edoc","hipe","syntax_tools","xmerl"], + IsEDocGenerated = lists:member(AppS, EDocApps), + Marker = if + %% The marker is in a file in *this* + %% application (which documentation obviously + %% is generated by EDoc), or it is in a file + %% in an application which documentation + %% is assumed to be generated by EDoc + AppS==this; IsEDocGenerated -> + Marker0; + + %% The marker is in a file in an application + %% which documentation is assumed NOT to be + %% generated by EDoc + true -> + case split(Marker0, "-") of + [Func,Arity] -> + Func++"/"++Arity; + _ -> + Marker0 + end + end, + if + %% Ignore file extension in file reference if it either + %% is ".xml" or if it is ".html" but AppS/=this, that + %% is, we're resolving an OTPROOT file reference + Ext=="xml"; + Ext=="html", AppS/=this -> + File++"#"++Marker; + true -> + File++"."++Ext++"#"++Marker + end; + + %% References to other files than XML files are kept as-is + _ -> + FileRef1 + end. + +%% otp_xmlify_blockquote(Es1) -> Es2 +%% Ensures that the content of a <blockquote> is divided into +%% <p>s using the {p, Es} construct. +otp_xmlify_blockquote([#xmlElement{name=p} = E|Es]) -> + [E | otp_xmlify_blockquote(Es)]; +otp_xmlify_blockquote([#xmlText{} = E|Es]) -> + {P, After} = find_p_ending(Es, []), + [{p, [E|P]} | otp_xmlify_blockquote(After)]; +otp_xmlify_blockquote([]) -> + []. + +%% otp_xmlify_code(E) -> Es +%% Takes a <code> xmlElement and split it into a list of <code> and +%% other xmlElements. Necessary when it contains more than a single +%% xmlText element. +%% Example: +%% #xmlElement{name=code, +%% content=[#xmlText{}, #xmlElement{name=br}, #xmlText{}]} +%% => +%% [#xmlElement{name=code, content=[#xmlText{}]}, +%% #xmlElement{name=br}, +%% #xmlElement{name=code, content=[#xmlText{}]}] +otp_xmlify_code(E) -> + otp_xmlify_code(E, E#xmlElement.content, []). +otp_xmlify_code(Code, [#xmlText{} = E|Es], Acc) -> + otp_xmlify_code(Code, Es, [Code#xmlElement{content=[E]}|Acc]); +otp_xmlify_code(Code, [#xmlElement{} = E|Es], Acc) -> + otp_xmlify_code(Code, Es, [E|Acc]); +otp_xmlify_code(_Code, [], Acc) -> + lists:reverse(Acc). + +%% otp_xmlify_dl(Es1) -> Es2 +%% Insert empty <dd> elements if necessary. +%% OTP DTDs does not allow <taglist>s with <tag>s but no <item>s. +otp_xmlify_dl([#xmlElement{name=dt} = E|Es]) -> + [E|otp_xmlify_dl(Es, E)]; +otp_xmlify_dl([E|Es]) -> + [E|otp_xmlify_dl(Es)]; +otp_xmlify_dl([]) -> + []. + +otp_xmlify_dl([#xmlElement{name=dd} = E|Es], _DT) -> + [E|otp_xmlify_dl(Es)]; +otp_xmlify_dl([#xmlElement{name=dt} = E|Es], DT) -> + DD = DT#xmlElement{name=dd, attributes=[], content=[]}, + [DD,E|otp_xmlify_dl(Es, E)]; +otp_xmlify_dl([E|Es], DT) -> + [E|otp_xmlify_dl(Es, DT)]; +otp_xmlify_dl([], DT) -> + DD = DT#xmlElement{name=dd, attributes=[], content=[]}, + [DD]. + +%% otp_xmlify_table(Es1) -> Es2 +%% Transform <table> contents into "text", that is, inline elements. +otp_xmlify_table([#xmlText{} = E|Es]) -> + [E | otp_xmlify_table(Es)]; +otp_xmlify_table([#xmlElement{name=tbody} = E|Es]) -> + otp_xmlify_table(E#xmlElement.content)++otp_xmlify_table(Es); +otp_xmlify_table([#xmlElement{name=tr, content=Content}|Es]) -> + %% Insert newlines between table rows + otp_xmlify_table(Content)++[{br,[]}]++otp_xmlify_table(Es); +otp_xmlify_table([#xmlElement{name=th, content=Content}|Es]) -> + [{em, Content} | otp_xmlify_table(Es)]; +otp_xmlify_table([#xmlElement{name=td, content=Content}|Es]) -> + otp_xmlify_e(Content) ++ otp_xmlify_table(Es); +otp_xmlify_table([]) -> + []. + +%%--Misc help functions used by otp_xmlify/1 et al--------------------- + +%% find_next(Tag, Es) -> {Es1, Es2} +%% Returns {Es1, Es2} where Es1 is the list of all elements up to (but +%% not including) the first element with tag Tag in Es, and Es2 +%% is the remaining elements of Es. +find_next(Tag, Es) -> + find_next(Tag, Es, []). +find_next(Tag, [#xmlElement{name=Tag} = E | Es], AccEs) -> + {lists:reverse(AccEs), [E|Es]}; +find_next(Tag, [E|Es], AccEs) -> + find_next(Tag, Es, [E|AccEs]); +find_next(_Tag, [], AccEs) -> + {lists:reverse(AccEs), []}. + +%% find_p_ending(Es, []) -> {Es1, Es2} +%% Returns {Es1, Es2} where Es1 is the list of all elements up to (but +%% not including) the first paragraph break in Es, and Es2 is +%% the remaining elements of Es2. +%% Paragraph break = <p> tag or empty line +%% the next blank line, <p> or end-of-list as P, and the remaining +%% elements of Es as After. +find_p_ending([#xmlText{value="\n \n"++_} = E|Es], P) -> + {lists:reverse(P), [E|Es]}; +find_p_ending([#xmlElement{name=p} = E|Es], P) -> + {lists:reverse(P), [E|Es]}; +find_p_ending([E|Es], P) -> + find_p_ending(Es, [E|P]); +find_p_ending([], P) -> + {lists:reverse(P), []}. + +%% is_paragraph(E | P) -> bool() +%% P = {p, Es} +is_paragraph(#xmlElement{name=p}) -> true; +is_paragraph({p, _Es}) -> true; +is_paragraph(_E) -> false. + +%% p_content(E | P) -> Es +p_content(#xmlElement{content=Content}) -> Content; +p_content({p, Content}) -> Content. + +%% is_empty(Str) -> bool() +%% Str = string() +%% Returns true if Str is empty in the sense that it contains nothing +%% but spaces, tabs or newlines. +is_empty("\n"++Str) -> + is_empty(Str); +is_empty(" "++Str) -> + is_empty(Str); +is_empty("\t"++Str) -> + is_empty(Str); +is_empty("") -> + true; +is_empty(_) -> + false. + +%% split(Str, Seps) -> [Str] +split(Str, Seps) -> + split(Str, Seps, []). + +split([Ch|Str], Seps, Acc) -> + case lists:member(Ch, Seps) of + true -> split(Str, Seps, Acc); + false -> split(Str, Seps, Acc, [Ch]) + end; +split([], _Seps, Acc) -> + lists:reverse(Acc). + +split([Ch|Str], Seps, Acc, Chs) -> + case lists:member(Ch, Seps) of + true -> split(Str, Seps, [lists:reverse(Chs)|Acc]); + false -> split(Str, Seps, Acc, [Ch|Chs]) + end; +split([], _Seps, Acc, Chs) -> + lists:reverse([lists:reverse(Chs)|Acc]). + +%%--Functions for creating an erlref document--------------------------- + +%% function_name(F) -> string() +%% F = #xmlElement{name=function} +%% Returns the name of a function as "name/arity". +function_name(E) -> + get_attrval(name, E) ++ "/" ++ get_attrval(arity, E). + +%% functions(Fs) -> Es +%% Fs = [{Name, F}] +%% Name = string() "name/arity" +%% F = #xmlElement{name=function} +functions(Fs) -> + Es = lists:flatmap(fun ({Name, E}) -> function(Name, E) end, Fs), + if + Es==[] -> + []; + true -> + {funcs, Es} + end. + +function(_Name, E=#xmlElement{content = Es}) -> + TypeSpec = get_content(typespec, Es), + [?NL,{func, [ ?NL, + {name, + case funcheader(TypeSpec) of + [] -> + signature(get_content(args, Es), + get_attrval(name, E)); + Spec -> Spec + end + }, + ?NL,{fsummary, fsummary(Es)}, + ?NL,local_types(TypeSpec), + ?NL,{desc, + label_anchor(E)++ + deprecated(Es)++ + fulldesc(Es)++ + seealso_function(Es)} + ]}]. + +fsummary([]) -> ["\s"]; +fsummary(Es) -> + Desc = get_content(description, Es), + case get_content(briefDescription, Desc) of + [] -> + fsummary_equiv(Es); % no description at all if no equiv + ShortDesc -> + text_only(ShortDesc) + end. + +fsummary_equiv(Es) -> + case get_content(equiv, Es) of + [] -> ["\s"]; + Es1 -> + case get_content(expr, Es1) of + [] -> ["\s"]; + [Expr] -> + ["Equivalent to ", Expr, ".",?NL] + end + end. + +label_anchor(E) -> + case get_attrval(label, E) of + "" -> []; + Ref -> [{marker, [{id, Ref}],[]},?NL] + end. + +label_anchor(Content, E) -> + case get_attrval(label, E) of + "" -> Content; + Ref -> {p,[{marker, [{id, Ref}],[]}, + {em, Content}]} + end. + +signature(Es, Name) -> + [Name, "("] ++ seq(fun arg/1, Es) ++ [") -> term()", ?NL]. + +arg(#xmlElement{content = Es}) -> + [get_text(argName, Es)]. + +funcheader([]) -> []; +funcheader(Es) -> + [t_name(get_elem(erlangName, Es))] ++ t_utype(get_elem(type, Es)). + +local_types([]) -> []; +local_types(Es) -> + local_defs2(get_elem(localdef, Es)). + +local_defs2([]) -> []; +local_defs2(Es) -> + {type,[?NL | [{v, localdef2(E)} || E <- Es]]}. + +%% Like localdef/1, but does not use label_anchor/2 -- we don't want any +%% markers or em tags in <v> tag, plain text only! +localdef2(#xmlElement{content = Es}) -> + case get_elem(typevar, Es) of + [] -> + t_utype(get_elem(type, Es)); + [V] -> + t_var(V) ++ [" = "] ++ t_utype(get_elem(type, Es)) + end. + +type_name(#xmlElement{content = Es}) -> + t_name(get_elem(erlangName, get_content(typedef, Es))). + +types(Ts) -> + Es = lists:flatmap(fun ({Name, E}) -> typedecl(Name, E) end, Ts), + [?NL, {taglist,[?NL|Es]}]. + +typedecl(Name, #xmlElement{content = Es}) -> + TypedefEs = get_content(typedef, Es), + Id = "type-"++Name, + [{tag, typedef(TypedefEs)}, + ?NL, + {item, [{marker,[{id,Id}],[]} | + local_defs(get_elem(localdef, TypedefEs)) ++ fulldesc(Es)]}, + ?NL]. + +typedef(Es) -> + Name = ([t_name(get_elem(erlangName, Es)), "("] + ++ seq(fun t_utype_elem/1, get_content(argtypes, Es), [")"])), + case get_elem(type, Es) of + [] -> + [{tt, Name}]; + Type -> + [{tt, Name ++ [" = "] ++ t_utype(Type)}] + end. + +local_defs([]) -> []; +local_defs(Es) -> + [?NL, {ul, [{li, [{tt, localdef(E)}]} || E <- Es]}]. + +localdef(E = #xmlElement{content = Es}) -> + Var = case get_elem(typevar, Es) of + [] -> + [label_anchor(t_abstype(get_content(abstype, Es)), E)]; + [V] -> + t_var(V) + end, + Var ++ [" = "] ++ t_utype(get_elem(type, Es)). + +deprecated(Es) -> + case get_content(deprecated, Es) of + [] -> []; + DeprEs -> + Es2 = get_content(fullDescription, + get_content(description, DeprEs)), + Es3 = otp_xmlify_e(Es2), + [{p, [{em, ["This function is deprecated: "]} |Es3]}, ?NL] + end. + +fulldesc(Es) -> + case get_content(fullDescription, get_content(description, Es)) of + [] -> + index_desc(Es); + Desc -> + [?NL|otp_xmlify(Desc)] ++ [?NL] + end. + +index_desc(Es) -> + Desc = get_content(description, Es), + case get_content(briefDescription, Desc) of + [] -> + equiv(Es); % no description at all if no equiv + ShortDesc -> + ShortDesc + end. + +seealso_module(Es) -> + case get_elem(see, Es) of + [] -> []; + Es1 -> + {section,[{title,["See also"]},{p,seq(fun see/1, Es1, [])}]} + end. +seealso_function(Es) -> + case get_elem(see, Es) of + [] -> []; + Es1 -> + [{p, [{em, ["See also:"]}, " "] ++ seq(fun see/1, Es1, ["."])}, + ?NL] + end. + +%% ELEMENT see PCDATA +%% ATTLIST name PCDATA +%% href PCDATA +see(#xmlElement{content=Es0} = E) -> + Href0 = get_attrval(href, E), + {Href, Es} = otp_xmlify_a_href(Href0, Es0), + [{seealso, [{marker, Href}], Es}]. + +equiv(Es) -> + case get_content(equiv, Es) of + [] -> ["\s"]; + Es1 -> + case get_content(expr, Es1) of + [] -> []; + [Expr] -> + Expr1 = [Expr], + Expr2 = case get_elem(see, Es1) of + [] -> + {c,Expr1}; + [E=#xmlElement{}] -> + case get_attrval(href, E) of + "" -> + {c,Expr1}; + Ref -> + {seealso, [{marker, Ref}], Expr1} + end + end, + [{p, ["Equivalent to ", Expr2, "."]}, ?NL] + end + end. + +authors(Es) -> + case get_elem(author, Es) of + [] -> + [?NL,{aname,["\s"]},?NL,{email,["\s"]}]; + Es1 -> + [?NL|seq(fun author/1, Es1, "", [])] + end. + +author(E=#xmlElement{}) -> + Name = case get_attrval(name, E) of + [] -> "\s"; + N -> N + end, + Mail = case get_attrval(email, E) of + [] -> "\s"; + M -> M + end, + [?NL,{aname,[Name]},?NL,{email,[Mail]}]. + +t_name([E]) -> + N = get_attrval(name, E), + case get_attrval(module, E) of + "" -> N; + M -> + S = M ++ ":" ++ N, + case get_attrval(app, E) of + "" -> S; + A -> "//" ++ A ++ "/" ++ S + end + end. + +t_utype([E]) -> + t_utype_elem(E). + +t_utype_elem(E=#xmlElement{content = Es}) -> + case get_attrval(name, E) of + "" -> t_type(Es); + Name -> + T = t_type(Es), + case T of + [Name] -> T; % avoid generating "Foo::Foo" + T -> [Name] ++ ["::"] ++ T + end + end. + +t_type([E=#xmlElement{name = typevar}]) -> + t_var(E); +t_type([E=#xmlElement{name = atom}]) -> + t_atom(E); +t_type([E=#xmlElement{name = integer}]) -> + t_integer(E); +t_type([E=#xmlElement{name = float}]) -> + t_float(E); +t_type([#xmlElement{name = nil}]) -> + t_nil(); +t_type([#xmlElement{name = list, content = Es}]) -> + t_list(Es); +t_type([#xmlElement{name = tuple, content = Es}]) -> + t_tuple(Es); +t_type([#xmlElement{name = 'fun', content = Es}]) -> + t_fun(Es); +t_type([#xmlElement{name = abstype, content = Es}]) -> + t_abstype(Es); +t_type([#xmlElement{name = union, content = Es}]) -> + t_union(Es); +t_type([#xmlElement{name = record, content = Es}]) -> + t_record(Es). + +t_var(E) -> + [get_attrval(name, E)]. + +t_atom(E) -> + [get_attrval(value, E)]. + +t_integer(E) -> + [get_attrval(value, E)]. + +t_float(E) -> + [get_attrval(value, E)]. + +t_nil() -> + ["[]"]. + +t_list(Es) -> + ["["] ++ t_utype(get_elem(type, Es)) ++ ["]"]. + +t_tuple(Es) -> + ["{"] ++ seq(fun t_utype_elem/1, Es, ["}"]). + +t_fun(Es) -> + ["("] ++ seq(fun t_utype_elem/1, get_content(argtypes, Es), + [") -> "] ++ t_utype(get_elem(type, Es))). + +t_record([E|Es]) -> + ["#", get_attrval(value, E), "{"++ seq(fun t_field/1, Es) ++"}"]. +t_field(#xmlElement{name=field, content=[Atom,Type]}) -> + [get_attrval(value, Atom), "="] ++ t_utype_elem(Type). + +t_abstype(Es) -> + case split_at_colon(t_name(get_elem(erlangName, Es)),[]) of + {Mod,Type} -> + [Type, "("] ++ + seq(fun t_utype_elem/1, get_elem(type, Es), [")"]) ++ + [" (see module ", Mod, ")"]; + Type -> + [Type, "("] ++ + seq(fun t_utype_elem/1, get_elem(type, Es), [")"]) + end. + +%% Split at one colon, but not at two (or more) +split_at_colon([$:,$:|_]=Rest,Acc) -> + lists:reverse(Acc)++Rest; +split_at_colon([$:|Type],Acc) -> + {lists:reverse(Acc),Type}; +split_at_colon([Char|Rest],Acc) -> + split_at_colon(Rest,[Char|Acc]); +split_at_colon([],Acc) -> + lists:reverse(Acc). + +t_union(Es) -> + seq(fun t_utype_elem/1, Es, " | ", []). + +%% seq(Fun, Es) +%% seq(Fun, Es, Tail) +%% seq(Fun, Es, Sep, Tail) -> [string()] +%% Fun = function(E) -> [string()] +%% Sep = string() +%% Tail = [string()] +%% Applies Fun to each element E in Es and return the appended list of +%% strings, separated by Sep which defaults to ", " and ended by Tail +%% which defaults to []. +seq(Fun, Es) -> + seq(Fun, Es, []). +seq(Fun, Es, Tail) -> + seq(Fun, Es, ", ", Tail). +seq(Fun, [E], _Sep, Tail) -> + Fun(E) ++ Tail; +seq(Fun, [E | Es], Sep, Tail) -> + Fun(E) ++ [Sep] ++ seq(Fun, Es, Sep, Tail); +seq(_Fun, [], _Sep, Tail) -> + Tail. + +%%--Misc functions for accessing fields etc----------------------------- + +%% Type definitions used below: +%% E = #xmlElement{} | #xmlText{} +%% Es = [E] +%% Tag = atom(), XHTML tag +%% Name = atom(), XHTML attribute name +%% Attrs = [#xmlAttribute{}] +%% Ts = [#xmlText{}] + +%% parent(E) -> module | overview +parent(E) -> + Parents = E#xmlElement.parents, + {Parent,_} = lists:last(Parents), + Parent. + +%% get_elem(Tag, Es1) -> Es2 +%% Returns a list of all elements in Es which have the name Tag. +get_elem(Name, [#xmlElement{name = Name} = E | Es]) -> + [E | get_elem(Name, Es)]; +get_elem(Name, [_ | Es]) -> + get_elem(Name, Es); +get_elem(_, []) -> + []. + +%% get_attr(Name, Attrs1) -> Attrs2 +%% Returns a list of all attributes in Attrs1 which have the name Name. +get_attr(Name, [#xmlAttribute{name = Name} = A | As]) -> + [A | get_attr(Name, As)]; +get_attr(Name, [_ | As]) -> + get_attr(Name, As); +get_attr(_, []) -> + []. + +%% get_attrval(Name, E) -> string() +%% If E has one attribute with name Name, return its value, otherwise "" +get_attrval(Name, #xmlElement{attributes = As}) -> + case get_attr(Name, As) of + [#xmlAttribute{value = V}] -> + V; + [] -> "" + end. + +%% get_content(Tag, Es1) -> Es2 +%% If there is one element in Es1 with name Tag, returns its contents, +%% otherwise [] +get_content(Name, Es) -> + case get_elem(Name, Es) of + [#xmlElement{content = Es1}] -> + Es1; + [] -> [] + end. + +%% get_text(Tag, Es) -> string() +%% If there is one element in Es with name Tag, and its content is +%% a single xmlText, return the value of this xmlText. +%% Otherwise return "". +get_text(Name, Es) -> + case get_content(Name, Es) of + [#xmlText{value = Text}] -> + Text; + [] -> "" + end. + +%% get_text(E) -> string() +%% Return the value of an single xmlText which is the content of E, +%% possibly recursively. +get_text(#xmlElement{content=[#xmlText{value=Text}]}) -> + Text; +get_text(#xmlElement{content=[E]}) -> + get_text(E). + +%% text_only(Es) -> Ts +%% Takes a list of xmlElement and xmlText and return a lists of xmlText. +text_only([#xmlElement{content = Content}|Es]) -> + text_only(Content) ++ text_only(Es); +text_only([#xmlText{} = E |Es]) -> + [E | text_only(Es)]; +text_only([]) -> + []. diff --git a/lib/erl_docgen/src/otp_specs.erl b/lib/erl_docgen/src/docgen_otp_specs.erl index edb437a942..edb437a942 100644 --- a/lib/erl_docgen/src/otp_specs.erl +++ b/lib/erl_docgen/src/docgen_otp_specs.erl diff --git a/lib/erl_docgen/src/docgen_xmerl_xml_cb.erl b/lib/erl_docgen/src/docgen_xmerl_xml_cb.erl new file mode 100644 index 0000000000..089b8f0c7d --- /dev/null +++ b/lib/erl_docgen/src/docgen_xmerl_xml_cb.erl @@ -0,0 +1,88 @@ +%% ``The contents of this file are subject to the Erlang Public License, +%% Version 1.1, (the "License"); you may not use this file except in +%% compliance with the License. You should have received a copy of the +%% Erlang Public License along with this software. If not, it can be +%% retrieved via the world wide web at http://www.erlang.org/. +%% +%% Software distributed under the License is distributed on an "AS IS" +%% basis, WITHOUT WARRANTY OF ANY KIND, either expressed or implied. See +%% the Licence for the specific language governing rights and limitations +%% under the License. +%% +%% The Initial Developer of the Original Code is Ericsson AB. +%% Portions created by Ericsson are Copyright 1999-2006, Ericsson AB. +%% All Rights Reserved.�� +%% +%% $Id$ +%% +-module(docb_xmerl_xml_cb). + +%% This is the callback module for exporting XHTML to a DocBuilder +%% erlref or chapter document in XML format. +%% See docb_edoc_xml_cb.erl for further information. +%% +%% The origin of this file is the xmerl module xmerl_otpsgml.erl +%% written by Ulf Wiger and Richard Carlsson. + +-export(['#xml-inheritance#'/0]). + +-export(['#root#'/4, + '#element#'/5, + '#text#'/1]). + +-include("xmerl.hrl"). + +'#xml-inheritance#'() -> + [xmerl_xml]. + +'#root#'(Data, _Attrs, [], _E) -> + ["<",DTD,">"] = hd(hd(Data)), + ["<?xml version=\"1.0\" encoding=\"latin1\" ?>\n", + "<!DOCTYPE "++DTD++" SYSTEM \""++DTD++".dtd\">\n", + Data]. + +'#element#'(Tag, Data, Attrs, _Parents, _E) -> + {NewTag, NewAttrs} = convert_tag(Tag, Attrs), + xmerl_lib:markup(NewTag, NewAttrs, Data). + +'#text#'(Text) -> + xmerl_lib:export_text(Text). + +%% Utility functions + +convert_tag(a, [Attr]) -> + case Attr#xmlAttribute.name of + href -> + Val = Attr#xmlAttribute.value, + case is_url(Val) of + true -> + {url, [Attr]}; + false -> + {seealso, [Attr#xmlAttribute{name=marker}]} + end; + name -> + {marker, [Attr#xmlAttribute{name=id}]} + end; +convert_tag(b, Attrs) -> {em, Attrs}; +convert_tag(blockquote, Attrs) -> {quote, Attrs}; +convert_tag(code, Attrs) -> {c, Attrs}; +convert_tag(dd, Attrs) -> {item, Attrs}; +convert_tag(dl, Attrs) -> {taglist, Attrs}; +convert_tag(dt, Attrs) -> {tag, Attrs}; +convert_tag(li, Attrs) -> {item, Attrs}; +convert_tag(ol, Attrs) -> {list, Attrs}; +convert_tag(strong, Attrs) -> {em, Attrs}; +convert_tag(td, Attrs) -> {cell, Attrs}; +convert_tag(tr, Attrs) -> {row, Attrs}; +convert_tag(tt, Attrs) -> {c, Attrs}; +convert_tag(ul, Attrs) -> {list, Attrs}; +convert_tag(underline, Attrs) -> {em, Attrs}; +convert_tag(Tag, Attrs) -> {Tag, Attrs}. + +is_url("http:"++_) -> true; +is_url("../"++_) -> true; +is_url(FileRef) -> + case filename:extension(FileRef) of + "" -> false; % no extension = xml file, DocBuilder resolves + _Ext -> true % extension, DocBuilder must not resolve + end. diff --git a/lib/erl_docgen/src/docgen_xml_check.erl b/lib/erl_docgen/src/docgen_xml_check.erl new file mode 100644 index 0000000000..5912e22e7b --- /dev/null +++ b/lib/erl_docgen/src/docgen_xml_check.erl @@ -0,0 +1,45 @@ +%% ``The contents of this file are subject to the Erlang Public License, +%% Version 1.1, (the "License"); you may not use this file except in +%% compliance with the License. You should have received a copy of the +%% Erlang Public License along with this software. If not, it can be +%% retrieved via the world wide web at http://www.erlang.org/. +%% +%% Software distributed under the License is distributed on an "AS IS" +%% basis, WITHOUT WARRANTY OF ANY KIND, either expressed or implied. See +%% the License for the specific language governing rights and limitations +%% under the License. +%% +%% The Initial Developer of the Original Code is Ericsson Utvecklings AB. +%% Portions created by Ericsson are Copyright 1999-2000, Ericsson +%% Utvecklings AB. All Rights Reserved.'' +%% +%% $Id$ +%% +-module(docb_xml_check). + +-export([validate/1]). +-deprecated([{validate,1,next_major_release}]). + +%% validate(File) -> ok | error | {error, badfile} +%% File = string(), file name with or without ".xml" extension +%% If XML validation fails for a file, the error information from +%% Xmerl is printed to terminal and the function returns error. +validate(File0) -> + File = case filename:extension(File0) of + ".xml" -> File0; + _ -> File0++".xml" + end, + case filelib:is_regular(File) of + true -> + DtdDir = docb_util:dtd_dir(), + case catch xmerl_scan:file(File, [{validation,true}, + {fetch_path,[DtdDir]}]) of + {'EXIT', Error} -> + io:format("~p~n", [Error]), + error; + {_Doc, _Misc} -> + ok + end; + false -> + {error, badfile} + end. |
