23300 2010-04-08 09:16:00 +0400 [FR] save library descriptions from .el "preambles" (";;; Commentary") 2010-07-13 11:47:45 +0400 1 1 3 Distributions Branch 4.1 emacs22-common unspecified all Linux CLOSED NOTABUG P3 normal --- 1 imz eugvv qa-4.1 oldest_to_newest 108469 0 imz 2010-04-08 09:16:00 +0400 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: .... 108471 1 eugvv 2010-04-08 10:03:37 +0400 If you want to read sources - install sources. 110569 2 imz 2010-07-13 11:47:45 +0400 (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,