Re: manpage : documenting /etc/default/foobar
On Sat, Jan 26, 2008 at 08:06:01PM +0100, Franklin PIAT wrote:
> I'm writing some manpages, and I wonder what's the current practice for
> documenting a file like in /etc/default/foobar.
>
> On my laptop [1], only /etc/default/rcS seems to have a manpage in the
> section 5.
As you note, I'm not sure that this is obviously common practice, but
IMO (speaking as the man-db maintainer) foobar(5) is clearly reasonable.
If there is another configuration file called 'foobar', it's probably in
the same package, and you can just document both in the same manual
page.
If you prefer, you can document it in the manual page for the program
instead. I think this is up to the maintainer's discretion. I would
probably only do this if the package is a fairly simple one consisting
of a single program and some configuration files; if it consists of
several programs, I would be strongly inclined to document the
configuration separately and insert cross-references in the program
documentation.
> The problem is that the filename is often the name of the
> package and/or the name of the binary.
This isn't a problem; you can have (say) both foobar(1) and foobar(5)
quite happily. man(1) has various documented ways to get at manual pages
that aren't the first one it finds.
Cheers,
--
Colin Watson [cjwatson@debian.org]
Reply to: