X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=blobdiff_plain;f=man%2Fxemacs%2Fpackages.texi;h=5696ebe57fece9f3e70b64a2e40f329ee05097fc;hp=32adac78e97527e92dbdaeecbdbb5a3c00f42113;hb=79d2db7d65205bc85d471590726d0cf3af5598e0;hpb=de1ec4b272dfa3f9ef2c9ae28a9ba67170d24da5 diff --git a/man/xemacs/packages.texi b/man/xemacs/packages.texi index 32adac7..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} +be used by XEmacs after a restart unless the package in question has not +been previously installed. -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 - -@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 @@ -278,7 +214,7 @@ 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,52 +430,10 @@ 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: @@ -472,201 +442,10 @@ 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. Items that have default settings have those defaults shown. - -@table @var -@item XEMACS = xemacs -If your XEmacs isn't in your path, change this. Native MS Windows users -should double quote this if the path has embedded spaces. - -@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 XEMACS_NATIVE_NT = -Set this to 't' if you are building on WinNT. NT users should note that -you still need the Cygwin environment to build the packages. - -@item XEMACS_INSTALLED_PACKAGES_ROOT = /usr/local/lib/xemacs -This is the directory tree under which the installed packages go. Under -this directory there would normally be @file{xemacs-packages/} for -standard (non-Mule) packages, @file{mule-packages/} for Mule packages -(if you built XEmacs with Mule), and possibly @file{site-packages/} for -3rd party packages that aren't distributed by XEmacs.org. - -@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 NONMULE_INSTALLED_PACKAGES_ROOT = $@{XEMACS_INSTALLED_PACKAGES_ROOT@}/xemacs-packages -This is where the non-Mule packages are installed to. You probably -don't want to change this. - -@item MULE_INSTALLED_PACKAGES_ROOT = $@{XEMACS_INSTALLED_PACKAGES_ROOT@}/mule-packages -This is where the Mule packages are installed to. You probably don't -want to change this. Please note that @code{make bindist} does -@emph{not} use this variable. When doing a @code{make bindist} -@emph{everything} goes into @var{NONMULE_INSTALLED_PACKAGES_ROOT}. - -@item NONMULE_PACKAGES = xemacs-packages -This is where you set the non-Mule packages that you want to install. eg: -@example - XEMACS_PACKAGES = xemacs-packages/xemacs-base xemacs-packages/bbdb -@end example - -@item MULE_PACKAGES = 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 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 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" ; one-line period-terminated 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 first letter should be capitalized, and the -string should end in a period. It need not be a complete sentence -grammatically. 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 @@ -676,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 September 22, 2002. +This data is up to date as of June 27, 2003. @subsection Normal Packages A very broad selection of elisp packages. @@ -793,6 +572,9 @@ GNU Emacs compatibility files. @item games Tetris, Sokoban, and Snake. +@item general-docs +General documentation. Presently, empty. + @item gnats XEmacs bug reports. @@ -851,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 language support. - @item pc PC style interface emulation. @@ -870,6 +652,9 @@ 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. @@ -982,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.