Using saved parent location: http://bzr.savannah.gnu.org/r/emacs/trunk/ Now on revision 101191. ------------------------------------------------------------ revno: 101191 committer: Chong Yidong branch nick: trunk timestamp: Wed 2010-08-25 23:31:34 -0400 message: Improvements to describe-package buffer. * lisp/help.el (help-map): Bind `C-h P' to describe-package. * lisp/menu-bar.el (menu-bar-describe-menu): Add describe-package. * lisp/emacs-lisp/package.el (package-refresh-contents): Catch errors when downloading archives. (describe-package-1): Add package commentary. (package-install-button-action): New function. (package-menu-mode-map): Bind ? to package-menu-describe-package. (package-menu-view-commentary): Function removed. (package-list-packages-internal): Hide the `package' package too. diff: === modified file 'etc/NEWS' --- etc/NEWS 2010-08-23 13:57:55 +0000 +++ etc/NEWS 2010-08-26 03:31:34 +0000 @@ -176,8 +176,12 @@ ** An Emacs Lisp package manager is now included. This is a convenient way to download and install additional packages, -from elpa.gnu.org. `M-x package-list-packages' shows a list of -packages, which can be selected for installation. +from elpa.gnu.org. + +*** `M-x list-packages' shows a list of packages, which can be +selected for installation. + +*** New command `describe-package', bound to `C-h P'. *** By default, all installed packages are loaded and activated automatically when Emacs starts up. To disable this, set === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2010-08-25 08:15:45 +0000 +++ lisp/ChangeLog 2010-08-26 03:31:34 +0000 @@ -1,3 +1,17 @@ +2010-08-26 Chong Yidong + + * help.el (help-map): Bind `C-h P' to describe-package. + + * menu-bar.el (menu-bar-describe-menu): Add describe-package. + + * emacs-lisp/package.el (package-refresh-contents): Catch errors + when downloading archives. + (describe-package-1): Add package commentary. + (package-install-button-action): New function. + (package-menu-mode-map): Bind ? to package-menu-describe-package. + (package-menu-view-commentary): Function removed. + (package-list-packages-internal): Hide the `package' package too. + 2010-08-25 Kenichi Handa * language/misc-lang.el ("Arabic"): New language environment. === modified file 'lisp/emacs-lisp/package.el' --- lisp/emacs-lisp/package.el 2010-08-24 21:36:33 +0000 +++ lisp/emacs-lisp/package.el 2010-08-26 03:31:34 +0000 @@ -216,6 +216,7 @@ (declare-function lm-header "lisp-mnt" (header)) (declare-function lm-commentary "lisp-mnt" (&optional file)) (declare-function dired-delete-file "dired" (file &optional recursive trash)) +(defvar url-http-end-of-headers) (defcustom package-archives '(("gnu" . "http://elpa.gnu.org/packages/")) "An alist of archives from which to fetch. @@ -1016,7 +1017,10 @@ (unless (file-exists-p package-user-dir) (make-directory package-user-dir t)) (dolist (archive package-archives) - (package--download-one-archive archive "archive-contents")) + (condition-case nil + (package--download-one-archive archive "archive-contents") + (error (message "Failed to download archive `%s'." + (car archive))))) (package-read-all-archive-contents)) ;;;###autoload @@ -1052,9 +1056,7 @@ guess) "Describe package: ") packages nil t nil nil guess)) - (list (if (equal val "") - guess - (intern val))))) + (list (if (equal val "") guess (intern val))))) (if (or (null package) (null (symbolp package))) (message "You did not specify a package") (help-setup-xref (list #'describe-package package) @@ -1064,38 +1066,60 @@ (describe-package-1 package))))) (defun describe-package-1 (package) - (let ((desc (cdr (assq package package-alist))) - reqs version installable) + (let ((package-name (symbol-name package)) + (built-in (assq package package--builtins)) + desc pkg-dir reqs version installable) (prin1 package) (princ " is ") - (cond - (desc - ;; This package is loaded (i.e. in `package-alist'). - (let (pkg-dir) - (setq version (package-version-join (package-desc-vers desc))) - (if (assq package package--builtins) - (princ "a built-in package.\n\n") - (setq pkg-dir (package--dir (symbol-name package) version)) - (if pkg-dir - (progn - (insert "a package installed in `") - (help-insert-xref-button (file-name-as-directory pkg-dir) - 'help-package-def pkg-dir) - (insert "'.\n\n")) - ;; This normally does not happen. - (insert "a deleted package.\n\n") - (setq version nil))))) - (t - ;; An uninstalled package. - (setq desc (cdr (assq package package-archive-contents)) + (if (setq desc (cdr (assq package package-alist))) + ;; This package is loaded (i.e. in `package-alist'). + (progn + (setq version (package-version-join (package-desc-vers desc))) + (cond (built-in + (princ "a built-in package.\n\n")) + ((setq pkg-dir (package--dir package-name version)) + (insert "an installed package.\n\n")) + (t ;; This normally does not happen. + (insert "a deleted package.\n\n") + (setq version nil)))) + ;; This package is not installed. + (setq desc (cdr (assq package package-archive-contents)) version (package-version-join (package-desc-vers desc)) installable t) - (insert "an installable package.\n\n"))) - (if version - (insert " Version: " version "\n")) + (insert "an uninstalled package.\n\n")) + + (insert " " (propertize "Status" 'face 'bold) ": ") + (cond (pkg-dir + (insert (propertize "Installed" 'face 'font-lock-comment-face)) + (insert " in `") + ;; Todo: Add button for uninstalling. + (help-insert-xref-button (file-name-as-directory pkg-dir) + 'help-package-def pkg-dir) + (insert "'.")) + (installable + (insert "Available -- ") + (let ((button-text (if (display-graphic-p) + "Install" + "[Install]")) + (button-face (if (display-graphic-p) + '(:box (:line-width 2 :color "dark grey") + :background "light grey" + :foreground "black") + 'link))) + (insert-text-button button-text + 'face button-face + 'follow-link t + 'package-symbol package + 'action 'package-install-button-action))) + (built-in + (insert (propertize "Built-in" 'face 'font-lock-builtin-face) ".")) + (t (insert "Deleted."))) + (insert "\n") + (when version + (insert " " (propertize "Version" 'face 'bold) ": " version "\n")) (setq reqs (package-desc-reqs desc)) (when reqs - (insert " Requires: ") + (insert " " (propertize "Requires" 'face 'bold) ": ") (let ((first t) name vers text) (dolist (req reqs) @@ -1110,28 +1134,45 @@ (t (insert ", "))) (help-insert-xref-button text 'help-package name)) (insert "\n"))) - (insert " Description: " (package-desc-doc desc) "\n") - ;; Todo: button for uninstalling a package. - (when installable - (let ((button-text (if (display-graphic-p) - "Install" - "[Install]")) - (button-face (if (display-graphic-p) - '(:box (:line-width 2 :color "dark grey") - :background "light grey" - :foreground "black") - 'link))) - (insert "\n") - (insert-text-button button-text - 'face button-face - 'follow-link t - 'package-symbol package - 'action (lambda (button) - (package-install - (button-get button 'package-symbol)) - (revert-buffer nil t) - (goto-char (point-min)))) - (insert "\n"))))) + (insert " " (propertize "Summary" 'face 'bold) + ": " (package-desc-doc desc) "\n\n") + + ;; Insert the package commentary. + ;; FIXME: We should try to be smarter about when to download. + (let ((readme (expand-file-name (concat package-name "-readme.txt") + package-user-dir))) + ;; Try downloading the commentary. If that fails, try an + ;; existing readme file in `package-user-dir'. + (cond ((let ((buffer + (condition-case nil + (url-retrieve-synchronously + (concat (package-archive-url package) + package-name "-readme.txt")) + (error nil))) + response) + (when buffer + (with-current-buffer buffer + (setq response (url-http-parse-response)) + (if (or (< response 200) (>= response 300)) + (setq response nil) + (setq buffer-file-name + (expand-file-name readme package-user-dir)) + (delete-region (point-min) (1+ url-http-end-of-headers)) + (save-buffer))) + (when response + (insert-buffer-substring buffer) + (kill-buffer buffer) + t)))) + ((file-readable-p readme) + (insert-file-contents readme) + (goto-char (point-max))))))) + +(defun package-install-button-action (button) + (let ((package (button-get button 'package-symbol))) + (when (y-or-n-p (format "Install package `%s'? " package)) + (package-install package) + (revert-buffer nil t) + (goto-char (point-min))))) ;;;; Package menu mode. @@ -1153,7 +1194,7 @@ (define-key map "~" 'package-menu-mark-obsolete-for-deletion) (define-key map "x" 'package-menu-execute) (define-key map "h" 'package-menu-quick-help) - (define-key map "?" 'package-menu-view-commentary) + (define-key map "?" 'package-menu-describe-package) (define-key map [menu-bar package-menu] (cons "Package" menu-map)) (define-key menu-map [mq] '(menu-item "Quit" quit-window @@ -1297,32 +1338,8 @@ (interactive) (message "n-ext, i-nstall, d-elete, u-nmark, x-ecute, r-efresh, h-elp")) -(defun package-menu-view-commentary () - "Display information about this package. -For single-file packages, shows the commentary section from the header. -For larger packages, shows the README file." - (interactive) - (let* ((pkg-name (package-menu-get-package)) - (buffer (url-retrieve-synchronously - (concat (package-archive-url pkg-name) - pkg-name - "-readme.txt"))) - start-point ok) - (with-current-buffer buffer - ;; FIXME: it would be nice to work with any URL type. - (setq start-point url-http-end-of-headers) - (setq ok (eq (url-http-parse-response) 200))) - (let ((new-buffer (get-buffer-create "*Package Info*"))) - (with-current-buffer new-buffer - (let ((buffer-read-only nil)) - (erase-buffer) - (insert "Package information for " pkg-name "\n\n") - (if ok - (insert-buffer-substring buffer start-point) - (insert "This package lacks a README file or commentary.\n")) - (goto-char (point-min)) - (view-mode))) - (display-buffer new-buffer t)))) +(define-obsolete-function-alias + 'package-menu-view-commentary 'package-menu-describe-package "24.1") ;; Return the name of the package on the current line. (defun package-menu-get-package () @@ -1426,7 +1443,7 @@ (setq name (car elt) desc (cdr elt) hold (assq name package-load-list)) - (unless (eq name 'emacs) + (unless (memq name '(emacs package)) (setq info-list (package-list-maybe-add name (package-desc-vers desc) === modified file 'lisp/help.el' --- lisp/help.el 2010-07-10 18:52:53 +0000 +++ lisp/help.el 2010-08-26 03:31:34 +0000 @@ -103,6 +103,7 @@ (define-key map "m" 'describe-mode) (define-key map "n" 'view-emacs-news) (define-key map "p" 'finder-by-keyword) + (define-key map "P" 'describe-package) (define-key map "r" 'info-emacs-manual) (define-key map "s" 'describe-syntax) (define-key map "t" 'help-with-tutorial) === modified file 'lisp/menu-bar.el' --- lisp/menu-bar.el 2010-08-25 06:53:55 +0000 +++ lisp/menu-bar.el 2010-08-26 03:31:34 +0000 @@ -1485,6 +1485,9 @@ (define-key menu-bar-describe-menu [describe-current-display-table] `(menu-item ,(purecopy "Describe Display Table") describe-current-display-table :help ,(purecopy "Describe the current display table"))) +(define-key menu-bar-describe-menu [describe-package] + `(menu-item ,(purecopy "Describe Package...") describe-package + :help ,(purecopy "Display documentation of a Lisp package"))) (define-key menu-bar-describe-menu [describe-face] `(menu-item ,(purecopy "Describe Face...") describe-face :help ,(purecopy "Display the properties of a face"))) @@ -1616,11 +1619,11 @@ (define-key menu-bar-help-menu [sep2] menu-bar-separator) (define-key menu-bar-help-menu [external-packages] - `(menu-item ,(purecopy "External Packages") menu-bar-help-extra-packages + `(menu-item ,(purecopy "Finding Extra Packages") menu-bar-help-extra-packages :help ,(purecopy "Lisp packages distributed separately for use in Emacs"))) (define-key menu-bar-help-menu [find-emacs-packages] - `(menu-item ,(purecopy "Find Emacs Packages") finder-by-keyword - :help ,(purecopy "Find packages and features by keyword"))) + `(menu-item ,(purecopy "Search Built-in Packages") finder-by-keyword + :help ,(purecopy "Find built-in packages and features by keyword"))) (define-key menu-bar-help-menu [more-manuals] `(menu-item ,(purecopy "More Manuals") ,menu-bar-manuals-menu)) (define-key menu-bar-help-menu [emacs-manual] ------------------------------------------------------------ revno: 101190 [merge] committer: Kenichi Handa branch nick: trunk timestamp: Thu 2010-08-26 09:51:37 +0900 message: xdisp.c (compute_stop_pos): Pay attention to bidi scan direction on calling composition_compute_stop_pos. diff: === modified file 'src/ChangeLog' --- src/ChangeLog 2010-08-25 05:58:15 +0000 +++ src/ChangeLog 2010-08-26 00:47:34 +0000 @@ -1,3 +1,8 @@ +2010-08-26 Kenichi Handa + + * xdisp.c (compute_stop_pos): Pay attention to bidi scan direction + on calling composition_compute_stop_pos. + 2010-08-25 Kenichi Handa * fontset.c (reorder_font_vector): Prefer a font-spec specifying === modified file 'src/xdisp.c' --- src/xdisp.c 2010-08-21 13:25:03 +0000 +++ src/xdisp.c 2010-08-26 00:47:34 +0000 @@ -3177,7 +3177,7 @@ { register INTERVAL iv, next_iv; Lisp_Object object, limit, position; - EMACS_INT charpos, bytepos; + EMACS_INT charpos, bytepos, stoppos; /* If nowhere else, stop at the end. */ it->stop_charpos = it->end_charpos; @@ -3267,8 +3267,12 @@ } } + if (it->bidi_p && it->bidi_it.scan_dir < 0) + stoppos = -1; + else + stoppos = it->stop_charpos; composition_compute_stop_pos (&it->cmp_it, charpos, bytepos, - it->stop_charpos, it->string); + stoppos, it->string); xassert (STRINGP (it->string) || (it->stop_charpos >= BEGV ------------------------------------------------------------ revno: 101189 [merge] committer: Kenichi Handa branch nick: trunk timestamp: Thu 2010-08-26 09:29:02 +0900 message: Add Arabic support. diff: === modified file 'etc/ChangeLog' --- etc/ChangeLog 2010-08-23 13:57:55 +0000 +++ etc/ChangeLog 2010-08-25 05:15:20 +0000 @@ -1,3 +1,7 @@ +2010-08-25 Kenichi Handa + + * HELLO: Change designation sequences for Arabic text. + 2010-08-23 Michael Albinus * NEWS: dbus.el supports alternative buses. === modified file 'etc/HELLO' --- etc/HELLO 2010-05-08 18:47:07 +0000 +++ etc/HELLO 2010-08-25 05:13:27 +0000 @@ -4,7 +4,7 @@ Europe: ,A!(BHola!, Gr,A|_(B Gott, Hyv,Add(B p,Ad(Biv,Add(B, Tere ,Au(Bhtust, Bon,Cu(Bu Cze,B6f(B!, Dobr,B}(B den, ,L7T`PRabRcYbU(B!, ,FCei\(B ,Fsar(B, $,1J2J0J;J0J@JOJ=J1J0(B Africa: $(3!A!,!>(B - Middle/Near East: ,Hylem(B, ,GGdSqdGe(B ,GYdjce(B + Middle/Near East: ,Hylem(B, $,1-g.$-s.1.$-g.%(B $,1-y.$.*.#.%(B South Asia: $,19h9n9x:-9d:'(B, $,15h5n5x6-5d6'(B, $,1?(?.?8?M>u?>?0(B, $,1@H@N@X@m@5@^@P@"(B, $,1;6;A;#;?;,;G(B, $,1AFAzB4AvB=B AqB*(B, $,1-=U=~=p=B(B, $(7"7"!#C!;"E"S"G!;"7"2"[!;"D"["#"G!>(B South East Asia: $,1\'\f\:\V\4\?\]\:(B, (1JP:R-4U(B, $,1H9H$HZHYH"H6b727>(B) $,17(7.787M6u7>70(B Braille $,2(3(1('('(5(B Burmese ($,1H9H\H4HZH9HL(B) $,1H9H$HZHYH"H + + * language/misc-lang.el ("Arabic"): New language environment. + Setup composition-function-table for Arabic characters. + + * international/fontset.el (setup-default-fontset): Fix typo for + arabic OTF spec (fini->fina). + 2010-08-25 Jan Djärv * menu-bar.el (menu-bar-set-tool-bar-position): Set frame parameter === modified file 'lisp/international/fontset.el' --- lisp/international/fontset.el 2010-03-01 11:50:57 +0000 +++ lisp/international/fontset.el 2010-08-25 05:13:27 +0000 @@ -433,7 +433,7 @@ (nil . "koi8-r")) (arabic ,(font-spec :registry "iso10646-1" - :otf '(arab nil (init medi fini liga))) + :otf '(arab nil (init medi fina liga))) (nil . "MuleArabic-0") (nil . "MuleArabic-1") (nil . "MuleArabic-2") === modified file 'lisp/international/mule-cmds.el' --- lisp/international/mule-cmds.el 2010-06-09 22:08:50 +0000 +++ lisp/international/mule-cmds.el 2010-08-25 05:13:27 +0000 @@ -2179,7 +2179,7 @@ ("af" . "Latin-1") ; Afrikaans ("am" "Ethiopic" utf-8) ; Amharic ("an" . "Latin-9") ; Aragonese - ; ar Arabic glibc uses 8859-6 + ("ar" . "Arabic") ; as Assamese ; ay Aymara ("az" . "UTF-8") ; Azerbaijani === modified file 'lisp/language/misc-lang.el' --- lisp/language/misc-lang.el 2010-03-08 01:50:35 +0000 +++ lisp/language/misc-lang.el 2010-08-25 05:13:27 +0000 @@ -40,8 +40,9 @@ IPA is International Phonetic Alphabet for English, French, German and Italian."))) -;; This is for Arabic. But, as we still don't have Arabic language -;; support, we at least define a coding system here. +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +;; Arabic +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; (define-coding-system 'iso-8859-6 "ISO-8859-6 based encoding (MIME:ISO-8859-6)." @@ -58,6 +59,19 @@ :mime-charset 'windows-1256) (define-coding-system-alias 'cp1256 'windows-1256) +(set-language-info-alist + "Arabic" '((charset unicode) + (coding-system utf-8 iso-8859-6 windows-1256) + (coding-priority utf-8 iso-8859-6 windows-1256) + (input-method . "arabic") + (sample-text . "Arabic السّلام عليكم") + (documentation . "Bidirectional editing is supported."))) + +(set-char-table-range + composition-function-table + '(#x600 . #x6FF) + (list ["[\u0600-\u06FF]+" 0 font-shape-gstring])) + (provide 'misc-lang) ;; arch-tag: 6953585c-1a1a-4c09-be82-a2518afb6074 ------------------------------------------------------------ revno: 101188 committer: Tom Tromey branch nick: trunk timestamp: Wed 2010-08-25 14:25:32 -0600 message: * vol2.texi (Top): Update. * vol1.texi (Top): Update. * tips.texi (Library Headers): Mention Package-Version and Package-Requires. * package.texi: New file. * os.texi (System Interface): Update pointers. * elisp.texi (Top): Link to new nodes. Include package.texi. * anti.texi (Antinews): Update pointers. diff: === modified file 'doc/lispref/ChangeLog' --- doc/lispref/ChangeLog 2010-08-25 05:23:47 +0000 +++ doc/lispref/ChangeLog 2010-08-25 20:25:32 +0000 @@ -1,3 +1,14 @@ +2010-08-25 Tom Tromey + + * vol2.texi (Top): Update. + * vol1.texi (Top): Update. + * tips.texi (Library Headers): Mention Package-Version and + Package-Requires. + * package.texi: New file. + * os.texi (System Interface): Update pointers. + * elisp.texi (Top): Link to new nodes. Include package.texi. + * anti.texi (Antinews): Update pointers. + 2010-08-25 Eli Zaretskii * processes.texi (Filter Functions): Fix last change. === modified file 'doc/lispref/anti.texi' --- doc/lispref/anti.texi 2010-01-13 08:35:10 +0000 +++ doc/lispref/anti.texi 2010-08-25 20:25:32 +0000 @@ -6,7 +6,7 @@ @c This node must have no pointers. -@node Antinews, GNU Free Documentation License, System Interface, Top +@node Antinews, GNU Free Documentation License, Packaging, Top @appendix Emacs 22 Antinews @c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries @c with the above version number. === modified file 'doc/lispref/elisp.texi' --- doc/lispref/elisp.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/elisp.texi 2010-08-25 20:25:32 +0000 @@ -159,6 +159,8 @@ * System Interface:: Getting the user id, system type, environment variables, and other such things. +* Packaging:: Preparing Lisp code for distribution. + Appendices * Antinews:: Info for users downgrading to Emacs 22. @@ -1394,6 +1396,12 @@ * Session Management:: Saving and restoring state with X Session Management. +Preparing Lisp code for distribution + +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. + Starting Up Emacs * Startup Summary:: Sequence of actions Emacs performs at startup. @@ -1490,6 +1498,8 @@ @include display.texi @include os.texi +@include package.texi + @c MOVE to Emacs Manual: include misc-modes.texi @c appendices === modified file 'doc/lispref/os.texi' --- doc/lispref/os.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/os.texi 2010-08-25 20:25:32 +0000 @@ -5,7 +5,7 @@ @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/os -@node System Interface, Antinews, Display, Top +@node System Interface, Packaging, Display, Top @chapter Operating System Interface This chapter is about starting and getting out of Emacs, access to === added file 'doc/lispref/package.texi' --- doc/lispref/package.texi 1970-01-01 00:00:00 +0000 +++ doc/lispref/package.texi 2010-08-25 20:25:32 +0000 @@ -0,0 +1,197 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 2010 +@c Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../../info/package +@node Packaging, Antinews, System Interface, Top +@chapter Preparing Lisp code for distribution +@cindex packaging + + Emacs provides a standard way for Emacs Lisp code to be distributed +to users. This approach lets users easily download, install, +uninstall, and upgrade Lisp code that they might want to use. + + A @dfn{package} is simply one or more files, formatted and bundled +in a particular way. Typically a package includes primarily Emacs +Lisp code, but it is possible to create other kinds of packages as +well. + +@menu +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. +@end menu + +@node Packaging Basics +@section Packaging Basics +@cindex packaging basics + + A package has a few attributes: +@cindex package attributes + +@table @asis +@item Name +A string, the name of the package. This attribute is mandatory. If +it does not exist, the package cannot be installed by the package +manager. + +@item Version +A version number, which is anything that can be parsed by +@code{version-to-list}. This attribute is mandatory. If it does not +exist, the package cannot be installed by the package manager. + +@item Brief description +This is shown to the user in the package menu buffer. It is just a +single line. On a terminal with 80 characters per line, there are +only 36 characters available in the package menu mode for showing the +brief description, so it is best to keep it very brief. If no brief +name is given, an empty string is used. + +@item Long description +This can be a @file{README} file or the like. This is available to +the user before the package is installed, via the package menu. It +should more fully describe the package and its capabilities, so a user +can read it to decide whether he wants to install the package. This +attribute is optional. + +@item Dependencies +This is a list of other packages and their minimal acceptable +versions. This is used both at download time (to make sure all the +needed code is available) and at activation time (to ensure a package +is only activated if all its dependencies have been successfully +activated). This attribute is optional. + +@item Manual +A package can optionally include an Info manual. +@end table + + Conceptually, a package goes through several state transitions (in +reality some of these transitions are grouped together): + +@table @asis +@item Download +Fetch the package from somewhere. + +@item Install +Unpack the package, or write a @file{.el} file into the appropriate +install directory. This step also includes extracting autoloads and +byte-compiling the Emacs Lisp code. + +@item Activate +Update @code{load-path} and @code{Info-directory-list} and evaluate +the autoloads, so that the package is ready for the user to use. +@end table + + It is best for users if packages do not do too much work at +activation time. The best approach is to have activation consist of +some autoloads and little more. + +@node Simple Packages +@section Simple Packages +@cindex single file packages + + The simplest package consists of a single Emacs Lisp source file. +In this case, all the attributes of the package (@pxref{Packaging +Basics}) are taken from this file. + + The package system expects this @file{.el} file to conform to the +Emacs Lisp library header conventions. @xref{Library Headers}. + + The name of the package is the same as the base name of the +@file{.el} file, as written in the first comment line. For example, +given the header line: + +@smallexample +;;; superfrobnicator.el --- frobnicate and bifurcate flanges +@end smallexample + +the package name will be @samp{superfrobnicator}. + + The short description of the package is also taken from the first +line of the file. + + If the file has a ``Commentary'' header, then it is used as the long +description. + + The version of the package comes either from the ``Package-Version'' +header, if it exists, or from the ``Version'' header. A package is +required to have a version number. Each release of a package must be +accompanied by an increase in the version number. + + If the file has a ``Package-Requires'' header, then that is used as +the package dependencies. Otherwise, the package is assumed not to +have any dependencies. + + A single-file package cannot have an Info manual. + + The file will be scanned for autoload cookies at install time. +@xref{Autoload}. + +@node Multi-file Packages +@section Multi-file Packages +@cindex multi-file packages + + A multi-file package is just a @file{.tar} file. While less +convenient to create than a single-file package, a multi-file package +also offers more features: it can include an Info manual, multiple +Emacs Lisp files, and also other data files needed by a package. + + The contents of the @file{.tar} file must all appear beneath a +single directory, named after the package and version. Files can +appear in subdirectories of this top-most directory, but Emacs Lisp +code will only be found (and thus byte-compiled) at the top-most +level. Also, the @file{.tar} file is typically also given this same +name. For example, if you are distributing version 1.3 of the +superfrobnicator, the package file would be named +``superfrobnicator-1.3.tar'' and the contents would all appear in the +directory @file{superfrobnicator-1.3} in that @file{.tar}. + + The package must include a @file{-pkg.el} file, named after the +package. In our example above, this file would be called +@file{superfrobnicator-pkg.el}. This file must have a single form in +it, a call to @code{define-package}. The package dependencies and +brief description are taken from this form. + +@defun define-package name version &optional docstring requirements +Define a package. @var{name} is the name of the package, a string. +@var{version} is the package's version, a string. It must be in a +form that can be understood by @code{version-to-list}. +@var{docstring} is the short description of the package. +@var{requirements} is a list of required packages and their versions. +@end defun + + If a @file{README} file exists in the content directory, then it is +used as the long description. + + If the package has an Info manual, you should distribute the needed +info files, plus a @file{dir} file made with @command{install-info}. +@xref{Invoking install-info, Invoking install-info, Invoking +install-info, texinfo, Texinfo}. + + Do not include any @file{.elc} files in the package. Those will be +created at install time. Note that there is no way to control the +order in which files are byte-compiled; your package must be robust +here. + + The installation process will scan all the @file{.el} files in the +package for autoload cookies. @xref{Autoload}. They are extracted +into a @file{-autoloads.el} file (e.g., +@file{superfrobnicator-autoloads.el}), so do not include a file of +that name in your package. + + Any other files in the @file{.tar} file are simply unpacked when the +package is installed. This can be useful if your package needs +auxiliary data files --- e.g., icons or sounds. + + Emacs Lisp code installed via the package manager must take special +care to be location-independent. One easy way to do this is to make +references to auxiliary data files relative to @var{load-file-name}. +For example: + +@smallexample +(defconst superfrobnicator-base (file-name-directory load-file-name)) + +(defun superfrobnicator-fetch-image (file) + (expand-file-name file superfrobnicator-base)) +@end smallexample === modified file 'doc/lispref/tips.texi' --- doc/lispref/tips.texi 2010-06-23 03:36:56 +0000 +++ doc/lispref/tips.texi 2010-08-25 20:25:32 +0000 @@ -1052,6 +1052,31 @@ This field is important; it's how people will find your package when they're looking for things by topic area. To separate the keywords, you can use spaces, commas, or both. + +@item Package-Version +If @samp{Version} is not suitable for use by the package manager, then +a package can define @samp{Package-Version}; it will be used instead. +This is handy if @samp{Version} is an RCS id or something else that +cannot be parsed by @code{version-to-list}. @xref{Packaging Basics}. + +@item Package-Requires +If this exists, it names packages on which the current package depends +for proper operation. @xref{Packaging Basics}. This is used by the +package manager both at download time (to ensure that a complete set +of packages is downloaded) and at activation time (to ensure that a +package is activated if and only if all its dependencies have been). + +Its format is a list of lists. The @code{car} of each sub-list is the +name of a package, as a symbol. The @code{cadr} of each sub-list is +the minimum acceptable version number, as a string. For instance: + +@smallexample +;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2")) +@end smallexample + +The package code automatically defines a package named @samp{emacs} +with the version number of the currently running Emacs. This can be +used to require a minimal version of Emacs for a package. @end table Just about every Lisp library ought to have the @samp{Author} and === modified file 'doc/lispref/vol1.texi' --- doc/lispref/vol1.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/vol1.texi 2010-08-25 20:25:32 +0000 @@ -180,6 +180,8 @@ * System Interface:: Getting the user id, system type, environment variables, and other such things. +* Packaging:: Preparing Lisp code for distribution. + Appendices * Antinews:: Info for users downgrading to Emacs 22. @@ -1415,6 +1417,12 @@ * Session Management:: Saving and restoring state with X Session Management. +Preparing Lisp code for distribution + +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. + Starting Up Emacs * Startup Summary:: Sequence of actions Emacs performs at startup. === modified file 'doc/lispref/vol2.texi' --- doc/lispref/vol2.texi 2010-07-10 18:52:53 +0000 +++ doc/lispref/vol2.texi 2010-08-25 20:25:32 +0000 @@ -179,6 +179,8 @@ * System Interface:: Getting the user id, system type, environment variables, and other such things. +* Packaging:: Preparing Lisp code for distribution. + Appendices * Antinews:: Info for users downgrading to Emacs 22. @@ -1414,6 +1416,12 @@ * Session Management:: Saving and restoring state with X Session Management. +Preparing Lisp code for distribution + +* Packaging Basics:: The basic concepts of Emacs Lisp packages. +* Simple Packages:: How to package a single .el file. +* Multi-file Packages:: How to package multiple files. + Starting Up Emacs * Startup Summary:: Sequence of actions Emacs performs at startup. ------------------------------------------------------------ revno: 101187 committer: Jan D branch nick: trunk timestamp: Wed 2010-08-25 08:53:55 +0200 message: * menu-bar.el (menu-bar-set-tool-bar-position): Set frame parameter on all frames. diff: === modified file 'lisp/ChangeLog' --- lisp/ChangeLog 2010-08-25 02:27:58 +0000 +++ lisp/ChangeLog 2010-08-25 06:53:55 +0000 @@ -1,3 +1,8 @@ +2010-08-25 Jan Djärv + + * menu-bar.el (menu-bar-set-tool-bar-position): Set frame parameter + on all frames. + 2010-08-24 Vinicius Jose Latorre * whitespace.el: Allow cleaning up blanks without blank === modified file 'lisp/menu-bar.el' --- lisp/menu-bar.el 2010-08-22 20:02:16 +0000 +++ lisp/menu-bar.el 2010-08-25 06:53:55 +0000 @@ -970,7 +970,8 @@ (defun menu-bar-set-tool-bar-position (position) (customize-set-variable 'tool-bar-mode t) - (set-frame-parameter nil 'tool-bar-position position) + (dolist (frame (frame-list)) + (set-frame-parameter frame 'tool-bar-position position)) (customize-set-variable 'default-frame-alist (cons (cons 'tool-bar-position position) (assq-delete-all 'tool-bar-position ------------------------------------------------------------ Use --include-merges or -n0 to see merged revisions.