GNU bug report logs - #68684
[PATCH] dictonary.el documentation

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 68684 in the body.
You can then email your comments to 68684 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] dictonary.el documentation
Date: Wed, 24 Jan 2024 02:15:12 -0800

[Message part 1 (text/plain, inline)]

Severity: wishlist

-------------------- Start of forwarded message --------------------
From: No Wayman <iarchivedmywholelife <at> gmail.com>
To: emacs-devel <at> gnu.org
Subject: [PATCH] dictonary.el documentation
Date: Tue, 23 Jan 2024 10:31:47 -0500

[Message part 2 (text/plain, attachment)]

[0001-lisp-net-dictionary.el-satisfy-checkdoc.patch (text/x-patch, attachment)]

[Message part 4 (text/plain, attachment)]

Message #8 received at 68684 <at> debbugs.gnu.org (full text, mbox):

From: Po Lu <luangruo <at> yahoo.com>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: torsten.hilbrich <at> gmx.net, 68684 <at> debbugs.gnu.org,
 iarchivedmywholelife <at> gmail.com
Subject: Re: bug#68684: [PATCH] dictonary.el documentation
Date: Wed, 24 Jan 2024 20:04:58 +0800

Stefan Kangas <stefankangas <at> gmail.com> writes:

> Subject: [PATCH] * lisp/net/dictionary.el: satisfy checkdoc
>
> (dictionary-tool-bar-map): add missing period
> (dictionary-process-popup-replies),
> (dictionary-read-definition),
> (dictionary-display-tooltip): rename ignored parameters
> (dictionary-tooltip-track-mouse): describe what function does, not just when
> (dictionary-switch-tooltip-mode): reword docstring in terms of ON parameter

Thanks.  Nowayman, we cannot install this as-is, since the formatting of
the commit message does not meet our standards.  Please capitalize the
first character in each sentence, punctuate sentences with periods
followed by two spaces, and either omit commas after the identifiers in
entries sharing a description or move such identifiers into a single
line and pair of parentheses, provided that such line totals fewer than
64 columns.

I find that a surprising number of individuals cannot produce correctly
formatted entries on the first attempt.  Is the layout of our
documentation part of the problem?  We should consider why the 124-odd
lines' worth of advice in CONTRIBUTE are being overlooked by most new
hands whose patches turn up in this list, and even some old ones,
because correcting improperly formatted patches individually gets old
fast.

Message #11 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Emanuel Berg <incal <at> dataswamp.org>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#68684: [PATCH] dictonary.el documentation
Date: Wed, 24 Jan 2024 13:20:34 +0100

Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text editors" wrote:

> I find that a surprising number of individuals cannot
> produce correctly formatted entries on the first attempt.
> Is the layout of our documentation part of the problem?

Reason one, that format isn't the cleanest one.

Compare to a really clean format, Bibtex, you see how really
clean it can be.

@book{operating-system-concepts,
  author    = {Abraham Silberschatz and Peter B Galvin},
  edition   = {4th},
  isbn      = {0-201-59292-4},
  pages     = {780},
  publisher = {Addison-Wesley},
  title     = {Operating System Concepts},
  year      = {1994}
}

Reason two is with 'git commit -a' you get a new Emacs
instance which is stressful and annoying and you don't have
everything you had one second ago which is even more annoying
as that is exactly what you need right now in the new
instance, so you often type it all manually which is even more
annoying if you have already typed it or something similar
many times under the same miserable regime.

-- 
underground experts united
https://dataswamp.org/~incal

Message #14 received at submit <at> debbugs.gnu.org (full text, mbox):

From: No Wayman <iarchivedmywholelife <at> gmail.com>
To: Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text
 editors" <bug-gnu-emacs <at> gnu.org>
Cc: Po Lu <luangruo <at> yahoo.com>, torsten.hilbrich <at> gmx.net, 68684 <at> debbugs.gnu.org,
 Stefan Kangas <stefankangas <at> gmail.com>
Subject: Re: bug#68684: [PATCH] dictonary.el documentation
Date: Wed, 24 Jan 2024 12:07:06 -0500

Po Lu via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs <at> gnu.org> writes:

> Stefan Kangas <stefankangas <at> gmail.com> writes:
>
>> Subject: [PATCH] * lisp/net/dictionary.el: satisfy checkdoc
>>
>> (dictionary-tool-bar-map): add missing period
>> (dictionary-process-popup-replies),
>> (dictionary-read-definition),
>> (dictionary-display-tooltip): rename ignored parameters
>> (dictionary-tooltip-track-mouse): describe what function does, not just when
>> (dictionary-switch-tooltip-mode): reword docstring in terms of ON parameter
 
> Thanks.  Nowayman, we cannot install this as-is, since the formatting of
> the commit message does not meet our standards.  Please capitalize the
> first character in each sentence, punctuate sentences with periods
> followed by two spaces, and either omit commas after the identifiers in
> entries sharing a description or move such identifiers into a single
> line and pair of parentheses, provided that such line totals fewer than
> 64 columns.

Patch offered as-is. Feel free to alter or discard.

Message #20 received at 68684 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Po Lu <luangruo <at> yahoo.com>
Cc: torsten.hilbrich <at> gmx.net, 68684 <at> debbugs.gnu.org,
 iarchivedmywholelife <at> gmail.com
Subject: Re: bug#68684: [PATCH] dictonary.el documentation
Date: Thu, 25 Jan 2024 15:29:33 -0800

Po Lu <luangruo <at> yahoo.com> writes:

> Thanks.  Nowayman, we cannot install this as-is, since the formatting
> of the commit message does not meet our standards.

Well, I'm happy to fix it up and install it.  I assume you reviewed it,
so do you see any other problems with the patch?

Skimming it very quickly, it looked like a fine contribution to me.

> fewer than 64 columns.

ChangeLogs should fit within 80 columns prefixed with a tab, so that
should be 72 columns.

> I find that a surprising number of individuals cannot produce
> correctly formatted entries on the first attempt.  Is the layout of
> our documentation part of the problem?

I think it's the format that's the problem.  It's archaic and foreign to
most developers.  There's not much to do about it, I think.

> correcting improperly formatted patches individually gets old fast.

I find that it's generally more time-effective to just fix up patches
when installing them, and then say something like:

    Installed.  I changed the commit message to better fit our
    conventions, please have a look for next time.

Usually, people will be more appreciative of that than long lists
enumerating every dot and comma that they got wrong.

Message #25 received at 68684-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: 68684-done <at> debbugs.gnu.org
Cc: torsten.hilbrich <at> gmx.net, iarchivedmywholelife <at> gmail.com
Subject: Re: bug#68684: [PATCH] dictonary.el documentation
Date: Tue, 24 Dec 2024 03:15:14 +0000

Version: 31.1

Stefan Kangas <stefankangas <at> gmail.com> writes:

> Severity: wishlist
>
> -------------------- Start of forwarded message --------------------
> From: No Wayman <iarchivedmywholelife <at> gmail.com>
> To: emacs-devel <at> gnu.org
> Subject: [PATCH] dictonary.el documentation
> Date: Tue, 23 Jan 2024 10:31:47 -0500
>

Pushed to master, thanks.  Closing.

>
> From 02c4f83176ab9fb1afdb3962f9b90023961ebaaa Mon Sep 17 00:00:00 2001
> From: Nicholas Vollmer <iarchivedmywholelife <at> gmail.com>
> Date: Tue, 23 Jan 2024 09:39:02 -0500
> Subject: [PATCH] * lisp/net/dictionary.el: satisfy checkdoc
>
> (dictionary-tool-bar-map): add missing period
> (dictionary-process-popup-replies),
> (dictionary-read-definition),
> (dictionary-display-tooltip): rename ignored parameters
> (dictionary-tooltip-track-mouse): describe what function does, not just when
> (dictionary-switch-tooltip-mode): reword docstring in terms of ON parameter
> ---
>  lisp/net/dictionary.el | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/lisp/net/dictionary.el b/lisp/net/dictionary.el
> index 1981b757017..4f4710a2920 100644
> --- a/lisp/net/dictionary.el
> +++ b/lisp/net/dictionary.el
> @@ -461,7 +461,7 @@ dictionary-tool-bar-map
>                                     :vert-only t
>                                     :help "Go backwards in history.")
>      map)
> -  "Like the default `tool-bar-map', but with additions for Dictionary mode")
> +  "Like the default `tool-bar-map', but with additions for Dictionary mode.")
>
>  ;;;###autoload
>  (define-derived-mode dictionary-mode special-mode "Dictionary"
> @@ -1316,7 +1316,7 @@ dictionary-popup-matching-words
>  			  dictionary-default-popup-strategy
>  			  'dictionary-process-popup-replies))
>
> -(defun dictionary-process-popup-replies (&ignore)
> +(defun dictionary-process-popup-replies (_)
>    (let ((list (dictionary-simple-split-string (dictionary-read-answer) "\n+")))
>
>      (let ((result (mapcar (lambda (item)
> @@ -1360,7 +1360,7 @@ dictionary-definition
>  	(dictionary-do-search word dictionary 'dictionary-read-definition t))
>      nil))
>
> -(defun dictionary-read-definition (&ignore)
> +(defun dictionary-read-definition (_)
>    (let ((list (dictionary-simple-split-string (dictionary-read-answer) "\n+")))
>      (mapconcat #'identity (cdr list) "\n")))
>
> @@ -1381,7 +1381,7 @@ dictionary-word-at-mouse-event
>  (defvar dictionary-tooltip-mouse-event nil
>    "Event that triggered the tooltip mode.")
>
> -(defun dictionary-display-tooltip (&ignore)
> +(defun dictionary-display-tooltip (_)
>    "Search the current word in the `dictionary-tooltip-dictionary'."
>    (interactive "e")
>    (if (and dictionary-tooltip-mode dictionary-tooltip-dictionary)
> @@ -1396,7 +1396,7 @@ dictionary-display-tooltip
>      nil))
>
>  (defun dictionary-tooltip-track-mouse (event)
> -  "Called whenever a dictionary tooltip display is about to be triggered."
> +  "Hide current tooltip and setup next tooltip in response to mouse movement EVENT."
>    (interactive "e")
>    (tooltip-hide)
>    (when dictionary-tooltip-mode
> @@ -1404,7 +1404,7 @@ dictionary-tooltip-track-mouse
>      (tooltip-start-delayed-tip)))
>
>  (defun dictionary-switch-tooltip-mode (on)
> -  "Turn off or on support for the dictionary tooltip mode.
> +  "Turn dictionary tooltip mode off or ON.
>
>  It is normally internally called with 1 to enable support for the
>  tooltip mode.  The hook function will check the value of the

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.