bug#35163: 25.1; `narrow-to-region' docstring no mention of args

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

25.1; `narrow-to-region' docstring no mention of args

The `narrow-to-region' docstring does not
mention its arguments as is the norm. And it
makes sense, often the first thing I do when
I bring up the help buffer for a function is to
search for a particular argument name to see
what it does.



In GNU Emacs 25.1.1 (arm-unknown-linux-gnueabihf, GTK+ Version 3.22.11)
 of 2017-09-16, modified by Debian built on bm-wb-02
System Description:	Raspbian GNU/Linux 9.8 (stretch)

Configured using:
 'configure --build arm-linux-gnueabihf
 --prefix=/usr --sharedstatedir=/var/lib
 --libexecdir=/usr/lib --localstatedir=/var/lib
 --infodir=/usr/share/info
 --mandir=/usr/share/man --with-pop=yes
 --enable-locallisppath=/etc/emacs25:/etc/emacs:/usr/local/share/emacs/25.1/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/25.1/site-lisp:/usr/share/emacs/site-lisp
 --with-sound=alsa --build arm-linux-gnueabihf
 --prefix=/usr --sharedstatedir=/var/lib
 --libexecdir=/usr/lib --localstatedir=/var/lib
 --infodir=/usr/share/info
 --mandir=/usr/share/man --with-pop=yes
 --enable-locallisppath=/etc/emacs25:/etc/emacs:/usr/local/share/emacs/25.1/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/25.1/site-lisp:/usr/share/emacs/site-lisp
 --with-sound=alsa --with-x=yes
 --with-x-toolkit=gtk3
 --with-toolkit-scroll-bars 'CFLAGS=-g -O2
 -fdebug-prefix-map=/build/emacs25-pkwV6G/emacs25-25.1+1=.
 -fstack-protector-strong -Wformat
 -Werror=format-security -Wall'
 'CPPFLAGS=-Wdate-time -D_FORTIFY_SOURCE=2'
 LDFLAGS=-Wl,-z,relro'

Configured features:
XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK SOUND
GPM DBUS GCONF GSETTINGS NOTIFY ACL LIBSELINUX
GNUTLS LIBXML2 FREETYPE M17N_FLT LIBOTF XFT
ZLIB TOOLKIT_SCROLL_BARS GTK3 X11

Important settings:
  value of $LANG: en_GB.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Fundamental

Minor modes in effect:
  show-paren-mode: t
  shell-dirtrack-mode: t
  erc-list-mode: t
  erc-menu-mode: t
  erc-autojoin-mode: t
  erc-ring-mode: t
  erc-networks-mode: t
  erc-pcomplete-mode: t
  erc-match-mode: t
  erc-button-mode: t
  erc-fill-mode: t
  erc-stamp-mode: t
  erc-netsplit-mode: t
  erc-irccontrols-mode: t
  erc-noncommands-mode: t
  erc-move-to-prompt-mode: t
  erc-readonly-mode: t
  erc-scrolltobottom-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-compression-mode: t
  transient-mark-mode: t

Recent messages:
scroll-up-1: Beginning of buffer [6 times]
 ...
 o-)
Saving file /home/incal/DO_THIS...
Wrote /home/incal/DO_THIS
Type "q" to restore previous buffer.
 hit: 123
 This is the one occurrence. [2 times]
Quit [2 times]
Mark set

Load-path shadows:
/usr/share/emacs/25.1/site-lisp/debian-startup hides /usr/share/emacs/site-lisp/debian-startup
/usr/share/emacs25/site-lisp/flim/md4 hides /usr/share/emacs/25.1/lisp/md4
/usr/share/emacs25/site-lisp/flim/hex-util hides /usr/share/emacs/25.1/lisp/hex-util
~/.emacs.d/lisp/abbrev hides /usr/share/emacs/25.1/lisp/abbrev
~/.emacs.d/emacs-init/gnus/server hides /usr/share/emacs/25.1/lisp/server
/usr/share/emacs25/site-lisp/flim/sasl-ntlm hides /usr/share/emacs/25.1/lisp/net/sasl-ntlm
/usr/share/emacs25/site-lisp/flim/sasl-cram hides /usr/share/emacs/25.1/lisp/net/sasl-cram
/usr/share/emacs25/site-lisp/flim/ntlm hides /usr/share/emacs/25.1/lisp/net/ntlm
/usr/share/emacs25/site-lisp/flim/sasl hides /usr/share/emacs/25.1/lisp/net/sasl
/usr/share/emacs25/site-lisp/flim/hmac-def hides /usr/share/emacs/25.1/lisp/net/hmac-def
/usr/share/emacs25/site-lisp/flim/hmac-md5 hides /usr/share/emacs/25.1/lisp/net/hmac-md5
/usr/share/emacs25/site-lisp/flim/sasl-digest hides /usr/share/emacs/25.1/lisp/net/sasl-digest
/home/incal/.emacs.d/elpa/seq-2.20/seq hides /usr/share/emacs/25.1/lisp/emacs-lisp/seq
/home/incal/.emacs.d/elpa/let-alist-1.0.5/let-alist hides /usr/share/emacs/25.1/lisp/emacs-lisp/let-alist

Features:
(shadow emacsbug conf-mode mm-archive sh-script
smie executable mailalias w3m-cookie canlock
url-http url-gw url-cache url-auth mail-extr qp
gnus-async gnus-bcklg gnus-ml make-mode
eieio-opt speedbar sb-image ezimage dframe
find-func whitespace cus-edit cus-start
cus-load tabify nnir cursor-sensor pop3 nndraft
nnmh nnml network-stream nsm starttls
gnus-agent nnvirtual nntp gnus-cache w3m-filter
ffap paren xsel w3m-form
google-translate-core-ui ido
google-translate-core google-translate-tk url
url-proxy url-privacy url-expand url-methods
url-history url-cookie url-domsuf url-util
url-parse url-vars json map lpr tramp-sh term
disp-table ehelp my-faces t-mouse man tex-mode
iterate-files seq-24 isbn my-bibtex bibtex
slime-presentations slime-repl slime-parse
bridge nroff-mode sgml-mode cobol-mode ada-mode
which-func imenu align find-file checkdoc
cc-mode cc-fonts cc-guess cc-menus cc-cmds
cc-styles cc-align cc-engine cc-vars cc-defs
guile summary message-my moggle mail-to-many
mail smtpmail sendmail font-lock-add
global-keys yank-my wrap-search w3m-unisearch
w3m-search spell-new ispell sort-my sort slime
etags xref project arc-mode archive-mode
noutline outline easy-mmode hyperspec shell-cli
revert-buffer-my lisp-new ielm kill keys
help-new debug apropos dired-x compile-my
mode-line compile article gnus-cite dl
bookmarks w3m-bookmark file-write-to erc-my
fill-new quit gnus-my group group-summary
gnus-srvr gnus-score score-mode gnus-msg
gnus-art mm-uu mml2015 mm-view mml-smime smime
dig mailcap gnus-sum gnus-group gnus-undo
gnus-start gnus-cloud nnimap nnmail mail-source
tls gnutls utf7 netrc nnoo parse-time gnus-spec
gnus-int gnus-range gnus-win message rfc822 mml
mml-sec epg mm-decode mm-bodies mm-encode
mail-parse rfc2231 rfc2047 rfc2045 ietf-drums
mailabbrev gmm-utils mailheader gnus gnus-ems
nnheader mail-utils edit tabs dired-my w3m-my
w3m-tabs w3m-session w3m browse-url doc-view
jka-compr image-mode timezone w3m-hist w3m-fb
bookmark-w3m w3m-ems w3m-ccl ccl w3m-favicon
w3m-image w3m-proc w3m-util time-my linux-shell
files-my tramp tramp-compat tramp-loaddefs
trampver ucs-normalize shell advice
sudo-user-path find-command window-new count
get-search-string caps-back buffer-menu
switch-to-buffer super scroll dired close buc
switch-to-buffer-regexp subr-x align-new
erc-list erc-menu erc-join erc-ring
erc-networks erc-pcomplete pcomplete comint
ansi-color ring erc-track erc-match erc-button
wid-edit erc-fill erc-stamp erc-netsplit
erc-goodies erc erc-backend erc-compat
format-spec auth-source cl-seq eieio eieio-core
cl-macs gnus-util time-date mm-util help-fns
mail-prsvr password-cache thingatpt pp
my-string search-regexp-in-files finder-inf
info slime-autoloads package epg-config seq
byte-opt gv bytecomp byte-compile cl-extra
help-mode easymenu cconv cl-loaddefs pcase
cl-lib w3m-load mule-util tooltip eldoc
electric uniquify ediff-hook vc-hooks
lisp-float-type mwheel x-win term/common-win
x-dnd tool-bar dnd fontset image regexp-opt
fringe tabulated-list newcomment elisp-mode
lisp-mode prog-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse
jit-lock font-lock syntax facemenu font-core
frame cl-generic cham georgian utf-8-lang
misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek
romanian slovak czech european ethiopic indian
cyrillic chinese charscript case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer
cl-preloaded nadvice loaddefs button faces
cus-face macroexp files text-properties overlay
sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable
backquote dbusbind inotify dynamic-setting
system-font-setting font-render-setting
move-toolbar gtk x-toolkit x multi-tty
make-network-process emacs)

Memory information:
((conses 8 562500 116792)
 (symbols 24 49692 133)
 (miscs 20 414 2943)
 (strings 16 124316 18946)
 (string-bytes 1 3748017)
 (vectors 8 73884)
 (vector-slots 4 1902625 44262)
 (floats 8 605 859)
 (intervals 28 10539 2722)
 (buffers 520 96))

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Eli Zaretskii]

> From: Emanuel Berg <moasenwood@zoho.eu>
> Date: Fri, 05 Apr 2019 20:51:37 +0200
> 
> 25.1; `narrow-to-region' docstring no mention of args
> 
> The `narrow-to-region' docstring does not
> mention its arguments as is the norm.

It does:

  When calling from a program, pass two arguments; positions (integers
  or markers) bounding the text that should remain visible.

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Eli Zaretskii wrote:

>> From: Emanuel Berg <moasenwood@zoho.eu>
>> Date: Fri, 05 Apr 2019 20:51:37 +0200
>> 
>> 25.1; `narrow-to-region' docstring no
>> mention of args
>> 
>> The `narrow-to-region' docstring does not
>> mention its arguments as is the norm.
>
> It does:
>
> When calling from a program, pass two
> arguments; positions (integers or markers)
> bounding the text that should remain visible.

The words START and END do not appear, in that
order, in the docstring. Actually, they don't
appear at all. That means they are
not searchable.

(checkdoc-current-buffer t) would tell you this
if you run it in an Elisp pack. If you run it
in a C file, I don't know what will happen, but
the principle is still a good idea both from
a principal and a practical standpoint.

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Eli Zaretskii]

> From: Emanuel Berg <moasenwood@zoho.eu>
> Cc: 35163@debbugs.gnu.org
> Date: Fri, 05 Apr 2019 21:26:55 +0200
> 
> Eli Zaretskii wrote:
> 
> >> From: Emanuel Berg <moasenwood@zoho.eu>
> >> Date: Fri, 05 Apr 2019 20:51:37 +0200
> >> 
> >> 25.1; `narrow-to-region' docstring no
> >> mention of args
> >> 
> >> The `narrow-to-region' docstring does not
> >> mention its arguments as is the norm.
> >
> > It does:
> >
> > When calling from a program, pass two
> > arguments; positions (integers or markers)
> > bounding the text that should remain visible.
> 
> The words START and END do not appear, in that
> order, in the docstring. Actually, they don't
> appear at all. That means they are
> not searchable.

This is a command, first and foremost.  The primary goal of its doc
string is to tell users (not Lisp programmers) how to use the command
and what it does.  In interactive usage, START and END come from the
region and are not under user control explicitly.

So I don't think there's anything wrong with this doc string.

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Eli Zaretskii wrote:

>> The words START and END do not appear, in
>> that order, in the docstring. Actually, they
>> don't appear at all. That means they are
>> not searchable.
>
> This is a command, first and foremost.
> The primary goal of its doc string is to tell
> users (not Lisp programmers) how to use the
> command and what it does. In interactive
> usage, START and END come from the region and
> are not under user control explicitly.
>
> So I don't think there's anything wrong with
> this doc string.

;;; docstring-experiment.el --- illustrate docstring deficiency

;;; Commentary:
;;;
;;; This file:
;;; http://user.it.uu.se/~embe8573/emacs-init/docstring-experiment.el
;;;
;;; Updated:  2019-04-06  09:05
;;;
;;; The purpose of this package is to
;;; illustrate the deficiency of certain
;;; docstrings with respect to the arguments of
;;; the functions.
;;;
;;; The first example docstring is from
;;; `re-search-forward' on GNU Emacs 25.1.1
;;; (arm-unknown-linux-gnueabihf, GTK+ Version
;;; 3.22.11) of 2017-09-16, modified by Debian.
;;;
;;; To illustrate even further, I have
;;; purposefully written an even worse
;;; docstring to a function that only
;;; exists here.
;;;
;;; To test, evaluate:
;;;
;;;     (checkdoc-current-buffer t)
;;;
;;; Here is some additional settings and
;;; helpers:
;;;
;;;     (require 'checkdoc)
;;;     (setq checkdoc-permit-comma-termination-flag t)
;;;
;;;     (defun check-package-style ()
;;;       (interactive)
;;;       (checkdoc-current-buffer t) ; TAKE-NOTES
;;;       (message "Style check done.") )
;;;     (defalias 'pack-style #'check-package-style)
;;;
;;; If you for some reason do not get
;;; `checkdoc' to work, the output is:
;;;
;;; *** docstring-experiment.el: checkdoc-current-buffer V 0.6.1
;;; docstring-experiment.el:37:
;;;   Argument ‘bound’ should appear (as BOUND) in the doc string
;;; docstring-experiment.el:60:
;;;   Arguments occur in the doc string out of order

;;; Code:

(defun illo-re-search-forward (regexp &optional bound noerror count)
  "Search forward from point for regular expression REGEXP.
Set point to the end of the occurrence found, and return point.
An optional second argument bounds the search; it is a buffer position.
  The match found must not end after that position.  A value of nil
  means search to the end of the accessible portion of the buffer.
Optional third argument, if t, means if fail just return nil (no error).
  If not nil and not t, move to limit of search and return nil.
Optional fourth argument COUNT, if a positive number, means to search
  for COUNT successive occurrences.  If COUNT is negative, search
  backward, instead of forward, for -COUNT occurrences.  A value of
  nil means the same as 1.
With COUNT positive, the match found is the COUNTth one (or first,
  if COUNT is 1 or nil) in the buffer located entirely after the
  origin of the search; correspondingly with COUNT negative.

Search case-sensitivity is determined by the value of the variable
‘case-fold-search’, which see.

See also the functions ‘match-beginning’, ‘match-end’, ‘match-string’,
and ‘replace-match’."
  (message "This function's purpose was not to be executed.") )

(defun illo-even-worse (out of order)
  "OUT is a nice place after too much computer work.
By a bridge the sound of the water can be very relaxing.
It gets your thoughts back to ORDER.
OF all the things I can think of now that would be the nicest."
  (message "Evaluate (checkdoc-current-buffer t) instead!") )

(provide 'docstring-experiment)
;;; docstring-experiment.el ends here

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Eli Zaretskii]

> From: Emanuel Berg <moasenwood@zoho.eu>
> Cc: 35163@debbugs.gnu.org
> Date: Sat, 06 Apr 2019 09:10:04 +0200
> 
> Eli Zaretskii wrote:
> 
> >> The words START and END do not appear, in
> >> that order, in the docstring. Actually, they
> >> don't appear at all. That means they are
> >> not searchable.
> >
> > This is a command, first and foremost.
> > The primary goal of its doc string is to tell
> > users (not Lisp programmers) how to use the
> > command and what it does. In interactive
> > usage, START and END come from the region and
> > are not under user control explicitly.
> >
> > So I don't think there's anything wrong with
> > this doc string.
> 
> ;;; docstring-experiment.el --- illustrate docstring deficiency

Please don't ask me to run arbitrary code I receive from the
Internet.  I'd appreciate a direct response to what I wrote above.

Thanks.

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Eli Zaretskii wrote:

> Please don't ask me to run arbitrary code
> I receive from the Internet. I'd appreciate
> a direct response to what I wrote above.

I'm dropping this issue 100%. I thought it
would be a quick fix, but if you want
docstrings that do not conform with your own
rules do it.

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Glenn Morris]

OP wants every doc string to literally contain the upper-case argument
names, ie START and END in this case (as per eg checkdoc's "Argument ...
should appear (as ...) in the doc string"). If you agree, it's a trivial
change. If not, close as wontfix.

(People who have particular ideas about doc strings could save everyone
a lot of time by sending patches.)

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: 35163@debbugs.gnu.org
> Date: Mon, 08 Apr 2019 12:24:58 -0400
> 
> OP wants every doc string to literally contain the upper-case argument
> names, ie START and END in this case (as per eg checkdoc's "Argument ...
> should appear (as ...) in the doc string"). If you agree, it's a trivial
> change. If not, close as wontfix.

Thanks, fixed.

> (People who have particular ideas about doc strings could save everyone
> a lot of time by sending patches.)

Or at least a clear description of the problem.

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Glenn Morris wrote:

> (People who have particular ideas about doc
> strings

Well, I don't know about "particular", as
I myself learned the rules from
(checkdoc-current-buffer t) when I did Elisp
packages. But yes, I think the rules
make sense!

> could save everyone a lot of time by
> sending patches.)

Should I interpret this as "one shouldn't
bother the maintainers with details like this"?
If so, I'm happy to supply patches instead,
only I haven't done it before and don't know
how to do it. In theory, you change the code,
then use a tool that generates a note of the
changes you made, and you submit that
note, right? Is there some Emacs mode or
infrastructure to help you with this?

Also, if the docstring is in the C code, does
that mean you have to recompile that source
file after the change? Docstrings for
C functions are themselves in the
C code, right?

As I'm using Emacs 25, does that mean I should
get a more recent version, for the single
purpose of doing this? If so, which one?
That sounds like a lot of work but thinking
about it I suppose it doesn't have to be.

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Basil L. Contovounesios]

[ Your Mail-Followup-To and Mail-Copies-To headers seem wrong, they
  should point to the bug address 35163@debbugs.gnu.org instead of
  bug-gnu-emacs@gnu.org. ]

Emanuel Berg <moasenwood@zoho.eu> writes:

> Glenn Morris wrote:
>
>> (People who have particular ideas about doc
>> strings
>
> Well, I don't know about "particular", as
> I myself learned the rules from
> (checkdoc-current-buffer t) when I did Elisp
> packages. But yes, I think the rules
> make sense!

They're conventions and decent guidelines for the general case, not
rules.  Humans reserve the right to exercise their own judgement.  In
particular, the "rule" to mention positional arguments in the order they
appear often makes for unreadable docstrings IME.

Note also the relevant Elisp manual node is called "Documentation
Tips"[1], and its opening paragraph reads as follows:

> Here are some tips and conventions for the writing of documentation
> strings.  You can check many of these conventions by running the command
> ‘M-x checkdoc-minor-mode’.

[1]: (info "(elisp) Documentation Tips")

>> could save everyone a lot of time by
>> sending patches.)
>
> Should I interpret this as "one shouldn't
> bother the maintainers with details like this"?

Not at all.  Eli (amongst several other fastidious contributors) keeps
himself very busy co-maintaining Emacs, yet he still manages to set a
stellar example of how documentation should be maintained.

I'm sure what Glenn and Eli meant is closer to "a patch speaks a
thousand words," i.e. it's easier and more efficient to convey one's
intentions by showing, rather than describing, them, especially over the
lossy communication medium that is email.

> If so, I'm happy to supply patches instead,
> only I haven't done it before and don't know
> how to do it. In theory, you change the code,
> then use a tool that generates a note of the
> changes you made, and you submit that
> note, right?

Right.

> Is there some Emacs mode or infrastructure to help you with this?

There are various tools you can use.  Since Emacs uses Git as its VCS,
the built-in Version Control[2] interface and/or the third-party
Magit[3][4] package would be obvious choices if you're already somewhat
familiar with Git.

Even simpler would be to use M-x diff[5][6] or the eponymous
command-line utilities 'diff' or 'patch'.  See, for example, the manual
node on Bugs[7], particularly its subnode on Sending Patches[8].  There
is also some related information under Contributing[9] and in the
CONTRIBUTE[10] file of the Emacs source tree[11].

[2]: (info "(emacs) Version Control")
[3]: https://github.com/magit/magit/
[4]: (info "(magit) Top")
[5]: (info "(emacs) Comparing Files")
[6]: (info "(emacs) Diff Mode")
[7]: (info "(emacs) Bugs")
[8]: (info "(emacs) Sending Patches")
[9]: (info "(emacs) Contributing")
[10]: http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE
[11]: http://git.savannah.gnu.org/cgit/emacs.git/

> Also, if the docstring is in the C code, does
> that mean you have to recompile that source
> file after the change?

You only need to recompile if you want the changes to appear next time
you run the compiled Emacs instance.  You do not need to recompile in
order to create and send a patch, though compilation warnings/errors can
alert you to unforeseen problems or mistakes prior to sending the patch.

> Docstrings for C functions are themselves in the C code, right?

Yes, they are written as multiline C comments of the form /* ... */.
For details, see (info "(elisp) Writing Emacs Primitives").

> As I'm using Emacs 25, does that mean I should
> get a more recent version, for the single
> purpose of doing this? If so, which one?
> That sounds like a lot of work but thinking
> about it I suppose it doesn't have to be.

If you are interested in contributing code and/or documentation, it
would definitely be easier if you checked out the Git sources[11], if
only so that you wouldn't be looking at outdated code/documentation.

Alternatively, you can download and/or install the most recent
release[12], or download the sources via 'apt-get source'.

[12]: https://www.gnu.org/software/emacs/download.html

Emacs 26 is the current release, and it includes many fixes since Emacs
25, so I would recommend looking at something at least as recent as
26.1, if not the emacs-26 or master branches of the Git repository (I
think Emacs 26.2 is due to be released soon as well).

Thanks for your interest,

-- 
Basil

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Basil L. Contovounesios wrote:

> [ Your Mail-Followup-To and Mail-Copies-To
>   headers seem wrong, they should point to
>   the bug address 35163@debbugs.gnu.org
>   instead of bug-gnu-emacs@gnu.org. ]

[ OK, now I reply tho this (i.e., your) message
  thru gmane.emacs.bugs, and after that, I hope
  to reply to Noam Postavsky's message, and
  I'll do that thru mail, and we'll perhaps see
  if there is a difference or both ways are
  broken. My hunch is it'll work if I use mail,
  but not if I use the Gmane newsgroup. ]

> They're conventions and decent guidelines for
> the general case, not rules. Humans reserve
> the right to exercise their own judgement.
> In particular, the "rule" to mention
> positional arguments in the order they appear
> often makes for unreadable docstrings IME.

OK, the rule to mention them in order makes
sense especially if you have a function with
tons of args. But most important is that they
are mentioned exactly as they are, so they can
be searched for. Often, in Elisp code, you see
this


    (some-function some-feature some-property t)


Now, you can often guess what everything does,
except for the last `t'. Brining up the help
and searching for the arg's name to find it
immediately in the docstring is a good way of
finding out, fast.

Thanks for your message, I'll keep it if this
situation appears again.

> Eli [...] keeps himself very busy
> co-maintaining Emacs, yet he still manages to
> set a stellar example of how documentation
> should be maintained.

... okay? I just thought that was a strange
statement. Like someone had _denied_ that (?)

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Basil L. Contovounesios wrote:

> [ Your Mail-Followup-To and Mail-Copies-To
>   headers seem wrong, they should point to
>   the bug address 35163@debbugs.gnu.org
>   instead of bug-gnu-emacs@gnu.org. ]

[ OK, now I reply tho this (i.e., your) message
  thru gmane.emacs.bugs, and after that, I hope
  to reply to Noam Postavsky's message, and
  I'll do that thru mail, and we'll perhaps see
  if there is a difference or both ways are
  broken. My hunch is it'll work if I use mail,
  but not if I use the Gmane newsgroup. ]

[ I was right, the Gmane newsgroups is to
  blame. So I re-send it here as well.
  Now everyone should be happy and content. ]

> They're conventions and decent guidelines for
> the general case, not rules. Humans reserve
> the right to exercise their own judgement.
> In particular, the "rule" to mention
> positional arguments in the order they appear
> often makes for unreadable docstrings IME.

OK, the rule to mention them in order makes
sense especially if you have a function with
tons of args. But most important is that they
are mentioned exactly as they are, so they can
be searched for. Often, in Elisp code, you see
this


    (some-function some-feature some-property t)


Now, you can often guess what everything does,
except for the last `t'. Brining up the help
and searching for the arg's name to find it
immediately in the docstring is a good way of
finding out, fast.

Thanks for your message, I'll keep it if this
situation appears again.

> Eli [...] keeps himself very busy
> co-maintaining Emacs, yet he still manages to
> set a stellar example of how documentation
> should be maintained.

... okay? I just thought that was a strange
statement. Like someone had _denied_ that (?)

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Basil L. Contovounesios]

Emanuel Berg <moasenwood@zoho.eu> writes:

> Basil L. Contovounesios wrote:
>
>> [ Your Mail-Followup-To and Mail-Copies-To
>>   headers seem wrong, they should point to
>>   the bug address 35163@debbugs.gnu.org
>>   instead of bug-gnu-emacs@gnu.org. ]
>
> [ OK, now I reply tho this (i.e., your) message
>   thru gmane.emacs.bugs, and after that, I hope
>   to reply to Noam Postavsky's message, and
>   I'll do that thru mail, and we'll perhaps see
>   if there is a difference or both ways are
>   broken. My hunch is it'll work if I use mail,
>   but not if I use the Gmane newsgroup. ]
>
> [ I was right, the Gmane newsgroups is to
>   blame. So I re-send it here as well.
>   Now everyone should be happy and content. ]

Indeed, your reply to Noam correctly kept the bug report CCed, whereas
your previous reply to me did not.

>> They're conventions and decent guidelines for
>> the general case, not rules. Humans reserve
>> the right to exercise their own judgement.
>> In particular, the "rule" to mention
>> positional arguments in the order they appear
>> often makes for unreadable docstrings IME.
>
> OK, the rule to mention them in order makes
> sense especially if you have a function with
> tons of args. But most important is that they
> are mentioned exactly as they are, so they can
> be searched for. Often, in Elisp code, you see
> this
>
>
>     (some-function some-feature some-property t)
>
>
> Now, you can often guess what everything does,
> except for the last `t'. Brining up the help
> and searching for the arg's name to find it
> immediately in the docstring is a good way of
> finding out, fast.

I think most of us agree that docstrings, especially those of public
functions, should mention their accepted arguments by name, if not in
the exact same order as they appear in the argument list.  Eli fixed
this for narrow-to-region[1] following your report.

[1: a5da653319]: * src/editfns.c (Fnarrow_to_region): Doc fix.  (Bug#35163)
  2019-04-08 19:53:48 +0300
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=a5da653319a3018074debfc7b4fdd90ac7ea838c

>> Eli [...] keeps himself very busy
>> co-maintaining Emacs, yet he still manages to
>> set a stellar example of how documentation
>> should be maintained.
>
> ... okay? I just thought that was a strange
> statement. Like someone had _denied_ that (?)

No-one denied that.  You said:

> Should I interpret this as "one shouldn't
> bother the maintainers with details like this"?

So my sentence was intended as an example of how un-bothered maintainers
are by details like this, in that e.g. Eli pays a lot of attention to
documenting things properly, and following Emacs and GNU conventions.

All I meant to say is that these documentation details aren't beneath
anyone.  I hope I've managed to explain myself properly.

Thanks,

-- 
Basil

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Basil L. Contovounesios wrote:

> Indeed, your reply to Noam correctly kept the
> bug report CCed, whereas your previous reply
> to me did not.

Hm - perhaps gmane.emacs.bugs shouldn't be used
at all, then?

BTW I didn't get a mail version of your latest
post - the one I reply to now - perhaps because
I used Gmane to begin with, I don't know.

> All I meant to say is that these
> documentation details aren't beneath anyone.
> I hope I've managed to explain
> myself properly.

Oh, don't you worry! Not all of us think of
mail as "the lossy communication medium that is
email" :) I actually think it is the very best
medium for communication ever
invented/engineered, not the least for
communication about technology (and
"technology" not limited to computers, or
course).

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Robert Pluim]

>>>>> On Tue, 09 Apr 2019 10:53:33 +0200, Emanuel Berg <moasenwood@zoho.eu> said:

    Emanuel> Basil L. Contovounesios wrote:
    >> Indeed, your reply to Noam correctly kept the bug report CCed,
    >> whereas your previous reply to me did not.

    Emanuel> Hm - perhaps gmane.emacs.bugs shouldn't be used at all,
    Emanuel> then?

It can be used fine as long as you remember to do a 'wide reply' , but
you should not set 'Mail-Followup-To: bug-gnu-emacs@gnu.org'

    Emanuel> BTW I didn't get a mail version of your latest post - the
    Emanuel> one I reply to now - perhaps because I used Gmane to
    Emanuel> begin with, I don't know.

Basil only replied to the bug report. Probably because you also have
'Mail-Copies-To: never' in your headers (which Gnus respected for
this message, but Iʼve added you back in).

Robert

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Robert Pluim wrote:

> It can be used fine as long as you remember
> to do a 'wide reply' , but you should not set
> 'Mail-Followup-To: bug-gnu-emacs@gnu.org'

I didn't set that manually, if that's what you
mean. I don't remember configuring anything
that could have amounted to that in this
situation, but I suppose it could have happened
just the same.

> Basil only replied to the bug report.
> Probably because you also have
> 'Mail-Copies-To: never' in your headers
> (which Gnus respected for this message, but
> I've added you back in).

OK, but I don't want mails of things that I get
thru the newsgroups! So if this issue, the
incorrect followups, can be, ehem, "addressed",
then I'd like to deal with it newsgroup-only.
But if it can't without too much effort, I can
just remember to use mail instead of the
newsgroup for bugs in particular, no big deal.

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Robert Pluim]

>>>>> On Tue, 09 Apr 2019 11:55:31 +0200, Emanuel Berg <moasenwood@zoho.eu> said:

    Emanuel> Robert Pluim wrote:
    >> It can be used fine as long as you remember to do a 'wide
    >> reply' , but you should not set 'Mail-Followup-To:
    >> bug-gnu-emacs@gnu.org'

    Emanuel> I didn't set that manually, if that's what you mean. I
    Emanuel> don't remember configuring anything that could have
    Emanuel> amounted to that in this situation, but I suppose it
    Emanuel> could have happened just the same.

Itʼs possible that itʼs set in your Gnus group parameters or
similar. Or itʼs an artifact of using gmane.

    >> Basil only replied to the bug report.  Probably because you
    >> also have 'Mail-Copies-To: never' in your headers (which Gnus
    >> respected for this message, but I've added you back in).

    Emanuel> OK, but I don't want mails of things that I get thru the
    Emanuel> newsgroups! So if this issue, the incorrect followups,
    Emanuel> can be, ehem, "addressed", then I'd like to deal with it
    Emanuel> newsgroup-only.  But if it can't without too much effort,
    Emanuel> I can just remember to use mail instead of the newsgroup
    Emanuel> for bugs in particular, no big deal.

Using 'Mail-Copies-To: never' is fine, as long as you then read the
mailing list or the gmane group for your bugs. (I didnʼt CC you on
this reply)

Robert

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Robert Pluim wrote:

> Using 'Mail-Copies-To: never' is fine

I know, but -

> as long as you then read the mailing list or
> the gmane group for your bugs. (I didnʼt CC
> you on this reply)

- except it isn't in this particular case as
the followup header isn't set correctly IIUC?

Perhaps you or someone else can try using
gmane.emacs.bugs as well so we'll see if this
is a local config issue on my part? (Unless we
have the same config that is :))

The one big problem with Gnus and configs is
you can't really do 'emacs -q' to find out if
the problem is with you or not, a method that
_almost_ always is waterproof in all the other
parts of the Emacs World where I'm a regular.

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Robert Pluim]

>>>>> On Tue, 09 Apr 2019 14:48:01 +0200, Emanuel Berg <moasenwood@zoho.eu> said:

    Emanuel> Robert Pluim wrote:
    >> Using 'Mail-Copies-To: never' is fine

    Emanuel> I know, but -

    >> as long as you then read the mailing list or the gmane group
    >> for your bugs. (I didnʼt CC you on this reply)

    Emanuel> - except it isn't in this particular case as the followup
    Emanuel> header isn't set correctly IIUC?

Correct.

    Emanuel> Perhaps you or someone else can try using
    Emanuel> gmane.emacs.bugs as well so we'll see if this is a local
    Emanuel> config issue on my part? (Unless we have the same config
    Emanuel> that is :))

I use gmane.emacs.bugs all the time, and donʼt have this problem.

    Emanuel> The one big problem with Gnus and configs is you can't
    Emanuel> really do 'emacs -q' to find out if the problem is with
    Emanuel> you or not, a method that _almost_ always is waterproof
    Emanuel> in all the other parts of the Emacs World where I'm a
    Emanuel> regular.

Yes, thatʼs true. In this case, Iʼd use 'G p', ie
('gnus-topic-edit-parameters') to see if you have any specific
settings for gmane.emacs.bugs. If that doesnʼt turn up anything, then
your .gnus.el and/or .emacs is the next place to look (probably in
posting styles).  As a last resort, look in .newsrc.eld

Robert

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Robert Pluim wrote:

> Yes, that's true. In this case, I'd use
> 'G p', ie ('gnus-topic-edit-parameters') to
> see if you have any specific settings for
> gmane.emacs.bugs.

Nah, I don't setup groups individually but
I can check it out anyway.

    ;;; Editing the group parameters for ‘gmane.emacs.bugs’.
    ;; Type ‘C-c C-c’ after you’ve finished editing.

    nil

> If that doesn't turn up anything, then your
> .gnus.el and/or .emacs is the next place to
> look (probably in posting styles).

I don't use that either.

    `gnus-posting-styles' is a variable defined
    in gnus-msg.el. Its value is nil

> As a last resort, look in .newsrc.eld

... look for what?

"gmane.emacs.bugs" appears twice, on line 7 [1]
and 13. [2]


PS. This reporting bug business sure was a lot
    of work! :) DS.


[1] (setq gnus-newsrc-alist
    '(("nntp+nntp.aioe.org:alt.os.linux" 6 ((1 .
    54560)) ((unexist) (tick 51892 51933 51941
    51945)) "nntp:nntp.aioe.org")
    ("nntp+nntp.aioe.org:alt.test" 6 ((1 . 430642))
    ((unexist)) "nntp:nntp.aioe.org")
    ("nntp+nntp.aioe.org:alt.tv.survivor" 3 ((1 .
    54485)) ((unexist)) "nntp:nntp.aioe.org")
    ("nndraft:drafts" 1 nil nil (nndraft "")
    ((gnus-dummy (gnus-draft-mode))))
    ("gmane.comp.shells.zsh.devel" 6 ((1 . 45428))
    nil nil) ("gmane.comp.shells.zsh.user" 6 ((1 .
    19229)) ((unexist)))
    ("gmane.comp.sysutils.docker.devel" 6 ((1 .
    3322))) ("gmane.comp.sysutils.docker.user" 3
    ((1 . 11789)) ((unexist)))
    ("gmane.comp.video.image-magick.user" 6 ((1 .
    22290)) nil nil) ("gmane.discuss" 3 ((1 .
    17550)) ((unexist))) ("gmane.emacs.bugs" 6 ((1
    . 157439)) ((unexist))) ("gmane.emacs.devel" 6
    ((1 . 235159)) ((unexist)))
    ("gmane.emacs.erc.general" 3 ((1 . 1469))
    ((unexist))) ("gmane.emacs.gnus.general" 3 ((1
    . 88499)) ((unexist))) ("gmane.emacs.gnus.user"
    3 ((1 . 18951)) ((unexist)))
    ("gmane.emacs.help" 3 ((1 . 119917)) ((unexist)
    (tick (119843 . 119844)))) ("gmane.emacs.w3m" 3
    ((1 . 10215)) ((unexist))) ("gmane.test" 6 ((1
    . 8444)) ((unexist))) ("nnml:mail.misc" 3 ((1 .
    8975)) ((unexist) (tick 8974)) "nnml:")
    ("nnml:mail.ml-ooa" 6 ((1 . 429)) ((unexist))
    "nnml:") ("nnml:mail.rsmh-ooa" 6 ((1 . 165))
    ((unexist)) "nnml:") ("nnml:mail.sent" 6 ((1 .
    7902)) ((unexist) (tick 7902)) "nnml:")))

[2] (setq gnus-topic-alist '(("misc"
    "nntp+nntp.aioe.org:alt.os.linux"
    "nntp+nntp.aioe.org:alt.test"
    "nntp+nntp.aioe.org:alt.tv.survivor"
    "nndraft:drafts" "gmane.comp.shells.zsh.devel"
    "gmane.comp.shells.zsh.user"
    "gmane.comp.sysutils.docker.devel"
    "gmane.comp.sysutils.docker.user"
    "gmane.comp.video.image-magick.user"
    "gmane.discuss" "gmane.emacs.bugs"
    "gmane.emacs.devel" "gmane.emacs.erc.general"
    "gmane.emacs.gnus.general"
    "gmane.emacs.gnus.user" "gmane.emacs.help"
    "gmane.emacs.w3m" "gmane.test"
    "nntp+nntp.aioe.org:gnu.emacs.help"
    "nnml:mail.misc" "nnml:mail.ml-ooa"
    "nnml:mail.rsmh-ooa" "nnml:mail.sent")
    ("Gnus")))

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Eli Zaretskii]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Date: Mon, 08 Apr 2019 23:19:38 +0100
> Cc: 35163@debbugs.gnu.org
> 
> >> could save everyone a lot of time by
> >> sending patches.)
> >
> > Should I interpret this as "one shouldn't
> > bother the maintainers with details like this"?
> 
> Not at all.  Eli (amongst several other fastidious contributors) keeps
> himself very busy co-maintaining Emacs, yet he still manages to set a
> stellar example of how documentation should be maintained.
> 
> I'm sure what Glenn and Eli meant is closer to "a patch speaks a
> thousand words," i.e. it's easier and more efficient to convey one's
> intentions by showing, rather than describing, them, especially over the
> lossy communication medium that is email.

That is true, but a clear and concrete description of the problem,
quoting the relevant parts of the current documentation, is a great
help, even if it is accompanied by a patch.  Maintaining documentation
frequently requires judgment calls, so a clear idea of the motivation
for the bug report/patch will make the report handling much more
efficient and free from misunderstandings.

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Noam Postavsky]

> From: Eli Zaretskii <eliz@gnu.org>

>> From: Glenn Morris <rgm@gnu.org>

>> OP wants every doc string to literally contain the upper-case argument
>> names, ie START and END in this case (as per eg checkdoc's "Argument ...
>> should appear (as ...) in the doc string"). If you agree, it's a trivial
>> change. If not, close as wontfix.
>
> Thanks, fixed.
>
>> (People who have particular ideas about doc strings could save everyone
>> a lot of time by sending patches.)
>
> Or at least a clear description of the problem.

To be fair, message [11] is fairly clear and pretty close to what Glenn
wrote (perhaps it misses the emphasis on satisfying checkdoc).  Things
unfortunately derailed after that.

An 80+ line elisp riddle on a report about a docstring bug is surely a
sign something has gone horribly wrong...

[11]: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=35163#11

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Emanuel Berg]

Noam Postavsky wrote:

>> Or at least a clear description of
>> the problem.
>
> To be fair, message [11] is fairly clear and
> pretty close to what Glenn wrote (perhaps it
> misses the emphasis on satisfying checkdoc).

I agree that message 11 is fairly clear,
however checkdoc is mentioned there as well:
"(checkdoc-current-buffer t) would tell you
this ..."

> Things unfortunately derailed after that.
> An 80+ line elisp riddle on a report about
> a docstring bug is surely a sign something
> has gone horribly wrong...

Ha ha :D

> [11]: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=35163#11

-- 
underground experts united
http://user.it.uu.se/~embe8573

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Eli Zaretskii]

> From: Emanuel Berg <moasenwood@zoho.eu>
> Date: Tue, 09 Apr 2019 02:48:39 +0200
> Cc: 35163@debbugs.gnu.org
> 
> Noam Postavsky wrote:
> 
> >> Or at least a clear description of
> >> the problem.
> >
> > To be fair, message [11] is fairly clear and
> > pretty close to what Glenn wrote (perhaps it
> > misses the emphasis on satisfying checkdoc).
> 
> I agree that message 11 is fairly clear,
> however checkdoc is mentioned there as well:
> "(checkdoc-current-buffer t) would tell you
> this ..."

Please realize that I cannot afford spending so much time on each bug
report.  I get about 200 email messages each day, perhaps 2/3 of them
about Emacs.  Just reading them all takes a large portion of the free
time I have.  A clearly described bug report usually gets fixed
immediately, within seconds of reading it.  When the issue is not so
clear, I ask follow-up questions.  Since whoever submitted the bug
report already invested some time on it -- in this case running
checkdoc -- I ask you to help me by providing the output, pointing out
the specific details which in your opinion needs fixing, and
preferably also explaining why you think they need to be fixed.
Asking me to repeat the steps that you already made makes the handling
much less efficient, and usually means the issue goes to the bottom of
my TODO.

If I don't act like that, I won't be able to cope with my daily email
inflow.

So please help me handle the issues you report efficiently by
providing the information you already have, because you've studied the
issue in advance.

TIA

bug#35163: 25.1; `narrow-to-region' docstring no mention of args

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@gmail.com>
> Date: Mon, 08 Apr 2019 19:09:39 -0400
> Cc: , Emanuel Berg <moasenwood@zoho.eu>
> 
> > Or at least a clear description of the problem.
> 
> To be fair, message [11] is fairly clear and pretty close to what Glenn
> wrote (perhaps it misses the emphasis on satisfying checkdoc).

Obviously, it wasn't clear enough to me, or I wouldn't have asked the
follow-up questions.  When it became clear, I pushed a change within
minutes.

> Things unfortunately derailed after that.
> 
> An 80+ line elisp riddle on a report about a docstring bug is surely a
> sign something has gone horribly wrong...

Indeed.