all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Re: trunk r116610: Fix docstring typos.
       [not found] <E1WJNLT-0002L5-Eb@vcs.savannah.gnu.org>
@ 2014-02-28 19:21 ` Glenn Morris
  2014-02-28 20:17   ` Juanma Barranquero
  0 siblings, 1 reply; 6+ messages in thread
From: Glenn Morris @ 2014-02-28 19:21 UTC (permalink / raw)
  To: Juanma Barranquero; +Cc: emacs-devel

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?



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: trunk r116610: Fix docstring typos.
  2014-02-28 19:21 ` trunk r116610: Fix docstring typos Glenn Morris
@ 2014-02-28 20:17   ` Juanma Barranquero
  2014-03-02  2:43     ` Xue Fuqiao
  2014-03-02  3:10     ` Glenn Morris
  0 siblings, 2 replies; 6+ messages in thread
From: Juanma Barranquero @ 2014-02-28 20:17 UTC (permalink / raw)
  To: Glenn Morris; +Cc: Emacs developers

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



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: trunk r116610: Fix docstring typos.
  2014-02-28 20:17   ` Juanma Barranquero
@ 2014-03-02  2:43     ` Xue Fuqiao
  2014-03-02  3:10     ` Glenn Morris
  1 sibling, 0 replies; 6+ messages in thread
From: Xue Fuqiao @ 2014-03-02  2:43 UTC (permalink / raw)
  To: emacs-devel

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/




^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: trunk r116610: Fix docstring typos.
  2014-02-28 20:17   ` Juanma Barranquero
  2014-03-02  2:43     ` Xue Fuqiao
@ 2014-03-02  3:10     ` Glenn Morris
  2014-03-02  4:08       ` Juanma Barranquero
  1 sibling, 1 reply; 6+ messages in thread
From: Glenn Morris @ 2014-03-02  3:10 UTC (permalink / raw)
  To: Juanma Barranquero; +Cc: Emacs developers

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.



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: trunk r116610: Fix docstring typos.
  2014-03-02  3:10     ` Glenn Morris
@ 2014-03-02  4:08       ` Juanma Barranquero
  2014-03-04  3:33         ` Stefan Monnier
  0 siblings, 1 reply; 6+ messages in thread
From: Juanma Barranquero @ 2014-03-02  4:08 UTC (permalink / raw)
  To: Glenn Morris; +Cc: Emacs developers

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



^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: trunk r116610: Fix docstring typos.
  2014-03-02  4:08       ` Juanma Barranquero
@ 2014-03-04  3:33         ` Stefan Monnier
  0 siblings, 0 replies; 6+ messages in thread
From: Stefan Monnier @ 2014-03-04  3:33 UTC (permalink / raw)
  To: Juanma Barranquero; +Cc: Emacs developers

> 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



^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2014-03-04  3:33 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <E1WJNLT-0002L5-Eb@vcs.savannah.gnu.org>
2014-02-28 19:21 ` trunk r116610: Fix docstring typos Glenn Morris
2014-02-28 20:17   ` Juanma Barranquero
2014-03-02  2:43     ` Xue Fuqiao
2014-03-02  3:10     ` Glenn Morris
2014-03-02  4:08       ` Juanma Barranquero
2014-03-04  3:33         ` Stefan Monnier

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.