Re: Blocks within a

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@gmx.net       http://yi.org/peter-e/