Better paths in documentation

[Julien ÉLIE]

En réponse à Russ Allbery :
> We don't want to require that the person compiling INN have a recent
> Pod::Man to get man pages of good quality.  However, we can generate .8.in
> pages from the POD and then substitute in the paths at build time, and
> that's not a bad idea.

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.


> It's a fair bit of tedious work, though.  But
> certainly if you feel like tackling that, I won't say no!

As I am currently reading all of INN documentation, I can do that meanwhile.

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)?

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?


> docs/remctld.8: $(srcdir)/docs/remctld.8.in
>        sed 's%\(\\f(CI\)*\@sysconfdir\(\\fI\)*\@%$(sysconfdir)%' \
>            < $(srcdir)/docs/remctld.8.in > $@
>
> is the recipe that I've used with other packages to substitute paths into
> generated man pages.

Thanks for the sample.

-- 
Julien ÉLIE

« Oublie les injures, n'oublie jamais les bienfaits. »