Re: [docbook-apps] refentry or section

[Denis Bradford <denis.bradford@verizon.net>]

I think you're dealing with apples and oranges.

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.

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.

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.



Samuel Wright wrote:
> Hi All,
> 
> I'm documenting some software apis, and was thinking of using sections
> (rather than sect1,2, etc due to possible reuse). Have since sound
> references and refentries.
> 
> Is the main advantage of using references and refentries that you can
> format them in a different manner to sections containing other text?
> Is that a strong enough reason to use them? What do you all use for
> apis in docbook?
> 
> Thanks in advance for any thoughts
> 
> S
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
> 
>