Bug 23300 - [FR] save library descriptions from .el "preambles" (";;; Commentary")
: [FR] save library descriptions from .el "preambles" (";;; Commentary")
Status: CLOSED NOTABUG
: Branch 4.1
(All bugs in Branch 4.1/emacs22-common)
: unspecified
: all Linux
: P3 normal
Assigned To:
:
:
:
:
:
  Show dependency tree
 
Reported: 2010-04-08 09:16 by
Modified: 2010-07-13 11:47 (History)


Attachments


Note

You need to log in before you can comment on or make changes to this bug.


Description From 2010-04-08 09:16:00
emacs22-common-22.2-alt5

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

$ rpm -qf /usr/share/emacs/22.2/lisp/net/webjump.el.bz2
emacs22-el-22.2-alt5
$ rpm -qf /usr/share/emacs/22.2/lisp/net/webjump.elc
emacs22-common-22.2-alt5
$ 

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:


;;; Commentary:

;; 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/")
;;                   )
;;                 webjump-sample-sites))
;;
;; 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.

;;; Code:

....
------- Comment #1 From 2010-04-08 10:03:37 -------
If you want to read sources - install sources.
------- Comment #2 From 2010-07-13 11:47:45 -------
(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,