Bug 23300

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:

....