diff options
Diffstat (limited to 'lib/erl_docgen/doc/src/block_tags.xml')
| -rw-r--r-- | lib/erl_docgen/doc/src/block_tags.xml | 431 |
1 files changed, 431 insertions, 0 deletions
diff --git a/lib/erl_docgen/doc/src/block_tags.xml b/lib/erl_docgen/doc/src/block_tags.xml new file mode 100644 index 0000000000..f5ba083f38 --- /dev/null +++ b/lib/erl_docgen/doc/src/block_tags.xml @@ -0,0 +1,431 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Block Tags</title> + <prepared/> + <docno/> + <date/> + <rev/> + <file>block_tags.xml</file> + </header> + + <p>Block tags typically define a separate block of information, such + as a paragraph or a list.</p> + + <p>The following subset of block tags are common for all DTDs in + the DocBuilder DTD suite: + <marker id="block_subset"></marker> + <seealso marker="#pTAG"><p></seealso>, + <seealso marker="#preTAG"><pre></seealso>, + <seealso marker="#codeTAG"><code></seealso>, + <seealso marker="#listTAG"><list></seealso>, + <seealso marker="#taglistTAG"><taglist></seealso>, + <seealso marker="#codeincludeTAG"><codeinclude></seealso> and + <seealso marker="#erlevalTAG"><erleval></seealso>. + </p> + + <section> + <marker id="brTAG"></marker> + <title><br> - Line Break</title> + + <p>Forces a newline. Example:</p> + <pre> +Eat yourself<br/>senseless! + </pre> + <p>results in:</p> + <p>Eat yourself<br/>senseless!</p> + + <p>The <c><![CDATA[<br>]]></c> tag is both a block- and an inline + tag.</p> + </section> + + <section> + <marker id="codeTAG"></marker> + <title><code> - Code Example</title> + + <p>Highlight code examples. Example:</p> + <pre> +<code> +sum([H|T]) -> + H + sum(T); +sum([]) -> + 0. +</code> + </pre> + <p>results in:</p> + <code> +sum([H|T]) -> + H + sum(T); +sum([]) -> + 0. + </code> + + <p>There is an attribute <c>type = "erl" | "c" | "none"</c>, but + currently this attribute is ignored by DocBuilder. Default value + is <c>"none"</c></p> + + <note> + <p>No tags are allowed within the tag and no + <seealso marker="character_entities">character + entities</seealso> are expanded.</p> + </note> + </section> + + <section> + <marker id="codeincludeTAG"></marker> + <title><codeinclude> - Code Inclusion</title> + + <p>Include external code snippets. The attribute <c>file</c> + gives the file name and <c>tag</c> defines a string which + delimits the code snippet. Example:</p> + <pre> +<codeinclude file="gazonk" tag="%% Erlang example"/> + </pre> + <p>results in:</p> + <codeinclude file="gazonk" tag="%% Erlang example"/> + + <p>provided there is a file named <c>gazonk</c> looking like this: + </p> + <code> +... + +%% Erlang example +-module(gazonk). + +start() -> + {error,"Pid required!"}. +start(Pid) -> + spawn(fun() -> init(Pid) end). +%% Erlang example + +... + </code> + + <p>If the <c>tag</c> attribute is omitted, the whole file is + included.</p> + + <p>There is also an attribute <c>type = "erl" | "c" | "none"</c>, but + currently this attribute is ignored by DocBuilder. Default value + is <c>"none"</c></p> + </section> + + <section> + <marker id="erlevalTAG"></marker> + <title><erleval> - Erlang Evaluation</title> + + <p>Include the result from evaluating an Erlang expression. Example: + </p> + <code><![CDATA[ +<erleval expr="{A,b,C}={a,b,c}. "/> + ]]></code> + <p>results in:</p> + <erleval expr="{A,b,C}={a,b,c}. "></erleval> + + <p>Note the '.' and space after the expression.</p> + </section> + + <section> + <marker id="listTAG"></marker> + <title><list> - List</title> + + <p>The attribute <c>type = "ordered"|"bulleted"</c> decides if + the list is numbered or bulleted. Default is <c>"bulleted"</c>. + </p> + + <p>Lists contains list items, tag <c><![CDATA[<item>]]></c>, which + can contain plain text, + the <seealso marker="#block_subset">common subset of block + tags</seealso> and <seealso marker="inline_tags">inline + tags</seealso>. Example:</p> + <pre> +<list type="ordered"> + <item>Askosal: + <list> + <item>Nullalisis</item> + <item>Facilisis</item> + </list> + </item> + <item>Ankara</item> +</list> + </pre> + <p>results in:</p> + <list type="ordered"> + <item> + <p>Askosal:</p> + <list type="bulleted"> + <item>Nullalisis</item> + <item>Facilisis</item> + </list> + </item> + <item>Ankara</item> + </list> + </section> + + <section> + <marker id="markerTAG"></marker> + <title><marker> - Marker</title> + + <p>Used as an anchor for hypertext references. The + <c><![CDATA[<marker>]]></c> tag is both a block- and an inline + tag and is described in + the <seealso marker="inline_tags#markerTAG">Inline Tags</seealso> + section.</p> + </section> + + <section> + <marker id="pTAG"></marker> + <title><p> - Paragraph</title> + + <p>Paragraphs contain plain text and + <seealso marker="inline_tags">inline tags</seealso>. Example:</p> + <pre> +<p>I call specific attention to + the authority given by the <em>21st Amendment</em> + to the Constitution to prohibit transportation + or importation of intoxicating liquors into + any State in violation of the laws of such + State.</p> + </pre> + <p>results in:</p> + <p>I call specific attention to + the authority given by the <em>21st Amendment</em> + to the Constitution to prohibit transportation + or importation of intoxicating liquors into + any State in violation of the laws of such + State.</p> + </section> + + <section> + <marker id="noteTAG"></marker> + <title><note> - Note</title> + + <p>Highlights a note. Can contain block tags except + <c><![CDATA[<note>]]></c>, <c><![CDATA[<warning>]]></c>, + <c><![CDATA[<image>]]></c> and <c><![CDATA[<table>]]></c>. + Example:</p> +<pre> +<note> + <p>This function is mainly intended for debugging.</p> +</note> + </pre> + <p>results in:</p> + <note> + <p>This function is mainly intended for debugging.</p> + </note> + </section> + + <section> + <marker id="preTAG"></marker> + <title><pre> - Pre-formatted Text</title> + + <p>Used for documentation of system interaction. Can contain text, + <seealso marker="inline_tags#seealsoTAG">seealso</seealso>, + <seealso marker="inline_tags#urlTAG">url</seealso> and + <c><![CDATA[<input>]]></c> tags.</p> + + <p>The <c><![CDATA[<input>]]></c> tag is used to highlight user + input. Example:</p> + <pre> +<pre> +$ <input>erl</input> +Erlang (BEAM) emulator version 5.5.3 [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.5.3 (abort with ^G) +1> <input>pwd().</input> +/home/user +2> <input>halt().</input> +</pre> + </pre> + <p> results in:</p> + <pre> +$ <input>erl</input> +Erlang (BEAM) emulator version 5.5.3 [async-threads:0] [hipe] [kernel-poll:false] + +Eshell V5.5.3 (abort with ^G) +1> <input>pwd().</input> +/home/user +2> <input>halt().</input> + </pre> + + <p>All <seealso marker="character_entities">character + entities</seealso> are expanded.</p> + </section> + + <section> + <marker id="quoteTAG"></marker> + <title><quote> - Quotation</title> + + <p>Highlight quotations from other works, or dialog spoken by + characters in a narrative. Contains one or more + <seealso marker="#pTAG"><p></seealso> tags. Example:</p> + <pre> +<p>Whereas Section 217(a) of the Act of Congress entitled +"An Act ..." approved June 16, 1933, provides as follows:</p> +<quote> + <p>Section 217(a) The President shall proclaim the law.</p> +</quote> + </pre> + <p>results in:</p> + <p>Whereas Section 217(a) of the Act of Congress entitled + "An Act ..." approved June 16, 1933, provides as follows:</p> + <quote> + <p>Section 217(a) The President shall proclaim the law.</p> + </quote> + </section> + + <section> + <marker id="taglistTAG"></marker> + <marker id="tagTAG"></marker> + <title><taglist> - Definition List</title> + + <p>Definition lists contains pairs of tags, + <c><![CDATA[<tag>]]></c>, and list items, + <c><![CDATA[<item>]]></c>.</p> + + <p><c><![CDATA[<tag>]]></c> can contain plain text, + <seealso marker="inline_tags#cTAG"><c></seealso>, + <seealso marker="inline_tags#emTAG"><em></seealso>, + <seealso marker="inline_tags#seealsoTAG"><seealso></seealso> + and <seealso marker="inline_tags#urlTAG"><url></seealso> + tags.</p> + + <p><c><![CDATA[<item>]]></c> can contain plain text, + the <seealso marker="#block_subset">common subset of block + tags</seealso> and <seealso marker="inline_tags">inline + tags</seealso>. Example:</p> + <pre> +<taglist> + <tag><c>eacces</c></tag> + <item>Permission denied.</item> + <tag><c>enoent</c></tag> + <item>No such file or directory.</item> +</taglist> + </pre> + <p>results in:</p> + <taglist> + <tag><c>eacces</c></tag> + <item>Permission denied.</item> + <tag><c>enoent</c></tag> + <item>No such file or directory.</item> + </taglist> + </section> + + <section> + <marker id="warningTAG"></marker> + <title><warning> - Warning</title> + + <p>Highlights a warning. Can contain block tags except + <c><![CDATA[<note>]]></c>, <c><![CDATA[<warning>]]></c>, + <c><![CDATA[<image>]]></c> and <c><![CDATA[<table>]]></c>. + Example:</p> +<pre> +<warning> + <p>This function might be removed in a future version without + prior warning.</p> +</warning> + </pre> + <p>results in:</p> + <warning> + <p>This function might be removed in a future version without + prior warning.</p> + </warning> + </section> + + <section> + <marker id="imageTAG"></marker> + <marker id="icaptionTAG"></marker> + <title><image> - Image</title> + + <p>Graphics is imported using the <c><![CDATA[<image>]]></c> tag. + An image caption <c><![CDATA[<icaption>]]></c>, containing plain + text, must be supplied. Example:</p> + <pre> +<image file="man"> + <icaption>A Silly Man</icaption> +</image> + </pre> + <p>results in:</p> + <image file="man.gif"> + <icaption>A Silly Man</icaption> + </image> + + <p>This assumes that <c>man.gif</c> exists in the current directory. + </p> + </section> + + <section> + <marker id="tableTAG"></marker> + <marker id="rowTAG"></marker> + <marker id="cellTAG"></marker> + <marker id="tcaptionTAG"></marker> + <title><table> - Table</title> + + <p>The table format is similar to how tables are described in HTML + 3.2. A table contains one or more rows, <c><![CDATA[<row>]]></c>, + and a table caption <c><![CDATA[<tcaption>]]></c>, containing + plain text.</p> + + <p>Each row contains one or more cells, <c><![CDATA[<cell>]]></c>. + The attributes <c>align = "left"|"center"|"right"</c> and + <c>valign = "top"|"middle"|"bottom"</c> decides how text is + aligned in the cell horizontally and vertically. Default is + "<c>left</c>" and "<c>middle</c>".</p> + + <p>Each cell contains plain text and + <seealso marker="inline_tags">inline tags</seealso>. Example:</p> + <pre><![CDATA[ + <table> + <row> + <cell align="left" valign="top"><em>Boys</em></cell> + <cell align="center" valign="middle"><em>Girls</em></cell> + </row> + <row> + <cell align="left" valign="middle">Juda</cell> + <cell align="right" valign="bottom">Susy</cell> + </row> + <row> + <cell align="left" valign="middle">Anders</cell> + <cell align="left" valign="middle">Victoria</cell> + </row> + <tcaption>A table caption</tcaption> + </table> + ]]></pre> + <p>results in:</p> + <table> + <row> + <cell align="left" valign="top"><em>Boys</em></cell> + <cell align="center" valign="middle"><em>Girls</em></cell> + </row> + <row> + <cell align="left" valign="middle">Juda</cell> + <cell align="right" valign="bottom">Susy</cell> + </row> + <row> + <cell align="left" valign="middle">Anders</cell> + <cell align="left" valign="middle">Victoria</cell> + </row> + <tcaption>A table caption</tcaption> + </table> + </section> +</chapter> + |