[SSSD] [PATCH] 0001-Copy-edit SSSD-LDAP man page

Stephen Gallagher sgallagh at redhat.com
Thu Jan 14 13:08:27 UTC 2010


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 01/14/2010 07:55 AM, Stephen Gallagher wrote:
> On 01/14/2010 07:42 AM, Stephen Gallagher wrote:
>> On 01/13/2010 09:13 PM, David O'Brien wrote:
>>> Updated patch attached
>>> A couple of comments inline
> 
>>> /David
> 
>>> Stephen Gallagher wrote:
>>>> -----BEGIN PGP SIGNED MESSAGE-----
>>>> Hash: SHA1
>>>>
>>>> On 01/12/2010 06:58 PM, David O'Brien wrote:
>>>>> Stephen Gallagher wrote:
>>>>>> -----BEGIN PGP SIGNED MESSAGE-----
>>>>>> Hash: SHA1
>>>>>>
>>>>>> On 01/11/2010 09:33 PM, David O'Brien wrote:
>>>>>>> Fix typos, review grammar, apply a few standards.
>>>>>>>
>>>>>> - -            If there are no more servers to try, the back end as
>>>>>> a whole
>>>>>> +            If there are no more machines to try, the back end as a
>>>>>> whole
>>>>>>
>>>>>> I'm not sure I agree with this change. We're talking about the servers
>>>>>> that provide the authentication or identity data here. I'm not sure
>>>>>> "machines" is expressive enough.
>>>>> I wrestled with this for a while... the previous two paragraphs talk
>>>>> about "machines" and "services", while the first paras talk about
>>>>> servers. Other doc that I've looked at talks about "hosts". I think
>>>>> if you want to maintain "server" in the statement above, we should be
>>>>> using "server" and not "machine" throughout the section. What do  you
>>>>> think?
>>>>
>>>> I think we need to define our terms better.
> 
>>> agree 100%
> 
>>>  I read "server" in the
>>>> context of failover as the union of a machine and a service. A machine
>>>> may run several different services, and a service may run on several
>>>> different machines.
> 
>>> And not only in the context of failover. What's a web server? A machine
>>> + httpd? Same for a name server?
> 
>>>>
>>>> I propose we define these terms more accurately, and then fix the
>>>> sentence:
> 
>>> Consistent definition of terms is something we consistently wrestle with
>>> in ECS. We are working on a Style Guide to address this, however, so
>>> hopefully we're only getting better :-)
>>>>
>>>> If the service connection attempt fails, then only this particular
>>>> service is considered offline and the back end automatically switches
>>>> over to the next service.
>>>>
>>>> To instead read:
>>>> If the service connection attempt fails, then only this particular
>>>> service is considered offline and the back end automatically switches
>>>> over to the next server.
> 
>>> Fixed
> 
>>>>
>>>>
>>>> To summarize:
>>>> machine: physical or virtual host that can run a service
>>>> service: An LDAP directory server or Kerberos KDC, etc. running on a
>>>> machine
>>>> server: A machine/service pair.
>>>>
>>>>>>                              Some directory servers, for example Active
>>>>>> Directory,
>>>>>> - -                            might deliver the realm part of the UPN
>>>>>> lower case
>>>>>> - -                            which may cause the authentication to
>>>>>> fail.
>>>>>> Set this
>>>>>> - -                            option to a non-zero value, if you
>>>>>> want to
>>>>>> use an
>>>>>> - -                            upper case realm.
>>>>>> +                            might deliver the realm part of the UPN in
>>>>>> lower case,
>>>>>> +                            which might cause the authentication to
>>>>>> fail. Set this
>>>>>> +                            option to a non-zero value if you want to
>>>>>> use an
>>>>>> +                            upper-case realm.
>>>>>>
>>>>>> The existing description is out of date. "a non-zero value" should be
>>>>>> "true" now.
>>>>> Fixed.
>>>>>
>>>>>> Please try to stay within coding standards. You have extended several
>>>>>> lines beyond the 79-character limit. (This limit exists so that the
>>>>>> source files can be viewed easily in a standard 80-character terminal
>>>>>> window without wrapping or horizontal scrolling)
>>>>> This is what my question about formatting was attempting to address.
>>>>> I was aware my changes were outside the original format, but wondered
>>>>> if that was something I needed to address myself or something that
>>>>> got handled by xslt processing or what. (I'm used to our own
>>>>> publishing system, which does all that for us.)
>>>>> So far I haven't been able to get Kate to do the right thing, and I
>>>>> tried to download and install manedit a couple of times but that's
>>>>> not playing nice either (website appears to be dead). I use CSB so
>>>>> I'm a bit limited in what I have access to :-\
>>>>>
>>>>
>>>> Sorry, I was unclear on what you meant. You can format the XML documents
>>>> with any spacing you want... when processing it to turn it into the
>>>> final manpage, it handles all whitespace appropriately. As part of our
>>>> project's coding standard, however, line lengths should be limited to 79
>>>> characters unless completely unavoidable.
>>>>
>>>> Formatting the XML document is a manual process. Most text editors have
>>>> a way to display which column you are currently typing into, and many
>>>> have autowrap capabilities that can be set in the options.
>>>>
>>>> Gedit, for example, displays "Ln 1, col 32" in the lower righthand
>>>> corner of the editing window to keep track of this. I know Gedit is
>>>> available to you. Bonus points: it does XML syntax highlighting.
> 
>>> I have this in Kate (but I'm trying Gedit to see how I like it), but I'm
>>> also curious about was the auto-indent (or lack of it) once you get into
>>> sections, subsections, paras, etc. I guess this is the price I pay for
>>> being used to scripts, processing tools, etc., that do things for me :D
>>>>
>>>>>>
>>>>>> Since I know you're new to git, the process for amending a patch is as
>>>>>> follows (assuming that you do not have additional patches beyond this
>>>>>> one in your private repository):
>>>>>>
>>>>>> Make your new changes as if you were creating a new patch. When you go
>>>>>> to commit them to your private repository, use the command 'git commit
>>>>>> - --amend' This will merge your current changes into the last patch
>>>>>> committed to your tree.
>>>>> I'll do this when we sort the server/machine question, thanks.
>>>>>
>>>>>> If you have other patches in your repository after this one, that
>>>>>> requires a bit more massaging with a 'git rebase -i' command, and you
>>>>>> should probably catch someone in #freeipa to walk you through it the
>>>>>> first time.
>>>>> No more patches right now.
>>>>> Thanks for your help and patience.
>>>>>
>>>>>
>>>>
>>>>
>>>> - -- Stephen Gallagher
>>>> RHCE 804006346421761
>>>>
> 
> 
>> Ah, I forgot to add in my last review that we should change:
>> "the back end as a whole switches to offline mode for a certain period
>> of time." to
>> "the back end as a whole switches to offline mode. We will attempt to
>> reconnect online every 30 seconds."
> 
>> I will make this minor edit myself and push your changes. Thanks!
> 
>> Ack.
> 
> 
> 
> Here's my new version, slightly modified from what I said above.
> 

After off-list review, here's the final version, acked by myself and
David O'Brian.

- -- 
Stephen Gallagher
RHCE 804006346421761

Delivering value year after year.
Red Hat ranks #1 in value among software vendors.
http://www.redhat.com/promo/vendor/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/

iEYEARECAAYFAktPF0sACgkQeiVVYja6o6PtBwCeLvUyJEOTFKUz8MuRb7tPUu7c
SMUAn1sfyliLl4RXm+dDFxpXIUDOUK5y
=zt+q
-----END PGP SIGNATURE-----
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-Copy-edit-mainly-fixing-typos-and-English.patch
Type: text/x-patch
Size: 21174 bytes
Desc: not available
URL: <https://lists.fedorahosted.org/pipermail/sssd-devel/attachments/20100114/c729682d/attachment.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-Copy-edit-mainly-fixing-typos-and-English.patch.sig
Type: application/pgp-signature
Size: 72 bytes
Desc: not available
URL: <https://lists.fedorahosted.org/pipermail/sssd-devel/attachments/20100114/c729682d/attachment.sig>


More information about the sssd-devel mailing list