Date: Thu, 26 Oct 2006 12:11:26 -0700 From: Doug Barton <dougb@FreeBSD.org> To: Yar Tikhiy <yar@comp.chem.msu.su> Cc: freebsd-doc@FreeBSD.org Subject: Re: New article Message-ID: <4541085E.3010809@FreeBSD.org> In-Reply-To: <20061026165447.GC48810@comp.chem.msu.su> References: <20061015173531.GB31717@comp.chem.msu.su> <453D1D14.1060000@FreeBSD.org> <20061026165447.GC48810@comp.chem.msu.su>
index | next in thread | previous in thread | raw e-mail
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
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?4541085E.3010809>