diff options
Diffstat (limited to 'lib/erl_docgen/doc/src')
21 files changed, 3052 insertions, 31 deletions
diff --git a/lib/erl_docgen/doc/src/Makefile b/lib/erl_docgen/doc/src/Makefile new file mode 100644 index 0000000000..ff50c12895 --- /dev/null +++ b/lib/erl_docgen/doc/src/Makefile @@ -0,0 +1,136 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2011-2011. All Rights Reserved. +# +# 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. +# +# %CopyrightEnd% +# +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(ERL_DOCGEN_VSN) +APPLICATION=erl_docgen + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = ref_man.xml +XML_REF6_FILES = \ + erl_docgen_app.xml + +XML_PART_FILES = \ + part.xml + +XML_CHAPTER_FILES = \ + overview.xml \ + doc-build.xml \ + user_guide_dtds.xml \ + refman_dtds.xml \ + notes.xml \ + inline_tags.xml \ + header_tags.xml \ + character_entities.xml \ + block_tags.xml + +BOOK_FILES = book.xml + +XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF6_FILES) \ + $(XML_PART_FILES) $(XML_CHAPTER_FILES) + +TECHNICAL_DESCR_FILES = + +EXAMPLE_FILES = \ + example.txt + +GIF_FILES = \ + man.gif + +# ---------------------------------------------------- + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info + +MAN6_FILES = $(XML_REF6_FILES:%_app.xml=$(MAN6DIR)/%.6) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +docs: pdf html man + +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +$(HTMLDIR)/example.txt: example.txt + $(INSTALL_DATA) $< $@ + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs examples $(HTML_REF_MAN_FILE) + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN6DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + rm -f $(JD_HTML) $(JD_PACK) + +man: $(MAN6_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +examples: $(GIF_FILES:%=$(HTMLDIR)/%) + +debug opt: + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man6 + $(INSTALL_DATA) $(MAN6DIR)/* $(RELEASE_PATH)/man/man6 + +release_spec: 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..0900d7f008 --- /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>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>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 OTP 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. 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="example.txt" tag="%% Erlang example"/> + </pre> + <p>results in:</p> + <codeinclude file="example.txt" tag="%% Erlang example"/> + + <p>provided there is a file named <c>examples.txt</c> looking like this: + </p> + <code> +... + +%% Erlang example +-module(example). + +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. 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/book.xml b/lib/erl_docgen/doc/src/book.xml index 9df5c39271..73bfb7916d 100644 --- a/lib/erl_docgen/doc/src/book.xml +++ b/lib/erl_docgen/doc/src/book.xml @@ -1,10 +1,10 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="iso-8859-1" ?> <!DOCTYPE book SYSTEM "book.dtd"> <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header titlestyle="normal"> <copyright> - <year>2004</year><year>2009</year> + <year>2004</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -21,27 +21,26 @@ </legalnotice> - <title>erl_docgen</title> + <title>Erl_Docgen</title> <prepared>Lars Thorsen</prepared> <docno></docno> - <date>2009-11-10</date> - <rev>0.1</rev> + <date>2011-11-10</date> + <rev>0.3</rev> <file>book.xml</file> </header> - <insidecover> - </insidecover> <pagetext>erl_docgen</pagetext> <preamble> <contents level="2"></contents> </preamble> <parts lift="no"> + <xi:include href="part.xml"/> </parts> <applications> + <xi:include href="ref_man.xml"/> </applications> <releasenotes> <xi:include href="notes.xml"/> </releasenotes> - <listofterms></listofterms> <index></index> </book> 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..9f55b68d18 --- /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 OTP 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/convert.howto b/lib/erl_docgen/doc/src/convert.howto deleted file mode 100644 index 2c72de8c4c..0000000000 --- a/lib/erl_docgen/doc/src/convert.howto +++ /dev/null @@ -1,13 +0,0 @@ - -- add xmlns:xi="http://www.w3.org/2001/XInclude" on top tag - in files whith include directives - -- change <include file="notes"></include> <xi:include href="notes.xml"/> - -- change <image file="a"/> to <image file="a.gif"/> - -- remove chapers directly in the book and put them in the part instead - --change title to just the application name - -- fix codeinclude : xml --> xmlsrc
\ No newline at end of file diff --git a/lib/erl_docgen/doc/src/doc-build.xml b/lib/erl_docgen/doc/src/doc-build.xml new file mode 100644 index 0000000000..08410a1539 --- /dev/null +++ b/lib/erl_docgen/doc/src/doc-build.xml @@ -0,0 +1,188 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!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>How to Build OTP like documentation</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>doc-build.xml</file> + </header> + + <section> + <title>Utilities to prepare XML files</title> + <section> + <title>Create XML files from code</title> + <p> + If there are EDoc comments in a module, the escript <c>xml_from_edoc.escript</c> + can be used to generate an XML file according to the <c>erlref</c> DTD + for this module. + </p> + <p> + Example: + </p> + <code> + + 1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/xml_from_edoc.escript ex1.erl + </code> + </section> + <section> + <title>Include code in XML</title> + <p>If there are OTP DTD <i>codeinclude</i> tags in the source XML file, the escript + <c>codeline_preprocessing.escript</c> can be used to include the code and produce + an XML file according to the OTP DTDs. + </p> + <p> + Example: + </p> + <code> + + 1> escript $(ERL_TOP)/lib/erl_docgen/priv/bin/codeline_preprocessing.escript ex1.xmlsrc ex1.xml + </code> + </section> + </section> + + <section> + <title>Use xsltproc to generate different output formats</title> + + <section> + <title>Parameters used in all the the XSL transformations</title> + <p> + These parameters to <c>xsltproc</c> are used for all the supported output formats. + </p> + <taglist> + <tag><c>docgen</c></tag> + <item> + Path to erl_docgen's top directory. + </item> + <tag><c>gendate</c></tag> + <item> + The date string that will be used in the documentation. + </item> + <tag><c>appname</c></tag> + <item> + The name of the application.> + </item> + <tag><c>appver</c></tag> + <item> + The version of the application. + </item> + </taglist> + </section> + + <section> + <title>Generate HTML output</title> + <p> + When generating HTML one also needs these three pramaters to <c>xsltproc</c>. + </p> + <taglist> + <tag><c>outdir</c></tag> + <item> + Output directory for the produced html files. + </item> + <tag><c>topdocdir</c></tag> + <item> + If one builds a standalone documentation for an application this should be set to ".". + </item> + <tag><c>pdfdir</c></tag> + <item> + Relative path from the html directory to where the pdf file are placed. + </item> + </taglist> + <p> + Example: + </p> + <code> + + 1> xsltproc --noout --stringparam outdir /tmp/myhtmldoc \ + --stringparam docgen $(ERL_TOP)/lib/erl_docgen \ + --stringparam topdocdir . \ + --stringparam pdfdir "$(PDFDIR)" \ + --xinclude \ + --stringparam gendate "December 5 2011" \ + --stringparam appname MyApp \ + --stringparam appver 0.1 \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \ + $ERL_TOP/lib/erl_docgen/priv/xsl/db_html.xsl mybook.xml + </code> + </section> + + <section> + <title>Generate PDF</title> + <p> + The generation of the PDF file is done in two steps. First is <c>xsltproc</c> used to generate a <c>.fo</c> file + which is used as input to the <c>fop</c> command to produce th PDF file. + </p> + <p> + Example: + </p> + <code> + + 1> xsltproc --output MyApp.fo \ + --stringparam docgen $ERL_TOP/lib/erl_docgen \ + --stringparam gendate "December 5 2011" \ + --stringparam appname MyApp \ + --stringparam appver 0.1 \ + --xinclude \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd_html_entities \ + $ERL_TOP/lib/erl_docgen/priv/xsl/db_pdf.xsl mybook.xml + + + 2> fop -fo MyApp.fo -pdf MyApp.pdf + </code> + </section> + + <section> + <title>Generate man pages</title> + <p> + Unix man pages can be generated with <c>xsltproc</c> from XML files written according to + the different OTP ref type DTDs. + </p> + <p> + Example: + </p> + <code> + + 1> xsltproc --output my_module.3\ + --stringparam docgen $ERL_TOP/lib/erl_docgen \ + --stringparam gendate "December 5 2011" \ + --stringparam appname MyApp \ + --stringparam appver 0.1 \ + --xinclude -path $ERL_TOP/lib/erl_docgen/priv/dtd \ + -path $ERL_TOP/lib/erl_docgen/priv/dtd_man_entities \ + $ERL_TOP/lib/erl_docgen/priv/xsl/db_man.xsl my_refpage.xml + </code> + </section> + + <section> + <title>Upcomming changes</title> + <p> + The output from the <c>erl_docgen</c> documentation build process is now just the OTP style. + But in a near future we will for example add the possibility to change logo, color in the PDF and + style sheet for the HTML. + </p> + </section> + + </section> +</chapter> diff --git a/lib/erl_docgen/doc/src/docgen_xml_check.xml b/lib/erl_docgen/doc/src/docgen_xml_check.xml new file mode 100644 index 0000000000..58cf069d81 --- /dev/null +++ b/lib/erl_docgen/doc/src/docgen_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>docgen_xml_check</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>docgen_xml_check</module> + <modulesummary>Validate XML documentation source code</modulesummary> + <description> + <p><c>docgen_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/erl_docgen.txt b/lib/erl_docgen/doc/src/erl_docgen.txt deleted file mode 100644 index 14a4dc8e10..0000000000 --- a/lib/erl_docgen/doc/src/erl_docgen.txt +++ /dev/null @@ -1,6 +0,0 @@ - - - -/home/otptest/bin/otp_wrap_ssh boddington /home/otptest/bin/otp_build_doc -rel r13b02 -view otptest_r13_daily_doc2 -csfile /usr/local/otp/config-specs/r13_dev.cs -insdir /ldisk/daily_build -_ -
\ No newline at end of file diff --git a/lib/erl_docgen/doc/src/erl_docgen_app.xml b/lib/erl_docgen/doc/src/erl_docgen_app.xml new file mode 100644 index 0000000000..25c473bb7e --- /dev/null +++ b/lib/erl_docgen/doc/src/erl_docgen_app.xml @@ -0,0 +1,64 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE appref SYSTEM "appref.dtd"> + +<appref> + <header> + <copyright> + <year>2011</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>erl_docgen</title> + <file>erl_docgen_app.xml</file> + </header> + <app>erl_docgen</app> + <appsummary> + The erl_docgen application is used to produce the OTP documentation. + </appsummary> + + <description> + <p> + The application consists of the following parts + <taglist> + <tag>XSL</tag> + <item> + <p> + A number of XSL files that is used to transform the xml files to html, pdf or man pages. + </p> + </item> + <tag>DTDs</tag> + <item> + <p> + The DTDs used for the OTP documentation. + </p> + </item> + <tag>escripts</tag> + <item> + <p> + Some scripts that is used to produce xml files according to OTP DTDs from some different input. + </p> + </item> + <tag>misc</tag> + <item> + <p> + Erlang logo, javascripts and css stylesheets used in the documentation. + </p> + </item> + </taglist> + </p> + </description> + +</appref> diff --git a/lib/erl_docgen/doc/src/example.txt b/lib/erl_docgen/doc/src/example.txt new file mode 100644 index 0000000000..ad86165391 --- /dev/null +++ b/lib/erl_docgen/doc/src/example.txt @@ -0,0 +1,17 @@ +This example code is used in block_tags.xml. + +%% Erlang example +-module(example). + +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/fasc_dtds.xml b/lib/erl_docgen/doc/src/fasc_dtds.xml new file mode 100644 index 0000000000..86eeb958f6 --- /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>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>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/header_tags.xml b/lib/erl_docgen/doc/src/header_tags.xml new file mode 100644 index 0000000000..dfae15107f --- /dev/null +++ b/lib/erl_docgen/doc/src/header_tags.xml @@ -0,0 +1,181 @@ +<?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>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. 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.</p> + </section> + + <section> + <marker id="responsibleTAG"></marker> + <title><responsible></title> + + <p>This optional tag is intended for administrative use and is + ignored.</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.</p> + </section> + + <section> + <marker id="checkedTAG"></marker> + <title><checked></title> + + <p>This optional tag is intended for administrative use and is + ignored.</p> + </section> + + <section> + <marker id="dateTAG"></marker> + <title><date></title> + + <p>This tag is intended for administrative use and is ignored.</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.</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..9b27da659b --- /dev/null +++ b/lib/erl_docgen/doc/src/inline_tags.xml @@ -0,0 +1,214 @@ +<?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 is to translate + <c><![CDATA[<seealso marker="File#Marker">text</seealso>]]></c> + to <c><![CDATA[<A HREF="File.html#Marker">text</A>]]></c>.</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>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> + + </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/notes.xml b/lib/erl_docgen/doc/src/notes.xml index 6a0eece56d..23f64b876a 100644 --- a/lib/erl_docgen/doc/src/notes.xml +++ b/lib/erl_docgen/doc/src/notes.xml @@ -1,4 +1,4 @@ -<?xml version="1.0" encoding="latin1" ?> +<?xml version="1.0" encoding="iso-8859-1" ?> <!DOCTYPE chapter SYSTEM "chapter.dtd"> <chapter> @@ -21,16 +21,59 @@ </legalnotice> - <title>erl_docgen Release Notes</title> + <title>Erl_Docgen Release Notes</title> <prepared>otp_appnotes</prepared> <docno>nil</docno> <date>nil</date> <rev>nil</rev> <file>notes.xml</file> </header> - <p>This document describes the changes made to the erl_docgen application.</p> + <p>This document describes the changes made to the <em>erl_docgen</em> application.</p> - <section><title>Erl_Docgen 0.2.6</title> + <section><title>Erl_Docgen 0.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Bug fixes concerning the generation of manpages. </p> + <p> + Own Id: OTP-9614</p> + </item> + <item> + <p> Fix syntax bug in eix files. </p> + <p> + Own Id: OTP-9617</p> + </item> + <item> + <p> Bug fix concerning the generation of manpages. </p> + <p> + Own Id: OTP-9759</p> + </item> + <item> + <p> Fixed an arity calculation bug for erlang functions + in the documentation index for html and pdf. </p> + <p> + Own Id: OTP-9772</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> The docbuilder application is removed in R15 and + parts still used in the OTP documentation build process + and the DTD documentation is moved to erl_docgen. </p> + <p> + Own Id: OTP-9721</p> + </item> + </list> + </section> + +</section> + +<section><title>Erl_Docgen 0.2.6</title> <section><title>Fixed Bugs and Malfunctions</title> <list> diff --git a/lib/erl_docgen/doc/src/overview.xml b/lib/erl_docgen/doc/src/overview.xml new file mode 100644 index 0000000000..2a420c53d9 --- /dev/null +++ b/lib/erl_docgen/doc/src/overview.xml @@ -0,0 +1,105 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!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>Overview OTP DTDs</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>overview.xml</file> + </header> + + <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>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 documentation of + an OTP application.</p> + + </section> + + <section> + <title>Basic Tags</title> + + <p>All DTDs in the OTP 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> + +</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..26d660df08 --- /dev/null +++ b/lib/erl_docgen/doc/src/part.xml @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="iso-8859-1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2011</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>Erl_Docgen User's Guide</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <description> + <p><em>Erl_Docgen</em> provides functionality for generating HTML/PDF/man + 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="doc-build.xml"/> + <xi:include href="overview.xml"/> + <xi:include href="user_guide_dtds.xml"/> + <xi:include href="refman_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/ref_man.xml b/lib/erl_docgen/doc/src/ref_man.xml new file mode 100644 index 0000000000..a2bc1a10a0 --- /dev/null +++ b/lib/erl_docgen/doc/src/ref_man.xml @@ -0,0 +1,36 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2011</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>Erl_Docgen Reference Manual</title> + <prepared>OTP Team</prepared> + <docno></docno> + <date>2011-11-10</date> + <rev>0.3</rev> + <file>ref_man.xml</file> + </header> + <description> + <p>The <em>erl_docgen</em> supports the OTP documentation build.</p> + </description> + <xi:include href="erl_docgen_app.xml"/> +</application> + 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..4f0e388a8a --- /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>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>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, it will + automatically be added 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>Then a marker like this will be added + <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..79a7701ce8 --- /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>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>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> + |
