GNU bug report logs - #55742
29.0.50; Confusing "pcase" documentation on the web

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 55742 in the body.
You can then email your comments to 55742 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: Rudolf Adamkovič <salutis <at> me.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.50; Confusing "pcase" documentation on the web
Date: Tue, 31 May 2022 17:21:54 +0200

In "The pcase macro" documentation on the web

https://www.gnu.org/software/emacs/manual/html_node/elisp/pcase-Macro.html

has "_" on its own line, surrounded with whitespace.  It looks like a
dash, and in a graphical browser, one has to select it to discover the
mistake.  Could we add the word "underscore" somewhere next to it?

Rudy

In GNU Emacs 29.0.50 (build 15, x86_64-apple-darwin21.4.0, NS appkit-2113.40 Version 12.3.1 (Build 21E258))
 of 2022-05-23 built on Workstation.local
Repository revision: 5a1a67a2562fab77856b48a38d89713d7f2c96d7
Repository branch: master
Windowing system distributor 'Apple', version 10.3.2113
System Description:  macOS 12.4

Configured using:
 'configure --with-json --with-native-compilation'

Configured features:
ACL DBUS GIF GLIB GMP GNUTLS JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY KQUEUE NS PDUMPER PNG RSVG SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS WEBP XIM ZLIB

Important settings:
  locale-coding-system: utf-8-unix

Major mode: Messages

Minor modes in effect:
  pdf-occur-global-minor-mode: t
  telega-root-auto-fill-mode: t
  telega-active-locations-mode: t
  telega-patrons-mode: t
  telega-mode-line-mode: t
  global-git-commit-mode: t
  magit-auto-revert-mode: t
  TeX-PDF-mode: t
  savehist-mode: t
  vertico-multiform-mode: t
  vertico-mouse-mode: t
  vertico-mode: t
  marginalia-mode: t
  global-diff-hl-mode: t
  global-hl-todo-mode: t
  global-corfu-mode: t
  corfu-mode: t
  org-roam-db-autosync-mode: t
  shell-dirtrack-mode: t
  global-subword-mode: t
  subword-mode: t
  save-place-mode: t
  global-auto-revert-mode: t
  delete-selection-mode: t
  global-goto-address-mode: t
  goto-address-mode: t
  tooltip-mode: t
  global-eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  context-menu-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  buffer-read-only: t
  size-indication-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
/Users/salutis/.emacs.d/elpa/transient-20220527.2213/transient hides /Users/salutis/src/emacs/nextstep/Emacs.app/Contents/Resources/lisp/transient

Features:
(shadow mail-extr lpr mule-diag consult-xref ert cl-print debug
backtrace ox-org rect graphviz-dot-mode tabify flyspell-correct pulse
cal-move bbdb bbdb-site timezone holidays hol-loaddefs cal-iso
geiser-mode geiser-xref geiser-guile info-look geiser-repl
geiser-compile geiser-debug geiser-image geiser-capf geiser-doc
geiser-menu geiser-edit etags fileloop xref geiser-completion
geiser-autodoc geiser-eval geiser-connection geiser-syntax geiser-log
geiser-popup view scheme tramp-cmds vterm tramp tramp-loaddefs trampver
tramp-integration files-x tramp-compat term ehelp vterm-module
term/xterm xterm avy autoload lisp-mnt mm-archive url-cache pdf-sync
pdf-annot pdf-outline pdf-links pdf-history pdf-occur ibuf-ext ibuffer
ibuffer-loaddefs tablist tablist-filter semantic/wisent/comp
semantic/wisent semantic/wisent/wisent semantic/util-modes semantic/util
semantic semantic/tag semantic/lex semantic/fw mode-local cedet
pdf-isearch pdf-misc pdf-tools pdf-view pdf-cache pdf-info pdf-util
pdf-macs shortdoc emoji-labels emoji multisession sqlite telega-obsolete
telega telega-tdlib-events telega-webpage visual-fill-column
telega-match telega-root telega-info telega-chat telega-modes
telega-company telega-user telega-notifications notifications
telega-voip telega-msg telega-tme telega-sticker telega-i18n
telega-vvnote bindat telega-ffplay telega-sort telega-filter telega-ins
telega-folders telega-inline telega-util telega-media telega-tdlib
rainbow-identifiers dired-aux telega-server telega-core telega-customize
cus-edit cus-start cus-load emacsbug vc-mtn vc-hg vc-bzr vc-src vc-sccs
vc-svn vc-cvs vc-rcs magit-extras face-remap magit-bookmark
magit-submodule magit-obsolete magit-blame magit-stash magit-reflog
magit-bisect magit-push magit-pull magit-fetch magit-clone magit-remote
magit-commit magit-sequence magit-notes magit-worktree magit-tag
magit-merge magit-branch magit-reset magit-files magit-refs magit-status
magit magit-repos magit-apply magit-wip magit-log which-func magit-diff
smerge-mode diff git-commit log-edit add-log magit-core magit-autorevert
magit-margin magit-transient magit-process magit-mode transient
magit-git magit-base mhtml-mode css-mode smie color js sgml-mode
facemenu network-stream emms-player-mpd emms-url tq emms-player-simple
emms-browser sort emms-playlist-sort emms-last-played emms-volume
emms-volume-sndioctl emms-volume-mixerctl emms-volume-pulse
emms-volume-amixer emms-playlist-mode emms-source-playlist
emms-source-file locate emms-cache emms-info emms-later-do emms
emms-compat char-fold misearch multi-isearch epa-file pass imenu
password-store auth-source-pass with-editor server consult-vertico
consult compat-28 recentf tree-widget citar-org oc-csl citeproc
citeproc-itemgetters citeproc-biblatex citeproc-bibtex citeproc-cite
citeproc-subbibs citeproc-sort citeproc-name citeproc-formatters
citeproc-number rst citeproc-proc citeproc-disamb citeproc-itemdata
citeproc-generic-elements citeproc-macro citeproc-choose citeproc-date
citeproc-context citeproc-prange citeproc-style citeproc-locale
citeproc-term f citeproc-rt citeproc-lib citeproc-s s let-alist queue
citar parsebib citar-file preview font-latex latex latex-flymake
tex-ispell tex-style tex texmathp tex-mode cursor-sensor paredit edmacro
kmacro savehist modus-operandi-theme modus-themes orderless
vertico-multiform vertico-mouse vertico marginalia pdf-loader diff-hl
log-view pcvs-util vc-dir ewoc vc hl-todo corfu org-roam-migrate
org-roam-log org-roam-mode org-roam-capture org-roam-id org-roam-node
org-roam-db org-roam-utils org-roam-compat org-roam org-capture
org-attach org-id emacsql-sqlite url-http url-auth url-gw nsm emacsql
emacsql-compiler magit-section compat-27 compat-26 compat dash
finder-inf elfeed-link elfeed-show elfeed-search elfeed-csv elfeed
elfeed-curl elfeed-log xml-query bookmark pp elfeed-db elfeed-lib vc-git
vc-dispatcher org-indent image-file image-converter ffap disp-table
ol-eww eww xdg url-queue mm-url ol-rmail ol-mhe ol-irc ol-info ol-gnus
nnselect gnus-art mm-uu mml2015 gnus-sum shr pixel-fill kinsoku url-file
url-dired svg dom gnus-group gnus-undo gnus-start gnus-dbus dbus xml
gnus-cloud nnimap nnmail mail-source utf7 netrc nnoo parse-time
gnus-spec gnus-int gnus-range gnus-win gnus nnheader range ol-docview
doc-view jka-compr image-mode exif ol-bibtex ol-bbdb ol-w3m ol-doi
org-link-doi notmuch notmuch-tree notmuch-jump notmuch-hello wid-edit
notmuch-show notmuch-print notmuch-crypto notmuch-mua notmuch-message
notmuch-draft notmuch-maildir-fcc notmuch-address notmuch-company
notmuch-parser notmuch-wash diff-mode coolj notmuch-query icalendar
diary-lib diary-loaddefs notmuch-tag crm notmuch-lib notmuch-version
notmuch-compat pcase hl-line message sendmail yank-media rmc ls-lisp
dired dired-loaddefs rfc822 mml mailabbrev mail-utils gmm-utils
mailheader mm-view mml-smime mml-sec epa derived epg rfc6068 epg-config
gnus-util smime gnutls puny dig mm-decode mm-bodies mm-encode mail-parse
rfc2231 rfc2047 rfc2045 mm-util ietf-drums mail-prsvr
display-fill-column-indicator display-line-numbers fortune lingua-franca
flyspell ispell org-clock ob-sqlite ob-sql ob-java ob-shell shell ob-C
cc-mode cc-fonts cc-guess cc-menus cc-cmds cc-styles cc-align cc-engine
cc-vars cc-defs ob-R ob-dot ob-scheme geiser ob-latex org-habit
org-inlinetask htmlize ox-texinfo ox-md ox-odt rng-loc rng-uri rng-parse
rng-match rng-dt rng-util rng-pttrn nxml-parse nxml-ns nxml-enc xmltok
nxml-util ox-latex ox-icalendar org-agenda org-refile ox-html table
ox-ascii ox-publish ox org-element avl-tree generator cap-words
superword subword saveplace bug-reference autorevert filenotify
flymake-proc flymake project compile text-property-search delsel
goto-addr thingatpt comp comp-cstr warnings cl-extra org ob ob-tangle
ob-ref ob-lob ob-table ob-exp org-macro org-footnote org-src ob-comint
org-pcomplete pcomplete comint ansi-color org-list org-faces
org-entities noutline outline easy-mmode org-version ob-emacs-lisp
ob-core ob-eval org-table oc-basic bibtex iso8601 time-date ol rx
org-keys oc org-compat advice org-macs org-loaddefs format-spec
find-func cal-menu calendar cal-loaddefs tex-site geiser-impl help-fns
radix-tree help-mode geiser-custom geiser-base ring info package
browse-url url url-proxy url-privacy url-expand url-methods url-history
url-cookie url-domsuf url-util mailcap url-handlers url-parse
auth-source cl-seq eieio eieio-core cl-macs eieio-loaddefs
password-cache json map url-vars seq gv subr-x byte-opt bytecomp
byte-compile cconv cl-loaddefs cl-lib iso-transl tooltip eldoc paren
electric uniquify ediff-hook vc-hooks lisp-float-type elisp-mode mwheel
term/ns-win ns-win ucs-normalize mule-util term/common-win tool-bar dnd
fontset image regexp-opt fringe tabulated-list replace newcomment
text-mode lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow
isearch easymenu timer select scroll-bar mouse jit-lock font-lock syntax
font-core term/tty-colors frame minibuffer nadvice simple cl-generic
philippine 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 composite
emoji-zwj charscript charprop case-table epa-hook jka-cmpr-hook help
abbrev obarray oclosure cl-preloaded button loaddefs faces cus-face
macroexp files window text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget keymap hashtable-print-readable backquote
threads dbusbind kqueue cocoa ns lcms2 multi-tty make-network-process
native-compile emacs)

Memory information:
((conses 16 2897246 409442)
 (symbols 48 68580 8)
 (strings 32 474154 32975)
 (string-bytes 1 46596264)
 (vectors 16 149892)
 (vector-slots 8 3372107 396503)
 (floats 8 49024 3720)
 (intervals 56 185022 20686)
 (buffers 992 97))

-- 
"Thinking is a momentary dismissal of irrelevancies."
-- Richard Buckminster Fuller, 1969

Rudolf Adamkovič <salutis <at> me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Rudolf Adamkovič <salutis <at> me.com>
Cc: 55742 <at> debbugs.gnu.org
Subject: Re: bug#55742: 29.0.50; Confusing "pcase" documentation on the web
Date: Wed, 01 Jun 2022 15:39:55 +0200

Rudolf Adamkovič <salutis <at> me.com> writes:

> In "The pcase macro" documentation on the web
>
> https://www.gnu.org/software/emacs/manual/html_node/elisp/pcase-Macro.html
>
> has "_" on its own line, surrounded with whitespace.  It looks like a
> dash, and in a graphical browser, one has to select it to discover the
> mistake.  Could we add the word "underscore" somewhere next to it?

Yup.  The texi here is 

---
@table @code

@item _
Matches any @var{expval}.
This is also known as @dfn{don't care} or @dfn{wildcard}.
---

Anybody know whether we have a convention for adding notes/comments
after a @code item?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 55742 <at> debbugs.gnu.org, salutis <at> me.com
Subject: Re: bug#55742: 29.0.50; Confusing "pcase" documentation on the web
Date: Wed, 01 Jun 2022 18:52:30 +0300

> Cc: 55742 <at> debbugs.gnu.org
> From: Lars Ingebrigtsen <larsi <at> gnus.org>
> Date: Wed, 01 Jun 2022 15:39:55 +0200
> 
> Rudolf Adamkovič <salutis <at> me.com> writes:
> 
> > In "The pcase macro" documentation on the web
> >
> > https://www.gnu.org/software/emacs/manual/html_node/elisp/pcase-Macro.html
> >
> > has "_" on its own line, surrounded with whitespace.  It looks like a
> > dash, and in a graphical browser, one has to select it to discover the
> > mistake.  Could we add the word "underscore" somewhere next to it?
> 
> Yup.  The texi here is 
> 
> ---
> @table @code
> 
> @item _
> Matches any @var{expval}.
> This is also known as @dfn{don't care} or @dfn{wildcard}.
> ---
> 
> Anybody know whether we have a convention for adding notes/comments
> after a @code item?

Like this:

  @item _ <at> r{ (underscore)}

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55742 <at> debbugs.gnu.org, salutis <at> me.com
Subject: Re: bug#55742: 29.0.50; Confusing "pcase" documentation on the web
Date: Wed, 01 Jun 2022 17:57:15 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> Like this:
>
>   @item _ <at> r{ (underscore)}

Thanks; I've now added this to the release branch.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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