New article

[Yar Tikhiy]

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