Re: Blocks within a <sect2>

Roberto Mello writes:

> I am working on the PL/pgSQL docs right now and I need a way to
> further subdivide blocks within a <sect2> in DocBook.
> For example, I have a "Variables and Constants" <sect2> and I want to
> have blocks for "Declaring Variables", "Declaring Constants" and
> "Assigning Values to Variables". Each with its own header that stands out
> as a block. How do I do that in DocBook?

<sect3> <sect4> <sect5> (no further)

> Another thing is how do I declare tha HTML equivalent of a
> "<A NAME='blah'>" so I can <link linkend="blah">FooBar</link> somewhere
> else?

Use 'id' attributes. E.g.,

| <sect2 id="foo">
| <title>About Foos</title>
|
| <para>
| ...
| </para>
| ...
| </sect2>

Elsewhere:

| For more information about Foos, refer to <xref linkend="foo">.

Note that the <xref> inserts the fitting text, like "Section 1.2.3". In
general, <link> should only be used in limited circumstances, as it won't
come out right in print.

As for id attribute naming, use some hierarchical scheme. E.g., if the
chapter is "PL/pgSQL", the sect1 is "Description", the sect2 is "Variables
and Constants", and sect3 is "Constants", use something like

<sect3 id="plpgsql-description-var-const">

The HTML files and anchors will be named like the id's. (Try 'ls
*.html'.)

Note that in theory you could <xref> to any element that has an id, but
the stylesheets we use only implement xrefs to a subset that contains
things like chapters, sect's, examples, tables, and similar named block
elements.

Actually, the existing PL/pgSQL documentation source should be a good
example of these concepts.

Btw., have you read the book at docbook.org?

--
Peter Eisentraut peter_e(at)gmx(dot)net http://yi.org/peter-e/