Re: [docbook-apps] refentry or section

["Samuel Wright" <lykoszine@gmail.com>]

Dennis,
Cheers for the answer.

On 30/05/07, Denis Bradford <denis.bradford@verizon.net> wrote:
> A reference is (I think) designed to be used for reference information,
> often presented in a dictionary-style for easy lookup. A reference is a
> collection of refentries, similar to a book comprising a bunch of
> chapters or articles. In addition to the normal kinds of output like
> HTML and PDF, refentries can also be transformed by the standard docbook
> xsl stylesheets to create man pages.

Exactly. Man pages do not interest me at this point. I am aware the
reference pages were originally create to enable man page output. What
I am interested in knowing is despite not needing man pages, is there
any advantage in using refentries to hold my api information than
sections and subsections.

The only clear advantage I see is that you have a different container
for "dictionary style" information, and thus can format that
differently to your textual sections. The actual markup  of a refentry
does not seem to add anything beyond what I can put in a section,
using funcsynopsis and sects or simplesects for synopsis, description,
etc...

Using sections rather than sect1 and sect2 means I can reuse them at a
different levels in the documentation, which I think is slightly more
difficult with refentries, as they can embedded within chapters and
parts but not sections.

"The value of a separate hierarchical structure is that it allows the
content model of sections in reference pages to be customized
differently than the content model of sections outside. For example,
because of this split, it was easy to add a recursive sectioning
element (Section) as a peer to Sect1 in DocBook V3.1 without
introducing it to RefEntrys, in which it would not be desirable."[1]

Is not very clear at all.

> By contrast, sections are general-purpose modules that might contain any
> kind of information (not just reference info). And they are usually
> smaller in scope - for example an article or chapter might be made up of
> sections. The analog of a section in a referentry is a refentry.

Granted sections are more general, but the scope is pretty much what
you make it. As far as I see it you could skip chapters entirely, and
just use sections. And as you can have sections within sections, you
can use them as refsection or refentry.

> For more (and better) info, see Norm Walsh's  book,
> http://www.docbook.org/tdg/en/html/docbook.html - esp. the chapter on
> Creating Docbook Documents.

Yes, I have read that.

> Also, I think a reference can be a good choice for an API, for the
> reason that you guessed: it's designed to give you a regular structure
> that makes information easy to up. I think that's what most people do
> with API docs. Non-reference components (chapters, articles), are less
> restrictive, more suitable (I would argue) for more narrative or
> variable content.

So to sum up here, I feel as though I _should_ use references,
refsections and refentries for my api information, and
chapters/sections/etc for my other content, _BUT_ I don't see that
much advantage in doing so, and you also accrue some extra markup for
no great reason.

Any more thoughts?

Thanks
S

[1] http://www.docbook.org/tdg/en/html/refsect1.html