* 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.