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

<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2007</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>Fascicules DTDs</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>fasc_dtds.xml</file>
  </header>

  <section>
    <title>The fascicules DTD</title>

    <p>The <c>fascicules</c> DTD is a special kind of DTD which can be
      used to specify the different parts of the documentation, and
      which one of those should be shown as default.</p>

    <p>Example:</p>

    <pre><![CDATA[
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE fascicules SYSTEM "fascicules.dtd">
<fascicules>
  <fascicule file="part" href="part_frame.html" entry="no">
    User's Guide
  </fascicule>
  <fascicule file="ref_man" href="ref_man_frame.html" entry="yes">
    Reference Manual
  </fascicule>
  <fascicule file="part_notes" href="part_notes_frame.html" entry="no">
    Release Notes
  </fascicule>
</fascicules>
    ]]></pre>

    <p>In the example, it is specified that the documentation for this
      application consists of three parts: User's Guide, where
      the "cover page" (with the two frames) is located in
      <c>part_frame.html</c>, Reference Manual with the cover page
      <c>ref_man_frame.html</c> and Release Notes with the cover page
      <c>part_notes_frame.html</c>.</p>

    <p>As a result, at the top of the left frame in the generated HTML
      documentation, there will be corresponding links to User's Guide,
      Reference Manual and Release Notes.</p>

    <p>The attribute <c>entry="yes"</c> specifies that it is
      the Reference Manual which should be shown as default. This means
      that when generating the HTML files, <c>application_frame.html</c>
      will be copied to <c>index.html</c>.</p>

    <note>
      <p>DocBuilder assumes that the XML file written according to
	the <c>fascicules</c> DTD is called <c>fascicules.xml</c>.</p>
    </note>

    <p>This file is optional. If it does not exist, there are no links
      to other parts of the documentation (as they are not known) in
      the left frame, and no <c>index.html</c> is created.</p>
  </section>

  <section>
    <marker id="fasciculesTAG"></marker>
    <title>&lt;fascicules&gt;</title>

    <p>Top level tag for the <c>fascicules</c> DTD.</p>

    <p>Contains one or more
      <seealso marker="#fasciculeTAG">&lt;fascicule&gt;</seealso>.</p>
  </section>

  <section>
    <marker id="fasciculeTAG"></marker>
    <title>&lt;fascicule&gt;</title>

    <p>Specifies properties for one "part" of the documentation for an
      application.</p>

    <p>Contains plain text, the name of this part.</p>

    <p>The <c>file</c> attribute should specify the file name for
      the corresponding <c>part</c> or <c>application</c>, without
      the <c>.xml</c> extension.</p>

    <p>The <c>href</c> attribute should specify the file name for
      the corresponding HTML cover page file, without the <c>.html</c>
      extension.</p>

    <p>The optional <c>entry="yes"|"no"</c> attribute specifies if
      the HTML cover page should be copied to <c>index.html</c> or
      not. Default is <c>"no"</c>.</p>
  </section>
</chapter>