On 4/24/06, Roland Illig <rillig@netbsd.org> wrote:
> Hiroki Sato wrote:
> > Jan Schaumann <jschauma@netmeister.org> wrote
> >   in <20060424131237.GB7626@netmeister.org>:
> >
> > js> Roland Illig <rillig@NetBSD.org> wrote:
> > js>
> > js> > I would like to have an additional attribute for the <varname> ta=
g, so
> > js> > that I can write <varname index=3D"yes">CONFIGURE_ARGS</varname>,=
 and the
> > js> > variable will automatically appear in the variable index (another
> > js> > appendix). From there, a backlink should go to the location where=
 the
> > js> > variable is used (for both the HTML and the PDF output). In the
> > js> > page-oriented output formats, the index should contain line numbe=
rs, and
> > js> > in the one-page HTML and the plain text formats, the index should
> > js> > contain the section number.
> > js> >
> > js> > Is that possible or do we need to switch to another documentation=
 format
> > js> > to do this?
> > js>
> > js> It is my understanding that this should be possible.  (Just as a si=
de
> > js> note, I believe that operations like this are what make the process=
ing
> > js> of the documents slow and resource intensive, as the entire documen=
t
> > js> tree needs to be processed to generate the index.)
> >
> >  Yes, possible.  Generating index is still not so resource intensive
> >  compared to the normal typeset process we are using now because
> >  it can also be done together with generating ToC or so.
> >  I think I will add this to my TODO list anyway.
> >
> >  BTW, should we have a complete reference manual for make variables
> >  in pkgsrc as an appendix?
>
> I think it was Julio who told me that this would make the text less
> readable, because the variables had to be ordered to some scheme, most
> probably alphabetic, or maybe by group. The latter does not make sense
> for an appendix, since the variables are already grouped properly in the
> various main chapters. That's why I want only an index, not a reference
> chapter.

Humm... I'm not sure about what I might have said in the past.  But
anyway: having an appendix seems reasonable if all it has is a list of
variable names and links to the real documentation -- that is, if is
simply a variable index.  The descriptions should not be in the
appendix itself, but rather in an appropriate section where there is
enough context to understand what the variable does from the correct
perspective.

--
Julio M. Merino Vidal <jmmv84@gmail.com>
The Julipedia - http://julipedia.blogspot.com/