<chapt id="listexamp">

  <heading>Lists and examples</heading>

  <sect id="lists">
    <heading>Lists</heading>
    
    <p>
      There are three kinds of lists:
      <list compact="compact">
	<item>
	  <p>
	    <tt>&lt;list&gt;</tt> - ordinary (bulleted) list
	  </p>
	</item>
	<item>
	  <p>
	    <tt>&lt;enumlist&gt;</tt> - numbered list
	  </p>
	</item>
	<item>
	  <p>
	    <tt>&lt;taglist&gt;</tt> - tagged list
	  </p>
	</item>
      </list>
    </p>

    <p>
      Each entry in an ordinary or numbered list is an item introduced
      by <tt>&lt;item&gt;</tt>.  Each entry in a tagged list is one or
      more <tt>&lt;tag&gt;</tt>s followed by an
      <tt>&lt;item&gt;</tt>.
    </p>

    <p>
      It is not necessary to mark the end of <tt>&lt;tag&gt;</tt> or
      <tt>&lt;item&gt;</tt> elements.
    </p>

    <p>
      All three types of list come in two flavours, depending on
      whether you specify the <tt>compact</tt> attribute (eg,
      <tt>&lt;taglist compact&gt;</tt>) or not (eg,
      <tt>&lt;enumlist&gt;</tt>).  The <tt>&lt;tag&gt;</tt> may
      contain only marked-up inline text.
    </p>

    <p>
      The compact versions are intended for use within paragraphs. The
      formatter will not put gaps around the list or between
      entries.<footnote><p>There is a problem with this in HTML.  The
      HTML formatter tries not to, by using HTML lists'
      <tt>compact</tt> attribute on the lists it generates, but not
      many browsers understand it properly.</p></footnote> The entries
      in a compact list should each be a single paragraph (it is not
      necessary to mark the start of the paragraph). Any lists inside
      a compact list should themselves be marked compact (though the
      formatters will in fact infer for themselves that they ought to
      be compact).
    </p>

    <p>
      The non-compact versions are intended to stand as paragraphs
      themselves.  Each entry in such a list may contain more than one
      paragraph (once again, the start of the first paragraph need not
      be marked).  The list is separated from the surrounding text,
      and the entries from each other, by blank lines as would be
      expected for paragraph breaks.
    </p>

  </sect>

  <sect id="examples">
    <heading>Examples</heading>

    <p>
      Examples - multi-line code fragments, scripts, and similar
      pieces of computer text - are introduced with
      <tt>&lt;example&gt;</tt> and finish with
      <tt>&lt;/example&gt;</tt>.
    </p>

    <p>
      The example will be formatted exactly as it is typed in, with
      spacing and newlines reproduced.  It will be displayed in a
      fixed-width font, usually the one used for the
      <tt>&lt;tt&gt;</tt> character style, even if the formatter
      usually uses a proportional font.  Any indentation which is
      appropriate will be added by the formatter; the example should
      be entered starting in the left hand column.
    </p>

    <p>
      Examples may contain marked up character text but may not
      contain cross-references or the character style elements
      <tt>&lt;em&gt;</tt>, <tt>&lt;strong&gt;</tt>,
      <tt>&lt;package&gt;</tt>, <tt>&lt;prgn&gt;</tt>,
      <tt>&lt;file&gt;</tt>, and <tt>&lt;tt&gt;</tt>. See <ref
      id="inline">.
    </p>

    <p>
      An example does not produce a paragraph break; examples are
      considered parts of paragraphs.  If an example is to be a
      paragraph on its own then paragraph start tags should be added
      as appropriate.
    </p>

    <p>
      Any SGML markup characters in the example must be escaped as
      usual - see <ref id="markup">. <tt>&lt;example&gt;</tt> does not
      work like TeX's <tt>verbatim</tt> environment.
    </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:
-->
