[kde-doc-english]Re: New to docbook and in need of help

[Lauri Watts]

On Saturday 20 April 2002 15.19, kelvin Gardiner wrote:
> Hi,
>
> I have just started to write KDE documentation. I am currently writing the
> documentation for Mahjonng. I have got to Preferences dialog and need a
> help with which tags I should use. The dialog has three panels (I'll call
> them panels as I can not find them in the visual dictionary)that contain
> options for different parts of the program. A wish to refer to each panel
> and then each option in that panel in turn. I'd like each panel and then
> each option to be separate visual when the HTML is produce, indented or
> whatever. 

Oh Kelvin, please beware of saying such things!

DocBook is semantic in nature.  Which means, you simply describe things and 
mark them up with what they *are* and the rest is taken care of by the 
stylesheets.

In this case, your best reference will probaby be that very kmines 
documentation you mention, which you will find in your sources in 
kdegames/doc/kmines/index.docbook (if you don't have the sources, you'll also 
find it installed in $KDEDIR/share/doc/HTML/en/kmines/index.docbook).  

As to specifics: The pages of a tabbed module are usually called "pages" or 
"tabs", or "panels".  We really should standardize on one, panels perhaps.

Probably what you want to do is something like this

<chapter id="preferences">
<title>Preferences</title>

<para>The preferences dialog is made up of several pages, where you can 
configure the behaviour of &kmahjongg;.</para>

<!-- If there's lots, you might put a list here, with links to each page, and 
describing what each one specifically covers -->

<sect1 id="first-tab">
<title>The <guilabel>First</guilabel> tab</title>

<para>On this page you can configure ...</para>

<variablelist>
<varlistentry>
<term><guilabel>The first option:</guilabel></term>
<listitem>
<para>Setting this to foo ...</para>
</listitem>
</varlistentry>
...
</variablelist>
</sect1>

<sect1 id="second-page">
<title>The <guilabel>Second</guilabel> page</title>

<<variablelist>
<varlistentry>
<term><guilabel>The first option:</guilabel></term>
<listitem>
<para>Setting this to foo ...</para>
</listitem>
</varlistentry>
...
</variablelist>
</sect1>
</chapter>

Hopefully this helped some,

Regards
-- 
Lauri Watts