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

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

<chapter>
  <header>
    <copyright>
      <year>2007</year><year>2013</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>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>