GNU bug report logs - #30025
26.0.90; [Documentation][26.1] Docstring for epa-pinentry-mode shows erroneous link

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Damien Cassou <damien <at> cassou.me>
Subject: bug#30025: closed (Re: bug#30025: 26.0.90; [Documentation][26.1]
 Docstring for epa-pinentry-mode shows erroneous link)
Date: Mon, 08 Jan 2018 21:30:02 +0000

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

Your bug report

#30025: 26.0.90; [Documentation][26.1] Docstring for epa-pinentry-mode shows erroneous link

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to 30025 <at> debbugs.gnu.org.

-- 
30025: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=30025
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Eli Zaretskii <eliz <at> gnu.org>
To: Damien Cassou <damien <at> cassou.me>
Cc: 30025-done <at> debbugs.gnu.org, rms <at> gnu.org
Subject: Re: bug#30025: 26.0.90;
 [Documentation][26.1] Docstring for epa-pinentry-mode shows erroneous
 link
Date: Mon, 08 Jan 2018 23:28:40 +0200

> Date: Mon, 08 Jan 2018 16:39:01 +0100
> Cc: rms <at> gnu.org
> 
> How to reproduce:
> 
> 1. C-h v epa-pinentry-mode RET
> 
> Expected: the word "error" should be represented as a keyword, not as a
>   link
> 
> Actual: the word "error" is a link to the function of the same name.

Thanks, fixed.

> What is best practice to describe symbols in docstring?

You need to use a magic word ;-)  (It's all described in the node
"Documentation Tips" of the ELisp manual.)

[Message part 3 (message/rfc822, inline)]

From: Damien Cassou <damien <at> cassou.me>
To: bug-gnu-emacs <at> gnu.org
Cc: rms <at> gnu.org
Subject: 26.0.90;
 [Documentation][26.1] Docstring for epa-pinentry-mode shows erroneous
 link
Date: Mon, 08 Jan 2018 16:39:01 +0100

How to reproduce:

1. C-h v epa-pinentry-mode RET

Expected: the word "error" should be represented as a keyword, not as a
  link

Actual: the word "error" is a link to the function of the same name.

The docstring of epa-pinentry-mode describes 4 possible symbols for the
value. These symbols only make sense in the context of the variable. In
particular, they are not function or variable names. Still, the word
error is represented as a link to the function of the same name.

What is best practice to describe symbols in docstring?

Best,

-- 
Damien Cassou
http://damiencassou.seasidehosting.st

"Success is the ability to go from one failure to another without
losing enthusiasm." --Winston Churchill

Previous Next

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