RE: [docbook-apps] appendix vs. reference?

["Rowland, Larry" <larry.rowland@hp.com>]

The reference section contains refentry elements, which were originally developed to produce man pages for UNIX-like systems.  In general references contain descriptions of things like commands, code-libraries, functions, and configuration file formats (in general, the things that users and developers of UNIX-like environments would find useful).  The pages tend to be highly structured with designated pieces like the refnamediv and the refsynopsopsisdive that are designed to make it easy to find the information you are looking for while rapidly scanning a page.  In many organizations refentry elements are not allowed to contain images so that they can be delivered via the man command in UNIX-like environments, which has to deliver via term windows using nroff.

The appendixes are more generic in nature and tend to contain more varied types of information that do not fit as comfortably into the linear-sequential nature of the chapter model.

Regards,
Larry Rowland

-----Original Message-----
From: Robert Nagle [mailto:idiotprogrammer@gmail.com] 
Sent: Friday, June 11, 2010 2:19 PM
To: docbook-apps@lists.oasis-open.org
Subject: [docbook-apps] appendix vs. reference?

I'm looking at the docbook 5 documentation. Here's one thing I can't
get my head around.

What's the difference between an appendix tag and a reference tag?
http://www.docbook.org/tdg5/en/html/reference.html
http://www.docbook.org/tdg5/en/html/appendix.html

I have some technical information and tables I wish to put at the end
for the reader's reference. But I'm not sure whether i should do an
appendix or a reference. I plan to have 3 or 4 appendices about
various unrelated topics.

i see that reference has a lot of refentries amd refentries has a a
lot of children, so I understand that reference is probably more
structured. What  kinds of content would be better suited as a
reference instead of an appendix and vice versa?

At what point do you decide an appendix should be a reference?

rj

-- 
Robert Nagle

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org