ALT Linux Bugzilla – #23300
[FR] save library descriptions from .el "preambles" (";;; Commentary")
Last modified: 2010-07-13 11:47:45
You need to
before you can comment on or make changes to this bug.
Often, the only place which holds a sensible doucmentation for an Emacs Lisp
library is the "preamble" of the source file. For example, in the section of
/usr/share/emacs/22.2/lisp/net/webjump.el.bz2 after the line
one can read useful information about the purpose and usage of this library
(cited below). But the user will be deprived of this documentation: if only the
emacs-common package is installed, this documentation is lost, because
emacs-common contains .elc's, and most .el's go into the optional emacs-el
$ rpm -qf /usr/share/emacs/22.2/lisp/net/webjump.el.bz2
$ rpm -qf /usr/share/emacs/22.2/lisp/net/webjump.elc
So, these commentary sections with documentation could be extracted and saved
separately in a special store in the emacs-common package; they could be
intergrated in to the Emacs help system: included in "apropos" searches, linked
to from the help screens whenever there is a link to the library, like in the
first line of the output from C-h f:
webjump is an interactive compiled Lisp function in `webjump.el'.
Or the .el/.elc separate packaging could be abandoned, because it results in
problems for a user: incomplete documentation, and remedying the problems is
too much work.
Complete quotation of the example documentation section from
/usr/share/emacs/22.2/lisp/net/webjump.el.bz2 , which the user is deprived of:
;; WebJump provides a sort of ``programmable hotlist'' of Web sites that can
;; quickly be invoked in your Web browser. Each Web site in the hotlist has a
;; name, and you select the desired site name via a completing string prompt in
;; the minibuffer. The URL for each Web site is defined as a static string or
;; a built-in or custom function, allowing interactive prompting for
;; site-specific queries and options.
;; Note that WebJump was originally intended to complement your conventional
;; browser-based hotlist, not replace it. (Though there's no reason you
;; couldn't use WebJump for your entire hotlist if you were so inclined.)
;; The `webjump-sites' variable, which defines the hotlist, defaults to some
;; example sites. You'll probably want to override it with your own favorite
;; sites. The documentation for the variable describes the syntax.
;; You may wish to add something like the following to your `.emacs' file:
;; (require 'webjump)
;; (global-set-key "\C-cj" 'webjump)
;; (setq webjump-sites
;; (append '(
;; ("My Home Page" . "www.someisp.net/users/joebobjr/")
;; ("Pop's Site" . "www.joebob-and-son.com/")
;; The above loads this package, binds `C-c j' to invoke WebJump, and adds your
;; personal favorite sites to the hotlist.
;; The `webjump-sample-sites' variable mostly contains some site entries that
;; are expected to be generally relevant to many users, but excluding
;; those that the GNU project would not want to recommend.
;; The `browse-url' package is used to submit URLs to the browser, so any
;; browser-specific configuration should be done there.
If you want to read sources - install sources.
(A note on Emacs usage.) I have overlooked that the part concerning accessing
and searching through the commentaries of the libraries is already implemented
by the "finder" library, cf. the commands `finder-commentary' and
`finder-by-keyword' (C-h p).
(In reply to comment #0)
> Often, the only place which holds a sensible doucmentation for an Emacs Lisp
> library is the "preamble" of the source file. For example, in the section of
> /usr/share/emacs/22.2/lisp/net/webjump.el.bz2 after the line
> ;;; Commentary:
> one can read useful information about the purpose and usage of this library
> (cited below). But the user will be deprived of this documentation: if only
> they could be
> intergrated in to the Emacs help system: included in "apropos" searches,