On 05/26/2010 03:20 AM, David O'Brien wrote:
ok, in this case I'd be more inclined to write, "If you use krb5 as the
authentication provider in an SSSD domain,..." (rather than using the
"key=value" format) because the tone of these types of passages is
slightly more conversational. Here I tend to steer away from "if
option=value and bool=true then set x=10". Easy to read and understand
if you deal with it on a daily basis, but I don't think that's the
primary audience of man pages and definitely not user doc.
Oh, I agree. I was just using shorthand above :)
>
>> "... the following options must be used."
>> - Is krb5_kpasswd an exception to this? That is, if the change
>> password service *is* running on the KDC, then there is no reason or
>> requirement to define alternative servers, right? In the example that I
>> have in the user doc (see bottom of page), isn't this defined as follows:
>>
>
> This is not a mandatory option. I think we probably want to change that
> sentence to "the following options MAY be used". There's actually a
fair
> amount of changes we probably need to make to the manpages. I'll try to
> list the important things below:
Should I wait for the appropriate person to make the required changes to
the man pages (from a technical perspective) so that I can then review
them from an English and readability angle? That will also reduce the
number of times I reproduce errors, etc., in the man pages in the user doc.
Yeah, I think it's probably a good idea to open a ticket to have
engineering go through that for accuracy, and then have you wordsmith
it. Could you open an upstream Trac ticket and assign it to Jakub, please?
Lastly, for all those options with "standard" or
"sensible" defaults,
how do I find out what they are?
The manpages should already list defaults for any that have them. If it
has a default, engineering has vetted it as either "standard" (where
such exists) or "sensible" (where no standard is written) :)
--
Stephen Gallagher
RHCE 804006346421761
Delivering value year after year.
Red Hat ranks #1 in value among software vendors.
http://www.redhat.com/promo/vendor/