OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [docbook] Automatically create index of commands

Hi David,

It might not be the easiest route, but I think the way to do it is to
use the <reference> and <refentry> tags in DocBook.  Each command would
become a <refentry>, and you could then group common commands within
specific <reference>s, each with its own title.  For example, we do this
for functions in our "Gamma Manual", as seen here:

(scroll down about 1/2 way)

The way to get a short description is to put a <refnamediv> in each
<refentry>, with a <refpurpose> to hold the description.

The output for all this does not appear in the index, as you have
requested, but rather in the table of contents.  However, you can also
auto-generate an index where everything is organized strictly
alphabetically, which appears at the back of the book.  Thus you get the
best of both worlds.  To my understanding, most technical manuals are
organized in this way.  

As I said above, it means a fair amount of work to mark up your text
like this, but you do gain quite a bit.  Depending on the number of
commands to mark up, you might want to create some kind of script or
macro to do the heavy lifting.

Hope that helps.



On Wed, 2003-08-27 at 12:06, David N. Welton wrote:
> Hi, I'm attempting something a little bit more complicated with my
> docbook work...  My application is growing, and new commands are being
> added.  Where a page with all the commands listed was once enough, it
> now seems that an index based on concepts would be useful to users,
> something like this:
> http://tmml.sourceforge.net/doc/tcl/index.html
> At the moment, I have a series of commands described like:
>     <variablelist>
>       <varlistentry>
> 	<term>
> 	  <cmdsynopsis>
> 	    <command>
> 	      var
> 	    </command>
> 	    <group choice="req">
> 	      <arg>get</arg>
> 	      <arg>list</arg>
> 	      <arg>exists</arg>
> 	      <arg>number</arg>
> 	      <arg>all</arg>
> 	    </group>
> 	  </cmdsynopsis>
> 	</term>
> 	<listitem>
> 	  <para>
> 	    The <command>var</command> command retrieves information
> 	    about GET or POST variables sent to the script via client
> 	    request.  It treats both GET and POST variables the same,
> 	    regardless of their origin.  Note that there are two
> 	    additional forms of <command>var</command>:
> 	    <command>var_qs</command> and <command>var_post</command>.
> 	    These two restrict the retrieval of information to
> 	    parameters arriving via the querystring
> 	    (?foo=bar&amp;bee=bop) or POSTing, respectively.
> 	  </para>
> I would like to have an index of all the commands in the list, and I'm
> wondering if there is any way to do that without some very heavy XSL
> hacking - i.e. something provided for in standard DocBook.
> Incidentally, I suppose it also means that I need some markup to
> describe where each command should be indexed, and a 'short
> description' for the index.  Suggestions for those?
> Thanks in advance for any ideas...  I've wallowed through the docs
> some, but don't see anything that seems to be the right fit.
> Hopefully, I just missed it or didn't quite see how to use it...
> Thankyou,
Robert McIlvride, Cogent Real-Time Systems, Inc.
robert@cogent.ca  (888) 628-2028  www.cogent.ca

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]