New article

[Doug Barton]

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

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

3. In note 2 you might want to mention /etc/network.subr.

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.

5. In Section 4, note 4 you might want to expand your "Note:" 
regarding prefixing the variables with ${name}. You might also want to 
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.

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.

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.

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!

Doug

-- 

     This .signature sanitized for your protection