Better paths in documentation

[Russ Allbery]

Julien ÉLIE <julien at trigofacile.com> writes:

> All right.
> By the way, there is a little problem with pgpverify.1 and perl-nocem.8
> because both of them are always regenerated at build time (indeed, they
> come from pgpverify.in and perl-nocem.in so they change and documentation
> is regenerated for those two scripts).

> Their man pages should perhaps be generated from the .in files.

Yes, they should be generated from the .in files.

> Do you reckon that stuff like I<pathetc> should be kept or converted to
> the right path (which would perhaps speak better to the reader)?

Anything that can be configured in inn.conf should probably still use the
inn.conf option names.

> And do you think that a "FILES" section should be added to POD
> documentation when needed?  For instance, we have in perl-nocem:

> %%%
> =head1 FILES

> /usr/local/news/bin/perl-nocem
> /usr/local/news/etc/nocem.ctl
> /usr/local/news/etc/pgp/ncmring.gpg
> %%%

> (which could also use @bindir@ and @PATHETC@)

> And is it the best format or should it be F<...>ied or with four spaces
> before each line?

It's a good idea to document the additional control and data files used,
using the files syntax of:

=head1 FILES

=over 4

=item F</usr/local/news/etc/nocem.ctl>

Description of what the file is for.

=back

Lots of work, but it's always helpful documentation to have.

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>

    Please send questions to the list rather than mailing me directly.
     <http://www.eyrie.org/~eagle/faqs/questions.html> explains why.