From owner-freebsd-rc@FreeBSD.ORG Mon Jul 1 22:30:55 2013 Return-Path: Delivered-To: freebsd-rc@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 88863230; Mon, 1 Jul 2013 22:30:55 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 3326B16F0; Mon, 1 Jul 2013 22:30:54 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.7/8.14.7) with ESMTP id r61MUsNd046447; Mon, 1 Jul 2013 16:30:54 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.7/8.14.7/Submit) with ESMTP id r61MUrP2046444; Mon, 1 Jul 2013 16:30:53 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Mon, 1 Jul 2013 16:30:53 -0600 (MDT) From: Warren Block To: Hiroki Sato Subject: Re: Proposal: multi-instance and self-contained rc.d script In-Reply-To: <20130702.062149.303421326784941070.hrs@allbsd.org> Message-ID: References: <20130701.062953.1443190655468739608.hrs@allbsd.org> <20130630221032.GB43309@stack.nl> <20130702.062149.303421326784941070.hrs@allbsd.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Mon, 01 Jul 2013 16:30:54 -0600 (MDT) Cc: freebsd-rc@FreeBSD.org X-BeenThere: freebsd-rc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Discussion related to /etc/rc.d design and implementation." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 01 Jul 2013 22:30:55 -0000 On Tue, 2 Jul 2013, Hiroki Sato wrote: > Warren Block wrote > in : > > 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.