diff options
Diffstat (limited to 'lib/erl_docgen/doc/src/inline_tags.xml')
| -rw-r--r-- | lib/erl_docgen/doc/src/inline_tags.xml | 257 |
1 files changed, 257 insertions, 0 deletions
diff --git a/lib/erl_docgen/doc/src/inline_tags.xml b/lib/erl_docgen/doc/src/inline_tags.xml new file mode 100644 index 0000000000..5bcca54c05 --- /dev/null +++ b/lib/erl_docgen/doc/src/inline_tags.xml @@ -0,0 +1,257 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1997</year><year>2011</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Inline Tags</title> + <prepared/> + <docno/> + <date/> + <rev/> + <file>inline_tags.xml</file> + </header> + + <p>Inline tags are typically used within block tags, for example to + highlight a word within a paragraph.</p> + + <section> + <marker id="brTAG"></marker> + <title><br> - Line Break</title> + + <p>Forces a newline. The <c><![CDATA[<br>]]></c> tag is both a + block- and an inline tag and is described in + the <seealso marker="block_tags#brTAG">Block Tags</seealso> + section.</p> + </section> + + <section> + <marker id="cTAG"></marker> + <title><c> - Code</title> + + <p>Highlights things like variables and file names in a text flow. + Can contain plain text only. Newlines and tabs are ignored as + opposed to the <seealso marker="block_tags#codeTAG">code</seealso> + tag. All <seealso marker="character_entities">character + entities</seealso> are expanded. Example:</p> + <pre> +<p>Returns <c>true</c> if <c>Term</c> is an integer.</p> + </pre> + <p>results in:</p> + <p>Returns <c>true</c> if <c>Term</c> is an integer.</p> + </section> + + <section> + <marker id="emTAG"></marker> + <title><em> - Emphasis</title> + + <p>Highlights words which are important within a text flow. Example: + </p> + <pre> +<p>The application <em>must</em> be up and running.</p> + </pre> + <p>results in:</p> + <p>The application <em>must</em> be up and running.</p> + + <p>Contains plain text or a + <seealso marker="#cTAG"><c></seealso> tag.</p> + </section> + + <section> + <marker id="markerTAG"/> + <title><marker> - Marker</title> + + <p>Used as an anchor for hypertext references. The <c>id</c> + attribute defines the name of the marker. Example:</p> + <marker id="marker_example"/> + <pre> +<marker id="marker_example"/> + </pre> + + <p>The <seealso marker="#seealsoTAG"><seealso></seealso> tag + is used to refer to the marker.</p> + + <p>The <c><![CDATA[<marker>]]></c> tag is both a block- and an + inline tag.</p> + </section> + + <section> + <marker id="pathTAG"></marker> + <title><path> - Path</title> + + <p>Highlights file paths. The attributes <c>unix</c> and + <c>windows</c> makes it possible to specify different paths for + different file path notations. Default for both are "". + Example:</p> + <pre> +<p>Look at the <path unix=".profile" windows="win.ini">start-up file</path> + if you intend to alter the initial behavior.</p> + </pre> + <p>If no <c>ptype</c> option is specified when calling + <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso>, + this simply results in:</p> + <p>"Look at the <path>start-up file</path> + if you intend to alter the initial behavior."</p> + + <p>If both the options <c>{ptype,unix}</c> and + <c>{ptype,windows}</c> are specified, the example instead results + in:</p> + <p>"Look at the <path unix=".profile" windows="win.ini">start-up file</path> + if you intend to alter the initial behavior."</p> + </section> + + <section> + <marker id="seealsoTAG"></marker> + <title><seealso> - Local Cross Reference</title> + + <p>A cross reference (hypertext link) to a marker in the same file, + a marker in another file, or (the top of) another file, given by + the <c>marker</c> attribute. Must contain plain text. Examples: + </p> + + <pre><![CDATA[ + <seealso marker="#marker_example">marker example</seealso> + ]]></pre> + <p>results in: + <seealso marker="#marker_example">marker example</seealso> + (a hypertext link to the marker example above).</p> + + <pre><![CDATA[ + <seealso marker="block_tags#markerTAG">marker tag</seealso> + ]]></pre> + <p>results in: + <seealso marker="block_tags#markerTAG">marker tag</seealso> + (a hypertext link to the marker section in the Block Tags + chapter).</p> + + <pre><![CDATA[ + <seealso marker="overview">Overview</seealso> + ]]></pre> + <p>results in: + <seealso marker="overview">Overview</seealso> + (a hypertext link to the Overview chapter).</p> + + <p>Note the use of "#" before the name of the marker. Note also + that the filename extension <c>.html</c> is omitted. This is + because the default behavior of DocBuilder is to translate + <c><![CDATA[<seealso marker="File#Marker">text</seealso>]]></c> + to <c><![CDATA[<A HREF="File.html#Marker">text</A>]]></c>.</p> + + <p>The default behaviour can be modified by using the callback + module option to <c>docb_transform:file/1,2</c> and defining a + callback function + <seealso marker="docb_transform#Module:seealso-1">Module:seealso/1</seealso>. + This possibility is for example used in OTP to resolve cross + references between applications.</p> + </section> + + <section> + <marker id="urlTAG"></marker> + <title><url> - Non-Local Cross Reference</title> + + <p>A reference to a file outside the documentation, a web address or + similar, given by the <c>href</c> attribute. Must contain plain + text. Example:</p> + <pre><![CDATA[ +<url href="http://www.erlang.org">erlang.org</url> + ]]></pre> + <p>results in: <url href="http://www.erlang.org">erlang.org</url> + </p> + </section> + + <section> + <marker id="termTAG"></marker> + <marker id="termdefTAG"></marker> + <title><term>, <termdef> - Glossary</title> + + <p>Used to highlight a term with a local (for this document only) or + global definition. The identity of the term is given by + the <c>id</c> attribute.</p> + + <p>For a locally defined term, the tag contains a + <c><termdef></c>, which in turn contains an explanation of + the term as plain text. Example:</p> + <pre><![CDATA[ +<term id="HTML"><termdef>Hyper-Text Markup Language</termdef></term> + ]]></pre> + + <p>For a globally defined term, the tag is empty. Example:</p> + <pre><![CDATA[ +<term id="HTML"/> + ]]></pre> + + <p>Global definitions are given to DocBuilder in a file, using the + <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso> + option <c>term_defs</c>. The file should contain a list of tuples, + one for each term definition, on the format + <c>{Id,Name,Definition,Owner}</c>. The <c>Owner</c> part is just + for administration, if there are several people contributing to a + term definition file. Example:</p> + <pre> +[..., + {"HTML", "HTML", "Hyper-Text Markup Language", "Gunilla"}, + ...]. + </pre> + + <p>DocBuilder will collect both local and global definitions in a + glossary, which can be reached from a link in the left frame of + the HTML documentation.</p> + + <p>In the generated HTML, it is the term name which will be visible. + For locally defined terms, the id and the name are the same. + The name has a hypertext link to the definition in the glossary. + Example:</p> + <pre><![CDATA[ +<term id="HTML"><termdef>Hyper-Text Markup Language</termdef></term> + ]]></pre> + <p>results in: <term id="HTML"><termdef>Hyper-Text Markup Language</termdef></term> + </p> + + <p>If a term is defined both locally and globally, the global + definition takes precedence.</p> + </section> + + <section> + <marker id="citeTAG"></marker> + <marker id="citedefTAG"></marker> + <title><cite>, <citedef> - Bibliography</title> + + <p>Works the same way as <c><term></c> and + <c><termdef></c>, but for a bibliography list rather than + a glossary.</p> + + <p>A global bibliography list is given to DocBuilder in a file, + using the <seealso marker="docb_transform#file/1">docb_transform:file/1,2</seealso> + option <c>cite_defs</c>. The file should contain a list of tuples, + one for each cite, on the format + <c>{Id,Title,Info,Owner}</c>. The <c>Owner</c> part is just + for administration, if there are several people contributing to a + bibliography file. Example:</p> + <pre> +[..., + {"erlbook", + "Concurrent Programming in ERLANG","J. Armstrong, R. Virding, C. Wikström, " + "M. Williams, Concurrent Programming in ERLANG, Prentice Hall, 1996, ISBN 0-13-508301-X", + "jocke"}, + ...]. + </pre> + </section> +</chapter> + |