Обсуждение: Small documentation issue

In fdwhandler.sgml, chapter fdwhandler has only one subsection
(fdw-routines).

If there is only one subsection, no table of contents is generated in
the chapter.
That means that people who navigate to the chapter from the main table
of contents
will not see that there is a subsection.

I know too little about the documentation building process, but is it
possible
to generate a table of contents even if there is only one subsection?

Yours,
Laurenz Albe

On Fri, Jul 1, 2011 at 3:15 AM, Albe Laurenz <laurenz.albe@wien.gv.at> wrote:
> In fdwhandler.sgml, chapter fdwhandler has only one subsection
> (fdw-routines).
>
> If there is only one subsection, no table of contents is generated in
> the chapter.
> That means that people who navigate to the chapter from the main table
> of contents
> will not see that there is a subsection.
>
> I know too little about the documentation building process, but is it
> possible
> to generate a table of contents even if there is only one subsection?

Maybe we could just add a sentence to the end of the third paragraph
with a pointer to the section that follows, so it would read like
this:

The callback functions are plain C functions and are not visible or
callable at the SQL level.  They are described in more detail in
Section 50.1.

-- 
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas <robertmhaas@gmail.com> writes:
> On Fri, Jul 1, 2011 at 3:15 AM, Albe Laurenz <laurenz.albe@wien.gv.at> wrote:
>> In fdwhandler.sgml, chapter fdwhandler has only one subsection
>> (fdw-routines).
>> 
>> If there is only one subsection, no table of contents is generated in
>> the chapter.
>> That means that people who navigate to the chapter from the main table
>> of contents
>> will not see that there is a subsection.
>> 
>> I know too little about the documentation building process, but is it
>> possible
>> to generate a table of contents even if there is only one subsection?

I don't know how to change the doc toolchain to do that either.  But
on reflection it seemed to me that this documentation was badly designed
anyhow, because it mixed up description of the FDW's routines with
actual introductory text.  I split that into an introduction and a
<sect1> for the routines.  Problem solved.

> Maybe we could just add a sentence to the end of the third paragraph
> with a pointer to the section that follows, so it would read like
> this:

> The callback functions are plain C functions and are not visible or
> callable at the SQL level.  They are described in more detail in
> Section 50.1.

Yeah, I did that too.
        regards, tom lane

Tom Lane wrote:
>>> In fdwhandler.sgml, chapter fdwhandler has only one subsection
>>> (fdw-routines).
>>>
>>> If there is only one subsection, no table of contents is generated
in
>>> the chapter.
[...]

> I don't know how to change the doc toolchain to do that either.  But
> on reflection it seemed to me that this documentation was badly
designed
> anyhow, because it mixed up description of the FDW's routines with
> actual introductory text.  I split that into an introduction and a
> <sect1> for the routines.  Problem solved.

Thanks!

Laurenz Albe