Better paths in documentation

[Russ Allbery]

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

> I wonder whether it would not be useful to put accurate paths
> in POD documentation.  That is to say having documentation
> which requires the use of such paths in doc/pod/page.pod.in
> in order to put the right paths inside, and not generic ones.

> For instance, instead of having
>     su news -c /usr/local/news/bin/rc.news
> in checklist.pod, we would have
>     su news -c @bindir@/rc.news
> in checklist.pod.in.

> It is just an idea and maybe there are more disadvantages than
> advantages to do so.  Any opinion about that?

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.  It's a fair bit of tedious work, though.  But
certainly if you feel like tackling that, I won't say no!

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.

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