This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Article with ToC


> I am new to DocBook and would appreciate general guidance in this
> matter:
> 
> I would like to re-write my HOWTO indicated in my signature using the
> DocBook DTD.

Sound choice.

> I would like to replicate the HOWTO as is. In particular, I anticipate
> using the "article" format, but want to have a Table of Contents on the
> Title Page. 

It's a good idea not to mix markup with appearance: where the ToC
appears is not an issue for DocBook: whatever output you end up with
(print, HTML, etc), your processor should be able to make the ToC
appear wherever you want it. All DocBook has to do is identify what it
is.

> Each section/subsection must be on a separate page, with the
> usual "prev," "next" etc. navigation links.

Again, this is a presentation matter: provided you store the
information in a form that a processor can identify, you can have it
output any way you want. If all the relevant sections of every
document are correctly labeled with an ID, it is straightforward to
make a processor/converter create all the cross-references.

By the same token it's common practice to automate ToCs: one way to do
this is to provide a link to the actual section, and leave it to your
processor/converter to copy the [sub]section title into the right
place. This lets you edit and reword titles and not have to worry
about keeping the ToC up to date, although you do have to make sure
you create the corresponding empty ToC entry for each [sub]section you
create.

Personally I wouldn't bother at all: I'd program my converter to
create all the HTML ToC stuff on-the-fly, using the sections I'd
created, much in the way that LaTeX does. That way there is nothing to
keep up to date so maintenance is that bit easier.

> If anyone knows of a document on the 'net using this "simple" scheme for
> which a SGML source is made available, I would appreciate an URL.

Here's the top of your file, in DocBook (apologies for the old version
(3.0) I haven't got around to updating it yet).

///Peter
-- 
<!doctype article public "-//Davenport//DTD DocBook V3.0//EN">
<article>
  <artheader>
    <title>Online Troubleshooting Resources</title>
    <subtitle>HOWTO</subtitle>
    <author>
      <firstname>Howard</firstname>
      <surname>Mann</surname>
      <affiliation>
	<address><email>howardm@xmission.com</email></address>
      </affiliation>
    </author>
    <revhistory>
      <revision>
	<revnumber>0.5</revnumber>
	<date>September 18, 1999</date>
      </revision>
    </revhistory>
    <abstract>
      <para>This document will direct Linux users to resources
available on the Internet that provide access to a vast amount of
Linux-related information useful in troubleshooting problems.</para>
    </abstract>
  </artheader>
  <tocchap>
    <tocentry></tocentry>
    <toclevel1>
      <tocentry linkend="intro"></tocentry>
      <toclevel2>
	<tocentry linkend="docupd"></tocentry>
	<tocentry linkend="copyright"></tocentry>
	<tocentry linkend="feedback"></tocentry>
      </toclevel2>
    </toclevel1>
    <toclevel1>
      <tocentry linkend="howtos"></tocentry>
      <toclevel2>
	<tocentry>etc</tocentry>
      </toclevel2>
    </toclevel1>
  </tocchap>
  <sect1 id="intro">
    <title>Introduction</title>
    <para>blah</para>
    <sect2 id="docupd">
      <title>Document Updates</title>
      <para>blah</para>
    </sect2>
  </sect1>
  <sect1 id="howtos">
    <title>HOWTOs and mini-HOWTOs</title>
    <para>blah</para>
  </sect1>
</article>


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]