Date: Thu, 26 Oct 2006 20:54:47 +0400 From: Yar Tikhiy <yar@comp.chem.msu.su> To: Doug Barton <dougb@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: New article Message-ID: <20061026165447.GC48810@comp.chem.msu.su> In-Reply-To: <453D1D14.1060000@FreeBSD.org> References: <20061015173531.GB31717@comp.chem.msu.su> <453D1D14.1060000@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, Oct 23, 2006 at 12:50:44PM -0700, Doug Barton wrote: > Yar Tikhiy wrote: > >Hi folks, > > > >I wrote an article on our rc.d subsystem. Its draft in sgml and > >html is available at http://people.freebsd.org/~yar/rcng/ . It has > >been reviewed on freebsd-rc. Now I'd like to add it to our article > >collection. I see that I should commit the article itself, then > >update www/docs/books.sgml. What else? > > I would appreciate it if you'd also add a link to this article to the > sections of the handbook and the porter's handbook that refer to rc.d It's a very good idea, thanx! Done. > scripting. Your short name of rc-scripting is good. You could also > consider rc-scripts to save a couple bytes, but it's up to you. I'd committed it as rc-scripting just before your mail arrived :-) > I have a few suggestions: > > 1. In your first dummy script, you could write this: > > start_cmd="${name}_start" > > which makes copy and pasting of script elements easier. Done. > 2. In Section 3, note 1 that paragraph is still a little bit tough to > follow. I would simplify everything after "/etc/rc.d/dummy start" by > saying something like, "In order to be properly managed by the rc.d > system, these scripts need to be written using the /bin/sh language. > If you have a service or port that uses a binary, or a startup routine > written in another language, please install that element in > /usr/libexec (for the system) or /usr/local/libexec (for ports) and > call that with a /bin/sh script in the appropriate rc.d directory." OK, dropped the lengthy discussion of how to stuff a junk non-sh(1) script in rc.d. I didn't like it anyway. :-) Your wording looks better than mine. But finally I suggested sbin, not libexec, for strange startup programs because this follows the practice of having rndc, ntpdc, apachectl all in sbin. > 3. In note 2 you might want to mention /etc/network.subr. Done. > 4. In note 4 (and elsewhere) you refer to "methods" for rc.subr to > invoke. I'm not very comfortable with this term, and it sounds too C++ > to me. I would prefer the use of the term "function" which is both > literally true and closer to how sh scripting is usually described. > I'm not insisting that you change it, just stating a strong preference. I belive that the term "method" was adopted by the NetBSD folks. It's used all over rc.subr(8) manpage, and I just followed it. After all, the thing doesn't need to be a function because it's just a shell expression stored in a variable. I tried to use "handler" at first, but saw that "method" was already standard. > 5. In Section 4, note 4 you might want to expand your "Note:" > regarding prefixing the variables with ${name}. You might also want to Oops, failed to see how the ${name} issue applies to section 4, note 4. Could you provide an example? > include a note that the preferred style is that the name of the > script, the PROVIDE: in the script, the value of the name variable, > and the prefix for the rc.conf variables should all be the same. Done. > 6. In Section 6, note 1, including flags in command_args is not just a > bad idea, it's not allowed. It causes anything included in > ${name}_flags to be included twice, and is the source of a lot of > problems for users. It would be a good idea to expand on that point a > little. Perhaps I worded that paragraph poorly. I meant not ${name}_flags, but additional -foo flags the script may want to pass to $command, besides ${name}_flags. Probably I should use the term "options" instead. Just reworded the note. > 7. In the introduction to Section 7 you mention USE_RC_SUBR. That > might be a good place to link to the section in the Porter's Handbook > that covers its use. Done. > While this may seem like a lot of notes, I'd like to emphasize that > overall this is an excellent article, and very well written. Thank you > for contributing it! Thank you for your appreciation! I come to the idea that writing documentation can be a respected way to have fun, too! :-) -- Yar
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20061026165447.GC48810>