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

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1997</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions 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 <seeguide marker="block_tags#brTAG">Block Tags</seeguide>
      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 <seeguide marker="block_tags#codeTAG">code</seeguide>
      tag. All <seeguide marker="character_entities">character
	entities</seeguide> 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
      <seeguide marker="#cTAG">&lt;c&gt;</seeguide> 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 <seeguide marker="#seeTAG">&lt;see*&gt;</seeguide> tags
      are 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="seeTAG"/>
    <title>&lt;see*&gt; - See tags</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. The syntax used within the <c>marker</c>
      attribute is <c>application:file#anchor</c> for the general case.
      <c>application</c> and <c>file</c> can be omitted if the link target
      is the current application or file.</p>
    <p>There are several different see tags that are to be used depending on
      what it is that they point to.</p>
    <taglist>
      <tag>&lt;seemfa&gt;</tag>
      <item>
        <p>Points to an MFA using the syntax <c>application:module#function/arity</c>.
        These links must point to functions documented in a &lt;funcs&gt; section.
          Examples:</p>
        <pre><![CDATA[
<seemfa marker="stdlib:string#length/1">string:length/1</seemfa>
<seemfa marker="string#length/1">string:length/1</seemfa>
<seemfa marker="#length/1">string:length/1</seemfa>
]]></pre>
        results in: <seemfa marker="stdlib:string#length/1">string:length/1</seemfa>.
      </item>
      <tag>&lt;seeerl&gt;</tag>
      <item>
        <p>Points to an Erlang module or a custom <seeguide marker="#markerTAG">marker</seeguide>
          within a module. Example:</p>
        <pre><![CDATA[
<seeerl marker="stdlib:string">string(3)</seeerl>,
<seeerl marker="stdlib:string#oldapi">Old API in string</seeerl>
]]></pre>
        results in: <seeerl marker="stdlib:string">string(3)</seeerl>,<seeerl marker="stdlib:string#oldapi">Old API in string</seeerl>.
      </item>
      <tag>&lt;seetype&gt;</tag>
      <item>
        <p>Points to a type using the syntax <c>application:module#type</c>.
        These links must point to types documented in a &lt;datatypes&gt; section.
        Example:</p>
        <pre><![CDATA[
<seetype marker="stdlib:string#grapheme_cluster">string::grapheme_cluster()</seetype>
]]></pre>
        results in: <seetype marker="stdlib:string#grapheme_cluster">string::grapheme_cluster()</seetype>.
      </item>
      <tag>&lt;seeapp&gt;</tag>
      <item><p>Points to the application documentation. <c>index</c> can be used as the target file.
        Example:</p>
        <pre><![CDATA[
<seeapp marker="stdlib:STDLIB_app">STDLIB app</seeapp>,
<seeapp marker="stdlib:index">STDLIB index</seeapp>
]]></pre>
        results in: <seeapp marker="stdlib:STDLIB_app">STDLIB</seeapp>, <seeapp marker="stdlib:index">STDLIB</seeapp>.
      </item>
      <tag>&lt;seecom&gt;</tag>
      <item>
        <p>Points to the documentation of any command line utility. Example:</p>
        <pre><![CDATA[
<seecom marker="erts:epmd">epmd</seecom>
]]></pre>
        results in: <seecom marker="erts:epmd">epmd</seecom>.
      </item>
      <tag>&lt;seecref&gt;</tag>
      <item>
        <p>Points to the documentation of any C reference. Example:</p>
      <pre><![CDATA[
<seecref marker="erts:erl_nif">erl_nif</seecref>
]]></pre>
        results in: <seecref marker="erts:erl_nif">erl_nif</seecref>.
      </item>
      <tag>&lt;seefile&gt;</tag>
      <item>
        <p>Points to the documentation of a file format. Example:</p>
        <pre><![CDATA[
<seefile marker="kernel:config">config(3)</seefile>
]]></pre>
        results in: <seefile marker="kernel:config">config(3)</seefile>.
      </item>
      <tag>&lt;seeguide&gt;</tag>
      <item>
        <p>Points to the User&quot;s Guide of any application.
          <c>index</c> can be used as the target file. Example:</p>
          <pre><![CDATA[
<seeguide marker="kernel:index">Kernel User's Guide Index</seeguide>,
<seeguide marker="kernel:logger_chapter">Logging in the Kernel User's Guide</seeguide>
]]></pre>
        results in: <seeguide marker="kernel:index">Kernel User's Guide Index</seeguide>,
        <seeguide marker="kernel:logger_chapter">Logging in the Kernel User's Guide</seeguide>.
      </item>
    </taglist>
  </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>

</chapter>