Better paths in documentation

Julien ÉLIE julien at
Sun Aug 19 18:55:07 UTC 2007

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
> 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 and 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


(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/
>        sed 's%\(\\f(CI\)*\@sysconfdir\(\\fI\)*\@%$(sysconfdir)%' \
>            < $(srcdir)/docs/ > $@
> 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. » 

More information about the inn-workers mailing list