Re: [avr-libc-dev] doxygen.config upgrade; man pages

[Theodore A. Roth]

On Wed, 14 Aug 2002, Joerg Wunsch wrote:

:) > Any objections to updating the doxy config file for 1.2.17?
:)
:) What exactly needs updating?
:)
:) I've been using your doxygen.config with both, 1.2.16 and 1.2.17,
:) and so far didn't notice problems.
:)
:) Anyway, yes, you can safely go ahead and update things there.

There wasn't much to update. It only added 2 or 3 new config items, so I
already updated it.

:)
:) Btw., i've been playing with installation options for the manual
:) pages, so this will happen some day, too.  Right now, i'm unhappy with
:) some of the pages (particularly those generated from the .dox files),
:) and would like to find a way to convert the main page into something
:) like a global avr_libc man page.

Feel free to do that. Hmmm... I wonder if you could flag things to be
included or excluded from the man page output?? I seem to remember seeing
something like conditionals in the doxy statements.

:)
:) Instead of prepending avr_ before each page name, i'm now more
:) inclined to just install the entire man page tree under
:) ${PREFIX}/share/doc/avr-libc/man, so people need to include this
:) directory into their ${MANPATH}.  OTOH, this offers the option to also
:) create man page links for each topic, so you can say "man cbi" to get
:) the documentation for the cbi() macro.  Or, you can say
:) "env MANPATH=${PREFIX}/share/doc/avr-libc/man xman&" to get the Xman
:) right for avr-libc. ;-)

Well, in my experience, having man pages in a non-standard place poses two
problems:

  - users will not even know about it or see it if they don't know about
    the $MANPATH env var.

  - `man -k` will be incomplete (at least on the redhat) unless the admin
    adds that path to whatever dirs makewhatis looks at.

:)
:) I don't like the version number in the docs installation directory.
:) We cannot have multiple instances of avr-libc installed by the same
:) time (since the installed libs would overwrite each other), so there's
:) IMHO not much point in versionizing the docs directory.

I don't think it hurts any thing by having it. It does let you know,
though, if the docs you are looking at are stale. Also, there's no
other place I know off where you can get the version number of the libc
which is installed on the system (This could be done in a header or
something though). Thus, there's no strong argument for changing it
(except that you don't like it ;-) and a few weak arguments for keeping it
as is. I'd say leave it for now.

Ted Roth