bug#68684: [PATCH] dictonary.el documentation

bug#68684: [PATCH] dictonary.el documentation

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 244 bytes --]

Severity: wishlist

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

[-- Attachment #2: Type: text/plain, Size: 652 bytes --]


I've attached a patch for what I think are a few improvements to 
dictionary.el's documentation.

There are still a handful of undocumented functions/commands.
The commentary section also redirects to an external source, which 
is not very helpful:

;; You can find more information in the README file of the GitHub
;; repository https://github.com/myrkr/dictionary-el

I bumped into all this when trying out dictionary-tooltip-mode.
I thought "oh, cool", enabled the mode, then...nothing happened.
That's due to the dictionary-tooltip-dictionary defaulting to nil. 
Perhaps this user option could default to 
dictionary-default-dictionary instead. 


[-- Attachment #3: 0001-lisp-net-dictionary.el-satisfy-checkdoc.patch --]
[-- Type: text/x-patch, Size: 3022 bytes --]

From 02c4f83176ab9fb1afdb3962f9b90023961ebaaa Mon Sep 17 00:00:00 2001
From: Nicholas Vollmer <iarchivedmywholelife@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
-- 
2.43.0


[-- Attachment #4: Type: text/plain, Size: 67 bytes --]

-------------------- End of forwarded message --------------------

bug#68684: [PATCH] dictonary.el documentation

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Stefan Kangas <stefankangas@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.

bug#68684: [PATCH] dictonary.el documentation

[Emanuel Berg]

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

bug#68684: [PATCH] dictonary.el documentation

[No Wayman]

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

> Stefan Kangas <stefankangas@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.

bug#68684: [PATCH] dictonary.el documentation

[Stefan Kangas]

Po Lu <luangruo@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.

bug#68684: [PATCH] dictonary.el documentation

[Stefan Kangas]

Version: 31.1

Stefan Kangas <stefankangas@gmail.com> writes:

> Severity: wishlist
>
> -------------------- Start of forwarded message --------------------
> From: No Wayman <iarchivedmywholelife@gmail.com>
> To: emacs-devel@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@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