GNU bug report logs - #10823
24.0.93; Make `C-h d' reporting more consistent and usable

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 10823 in the body.
You can then email your comments to 10823 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: Jambunathan K <kjambunathan <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.0.93; Make `C-h d' reporting more consistent and usable
Date: Thu, 16 Feb 2012 10:33:42 +0530

I find that C-h d gives me a fairly good coverage of a particular
"feature" that I am trying to hunt down. Unfortunately for the amount of
information that it prints, the navigation of the *Apropos* buffer is
cumbersome.

Let me explain with an explain. Down below is a snapshot of first few
paragraphs when I do a

  C-h d apropos

Here are a few things that I find noisome. These are documented in the
text below.


----------------
apropos-read-pattern
  Function: Read an apropos pattern, either a word list or a regexp.

<<Big wall of text>>

(fn SUBJECT) 

,---- ^^^^^^^^^^^^^^
| By the time I reach here, I have almost forgotten what "fn" I am looking
| at. I also find this style of reporting inconsisten with C-h v and C-h f
| style of reporting where the function signature is on the top.
`----

----------------

,---- ^^^^^^^^^^^^^^
| Can these separators be converted to page breaks? So that I can move
| between the different blocks using page navigation commands. Doing a
| incremental re-search for -----+ is painful particularly when some of
| the listed commands that have docstring which have horizontal rules in
| them.
`----

apropos
  Command: Show all meaningful Lisp symbols whose names match PATTERN.

<<Another big wall of text>>

(fn PATTERN &optional DO-ALL)

----------------
apropos-command
  Command: Show commands (interactively callable functions) that match
           PATTERN.


,----[ C-h v internal-doc-file-name RET ]
| internal-doc-file-name is a variable defined in `C source code'.
| Its value is "DOC-X"
| 
| Documentation:
| Name of file containing documentation strings of built-in symbols.
| 
| [back]
`----

,----
| Can someone clarify what the file is and what qualifies as "built-in"
| symbols. Does it include the "whole" of what ships with vanilla Emacs or
| just a subset of it. I tried looking around in the info manual. I found
| nothing much which could give me a sense of "coverage" of the reported
| list.
`----

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

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: Jambunathan K <kjambunathan <at> gmail.com>
Cc: 10823 <at> debbugs.gnu.org
Subject: Re: bug#10823: 24.0.93;
	Make `C-h d' reporting more consistent and usable
Date: Thu, 16 Feb 2012 08:48:26 -0500

> ----------------
> apropos-read-pattern
>   Function: Read an apropos pattern, either a word list or a regexp.

> <<Big wall of text>>

> (fn SUBJECT) 

> ,---- ^^^^^^^^^^^^^^
> | By the time I reach here, I have almost forgotten what "fn" I am looking
> | at. I also find this style of reporting inconsisten with C-h v and C-h f
> | style of reporting where the function signature is on the top.
> `----

It's a plain bug: when the "(fn FOO)" convention was added, the apropos
code was not updated correspondingly.  I.e. apropos needs to use
help-split-fundoc.

> ----------------

> ,---- ^^^^^^^^^^^^^^
> | Can these separators be converted to page breaks? So that I can move
> | between the different blocks using page navigation commands. Doing a

There are many ways to do that.  A trivial way is to set page-delimiter
in those buffers to a regexp that matches those lines.

> ,----[ C-h v internal-doc-file-name RET ]
> | internal-doc-file-name is a variable defined in `C source code'.
> | Its value is "DOC-X"
> | 
> | Documentation:
> | Name of file containing documentation strings of built-in symbols.
> | 
> | [back]
> `----

> ,----
> | Can someone clarify what the file is and what qualifies as "built-in"
> | symbols. Does it include the "whole" of what ships with vanilla Emacs or
> | just a subset of it. I tried looking around in the info manual. I found
> | nothing much which could give me a sense of "coverage" of the reported
> | list.
> `----

I don't understand the connection between this question and the
previous ones.  Is there any?
"built-in" here really means "included in the `emacs' binary",
i.e. either defined in C or preloaded.
But this is an internal variable which you shouldn't need to care about.


        Stefan

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

From: Jambunathan K <kjambunathan <at> gmail.com>
To: 10823-done <at> debbugs.gnu.org
Subject: Re: bug#10823: 24.0.93;
 Make `C-h d' reporting more consistent and usable
Date: Fri, 15 Nov 2013 10:05:11 +0530

OP here.  Closing it.

Previous Next

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