path: root/lib/docbuilder/doc/src/inline_tags.xml

<?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>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>&lt;br&gt; - 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>&lt;c&gt; - 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>
&lt;p>Returns &lt;c>true&lt;/c> if &lt;c>Term&lt;/c> is an integer.&lt;/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>&lt;em&gt; - Emphasis</title>

    <p>Highlights words which are important within a text flow. Example:
    </p>
    <pre>
&lt;p>The application &lt;em>must&lt;/em> be up and running.&lt;/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">&lt;c&gt;</seealso> tag.</p>
  </section>

  <section>
    <marker id="markerTAG"/>
    <title>&lt;marker&gt; - 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>
&lt;marker id="marker_example"/&gt;
    </pre>
  
    <p>The <seealso marker="#seealsoTAG">&lt;seealso&gt;</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>&lt;path&gt; - 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>
&lt;p>Look at the &lt;path unix=".profile" windows="win.ini"&gt;start-up file&lt;/path&gt;
  if you intend to alter the initial behavior.&lt;/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>&lt;seealso&gt; - 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>&lt;url&gt; - 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>&lt;term&gt;, &lt;termdef&gt; - 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>&lt;termdef&gt;</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>&lt;cite&gt;, &lt;citedef&gt; - Bibliography</title>

    <p>Works the same way as <c>&lt;term&gt;</c> and
      <c>&lt;termdef&gt;</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&ouml;m, M. Williams, Concurrent Programming in ERLANG, Prentice Hall, 1996, ISBN 0-13-508301-X","jocke"},
 ...].
    </pre>
  </section>
</chapter>