New article

[Doug Barton]

Note, I'm snipping the bits where we agree for brevity.

Yar Tikhiy wrote:

> I'd committed it as rc-scripting just before your mail arrived :-)

Fair enough.

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

No problem. Your reasoning is sound.

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

Ewww, ick! :)  I looked in Luke's original paper and didn't find it, 
but if that's the convention, so be it.

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

It's the issue I describe below. Prefixing global (e.g., rc.conf) 
variables with the value of $name is not just a good idea, it's 
mandatory.

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

Makes more sense now, thanks.

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

It's well deserved. :)

> I come to the idea that writing
> documentation can be a respected way to have fun, too! :-)

Great, now spread the word! Seriously though, I find that I am forced 
to a greater understanding of the topic when I attempt to document 
something, so it's not just fun and useful to our users, it can help 
you as a developer as well. Thanks for taking the plunge!

Doug

-- 

     This .signature sanitized for your protection