<chapt id="inline">

  <heading>Marked-up inline text and character style markup</heading>

  <p>
    Ordinary text (called `inline text' in this document) may contain
    a elements for special formatting and cross-referencing.  Inline
    text appears in chapter, appendix and section titles, in the
    copyright summary, inside paragraphs and in other similar places.
  </p>

  <sect>
    <heading>Character style</heading>

    <p>
      There are a number of elements for denoting special significance
      of certain pieces of text.  For all of them the end of the
      special text must be marked up explicitly, by using an explicit
      end tag <tt>&lt;<var>element</var>&gt;</tt>, the abbreviated end
      tag for closing the innermost element <tt>&lt;/&gt;</tt> or the
      slash <tt>/</tt> which finishes the most abbreviated form of
      element markup (see <ref id="markup">).
    </p>

    <p>
      <taglist>

	<tag>
	  <tt>&lt;em&gt;</tt> - emphasis
	</tag>
	<item>
	  <p>
	    Indicates that the contained text is more important or
	    more significant than that surrounding it.
	  </p>
	  <p>
	    Typically this will be represented by italics if
	    available, or emboldened or underlined text, or in plain
	    text formats with no character highlighting available by
	    surrounding the text with asterisks like *this*.
	  </p>
	</item>

	<tag>
	  <tt>&lt;strong&gt;</tt> - more emphasis
	</tag>
	<item>
	  <p>
	    Indicates that the contained text is even more important
	    or even more significant than that surrounding it.
	  </p>
	  <p>
	    Typically this will be represented by bold if available or
	    in plain text formats with no character highlighting
	    available by surrounding the text with asterisks like
	    *this*.
	  </p>
	</item>

	<tag>
	  <tt>&lt;var&gt;</tt> - metasyntactic variable
	</tag>
	<item>
	  <p>
	    Indicates that the contained text is a metasyntactic
	    variable.  Ie, it is the name of an object or piece of
	    syntax which when actually used would have a real value
	    substituted.
	  </p>
	  <p>
	    Typically this will be represented by italics, or in plain
	    text formats by surrounding the text with angle brackets
	    like &lt;this&gt;. If several metasyntactic variables
	    appear one after the other they should each be given their
	    own <tt>&lt;var&gt;</tt> element.
	  </p>
	</item>

	<tag>
	  <tt>&lt;package&gt;</tt> - package name
	</tag>
	<item>
	  <p>
	    Indicates that the contained text is the name of a Debian
	    package.
	  </p>
	  <p>
	    This will usually be rendered using a fixed-width font; in
	    plain-text formats quotes may be used around the element.
	  </p>
	</item>

	<tag>
	  <tt>&lt;prgn&gt;</tt> - name of a program or well-known file
	</tag>
	<item>
	  <p>
	    Indicates that the contained text is the name of a
	    program, a well-known filename (usually without paths), a
	    function or some similar thing which has a name in the
	    computer.
	  </p>
	  <p>
	    In output formats where character highlighting and various
	    font styles are available this is usually represented by
	    using a fixed-width font.  In plain text output formats
	    quotes may be used around the element.
	  </p>
	</item>

	<tag>
	  <tt>&lt;file&gt;</tt> - full file or directory name
	</tag>
	<item>
	  <p>
	    Indicates that the contained text is the full pathname of
	    a file, buffer, directory, etc.
	  </p>
	  <p>
	    This will usually be rendered using a fixed-width font; in
	    plain-text formats quotes may be used around the element.
	  </p>
	</item>

	<tag>
	  <tt>&lt;tt&gt;</tt> - code or output fragment, command string
	</tag>
	<item>
	  <p>
	    Indicates that the contained text is a general string
	    which came out of or is going in to a computer.  It should
	    be used for command strings or code fragments that should
	    be displayed inline and wordrapped (see also <ref
	    id="examples"> for an alternative), and so forth.  It is
	    frequently necessary to introduce metasyntactic variables
	    into these strings, in which case they should be made part
	    of the <tt>&lt;tt&gt;</tt> element rather than elements
	    alongside it.
	  </p>
	  <p>
	    This will usually be rendered using a fixed-width font; in
	    plain-text formats quotes may be used around the element.
	  </p>
	</item>

	<tag>
	  <tt>&lt;qref id="<var>refid</var>"&gt;</tt> - quiet reference
	</tag>
	<item>
	  <p>
	    Produces a `quiet reference' to the named reference id
	    (see <ref id="xref">).  This should be used where a
	    cross-reference would be useful if not intrusive, but
	    where it is not essential and should be left out if it
	    would need to intrude on the text.
	  </p>
	  <p>
	    In formats where cross-references can be made
	    non-intrusively by making a region of text a hyperlink
	    without introducing in-line text this element will cause
	    its contained text to become a hyperlink to the target of
	    the cross-reference.  In other formats this element will
	    not have any effect.
	  </p>
	</item>

      </taglist>
    </p>

  </sect>

  <sect id="xref">
    <heading>Cross-references</heading>

    <p>
      There are a number of elements for introducing cross-references
      either to other parts of the same document or to other
      documents.
    </p>

    <p>
      The intra-document cross-references are based on a scheme of
      reference identifiers.  Each chapter, appendix, section,
      subsection etc. may have an <tt>id</tt> attribute giving its
      reference id - for example <tt>&lt;chapt id="spong"&gt;</tt>
      specifies that the chapter or appendix being started has
      reference id <tt>spong</tt>.  This reference id can then be
      referred to in other parts of the document using the special
      cross-referencing elements.
    </p>

    <p>
      The reference identifier will also be used for generating
      filenames and reference tokens for formats such as HTML which
      produce several output files; if no reference ids are specified
      then the chapter, appendix and section numbers will be used.  It
      is a good idea to give at least all your chapter and appendix
      reference ids so that the filenames will not change if you
      change the order of the chapters, appendices or sections in your
      document.
    </p>

    <p>
      <taglist>

	<tag>
	  <tt>&lt;ref id="<var>refid</var>"&gt;</tt> - intra-document
	  cross reference
	</tag>
	<item>
	  <p>
	    This generates a cross-reference within the same document
	    to the chapter, appendix or section with id
	    <var>refid</var>.
	  </p>
	  <p>
	    The <tt>&lt;ref&gt;</tt> element does not have any
	    contents; the chapter, appendix or section number and
	    title and its page number or whatever is appropriate for
	    the output format will be inserted into the text at the
	    point where the tag appears.
	  </p>
	  <p>
	    Syntactically the cross reference is a noun phrase,
	    suitable for uses like <tt>(see &lt;ref
	    id="<var>...</var>"&gt;)</tt> or <tt>further info is in
	    &lt;ref id="<var>...</var>"&gt;.</tt>.
	  </p>
	</item>

	<tag>
	  <tt>&lt;manref name="<var>name</var>"
	    section="<var>section</var>"&gt;</tt> - manpage
	</tag>
	<item>
	  <p>
	    Generates a cross-reference to the manpage for
	    <var>name</var> in section <var>section</var>.  This tag
	    does not have any contents; text describing the page,
	    typically <tt><var>name</var>(<var>section</var>)</tt>,
	    will be inserted at the point where
	    <tt>&lt;manref&gt;</tt> appears.
	  </p>
	</item>

	<tag>
	  <tt>&lt;email&gt;</tt> - email address
	</tag>
	<item>
	  <p>
	    Indicates that the contained text is an email address. The
	    contents of the tag should be just the text of the email
	    address itself; character style markup and
	    cross-references are forbidden.  Usually the end tag
	    <tt>&lt;/email&gt;</tt> may not be omitted, but it may be
	    left out when it appears in an <tt>&lt;author&gt;</tt> as
	    the end of the <tt>&lt;author&gt;</tt>, implied by the
	    start of the next element, will imply the end of the email
	    address.
	  </p>
	  <p>
	    In some formats this will generate a true cross-reference
	    which might (for example) be used to send email to the
	    address quoted.  In others it will just mark the text
	    specially, usually including angle brackets <tt>&lt;</tt>
	    <tt>&gt;</tt> around it.
	  </p>
	</item>

	<tag>
	  <tt>&lt;ftpsite&gt;</tt> - anonymous FTP site name
	</tag>
	<tag>
	  <tt>&lt;ftppath&gt;</tt> - path on most recently named FTP site
	</tag>
	<item>
	  <p>
	    <tt>&lt;ftpsite&gt;</tt> indicates that the content of the
	    element is the DNS name of an anonymous FTP site, and
	    <tt>&lt;ftppath&gt;</tt> that it is a pathname on that
	    site.  Both elements may not contain any character style
	    markup or cross-references.
	  </p>
	  <p>
	    Typically both elements will be rendered in a fixed width
	    font; if possible, the <tt>&lt;ftppath&gt;</tt> will be
	    made into a functional hyperlink to the named file or
	    directory on the most recent <tt>&lt;ftpsite&gt;</tt>.
	  </p>
	  <p>
	    <tt>&lt;ftppath&gt;</tt> must always have been preceded by
	    a <tt>&lt;ftpsite&gt;</tt> in the same chapter or
	    appendix, but once one site has been named several paths
	    may be appear.
	  </p>
	</item>

	<tag>
	  <tt>&lt;httpsite&gt;</tt> - HTTP site name
	</tag>
	<tag>
	  <tt>&lt;httppath&gt;</tt> - path on most recently named HTTP site
	</tag>
	<item>
	  <p>
	    <tt>&lt;httpsite&gt;</tt> indicates that the content of
	    the element is the DNS name of an HTTP site, and
	    <tt>&lt;httppath&gt;</tt> that it is a pathname on that
	    site.  Both elements may not contain any character style
	    markup or cross-references.
	  </p>
	  <p>
	    Typically both elements will be rendered in a fixed width
	    font; if possible, the <tt>&lt;httppath&gt;</tt> will be
	    made into a functional hyperlink to the named file or
	    directory on the most recent <tt>&lt;httpsite&gt;</tt>.
	  </p>
	  <p>
	    <tt>&lt;httppath&gt;</tt> must always have been preceded
	    by a <tt>&lt;httpsite&gt;</tt> in the same chapter or
	    appendix, but once one site has been named several paths
	    may be appear.
	  </p>
	</item>

	<tag>
	  <tt>&lt;url id="<var>id</var>"
	  name="<var>name</var>"&gt;</tt> - URL
	</tag>
	<item>
	  <p>
	    Generates a cross-reference to the URL with the indicated
	    <var>id</var> and uses the optional <var>name</var> in the
	    document as reference indicator.  This tag does not have
	    any contents.
	  </p>
	  <p>
	    Typically this element will be rendered in a fixed width
	    font; if possible, <var>id</var> will be made into a
	    functional hyperlink using <var>name</var> as place
	    holder.
	  </p>
	  <p>
	    Do not put this tag between &lt;file&gt; and &lt;/file&gt;.
	    This is known to break relative link in PDF format.
	  </p>
	</item>

      </taglist>
    </p>

  </sect>

  <sect id="footnotes">
    <heading>Footnotes</heading>

    <p>
      Footnotes may appear in most inline text, and are indicated by
      <tt>&lt;footnote&gt;<var>...</var>&lt;/footnote&gt</tt>. The
      text of the footnote itself will be removed and placed elsewhere
      (where depends on the format), and replaced with a reference or
      hyperlink to the footnote.
    </p>

    <p>
      The contents of the footnote should be one or more paragraphs;
      the start of the first paragraph need not be marked explicitly.
      Inline markup elements such as character style do not take
      effect on the contents of footnotes defined inside them - the
      footnote gets a `clean slate'.
    </p>

    <p>
      Footnotes may be nested, but this is rarely a good idea.
    </p>

  </sect>

  <sect id="comment">
    <heading>Comment</heading>

    <p>
      Comments may appear in most inline text, and are indicated by
      <tt>&lt;comment editor="foo"&gt;<var>...</var>&lt;/comment&gt</tt>. 
      The text of the comment itself will be removed and placed elsewhere
      (where depends on the format), and replaced with a reference or
      hyperlink to the footnote if -m option is used to enable this.
    </p>

    <p>
      The contents of the comment should be one or more paragraphs;
      the start of the first paragraph need not be marked explicitly.
    </p>

  </sect>

</chapt>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:("../debiandoc-sgml.en.sgml" "book" "chapt")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
