X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Fxemacs%2Fpackages.texi;h=5696ebe57fece9f3e70b64a2e40f329ee05097fc;hb=e21533bd43f4077dcc1fb9560c93c82c6d855d19;hp=6a9cba0dd7fb4875dd0c24b53a0dc0d5fd379ddf;hpb=dbf2768f7b146e97e37a27316f70bb313f1acf15;p=chise%2Fxemacs-chise.git.1 diff --git a/man/xemacs/packages.texi b/man/xemacs/packages.texi index 6a9cba0..5696ebe 100644 --- a/man/xemacs/packages.texi +++ b/man/xemacs/packages.texi @@ -20,7 +20,6 @@ local needs with safe removal of unnecessary code. * Installing Packages:: How to install packages. * Building Packages:: Building packages from CVS sources. * Local.rules File:: This is an important file that you must create. -* Creating Packages:: The basics. * Available Packages:: A brief directory of packaged LISP. @end menu @@ -32,13 +31,13 @@ local needs with safe removal of unnecessary code. There are two main flavors of packages. @itemize @bullet -@item +@item Regular Packages @cindex regular packages A regular package is one in which multiple files are involved and one may not in general safely remove any of them. -@item +@item Single-File Packages @cindex single-file packages A single-file package is an aggregate collection of thematically @@ -70,6 +69,7 @@ savings). Currently, source packages are only available via CVS. See @url{http://cvs.xemacs.org/} for details. + @node Installing Packages, Building Packages, Package Terminology, Packages @comment node-name, next, previous, up @cindex installing packages @@ -95,7 +95,7 @@ where you grabbed the core distribution from, and are located in the subdirectory @file{packages}. Package file names follow the naming convention @file{--pkg.tar.gz}. -If you have @ref{(EFS)}, packages can be installed over the network. +If you have EFS @ref{(EFS)}, packages can be installed over the network. Alternatively, if you have copies of the packages locally, you can install packages from a local disk or CDROM. @@ -107,13 +107,13 @@ are installed, using the visual package browser and installer. You can access it via the menus: @example - Tools -> Packages -> List and Install +Tools -> Packages -> List and Install @end example Or, you can get to it via the keyboard: @example -M-x pui-list-packages +@code{M-x pui-list-packages} @end example Hint to system administrators of multi-user systems: it might be a good @@ -125,10 +125,10 @@ using the @code{package-get-package-provider} function. Eg., if you know that you need @code{thingatpt}, type: @example -M-x package-get-package-provider RET thingatpt +@code{M-x package-get-package-provider RET thingatpt} @end example -which will return something like (fsf-compat "1.08"). You can the use +which will return something like @samp{(fsf-compat "1.08")}. You can the use one of the methods above for installing the package you want. @subsection XEmacs and Installing Packages @@ -136,80 +136,18 @@ one of the methods above for installing the package you want. There are three main ways to install packages: @menu -* Sumo:: All at once, using the 'Sumo Tarball'. -* Manually:: Using individual package tarballs. * Automatically:: Using the package tools from XEmacs. +* Manually:: Using individual package tarballs. +* Sumo:: All at once, using the 'Sumo Tarball'. * Which Packages:: Which packages to install. * Removing Packages:: Removing packages. @end menu But regardless of the method you use to install packages, they can only -be used by XEmacs after a restart. - -@node Sumo, Manually, ,Installing Packages -@comment node-name, next, previous, up -@cindex sumo package install -@heading Installing the Sumo Packages: -Those with little time, cheap connections and plenty of disk space can -install all the packages at once using the sumo tarballs. -Download the file: @file{xemacs-sumo.tar.gz} - -For an XEmacs compiled with Mule you also need: @file{xemacs-mule-sumo.tar.gz} - -N.B. They are called 'Sumo Tarballs' for good reason. They are -currently about 19MB and 4.5MB (gzipped) respectively. - -Install them by: - -@code{cd $prefix/lib/xemacs ; gunzip -c | tar xvf - RET} - -Or, if you have GNU tar: - -@code{cd $prefix/lib/xemacs ; tar zxvf /path/to/ RET} - -As the Sumo tarballs are not regenerated as often as the individual -packages, it is recommended that you use the automatic package tools -afterwards to pick up any recent updates. - -@node Manually, Automatically, Sumo, Installing Packages -@comment node-name, next, previous, up -@cindex manual package install -@heading Manual Package Installation: -Fetch the packages from the FTP site, CD-ROM whatever. The filenames -have the form @file{name--pkg.tar.gz} and are gzipped tar files. For -a fresh install it is sufficient to untar the file at the top of the -package hierarchy. - -Note: If you are upgrading packages already installed, it's best to -remove the old package first @ref{Removing Packages}. - -For example if we are installing the @file{xemacs-base} -package (version 1.48): - -@example - mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet - cd $prefix/lib/xemacs/xemacs-packages RET - gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET - -Or if you have GNU tar, the last step can be: - - tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET -@end example - -For MULE related packages, it is best to untar into the mule-packages -hierarchy, i.e. for the @file{mule-base} package, version 1.37: - -@example - mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet - cd $prefix/lib/xemacs/mule-packages RET - gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET - -Or if you have GNU tar, the last step can be: - - tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET -@end example +be used by XEmacs after a restart unless the package in question has not +been previously installed. -@node Automatically, Which Packages ,Manually, Installing Packages +@node Automatically, Manually, ,Installing Packages @comment node-name, next, previous, up @cindex automatic package install @cindex package tools @@ -229,33 +167,31 @@ you need are: and optionally: - mule-base - Needed if you want to use XEmacs with MULE. + mailcrypt - To do PGP verification of the @file{package-index} + file. @end example After installing these by hand, fire up XEmacs and follow these steps. @enumerate 1 -@item +@item Choose a download site. -via menu: Tools -> Packages -> Add Download Site +via menu: Tools -> Packages -> Set Download Site via keyb: @code{M-x customize-variable RET package-get-remote RET} (put in the details of remote host and directory) If the package tarballs _AND_ the package-index file are in a -local directory, you can: @code{M-x pui-add-install-directory RET} +local directory, you can: @code{M-x pui-set-local-package-get-directory RET} -@item +@item Obtain a list of packages and display the list in a buffer named @file{*Packages*}. menu: Tools -> Packages -> List & Install keyb: @code{M-x pui-list-packages RET} XEmacs will now connect to the remote site and download the -latest package-index file. If you see an error about the -package-index entries not being PGP signed, you can safely -ignore this because PGP has not been integrated into the XEmacs -package tools yet. +latest package-index file. The visual package browser will then display a list of all packages. Help information will be displayed at the very bottom of the buffer; you @@ -274,11 +210,11 @@ The package has been marked for installation/update. @end table If there is no character in the first column, the package has been -installed and is up-to-date. +installed and is up to date. From here, you can select or unselect packages for installation using the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from -the (Popup) Menu. +the Popup @kbd{Mouse-3} Menu. Once you've finished selecting the packages, you can press the @kbd{x} key (or use the menu) to actually install the packages. Note that you will have to restart XEmacs for XEmacs to @@ -307,15 +243,17 @@ Kill the package buffer. @end table Moving the mouse over a package will also cause additional information -about the package to be displayed in the minibuffer. +about the package to be displayed in the minibuffer. If you have +balloon-help enabled a balloon-help frame will pop up and display +additional package information also. -@item +@item Choose the packages you wish to install. mouse: Click button 2 on the package name. keyb: @kbd{RET} on the package name -@item +@item Make sure you have everything you need. menu: Packages -> Add Required keyb: @kbd{r} @@ -327,7 +265,7 @@ those packages also. For novices and gurus alike, this step can save your bacon. It's easy to forget to install a critical package. -@item +@item Download and install the packages. menu: Packages -> Install/Remove Selected keyb: @kbd{x} @@ -343,7 +281,81 @@ Enter the name of the package (e.g., @code{prog-modes}), and XEmacs will search for the latest version and install it and any packages that it depends upon. -@node Which Packages, Removing Packages, Automatically, Installing Packages +@heading Keeping Packages Up To Date: +Once you have the packages you want installed (using any of the above +methods) you'll want to keep them up to date. You can do this easily +from the menubar: + +@example +Tools -> Packages -> Set Download Site +Tools -> Packages -> Update Installed Packages +@end example + + +@node Manually, Sumo, Automatically, Installing Packages +@comment node-name, next, previous, up +@cindex manual package install +@heading Manual Package Installation: +Fetch the packages from the FTP site, CD-ROM whatever. The filenames +have the form @file{name--pkg.tar.gz} and are gzipped tar files. For +a fresh install it is sufficient to untar the file at the top of the +package hierarchy. + +Note: If you are upgrading packages already installed, it's best to +remove the old package first @ref{Removing Packages}. + +For example if we are installing the @file{xemacs-base} +package (version 1.48): + +@example + mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet + cd $prefix/lib/xemacs/xemacs-packages RET + gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET + +Or if you have GNU tar, the last step can be: + + tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET +@end example + +For MULE related packages, it is best to untar into the mule-packages +hierarchy, i.e. for the @file{mule-base} package, version 1.37: + +@example + mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet + cd $prefix/lib/xemacs/mule-packages RET + gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET + +Or if you have GNU tar, the last step can be: + + tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET +@end example + +@node Sumo, Which Packages, Manually, Installing Packages +@comment node-name, next, previous, up +@cindex sumo package install +@heading Installing the Sumo Packages: +Those with little time, cheap connections and plenty of disk space can +install all the packages at once using the sumo tarballs. +Download the file: @file{xemacs-sumo.tar.gz} + +For an XEmacs compiled with Mule you also need: @file{xemacs-mule-sumo.tar.gz} + +N.B. They are called 'Sumo Tarballs' for good reason. They are +currently about 19MB and 4.5MB (gzipped) respectively. + +Install them by: + +@code{cd $prefix/lib/xemacs ; gunzip -c | tar xvf - RET} + +Or, if you have GNU tar: + +@code{cd $prefix/lib/xemacs ; tar zxvf /path/to/ RET} + +As the Sumo tarballs are not regenerated as often as the individual +packages, it is recommended that you use the automatic package tools +afterwards to pick up any recent updates. + +@node Which Packages, Removing Packages, Sumo, Installing Packages @comment node-name, next, previous, up @cindex which packages @cindex choosing packages @@ -354,7 +366,7 @@ everything. A good minimal set of packages for XEmacs-latin1 would be xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs, edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes, -text-modes, time +text-modes, time, mailcrypt If you are using the XEmacs package tools, don't forget to do: @@ -402,7 +414,7 @@ Currently, source packages are only available via anonymous CVS. See @item GNU make (3.75 or later preferred). @item makeinfo -(1.68 from texinfo-3.11 or later required). +(4.2 from GNU texinfo 4.2 or later required). @item GNU tar (or equivalent). @item GNU gzip @@ -418,243 +430,22 @@ The packages CVS sources are most useful for creating XEmacs package tarballs for installation into your own XEmacs installations or for distributing to others. -Supported operations from @file{make} are: - -@table @code -@item all -Bytecompile all files, build and bytecompile byproduct files like -@file{auto-autoloads.el} and @file{custom-load.el}. Create info version -of TeXinfo documentation if present. - -@item bindist -Does a @code{make all} as well as create a binary package tarball in the -staging directory. - -@item install -Bytecompile all files, build and bytecompile byproduct files like -@file{auto-autoloads.el} and @file{custom-load.el}. Create info version -of TeXinfo documentation if present. And install everything into the -staging directory. - -@item srckit -Usually aliased to @code{srckit-std}. This does a @code{make -distclean} and creates a package source tarball in the staging -directory. This is generally only of use for package maintainers. - -@item binkit -May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo}, -@code{binkit-sourcedata}, or -@code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is -nothing to install in a data directory or info directory. -@code{sourceinfo} indicates that source and info files are to be -installed. @code{sourcedata} indicates that source and etc (data) files -are to be installed. @code{sourcedatainfo} indicates source, etc -(data), and info files are to be installed. A few packages have needs -beyond the basic templates so this is not yet complete. - -@item dist -Runs the rules @code{srckit} followed by @code{binkit}. This is -primarily of use by XEmacs maintainers producing files for distribution. - -@item clean -Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}. - -@item distclean -Remove all created files. -@end table +For a list and description of the different @file{Makefile} targets, +@xref{Makefile Targets,,,lispref}. -@node Local.rules File, Creating Packages, Building Packages, Packages +@node Local.rules File, Available Packages, Building Packages, Packages @comment node-name, next, previous, up @cindex local.rules @heading The Local.rules File: This file is used when building and installing packages from source. In -the top level of the CVS module, @file{xemacs-packages}, contains the +the top level of the CVS module, @file{packages}, contains the file, @file{Local.rules.template}. Simply copy that to @file{Local.rules} and edit it to suit your needs. -These are the variables in 'Local.rules' that you will need to -address. - -@table @var -@item symlink = -Set this to 't' if you want to do a "run in place". -Setting this doesn't work well with 'make bindist' - -@item XEMACS_PACKAGES = -This is where you set the normal packages that you -want to install. eg: -@example - XEMACS_PACKAGES = xemacs-packages/xemacs-base xemacs-packages/bbdb -@end example - -@item XEMACS_STAGING = $@{XEMACS_PACKAGES_BASE@}/../Packages -Set this to where you want normal packages to be -installed to. - -@item PACKAGE_INDEX = package-index -If you want the package-index file to have a different -name, change this. +For a complete discussion of the @file{Local.rules} file, +@xref{Local.rules File,,,lispref}. -@item BUILD_WITHOUT_MULE = -Building from CVS defaults to building the Mule -packages. Set this to 't' if you don't want/have Mule - -@item MULE_PACKAGES = -Same as for 'XEMACS_PACKAGES' except you list the Mule -packages you want to install here. eg: -@example - MULE_PACKAGES = mule-packages/mule-base mule-packages/skk -@end example - -@item MULE_STAGING = $@{XEMACS_PACKAGES_BASE@}/../Mule-Packages -Set this to where you want Mule packages installed -to. Note: 'make bindist' does not use this variable. - -@item XEMACS = xemacs -If your XEmacs isn't in your path, change this. - -@item XEMACS_NATIVE_NT = -Set this to 't' if you are building on WinNT. - -@item INSTALL = install -c -The path to your BSD compatible install program. - -@item TAR = tar -The path to your tar program - -@item BZIP2 = -If you want bzip2 tarballs, set this. - -@item MAKEINFO = makeinfo -The path to your makeinfo program -@end table - - -@node Creating Packages, Available Packages, Local.rules File, Packages -@comment node-name, next, previous, up -@cindex creating packages -@heading Creating Packages: -Creating a package from an existing Lisp library is not very difficult. - -In addition to the Lisp libraries themselves, you need a -@file{package-info.in} file and a simple @file{Makefile}. The rest is -done by @file{XEmacs.rules}, part of the packaging system -infrastructure. - -@file{package-info.in} contains a single Lisp form like this: - -@example -(name ; your package's name - (standards-version 1.1 - version VERSION - author-version AUTHOR_VERSION - date DATE - build-date BUILD_DATE - maintainer MAINTAINER - distribution xemacs ; change to "mule" if MULE is needed - priority high - category CATEGORY - dump nil - description "description" ; a one-line description string - filename FILENAME - md5sum MD5SUM - size SIZE - provides (feature1 feature2) ; one for every `provides' form - requires (REQUIRES) - type regular -)) -@end example - -You must fill in the four commented lines. The value of @code{name} is -the name of your package as an unquoted symbol. Normally it is the name -of the main Lisp file or principal feature provided. The allowed values -for distribution are @code{xemacs} and @code{mule}. Write them as -unquoted symbols. The @code{description} is a quoted Lisp string; use -the usual conventions. The value for @code{provides} is a list of -feature symbols (written unquoted). All of the features provided by -libraries in your package should be elements of this list. Implementing -an automatic method for generating the @file{provides} line is -desirable, but as yet undone. - -The variables in upper-case are references to variables set in the -@file{Makefile} or automatically generated. Do not change them; they -are automatically filled in by the build process. - -The remaining lines refer to implementation constants -(@code{standards-version}), or features that are unimplemented or have -been removed (@code{priority} and @code{dump}). The @code{type} line is -not normally relevant to external maintainers; the alternate value is -@code{single-file}, which refers to packages consed up out of a number -of single-file libraries that are more or less thematically related. An -example is @code{prog-modes}. Single-file packages are basically for -administrative convenience, and new packages should generally be created -as regular packages. - -The @file{Makefile} is quite stylized. The idea is similar to an -@file{Imakefile} or an @code{automake} file: the complexity is hidden in -generic rules files, in this case the @file{XEmacs.rules} include file -in the top directory of the packages hierarchy. Although a number of -facilities are available for complex libraries, most simple packages' -@file{Makefile}s contain a copyright notice, a few variable definitions, -an include for @file{XEmacs.rules}, and a couple of standard targets. - -The first few @code{make} variables defined are @code{VERSION}, -@code{AUTHOR_VERSION}, @code{MAINTAINER}, @code{PACKAGE}, -@code{PKG_TYPE}, @code{REQUIRES}, and @code{CATEGORY}. All but one were -described in the description of @file{package-info.in}. The last is an -administrative grouping. Current categories include @code{standard}, -and @code{mule}. - -Next, define the variable @code{ELCS}. This contains the list of the -byte-compiled Lisp files used by the package. These files and their -@file{.el} versions will be included in the binary package. If there -are other files (such as extra Lisp sources or an upstream -@file{Makefile}) that are normally placed in the installed Lisp -directory, but not byte-compiled, they can be listed as the value of -@code{EXTRA_SOURCES}. - -The include is simply -@example -include ../../XEmacs.rules -@end example - -The standard targets follow. These are - -@example -all:: $(ELCS) auto-autoloads.elc - -srckit: srckit-alias - -binkit: binkit-alias -@end example - -Other targets (such as Texinfo sources) may need to be added as -dependencies for the @code{all} target. Dependencies for @code{srckit} -and @code{binkit} (that is, values for @var{srckit-alias} and -@var{binkit-alias}) are defined in @file{XEmacs.rules}. The most useful -of these values are given in the following table. - -@table @var -@item srckit-alias -Usually set to @code{srckit-std}. - -@item binkit-alias -May be set to @code{binkit-sourceonly}, @code{binkit-sourceinfo}, -@code{binkit-sourcedata}, or -@code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is -nothing to install in a data directory or info directory. -@code{sourceinfo} indicates that source and info files are to be -installed. @code{sourcedata} indicates that source and etc (data) files -are to be installed. @code{sourcedatainfo} indicates source, etc -(data), and info files are to be installed. -@end table - -Data files include things like pixmaps for a package-specific toolbar, -and are normally installed in @file{etc/@var{PACKAGE_NAME}}. A few -packages have needs beyond the basic templates. See @file{XEmacs.rules} -or a future revision of this manual for details. - -@node Available Packages, , Creating Packages, Packages +@node Available Packages, , Local.rules File, Packages @comment node-name, next, previous, up @cindex available packages @cindex packages @@ -664,7 +455,7 @@ xemacs.org and it's mirrors. If a particular package that you are looking for isn't here, please send a message to the @email{xemacs-beta@@xemacs.org, XEmacs Beta list}. -This data is up-to-date as of August 8, 2002. +This data is up to date as of June 27, 2003. @subsection Normal Packages A very broad selection of elisp packages. @@ -769,15 +560,21 @@ Footnoting in mail message editing modes. @item forms Forms editing support (obsolete, use the built-in Widget instead). +@item fortran-modes +Fortran language support. + @item frame-icon Provide a WM icon based on major mode. @item fsf-compat -FSF Emacs compatibility files. +GNU Emacs compatibility files. @item games Tetris, Sokoban, and Snake. +@item general-docs +General documentation. Presently, empty. + @item gnats XEmacs bug reports. @@ -785,7 +582,7 @@ XEmacs bug reports. The Gnus Newsreader and Mailreader. @item haskell-mode -Haskell editing support. +Haskell language support. @item hm--html-menus HTML editing. @@ -836,13 +633,13 @@ Support for Multiple Major Modes within a single buffer. Miscellaneous Networking Utilities. This is a single-file package and files may be deleted at will. +@item ocaml +Objective Caml editing support. + @item os-utils Miscellaneous single-file O/S utilities, for printing, archiving, compression, remote shells, etc. -@item ocaml -Objective Caml editing support. - @item pc PC style interface emulation. @@ -852,6 +649,12 @@ CVS frontend. @item pcomplete Provides programmatic completion. +@item perl-modes +Perl language support. + +@item pgg +Emacs interface to various PGP implementations. + @item prog-modes Miscellaneous single-file lisp files for various programming languages. @@ -861,12 +664,23 @@ Print buffers to PostScript printers. @item psgml Validated HTML/SGML editing. +@item psgml-dtds +A collection of DTDs for psgml. Note that this package is deprecated +and will be removed in the future, most likely Q2/2003. Instead of using +this, you should install needed DTDs yourself. + +@item python-modes +Python language support. + @item reftex Emacs support for LaTeX cross-references, citations. @item rmail An obsolete Emacs mailer. If you do not already use it don't start. +@item ruby-modes +Ruby language support. + @item sasl Simple Authentication and Security Layer (SASL) library. @@ -953,6 +767,9 @@ An Emacs mailer. @item w3 A Web browser. +@item x-symbol +Semi WYSIWYG for LaTeX, HTML, etc, using additional fonts. + @item xemacs-base Fundamental XEmacs support. Install this unless you wish a totally naked XEmacs.