all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* bug#10823: 24.0.93; Make `C-h d' reporting more consistent and usable
@ 2012-02-16  5:03 Jambunathan K
  2012-02-16 13:48 ` Stefan Monnier
  2013-11-15  4:35 ` Jambunathan K
  0 siblings, 2 replies; 3+ messages in thread
From: Jambunathan K @ 2012-02-16  5:03 UTC (permalink / raw)
  To: 10823


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.
`----





^ permalink raw reply	[flat|nested] 3+ messages in thread

* bug#10823: 24.0.93; Make `C-h d' reporting more consistent and usable
  2012-02-16  5:03 bug#10823: 24.0.93; Make `C-h d' reporting more consistent and usable Jambunathan K
@ 2012-02-16 13:48 ` Stefan Monnier
  2013-11-15  4:35 ` Jambunathan K
  1 sibling, 0 replies; 3+ messages in thread
From: Stefan Monnier @ 2012-02-16 13:48 UTC (permalink / raw)
  To: Jambunathan K; +Cc: 10823

> ----------------
> 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





^ permalink raw reply	[flat|nested] 3+ messages in thread

* bug#10823: 24.0.93; Make `C-h d' reporting more consistent and usable
  2012-02-16  5:03 bug#10823: 24.0.93; Make `C-h d' reporting more consistent and usable Jambunathan K
  2012-02-16 13:48 ` Stefan Monnier
@ 2013-11-15  4:35 ` Jambunathan K
  1 sibling, 0 replies; 3+ messages in thread
From: Jambunathan K @ 2013-11-15  4:35 UTC (permalink / raw)
  To: 10823-done


OP here.  Closing it.





^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2013-11-15  4:35 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-02-16  5:03 bug#10823: 24.0.93; Make `C-h d' reporting more consistent and usable Jambunathan K
2012-02-16 13:48 ` Stefan Monnier
2013-11-15  4:35 ` Jambunathan K

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.