Proposal: multi-instance and self-contained rc.d script

[Warren Block]

On Tue, 2 Jul 2013, Hiroki Sato wrote:

> Warren Block <wblock at wonkity.com> wrote
>  in <alpine.BSF.2.00.1307010624530.29556 at wonkity.com>:
>
> wb> On Mon, 1 Jul 2013, Jilles Tjoelker wrote:
> wb>
> wb> > On Mon, Jul 01, 2013 at 06:29:53AM +0900, Hiroki Sato wrote:
> wb> ...
> wb> >>    b) Make rc.d/foo always have rc.d/foo(8) manual page.
> wb> >
> wb> > However, I don't like another set of manual pages.
> wb>
> wb> They could be autogenerated by reading comments and variable values in
> wb> the rc.d scripts.  Of course the rc.d scripts would have to contain
> wb> that information.  At least it would be in the same file, helping to
> wb> keep the doc in sync with the script.  This is not to suggest a full
> wb> man page in the script, just a short text summary along with variables
> wb> that may be used.
> wb>
> wb> '/etc/rc.d/routed manpage' would return the generated mdoc code.
> wb> '/etc/rc.d/routed help' could pipe that output to man.
> wb>
> wb> What filenames or section would be used for the generated man pages?
> wb> routed(8) already exists, and "rc.d/routed.8" has problems both as a
> wb> filename and an argument to man(1).
>
> I do not think manual page autogeneration is simple becuase what we
> need is not just for one-line comments about each variable.  The goal
> of adding manual pages is a replacement of rc.conf(5) manual page.
> It includes examples and usage of complex rc.d scripts like
> rc.d/netif.  If we want an option to show comments for variables,
> adding the third parameter into set_rcvar like this:
>
>  set_rcvar program /sbin/routed "Pathname of routing daemon"
>
> makes "rc.d/routed rcvar" possible to show them as
>
>  routed_program="/sbin/routed"   # Pathname of routing daemon (default: "/sbin/routed")

I agree that full man pages give a lot more capabilities.

> wb> routed(8) already exists, and "rc.d/routed.8" has problems both as a
> wb> filename and an argument to man(1).
>
> What is the problem with the name rc.d/routed(8)?

If you mean to add an rc.d directory to /usr/share/man/man8, then that 
will work.  I thought you meant creating filenames with embedded 
slashes.