Re: trunk r116610: Fix docstring typos.

Re: trunk r116610: Fix docstring typos.

[Glenn Morris]

Juanma Barranquero wrote:

>   Fix docstring typos.
[...]
> -  "Keymap used in `finder-mode'.")
> +  "Keymap used in Finder mode.")

It was not a typo that I used a form that would give a hyperlink.
Why change it?

Re: trunk r116610: Fix docstring typos.

[Juanma Barranquero]

On Fri, Feb 28, 2014 at 8:21 PM, Glenn Morris <rgm@gnu.org> wrote:
> Juanma Barranquero wrote:
>
>>   Fix docstring typos.
> [...]
>> -  "Keymap used in `finder-mode'.")
>> +  "Keymap used in Finder mode.")
>
> It was not a typo that I used a form that would give a hyperlink.
> Why change it?

Because of the way it is redacted, it is a reference to the *mode*,
not the function. If you'd written "Keymaps used when running
`finder-mode'" (or something like that) I wouldn't have changed it.
I've done that with many docstrings where they talked about
"something-mode" and they were refering generically to the mode, and
not specifically the function.

If you feel strongly about having these hyperlinks, then revert the
change, but I'd suggest rewriting the docstring to emphasize what is
being talked about.

    J

Re: trunk r116610: Fix docstring typos.

[Xue Fuqiao]

Juanma Barranquero <lekktu@gmail.com> writes:
>> Juanma Barranquero wrote:
>>
>>>   Fix docstring typos.
>> [...]
>>> -  "Keymap used in `finder-mode'.")
>>> +  "Keymap used in Finder mode.")
>>
>> It was not a typo that I used a form that would give a hyperlink.
>> Why change it?
>
> Because of the way it is redacted, it is a reference to the *mode*,
> not the function. If you'd written "Keymaps used when running
> `finder-mode'" (or something like that) I wouldn't have changed it.
> I've done that with many docstrings where they talked about
> "something-mode" and they were refering generically to the mode, and
> not specifically the function.

Fair enough.  Maybe we should mention it in doc/lispref/tips.texi?

-- 
http://www.gnu.org/software/emacs/

Re: trunk r116610: Fix docstring typos.

[Glenn Morris]

Juanma Barranquero wrote:

>>> -  "Keymap used in `finder-mode'.")
>>> +  "Keymap used in Finder mode.")
>>
>> It was not a typo that I used a form that would give a hyperlink.
>> Why change it?
>
> Because of the way it is redacted, it is a reference to the *mode*,
> not the function. If you'd written "Keymaps used when running
> `finder-mode'" (or something like that) I wouldn't have changed it.

I don't agree with the (IMO tenuous) distinction that you are trying to
make. finder-mode is a function, it uses finder-mode-map, what I wrote
was not a typo. I found the old form with the hyperlink more useful.

Re: trunk r116610: Fix docstring typos.

[Juanma Barranquero]

On Sun, Mar 2, 2014 at 4:10 AM, Glenn Morris <rgm@gnu.org> wrote:

> I don't agree with the (IMO tenuous) distinction that you are trying to
> make.

Well, I don't find it tenuous at all. A docstring, for example, that
says "When the buffer is in `foo-mode' do that" does not make much
sense. The buffer cannot be in foo-mode, it can be in Foo mode, which
is activated by function foo-mode.

But I'm neither able nor wanting to impose my opinion.

> what I wrote was not a typo.

I often write "Docstring typo fix" as a shorthand. Sometimes they are
typos, sometimes infelicities, sometimes just whitespace changes.
Please don't be offended by my word choice in ChangeLog entries.

> I found the old form with the hyperlink more useful.

Then, by all means, change it to your liking. Not worth discussing
about such a trivial matter, IMO.

Thanks,

    Juanma

Re: trunk r116610: Fix docstring typos.

[Stefan Monnier]

> Well, I don't find it tenuous at all. A docstring, for example, that
> says "When the buffer is in `foo-mode' do that" does not make much
> sense. The buffer cannot be in foo-mode, it can be in Foo mode, which
> is activated by function foo-mode.

It's indeed an abuse: saying "When the buffer is in `tehrth'" wouldn't
make sense (when tehrth is the function that enabled Foo mode).
But since the function that activates Foo mode is called `foo-mode'
instead of `tehrth', the abusive "When the buffer is in `foo-mode'" is
clear enough.  I don't know of anyone who ever got confused by it.
If you want to rewrite them differently, that's fine, but removing the
hyperlink does not seem like a good way to fix the very minor abuse.


        Stefan