mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-30 04:10:54 -08:00
Code Issues Projects Releases Wiki Activity

Move here from ../../man

Browse source
This commit is contained in:
Glenn Morris 2007-09-06 05:07:05 +00:00
parent 92f9b43f92
commit 4009494e10
46 changed files with 165283 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

23
doc/misc/.gitignore vendored Normal file
View file

@ -0,0 +1,23 @@
*.aux
*.cp
*.cps
*.dvi
*.fn
*.fns
*.ky
*.kys
*.log
*.op
*.ops
*.pdf
*.pg
*.pgs
*.ps
*.tmp
*.toc
*.tp
*.tps
*.vr
*.vrs
Makefile
makefile

49
doc/misc/ChangeLog Normal file
View file

@ -0,0 +1,49 @@
2007-09-06 Glenn Morris <rgm@gnu.org>
* Move manual sources from man/ to subdirectories of doc/.
Split into the Emacs manual in emacs/, and other manuals in misc/.
Change all setfilename commands to use ../../info.
* Makefile.in: Move the parts of the old man/Makefile.in that do not
refer to the Emacs manual here.
(infodir): New variable.
(INFO_TARGETS, info): Use infodir. Also used by all info targets.
(cc-mode.texi, faq.texi): Update references to source file locations.
* makefile.w32-in: Move the parts of the old man/makefile.w32-in that
do not refer to the Emacs manual here.
(infodir, MULTI_INSTALL_INFO, ENVADD): Go up one more level.
* Makefile.in: Add `basename' versions of all info targets, for
convenience when rebuilding just one manual.
(../etc/GNU): Delete obsolete target.
(.SUFFIXES): Use $(TEXI2DVI) rather than texi2dvi.
(mostlyclean): Add *.op, *.ops. Move *.aux *.cps *.fns *.kys *.pgs
*.vrs *.toc here...
(maintainer-clean): ...from here.
* makefile.w32-in (../etc/GNU): Delete obsolete target.
;; Local Variables:
;; coding: iso-2022-7bit
;; fill-column: 79
;; add-log-time-zone-rule: t
;; End:
Copyright (C) 2007 Free Software Foundation, Inc.
This file is part of GNU Emacs.
GNU Emacs is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3, or (at your option)
any later version.
GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Emacs; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.

368
doc/misc/Makefile.in Normal file
View file

@ -0,0 +1,368 @@
#### Makefile for the Emacs Manual and other documentation.
# Copyright (C) 1994, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
# 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
# This file is part of GNU Emacs.
# GNU Emacs is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
# GNU Emacs is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with GNU Emacs; see the file COPYING. If not, write to
# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301, USA.
# Where to find the source code. $(srcdir) will be the man
# subdirectory of the source tree. This is
# set by the configure script's `--srcdir' option.
srcdir=@srcdir@
top_srcdir=@top_srcdir@
# Tell make where to find source files; this is needed for the makefiles.
VPATH=@srcdir@
# The makeinfo program is part of the Texinfo distribution.
# Use --force so that it generates output even if there are errors.
MAKEINFO = makeinfo --force
INFO_TARGETS = ../info/emacs ../info/ccmode ../info/cl \
../info/dired-x ../info/ediff ../info/forms ../info/gnus \
../info/message ../info/sieve ../info/pgg ../info/emacs-mime \
../info/info ../info/mh-e ../info/reftex \
../info/sc ../info/vip ../info/viper ../info/widget \
../info/efaq ../info/ada-mode ../info/autotype ../info/calc \
../info/idlwave ../info/eudc ../info/ebrowse ../info/pcl-cvs \
../info/woman ../info/eshell ../info/org ../info/url \
../info/speedbar ../info/tramp ../info/ses ../info/smtpmail \
../info/flymake ../info/newsticker ../info/rcirc ../info/erc
DVI_TARGETS = emacs.dvi calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \
ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \
gnus.dvi message.dvi sieve.dvi pgg.dvi mh-e.dvi \
reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \
ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \
pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \
speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \
newsticker.dvi emacs-xtra.dvi rcirc.dvi erc.dvi
INFOSOURCES = info.texi
# The following rule does not work with all versions of `make'.
.SUFFIXES: .texi .dvi
.texi.dvi:
texi2dvi $<
TEXI2DVI = texi2dvi
ENVADD = TEXINPUTS="$(srcdir):$(TEXINPUTS)" MAKEINFO="$(MAKEINFO) -I$(srcdir)"
EMACS_XTRA=\
$(srcdir)/arevert-xtra.texi \
$(srcdir)/cal-xtra.texi \
$(srcdir)/dired-xtra.texi \
$(srcdir)/picture-xtra.texi \
$(srcdir)/emerge-xtra.texi \
$(srcdir)/vc-xtra.texi \
$(srcdir)/vc1-xtra.texi \
$(srcdir)/vc2-xtra.texi \
$(srcdir)/fortran-xtra.texi \
$(srcdir)/msdog-xtra.texi
EMACSSOURCES= \
${srcdir}/emacs.texi \
${srcdir}/doclicense.texi \
${srcdir}/gpl.texi \
${srcdir}/screen.texi \
${srcdir}/commands.texi \
${srcdir}/entering.texi \
${srcdir}/basic.texi \
${srcdir}/mini.texi \
${srcdir}/m-x.texi \
${srcdir}/help.texi \
${srcdir}/mark.texi \
${srcdir}/killing.texi \
${srcdir}/regs.texi \
${srcdir}/display.texi \
${srcdir}/search.texi \
${srcdir}/fixit.texi \
${srcdir}/files.texi \
${srcdir}/buffers.texi \
${srcdir}/windows.texi \
${srcdir}/frames.texi \
${srcdir}/mule.texi \
${srcdir}/major.texi \
${srcdir}/indent.texi \
${srcdir}/text.texi \
${srcdir}/programs.texi \
${srcdir}/building.texi \
${srcdir}/maintaining.texi \
${srcdir}/abbrevs.texi \
${srcdir}/sending.texi \
${srcdir}/rmail.texi \
${srcdir}/dired.texi \
${srcdir}/calendar.texi \
${srcdir}/misc.texi \
${srcdir}/custom.texi \
${srcdir}/trouble.texi \
${srcdir}/cmdargs.texi \
${srcdir}/xresources.texi \
${srcdir}/anti.texi \
${srcdir}/macos.texi \
${srcdir}/msdog.texi \
${srcdir}/gnu.texi \
${srcdir}/glossary.texi \
${srcdir}/ack.texi \
${srcdir}/kmacro.texi \
$(EMACS_XTRA)
info: $(top_srcdir)/info $(INFO_TARGETS)
$(top_srcdir)/info:
mkdir $@
dvi: $(DVI_TARGETS)
# Note that all the Info targets build the Info files
# in srcdir. There is no provision for Info files
# to exist in the build directory.
# In a distribution of Emacs, the Info files should be up to date.
# The following target uses an explicit -o switch to work around
# the @setfilename directive in info.texi, which is required for
# the Texinfo distribution.
../info/info: ${INFOSOURCES}
cd $(srcdir); $(MAKEINFO) --no-split info.texi -o $@
info.dvi: ${INFOSOURCES}
$(ENVADD) $(TEXI2DVI) ${srcdir}/info.texi
../info/emacs: ${EMACSSOURCES}
cd $(srcdir); $(MAKEINFO) emacs.texi
emacs.dvi: ${EMACSSOURCES}
$(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi
# This target is here so you could easily get the list of the *.texi
# files which belong to the Emacs manual (as opposed to the separate
# manuals for CL, CC Mode, Ebrowse, etc.). With this target, you can
# say things like "grep foo `make emacsman`".
emacsman:
@echo $(EMACSSOURCES)
../info/ccmode: cc-mode.texi
cd $(srcdir); $(MAKEINFO) cc-mode.texi
cc-mode.dvi: cc-mode.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/cc-mode.texi
../info/ada-mode: ada-mode.texi
cd $(srcdir); $(MAKEINFO) ada-mode.texi
ada-mode.dvi: ada-mode.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/ada-mode.texi
../info/pcl-cvs: pcl-cvs.texi
cd $(srcdir); $(MAKEINFO) pcl-cvs.texi
pcl-cvs.dvi: pcl-cvs.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/pcl-cvs.texi
../info/eshell: eshell.texi
cd $(srcdir); $(MAKEINFO) eshell.texi
eshell.dvi: eshell.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/eshell.texi
../info/cl: cl.texi
cd $(srcdir); $(MAKEINFO) cl.texi
cl.dvi: cl.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/cl.texi
../info/dired-x: dired-x.texi
cd $(srcdir); $(MAKEINFO) dired-x.texi
dired-x.dvi: dired-x.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/dired-x.texi
../info/ediff: ediff.texi
cd $(srcdir); $(MAKEINFO) ediff.texi
ediff.dvi: ediff.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/ediff.texi
emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA)
$(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi
../info/forms: forms.texi
cd $(srcdir); $(MAKEINFO) forms.texi
forms.dvi: forms.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/forms.texi
# gnus/message/emacs-mime/sieve/pgg are part of Gnus:
../info/gnus: gnus.texi gnus-faq.texi
cd $(srcdir); $(MAKEINFO) gnus.texi
gnus.dvi: gnus.texi gnus-faq.texi
sed -e '/@iflatex/,/@end iflatex/d' ${srcdir}/gnus.texi > gnustmp.texi
$(ENVADD) $(TEXI2DVI) gnustmp.texi
cp gnustmp.dvi $*.dvi
rm gnustmp.*
../info/message: message.texi
cd $(srcdir); $(MAKEINFO) message.texi
message.dvi: message.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/message.texi
../info/sieve: sieve.texi
cd $(srcdir); $(MAKEINFO) sieve.texi
sieve.dvi: sieve.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/sieve.texi
../info/emacs-mime: emacs-mime.texi
cd $(srcdir); $(MAKEINFO) --enable-encoding emacs-mime.texi
emacs-mime.dvi: emacs-mime.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-mime.texi
../info/pgg: pgg.texi
cd $(srcdir); $(MAKEINFO) pgg.texi
pgg.dvi: pgg.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/pgg.texi
../info/mh-e: mh-e.texi
cd $(srcdir); $(MAKEINFO) mh-e.texi
mh-e.dvi: mh-e.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/mh-e.texi
../info/reftex: reftex.texi
cd $(srcdir); $(MAKEINFO) reftex.texi
reftex.dvi: reftex.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/reftex.texi
../info/sc: sc.texi
cd $(srcdir); $(MAKEINFO) sc.texi
sc.dvi: sc.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/sc.texi
../info/vip: vip.texi
cd $(srcdir); $(MAKEINFO) vip.texi
vip.dvi: vip.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/vip.texi
../info/viper: viper.texi
cd $(srcdir); $(MAKEINFO) viper.texi
viper.dvi: viper.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/viper.texi
../info/widget: widget.texi
cd $(srcdir); $(MAKEINFO) widget.texi
widget.dvi: widget.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/widget.texi
../info/efaq: faq.texi
cd $(srcdir); $(MAKEINFO) faq.texi
faq.dvi: faq.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/faq.texi
../etc/GNU: gnu1.texi gnu.texi
cd $(srcdir) && makeinfo --no-headers -o ../etc/GNU gnu1.texi
../info/autotype: autotype.texi
cd $(srcdir); $(MAKEINFO) autotype.texi
autotype.dvi: autotype.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/autotype.texi
../info/calc: calc.texi
cd $(srcdir); $(MAKEINFO) calc.texi
calc.dvi: calc.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/calc.texi
# This is produced with --no-split to avoid making files whose
# names clash on DOS 8+3 filesystems
../info/idlwave: idlwave.texi
cd $(srcdir); $(MAKEINFO) --no-split idlwave.texi
idlwave.dvi: idlwave.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/idlwave.texi
../info/eudc: eudc.texi
cd $(srcdir); $(MAKEINFO) eudc.texi
eudc.dvi: eudc.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/eudc.texi
../info/ebrowse: ebrowse.texi
cd $(srcdir); $(MAKEINFO) ebrowse.texi
ebrowse.dvi: ebrowse.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/ebrowse.texi
../info/woman: woman.texi
cd $(srcdir); $(MAKEINFO) woman.texi
woman.dvi: woman.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/woman.texi
../info/org: org.texi
cd $(srcdir); $(MAKEINFO) org.texi
org.dvi: org.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/org.texi
../info/url: url.texi
cd $(srcdir); $(MAKEINFO) url.texi
url.dvi: url.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/url.texi
../info/speedbar: speedbar.texi
cd $(srcdir); $(MAKEINFO) speedbar.texi
speedbar.dvi: speedbar.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/speedbar.texi
../info/tramp: tramp.texi trampver.texi
cd $(srcdir); $(MAKEINFO) -D emacs tramp.texi
tramp.dvi: tramp.texi trampver.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/tramp.texi
../info/ses: ses.texi
cd $(srcdir); $(MAKEINFO) ses.texi
ses.dvi: ses.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/ses.texi
../info/smtpmail: smtpmail.texi
cd $(srcdir); $(MAKEINFO) smtpmail.texi
smtpmail.dvi: smtpmail.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/smtpmail.texi
../info/flymake: flymake.texi
cd $(srcdir); $(MAKEINFO) flymake.texi
flymake.dvi: flymake.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/flymake.texi
../info/newsticker: newsticker.texi
cd $(srcdir); $(MAKEINFO) newsticker.texi
newsticker.dvi: newsticker.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/newsticker.texi
../info/rcirc: rcirc.texi
cd $(srcdir); $(MAKEINFO) rcirc.texi
rcirc.dvi: rcirc.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/rcirc.texi
../info/erc: erc.texi
cd $(srcdir); $(MAKEINFO) erc.texi
erc.dvi: erc.texi
$(ENVADD) $(TEXI2DVI) ${srcdir}/erc.texi
mostlyclean:
rm -f *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.*
clean: mostlyclean
rm -f *.dvi
distclean: clean
maintainer-clean: distclean
rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc
for file in $(INFO_TARGETS); do rm -f $${file}*; done
# Formerly this directory had texindex.c and getopt.c in it
# and this makefile built them to make texindex.
# That caused trouble because this is run entirely in the source directory.
# Since we expect to get texi2dvi from elsewhere,
# it is ok to expect texindex from elsewhere also.

1410
doc/misc/ada-mode.texi Normal file
View file

File diff suppressed because it is too large Load diff

676
doc/misc/autotype.texi Normal file
View file

@ -0,0 +1,676 @@
\input texinfo
@c This is an annex of the Emacs manual.
@c Copyright (C) 1994, 1995, 2001, 2002, 2003, 2004,
@c 2005, 2006, 2007 Free Software Foundation, Inc.
@c Author: Daniel.Pfeiffer@Informatik.START.dbp.de, fax (+49 69) 7588-2389
@setfilename ../info/autotype
@c @node Autotypist, Picture, Abbrevs, Top
@c @chapter Features for Automatic Typing
@settitle Features for Automatic Typing
@c @cindex text
@c @cindex selfinserting text
@c @cindex autotypist
@copying
Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004,
2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``The GNU Manifesto'', ``Distribution'' and
``GNU GENERAL PUBLIC LICENSE'', with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* Autotype: (autotype). Convenient features for text that you enter frequently
in Emacs.
@end direntry
@titlepage
@sp 10
@center @titlefont{Autotyping}
@sp 2
@center @subtitlefont{Convenient features for text that you enter
frequently in Emacs}
@sp 2
@center Daniel Pfeiffer
@center additions by Dave Love
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@node Top
@top Autotyping
Under certain circumstances you will find yourself typing similar things
over and over again. This is especially true of form letters and programming
language constructs. Project-specific header comments, flow-control
constructs or magic numbers are essentially the same every time. Emacs has
various features for doing tedious and repetitive typing chores for you
in addition to the Abbrev features (@pxref{(emacs)Abbrevs}).
One solution is using skeletons, flexible rules that say what to
insert, and how to do it. Various programming language modes offer some
ready-to-use skeletons, and you can adapt them to suit your needs or
taste, or define new ones.
Another feature is automatic insertion of what you want into empty files,
depending on the file-name or the mode as appropriate. You can have a file or
a skeleton inserted, or you can call a function. Then there is the
possibility to have Un*x interpreter scripts automatically take on a magic
number and be executable as soon as they are saved. Or you can have a
copyright notice's year updated, if necessary, every time you save a
file. Similarly for time stamps in the file.
URLs can be inserted based on a word at point. Flexible templates can
be defined for inserting and navigating between text more generally. A
sort of meta-expansion facility can be used to try a set of alternative
completions and expansions of text at point.
@menu
* Using Skeletons:: How to insert a skeleton into your text.
* Wrapping Skeletons:: Putting existing text within a skeleton.
* Skeletons as Abbrevs:: An alternative for issuing skeleton commands.
* Skeleton Language:: Making skeleton commands insert what you want.
* Inserting Pairs:: Typing one character and getting another
after point.
* Autoinserting:: Filling up empty files as soon as you visit them.
* Copyrights:: Inserting and updating copyrights.
* Executables:: Turning interpreter scripts into executables.
* Timestamps:: Updating dates and times in modified files.
* QuickURL:: Inserting URLs based on text at point.
* Tempo:: Flexible template insertion.
* Hippie Expand:: Expansion of text trying various methods.
* GNU Free Documentation License:: The license for this documentation.
* Concept Index::
* Command Index::
* Variable Index::
@end menu
@node Using Skeletons
@chapter Using Skeletons
@cindex skeletons
@cindex using skeletons
When you want Emacs to insert a form letter or a typical construct of the
programming language you are using, skeletons are a means of accomplishing
this. Normally skeletons each have a command of their own, that, when called,
will insert the skeleton. These commands can be issued in the usual ways
(@pxref{(emacs)Commands}). Modes that offer various skeletons will often
bind these to key-sequences on the @kbd{C-c} prefix, as well as having
an @cite{Insert} menu and maybe even predefined abbrevs for them
(@pxref{Skeletons as Abbrevs}).
The simplest kind of skeleton will simply insert some text indented
according to the major mode and leave the cursor at a likely place in the
middle. Interactive skeletons may prompt you for a string that will be part
of the inserted text.
Skeletons may ask for input several times. They even have a looping
mechanism in which you will be asked for input as long as you are willing to
furnish it. An example would be multiple ``else if'' conditions. You can
recognize this situation by a prompt ending in @key{RET}, @kbd{C-g}
or @kbd{C-h}. This
means that entering an empty string will simply assume that you are finished.
Typing quit on the other hand terminates the loop but also the rest of the
skeleton, e.g. an ``else'' clause is skipped. Only a syntactically necessary
termination still gets inserted.
@node Wrapping Skeletons
@chapter Wrapping Skeletons Around Existing Text
@cindex wrapping skeletons
Often you will find yourself with some code that for whatever reason
suddenly becomes conditional. Or you have written a bit of text and want to
put it in the middle of a form letter. Skeletons provide a means for
accomplishing this, and can even, in the case of programming languages,
reindent the wrapped code for you.
Skeleton commands take an optional numeric prefix argument
(@pxref{(emacs)Arguments}). This is interpreted in two different ways depending
on whether the prefix is positive, i.e. forwards oriented or negative,
i.e. backwards oriented.
A positive prefix means to wrap the skeleton around that many
following words. This is accomplished by putting the words there where
the point is normally left after that skeleton is inserted (@pxref{Using
Skeletons}). The point (@pxref{(emacs)Point}) is left at the next
interesting spot in the skeleton instead.
A negative prefix means to do something similar with that many precedingly
marked interregions (@pxref{(emacs)Mark}). In the simplest case, if you type
@kbd{M--} just before issuing the skeleton command, that will wrap the
skeleton around the current region, just like a positive argument would have
wrapped it around a number of words.
Smaller negative arguments will wrap that many interregions into successive
interesting spots within the skeleton, again leaving the point at the next one.
We speak about interregions rather than regions here, because we treat them in
the order they appear in the buffer, which coincides with successive regions
only if they were marked in order.
That is, if you marked in alphabetical order the points A B C [] (where []
represents the point) and call a skeleton command with @kbd{M-- 3}, you will
wrap the text from A to B into the first interesting spot of the skeleton, the
text from B to C into the next one, the text from C to the point into the
third one, and leave the point in the fourth one. If there are less marks in
the buffer, or if the skeleton defines less interesting points, the surplus is
ignored.
If, on the other hand, you marked in alphabetical order the points [] A C B,
and call a skeleton command with @kbd{M-- 3}, you will wrap the text from
point to A, then the text from A to C and finally the text from C to B. This
is done because the regions overlap and Emacs would be helplessly lost if it
tried to follow the order in which you marked these points.
@node Skeletons as Abbrevs
@chapter Skeletons as Abbrev Expansions
@cindex skeletons as abbrevs
Rather than use a key binding for every skeleton command, you can also
define an abbreviation (@pxref{(emacs)Defining Abbrevs}) that will expand
(@pxref{(emacs)Expanding Abbrevs}) into the skeleton.
Say you want @samp{ifst} to be an abbreviation for the C language if
statement. You will tell Emacs that @samp{ifst} expands to the empty string
and then calls the skeleton command. In Emacs Lisp you can say something like
@code{(define-abbrev c-mode-abbrev-table "ifst" "" 'c-if)}. Or you can edit
the output from @kbd{M-x list-abbrevs} to make it look like this:
@example
(c-mode-abbrev-table)
"if" 0 "" c-if
@end example
@noindent
(Some blank lines of no semantic significance, and other abbrev tables,
have been omitted.)
@node Skeleton Language
@chapter Skeleton Language
@cindex skeleton language
@findex skeleton-insert
Skeletons are an shorthand extension to the Lisp language, where various
atoms directly perform either actions on the current buffer or rudimentary
flow control mechanisms. Skeletons are interpreted by the function
@code{skeleton-insert}.
A skeleton is a list starting with an interactor, which is usually a
prompt-string, or @code{nil} when not needed, but can also be a Lisp
expression for complex read functions or for returning some calculated value.
The rest of the list are any number of elements as described in the following
table:
@table @asis
@item @code{"@var{string}"}, @code{?@var{c}}, @code{?\@var{c}}
@vindex skeleton-transformation
Insert string or character. Literal strings and characters are passed through
@code{skeleton-transformation} when that is non-@code{nil}.
@item @code{?\n}
@c ??? something seems very wrong here.
Insert a newline and align under current line. Use newline character
@code{?\n} to prevent alignment.
@item @code{_}
Interesting point. When wrapping skeletons around successive regions, they are
put at these places. Point is left at first @code{_} where nothing is wrapped.
@item @code{>}
Indent line according to major mode. When following element is @code{_}, and
there is a interregion that will be wrapped here, indent that interregion.
@item @code{&}
Logical and. Iff preceding element moved point, i.e. usually inserted
something, do following element.
@item @code{|}
Logical xor. Iff preceding element didn't move point, i.e. usually inserted
nothing, do following element.
@item @code{-@var{number}}
Delete preceding number characters. Depends on value of
@code{skeleton-untabify}.
@item @code{()} or @code{nil}
Ignored.
@item @var{lisp-expression}
Evaluated, and the return value is again interpreted as a skeleton element.
@item @code{str}
A special variable that, when evaluated the first time, usually prompts
for input according to the skeleton's interactor. It is then set to the
return value resulting from the interactor. Each subskeleton has its local
copy of this variable.
@item @code{v1}, @code{v2}
Skeleton-local user variables.
@item @code{'@var{expression}}
Evaluate following Lisp expression for its side-effect, but prevent it from
being interpreted as a skeleton element.
@item @var{skeleton}
Subskeletons are inserted recursively, not once, but as often as the user
enters something at the subskeletons interactor. Thus there must be a
@code{str} in the subskeleton. They can also be used non-interactively, when
prompt is a lisp-expression that returns successive list-elements.
@item @code{resume:}
Ignored. Execution resumes here if the user quits during skeleton
interpretation.
@item @code{quit}
A constant which is non-@code{nil} when the @code{resume:} section was entered
because the user quit.
@end table
@findex skeleton-further-elements
Some modes also use other skeleton elements they themselves defined. For
example in shell script mode's skeletons you will find @code{<} which does a
rigid indentation backwards, or in CC mode's skeletons you find the
self-inserting elements @code{@{} and @code{@}}. These are defined by the
buffer-local variable @code{skeleton-further-elements} which is a list of
variables bound while interpreting a skeleton.
@findex define-skeleton
The macro @code{define-skeleton} defines a command for interpreting a
skeleton. The first argument is the command name, the second is a
documentation string, and the rest is an interactor and any number of skeleton
elements together forming a skeleton. This skeleton is assigned to a variable
of the same name as the command and can thus be overridden from your
@file{~/.emacs} file (@pxref{(emacs)Init File}).
@node Inserting Pairs
@chapter Inserting Matching Pairs of Characters
@cindex inserting pairs
@cindex pairs
Various characters usually appear in pairs. When, for example, you insert
an open parenthesis, no matter whether you are programming or writing prose,
you will surely enter a closing one later. By entering both at the same time
and leaving the cursor inbetween, Emacs can guarantee you that such
parentheses are always balanced. And if you have a non-qwerty keyboard, where
typing some of the stranger programming language symbols makes you bend your
fingers backwards, this can be quite relieving too.
@findex skeleton-pair-insert-maybe
@vindex skeleton-pair
This is done by binding the first key (@pxref{(emacs)Rebinding}) of
the pair to @code{skeleton-pair-insert-maybe} instead of
@code{self-insert-command}. The ``maybe'' comes from the fact that
this at-first surprising behavior is initially turned off. To enable
it, you must set @code{skeleton-pair} to some non-@code{nil} value.
And even then, a positive argument (@pxref{(emacs)Arguments}) will
make this key behave like a self-inserting key
(@pxref{(emacs)Inserting Text}).
@vindex skeleton-pair-on-word
While this breaks with the stated intention of always balancing pairs, it
turns out that one often doesn't want pairing to occur, when the following
character is part of a word. If you want pairing to occur even then, set
@code{skeleton-pair-on-word} to some non-@code{nil} value.
@vindex skeleton-pair-alist
Pairing is possible for all visible characters. By default the
parenthesis @samp{(}, the square bracket @samp{[}, the brace
@samp{@{}, the pointed bracket @samp{<} and the backquote @samp{`} all
pair with the symmetrical character. All other characters pair
themselves. This behavior can be modified by the variable
@code{skeleton-pair-alist}. This is in fact an alist of skeletons
(@pxref{Skeleton Language}), with the first part of each sublist
matching the typed character. This is the position of the interactor,
but since pairs don't need the @code{str} element, this is ignored.
Some modes have bound the command @code{skeleton-pair-insert-maybe}
to relevant keys. These modes also configure the pairs as
appropriate. For example, when typing english prose, you'd expect the
backquote (@samp{`}) to pair with the quote (@samp{'}), while in Shell
script mode it must pair to itself. They can also inhibit pairing in
certain contexts. For example an escaped character stands for itself.
@node Autoinserting
@chapter Autoinserting Text in Empty Files
@cindex autoinserting
@findex auto-insert
@kbd{M-x auto-insert} will put some predefined text at the beginning of
the buffer. The main application for this function, as its name suggests,
is to have it be called automatically every time an empty, and only an
empty file is visited. This is accomplished by putting @code{(add-hook
'find-file-hook 'auto-insert)} into your @file{~/.emacs} file
(@pxref{(emacs)Init File}).
@vindex auto-insert-alist
What gets inserted, if anything, is determined by the variable
@code{auto-insert-alist}. The @sc{car}s of this list are each either
a mode name, making an element applicable when a buffer is in that
mode. Or they can be a string, which is a regexp matched against the
buffer's file name. In that way different kinds of files that have
the same mode in Emacs can be distinguished. The @sc{car}s may also
be cons cells consisting of mode name or regexp as above and an
additional descriptive string.
When a matching element is found, the @sc{cdr} says what to do. It may
be a string, which is a file name, whose contents are to be inserted, if
that file is found in the directory @code{auto-insert-directory} or under a
absolute file name. Or it can be a skeleton (@pxref{Skeleton Language}) to
be inserted.
It can also be a function, which allows doing various things. The function
can simply insert some text, indeed, it can be skeleton command (@pxref{Using
Skeletons}). It can be a lambda function which will for example conditionally
call another function. Or it can even reset the mode for the buffer. If you
want to perform several such actions in order, you use a vector, i.e. several
of the above elements between square brackets (@samp{[@r{@dots{}}]}).
By default C and C++ headers insert a definition of a symbol derived from
the filename to prevent multiple inclusions. C and C++ sources insert an
include of the header. Makefiles insert the file makefile.inc if it exists.
TeX and bibTeX mode files insert the file tex-insert.tex if it exists, while
LaTeX mode files insert a typical @code{\documentclass} frame. Html
files insert a skeleton with the usual frame.
Ada mode files call the Ada header skeleton command. Emacs lisp
source files insert the usual header, with a copyright of your
environment variable @env{$ORGANIZATION} or else the FSF, and prompt
for valid keywords describing the contents. Files in a @file{bin}
directory for which Emacs could determine no specialized mode
(@pxref{(emacs)Choosing Modes}) are set to Shell script mode.
@findex define-auto-insert
In Lisp (@pxref{(emacs)Init File}) you can use the function
@code{define-auto-insert} to add to or modify
@code{auto-insert-alist}. See its documentation with @kbd{C-h f
define-auto-insert}.
@vindex auto-insert
The variable @code{auto-insert} says what to do when @code{auto-insert} is
called non-interactively, e.g. when a newly found file is empty (see above):
@table @asis
@item @code{nil}
Do nothing.
@item @code{t}
Insert something if possible, i.e. there is a matching entry in
@code{auto-insert-alist}.
@item other
Insert something if possible, but mark as unmodified.
@end table
@vindex auto-insert-query
The variable @code{auto-insert-query} controls whether to ask about
inserting something. When this is @code{nil}, inserting is only done with
@kbd{M-x auto-insert}. When this is @code{function}, you are queried
whenever @code{auto-insert} is called as a function, such as when Emacs
visits an empty file and you have set the above-mentioned hook. Otherwise
you are alway queried.
@vindex auto-insert-prompt
When querying, the variable @code{auto-insert-prompt}'s value is used as a
prompt for a y-or-n-type question. If this includes a @samp{%s} construct,
that is replaced by what caused the insertion rule to be chosen. This is
either a descriptive text, the mode-name of the buffer or the regular
expression that matched the filename.
@node Copyrights
@chapter Inserting and Updating Copyrights
@cindex copyrights
@findex copyright
@kbd{M-x copyright} is a skeleton inserting command, that adds a copyright
notice at the point. The ``by'' part is taken from your environment variable
@env{$ORGANIZATION} or if that isn't set you are prompted for it. If the
buffer has a comment syntax (@pxref{(emacs)Comments}), this is inserted as a comment.
@findex copyright-update
@vindex copyright-limit
@vindex copyright-current-year
@kbd{M-x copyright-update} looks for a copyright notice in the first
@code{copyright-limit} characters of the buffer and updates it when necessary.
The current year (variable @code{copyright-current-year}) is added to the
existing ones, in the same format as the preceding year, i.e. 1994, '94 or 94.
If a dash-separated year list up to last year is found, that is extended to
current year, else the year is added separated by a comma. Or it replaces
them when this is called with a prefix argument. If a header referring to a
wrong version of the GNU General Public License (@pxref{(emacs)Copying}) is found,
that is updated too.
An interesting application for this function is to have it be called
automatically every time a file is saved. This is accomplished by
putting @code{(add-hook 'before-save-hook 'copyright-update)} into
your @file{~/.emacs} file (@pxref{(emacs)Init File}). Alternative,
you can do @kbd{M-x customize-variable @key{RET} before-save-hook
@key{RET}}. @code{copyright-update} is conveniently listed as an
option in the customization buffer.
@vindex copyright-query
The variable @code{copyright-query} controls whether to update the
copyright or whether to ask about it. When this is @code{nil} updating is
only done with @kbd{M-x copyright-update}. When this is @code{function}
you are queried whenever @code{copyright-update} is called as a function,
such as in the @code{before-save-hook} feature mentioned above. Otherwise
you are always queried.
@node Executables
@chapter Making Interpreter Scripts Executable
@cindex executables
@vindex executable-prefix
@vindex executable-chmod
Various interpreter modes such as Shell script mode or AWK mode will
automatically insert or update the buffer's magic number, a special
comment on the first line that makes the @code{exec} systemcall know
how to execute the script. To this end the script is automatically
made executable upon saving, with @code{executable-chmod} as argument
to the system @code{chmod} command. The magic number is prefixed by
the value of @code{executable-prefix}.
@vindex executable-magicless-file-regexp
Any file whose name matches @code{executable-magicless-file-regexp} is not
furnished with a magic number, nor is it made executable. This is mainly
intended for resource files, which are only meant to be read in.
@vindex executable-insert
The variable @code{executable-insert} says what to do when
@code{executable-set-magic} is called non-interactively, e.g. when file has no
or the wrong magic number:
@table @asis
@item @code{nil}
Do nothing.
@item @code{t}
Insert or update magic number.
@item other
Insert or update magic number, but mark as unmodified.
@end table
@findex executable-set-magic
@vindex executable-query
The variable @code{executable-query} controls whether to ask about
inserting or updating the magic number. When this is @code{nil} updating
is only done with @kbd{M-x executable-set-magic}. When this is
@code{function} you are queried whenever @code{executable-set-magic} is
called as a function, such as when Emacs puts a buffer in Shell script
mode. Otherwise you are alway queried.
@findex executable-self-display
@kbd{M-x executable-self-display} adds a magic number to the buffer, which
will turn it into a self displaying text file, when called as a Un*x command.
The ``interpreter'' used is @code{executable-self-display} with argument
@samp{+2}.
@node Timestamps
@chapter Maintaining Timestamps in Modified Files
@cindex timestamps
@findex time-stamp
@vindex before-save-hook
The @code{time-stamp} command can be used to update automatically a
template in a file with a new time stamp every time you save the file.
Customize the hook @code{before-save-hook} to add the function
@code{time-stamp} to arrange this. It you use Custom to do this,
then @code{time-stamp} is conveniently listed as an option in the
customization buffer.
@vindex time-stamp-active
@vindex time-stamp-format
@vindex time-stamp-start
The time stamp is updated only if the customizable variable
@code{time-stamp-active} is on, which it is by default; the command
@code{time-stamp-toggle-active} can be used to toggle it. The format of
the time stamp is set by the customizable variable
@code{time-stamp-format}.
@vindex time-stamp-line-limit
@vindex time-stamp-end
@vindex time-stamp-count
@vindex time-stamp-inserts-lines
The variables @code{time-stamp-line-limit}, @code{time-stamp-start},
@code{time-stamp-end}, @code{time-stamp-count}, and
@code{time-stamp-inserts-lines} control finding the template. Do not
change these in your init file or you will be incompatible with other
people's files. If you must change them, do so only in the local
variables section of the file itself.
Normally the template must appear in the first 8 lines of a file and
look like one of the following:
@example
Time-stamp: <>
Time-stamp: " "
@end example
The time stamp is written between the brackets or quotes:
@example
Time-stamp: <1998-02-18 10:20:51 gildea>
@end example
@node QuickURL
@chapter QuickURL: Inserting URLs Based on Text at Point
@vindex quickurl-url-file
@findex quickurl
@cindex URLs
@kbd{M-x quickurl} can be used to insert a URL into a buffer based on
the text at point. The URLs are stored in an external file defined by
the variable @code{quickurl-url-file} as a list of either cons cells of
the form @code{(@var{key} . @var{URL})} or
lists of the form @code{(@var{key} @var{URL} @var{comment})}. These
specify that @kbd{M-x quickurl} should insert @var{URL} if the word
@var{key} is at point, for example:
@example
(("FSF" "http://www.fsf.org/" "The Free Software Foundation")
("emacs" . "http://www.emacs.org/")
("hagbard" "http://www.hagbard.demon.co.uk" "Hagbard's World"))
@end example
@findex quickurl-add-url
@findex quickurl-list
@kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL}
pair. @kbd{M-x quickurl-list} provides interactive editing of the URL
list.
@node Tempo
@chapter Tempo: Flexible Template Insertion
@cindex templates
The Tempo package provides a simple way to define powerful templates, or
macros, if you wish. It is mainly intended for, but not limited to,
programmers to be used for creating shortcuts for editing
certain kinds of documents.
@findex tempo-backward-mark
@findex tempo-forward-mark
A template is defined as a list of items to be inserted in the current
buffer at point. Some can be simple strings, while others can control
formatting or define special points of interest in the inserted text.
@kbd{M-x tempo-backward-mark} and @kbd{M-x tempo-forward-mark} can be
used to jump between such points.
More flexible templates can be created by including Lisp symbols, which
will be evaluated as variables, or lists, which will be evaluated
as Lisp expressions. Automatic completion of specified tags to expanded
templates can be provided.
@findex tempo-define-template
See the documentation for @code{tempo-define-template} for the different
items that can be used to define a tempo template with a command for
inserting it.
See the commentary in @file{tempo.el} for more information on using the
Tempo package.
@node Hippie Expand
@chapter `Hippie' Expansion
@findex hippie-expand
@kindex M-/
@vindex hippie-expand-try-functions-list
@kbd{M-x hippie-expand} is a single command providing a variety of
completions and expansions. Called repeatedly, it tries all possible
completions in succession.
Which ones to try, and in which order, is determined by the contents of
the customizable option @code{hippie-expand-try-functions-list}. Much
customization of the expansion behavior can be made by changing the
order of, removing, or inserting new functions in this list. Given a
positive numeric argument, @kbd{M-x hippie-expand} jumps directly that
number of functions forward in this list. Given some other argument (a
negative argument or just @kbd{C-u}) it undoes the tried completion.
See the commentary in @file{hippie-exp.el} for more information on the
possibilities.
Typically you would bind @code{hippie-expand} to @kbd{M-/} with
@code{dabbrev-expand}, the standard binding of @kbd{M-/}, providing one
of the expansion possibilities.
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
@node Concept Index
@unnumbered Concept Index
@printindex cp
@node Command Index
@unnumbered Command Index
@printindex fn
@node Variable Index
@unnumbered Variable Index
@printindex vr
@setchapternewpage odd
@contents
@bye
@ignore
arch-tag: 54001b27-5ef8-4a9d-a199-905d650fafba
@end ignore

36190
doc/misc/calc.texi Normal file
View file

File diff suppressed because it is too large Load diff

6998
doc/misc/cc-mode.texi Normal file
View file

File diff suppressed because it is too large Load diff

5377
doc/misc/cl.texi Normal file
View file

File diff suppressed because it is too large Load diff

1275
doc/misc/dired-x.texi Normal file
View file

File diff suppressed because it is too large Load diff

416
doc/misc/doclicense.texi Normal file
View file

@ -0,0 +1,416 @@
@c -*-texinfo-*-
@center Version 1.2, November 2002
@display
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display
@sp 1
@enumerate 0
@item
PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document ``free'' in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of ``copyleft,'' which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
@sp 1
@item
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The ``Document,'' below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as ``you.'' You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A ``Secondary Section'' is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not ``Transparent'' is called ``Opaque.''
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
A section ``Entitled XYZ'' means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as ``Acknowledgements,''
``Dedications,'' ``Endorsements,'' or ``History.'') To ``Preserve the Title''
of such a section when you modify the Document means that it remains a
section ``Entitled XYZ'' according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
@sp 1
@item
VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
@sp 1
@item
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
@sp 1
@item
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.@*
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.@*
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.@*
D. Preserve all the copyright notices of the Document.@*
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.@*
F. Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.@*
G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.@*
H. Include an unaltered copy of this License.@*
I. Preserve the section Entitled ``History,'' Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.@*
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.@*
K. For any section Entitled ``Acknowledgements'' or ``Dedications,''
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.@*
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.@*
M. Delete any section Entitled ``Endorsements.'' Such a section
may not be included in the Modified Version.@*
N. Do not retitle any existing section to be Entitled ``Endorsements''
or to conflict in title with any Invariant Section.@*
O. Preserve any Warranty Disclaimers.@*
@sp 1
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled ``Endorsements,'' provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
@sp 1
@item
COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled ``History''
in the various original documents, forming one section Entitled
``History''; likewise combine any sections Entitled ``Acknowledgements,''
and any sections Entitled ``Dedications.'' You must delete all sections
Entitled ``Endorsements.''
@sp 1
@item
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
@sp 1
@item
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an ``aggregate'' if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
@sp 1
@item
TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled ``Acknowledgements,''
``Dedications,'' or ``History,'' the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
@sp 1
@item
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
@sp 1
@item
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
@end enumerate
@unnumberedsec ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
@smallexample
@group
Copyright (C) @var{year} @var{your name}.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License.''
@end group
@end smallexample
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the ``with...Texts.'' line with this:
@smallexample
@group
with the Invariant Sections being @var{list their titles}, with the
Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
@end group
@end smallexample
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
@ignore
arch-tag: c1679162-1d8a-4f02-bc52-2e71765f0165
@end ignore

1462
doc/misc/ebrowse.texi Normal file
View file

File diff suppressed because it is too large Load diff

2546
doc/misc/ediff.texi Normal file
View file

File diff suppressed because it is too large Load diff

1832
doc/misc/emacs-mime.texi Normal file
View file

File diff suppressed because it is too large Load diff

1027
doc/misc/erc.texi Normal file
View file

File diff suppressed because it is too large Load diff

948
doc/misc/eshell.texi Normal file
View file

@ -0,0 +1,948 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename ../info/eshell
@settitle Eshell: The Emacs Shell
@synindex vr fn
@c %**end of header
@copying
This manual is for Eshell, the Emacs shell.
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004,
2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* Eshell: (eshell). A command shell implemented in Emacs Lisp.
@end direntry
@setchapternewpage on
@titlepage
@sp 4
@c The title is printed in a large font.
@center @titlefont{User's Guide}
@sp
@center @titlefont{to}
@sp
@center @titlefont{Eshell: The Emacs Shell}
@ignore
@sp 2
@center release 2.4
@c -release-
@end ignore
@sp 3
@center John Wiegley
@c -date-
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@c ================================================================
@c The real text starts here
@c ================================================================
@ifnottex
@node Top, What is Eshell?, (dir), (dir)
@top Eshell
This manual documents Eshell, a shell-like command interpretor
implemented in Emacs Lisp. It invokes no external processes except for
those requested by the user. It is intended to be a functional
replacement for command shells such as @command{bash}, @command{zsh},
@command{rc}, or @command{4dos}; since Emacs itself is capable of
handling the sort of tasks accomplished by those tools.
@c This manual is updated to release 2.4 of Eshell.
@end ifnottex
@menu
* What is Eshell?:: A brief introduction to the Emacs Shell.
* Command basics:: The basics of command usage.
* Commands::
* Arguments::
* Input/Output::
* Process control::
* Extension modules::
* Extras and Goodies::
* Bugs and ideas:: Known problems, and future ideas.
* GNU Free Documentation License:: The license for this documentation.
* Concept Index::
* Function and Variable Index::
* Key Index::
@end menu
@node What is Eshell?
@chapter What is Eshell?
@cindex what is Eshell?
@cindex Eshell, what it is
Eshell is a @dfn{command shell} written in Emacs Lisp. Everything it
does, it uses Emacs' facilities to do. This means that Eshell is as
portable as Emacs itself. It also means that cooperation with Lisp code
is natural and seamless.
What is a command shell? To properly understand the role of a shell,
it's necessary to visualize what a computer does for you. Basically, a
computer is a tool; in order to use that tool, you must tell it what to
do---or give it ``commands.'' These commands take many forms, such as
clicking with a mouse on certain parts of the screen. But that is only
one form of command input.
By far the most versatile way to express what you want the computer to
do is by using an abbreviated language called @dfn{script}. In
script, instead of telling the computer, ``list my files, please'',
one writes a standard abbreviated command word---@samp{ls}. Typing
@samp{ls} in a command shell is a script way of telling the computer
to list your files.@footnote{This is comparable to viewing the
contents of a folder using a graphical display.}
The real flexibility of this approach is apparent only when you realize
that there are many, many different ways to list files. Perhaps you
want them sorted by name, sorted by date, in reverse order, or grouped
by type. Most graphical browsers have simple ways to express this. But
what about showing only a few files, or only files that meet a certain
criteria? In very complex and specific situations, the request becomes
too difficult to express using a mouse or pointing device. It is just
these kinds of requests that are easily solved using a command shell.
For example, what if you want to list every Word file on your hard
drive, larger than 100 kilobytes in size, and which hasn't been looked
at in over six months? That is a good candidate list for deletion, when
you go to clean up your hard drive. But have you ever tried asking your
computer for such a list? There is no way to do it! At least, not
without using a command shell.
The role of a command shell is to give you more control over what your
computer does for you. Not everyone needs this amount of control, and
it does come at a cost: Learning the necessary script commands to
express what you want done. A complicated query, such as the example
above, takes time to learn. But if you find yourself using your
computer frequently enough, it is more than worthwhile in the long run.
Any tool you use often deserves the time spent learning to master it.
@footnote{For the understandably curious, here is what that command
looks like: But don't let it fool you; once you know what's going on,
it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.}
@menu
* Contributors to Eshell:: People who have helped out!
@end menu
@node Contributors to Eshell
@section Contributors to Eshell
@cindex contributors
@cindex authors
Contributions to Eshell are welcome. I have limited time to work on
this project, but I will gladly add any code you contribute to me to
this package.
The following persons have made contributions to Eshell.
@itemize @bullet
@item
Eli Zaretskii made it possible for Eshell to run without requiring
asynchronous subprocess support. This is important for MS-DOS, which
does not have such support.@refill
@item
Miles Bader contributed many fixes during the port to Emacs 21.@refill
@item
Stefan Monnier fixed the things which bothered him, which of course made
things better for all.@refill
@item
Gerd Moellmann also helped to contribute bug fixes during the initial
integration with Emacs 21.@refill
@item
Alex Schroeder contributed code for interactively querying the user
before overwriting files.@refill
@item
Sudish Joseph helped with some XEmacs compatibility issues.@refill
@end itemize
Apart from these, a lot of people have sent suggestions, ideas,
requests, bug reports and encouragement. Thanks a lot! Without you
there would be no new releases of Eshell.
@node Command basics
@chapter Basic overview
A command shell is a means of entering verbally-formed commands. This
is really all that it does, and every feature described in this manual
is a means to that end. Therefore, it's important to take firm hold on
exactly what a command is, and how it fits in the overall picture of
things.
@menu
* Commands verbs:: Commands always begin with a verb.
* Command arguments:: Some verbs require arguments.
@end menu
@node Commands verbs
@section Commands verbs
Commands are expressed using @dfn{script}, a special shorthand language
computers can understand with no trouble. Script is an extremely simple
language; oddly enough, this is what makes it look so complicated!
Whereas normal languages use a variety of embellishments, the form of a
script command is always:
@example
@var{verb} [@var{arguments}]
@end example
The verb expresses what you want your computer to do. There are a fixed
number of verbs, although this number is usually quite large. On the
author's computer, it reaches almost 1400 in number. But of course,
only a handful of these are really necessary.
Sometimes, the verb is all that's written. A verb is always a single
word, usually related to the task it performs. @command{reboot} is a
good example. Entering that on GNU/Linux will reboot the
computer---assuming you have sufficient privileges.
Other verbs require more information. These are usually very capable
verbs, and must be told specifically what to do. The extra information
is given in the form of @dfn{arguments}. For example, the
@command{echo} verb prints back whatever arguments you type. It
requires these arguments to know what to echo. A proper use of
@command{echo} looks like this:
@example
echo This is an example of using echo!
@end example
This script command causes the computer to echo back: ``This is an
example of using echo!''
Although command verbs are always simple words, like @command{reboot} or
@command{echo}, arguments may have a wide variety of forms. There are
textual arguments, numerical arguments---even Lisp arguments.
Distinguishing these different types of arguments requires special
typing, for the computer to know exactly what you mean.
@node Command arguments
@section Command arguments
Eshell recognizes several different kinds of command arguments:
@enumerate
@item Strings (also called textual arguments)
@item Numbers (floating point or integer)
@item Lisp lists
@item Lisp symbols
@item Emacs buffers
@item Emacs process handles
@end enumerate
Most users need to worry only about the first two. The third, Lisp lists,
occur very frequently, but almost always behind the scenes.
Strings are the most common type of argument, and consist of nearly any
character. Special characters---those used by Eshell
specifically---must be preceded by a backslash (@samp{\}). When in doubt, it
is safe to add backslashes anywhere and everywhere.
Here is a more complicated @command{echo} example:
@example
echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar
@end example
Beyond this, things get a bit more complicated. While not beyond the
reach of someone wishing to learn, it is definitely beyond the scope of
this manual to present it all in a simplistic manner. Get comfortable
with Eshell as a basic command invocation tool, and learn more about the
commands on your system; then come back when it all sits more familiarly
on your mind. Have fun!
@node Commands
@chapter Commands
@menu
* Invocation::
* Completion::
* Aliases::
* History::
* Scripts::
* Built-ins::
@end menu
Essentially, a command shell is all about invoking commands---and
everything that entails. So understanding how Eshell invokes commands
is the key to comprehending how it all works.
@node Invocation
@section Invocation
Unlike regular system shells, Eshell never invokes kernel functions
directly, such as @code{exec(3)}. Instead, it uses the Lisp functions
available in the Emacs Lisp library. It does this by transforming the
command you specify into a callable Lisp form.@footnote{To see the Lisp
form that will be invoked, type: @samp{eshell-parse-command "echo
hello"}}
This transformation, from the string of text typed at the command
prompt, to the ultimate invocation of either a Lisp function or external
command, follows these steps:
@enumerate
@item Parse the command string into separate arguments.
@item
@end enumerate
@node Completion
@section Completion
@node Aliases
@section Aliases
@node History
@section History
Eshell knows a few built-in variables:
@table @code
@item $+
@vindex $+
This variable always contains the current working directory.
@item $-
@vindex $-
This variable always contains the previous working directory (the
current working directory from before the last @code{cd} command).
@end table
@node Scripts
@section Scripts
@node Built-ins
@section Built-in commands
Here is a list of built-in commands that Eshell knows about:
@table @code
@item cd
@findex cd
This command changes the current working directory. Usually, it is
invoked as @samp{cd foo} where @file{foo} is the new working
directory. But @code{cd} knows about a few special arguments:
When it receives no argument at all, it changes to the home directory.
Giving the command @samp{cd -} changes back to the previous working
directory (this is the same as @samp{cd $-}).
The command @samp{cd =} shows the directory stack. Each line is
numbered.
With @samp{cd =foo}, Eshell searches the directory stack for a
directory matching the regular expression @samp{foo} and changes to
that directory.
With @samp{cd -42}, you can access the directory stack by number.
@end table
@node Arguments
@chapter Arguments
@menu
* The Parser::
* Variables::
* Substitution::
* Globbing::
* Predicates::
@end menu
@node The Parser
@section The Parser
@node Variables
@section Variables
@node Substitution
@section Substitution
@node Globbing
@section Globbing
@node Predicates
@section Predicates
@node Input/Output
@chapter Input/Output
@node Process control
@chapter Process control
@node Extension modules
@chapter Extension modules
@menu
* Writing a module::
* Module testing::
* Directory handling::
* Key rebinding::
* Smart scrolling::
* Terminal emulation::
* Built-in UNIX commands::
@end menu
@node Writing a module
@section Writing a module
@node Module testing
@section Module testing
@node Directory handling
@section Directory handling
@node Key rebinding
@section Key rebinding
@node Smart scrolling
@section Smart scrolling
@node Terminal emulation
@section Terminal emulation
@node Built-in UNIX commands
@section Built-in UNIX commands
@node Extras and Goodies
@chapter Extras and Goodies
@node Bugs and ideas
@chapter Bugs and ideas
@cindex reporting bugs and ideas
@cindex bugs, how to report them
@cindex author, how to reach
@cindex email to the author
@cindex FAQ
@cindex problems, list of common
If you find a bug or misfeature, don't hesitate to let me know! Send
email to @email{johnw@@gnu.org}. Feature requests should also be sent
there. I prefer discussing one thing at a time. If you find several
unrelated bugs, please report them separately.
If you have ideas for improvements, or if you have written some
extensions to this package, I would like to hear from you. I hope you
find this package useful!
@menu
* Known problems::
@end menu
@node Known problems
@section Known problems
@cindex known bugs
@cindex bugs, known
Below is complete list of known problems with Eshell version 2.4.2,
which is the version included with Emacs 22.
@table @asis
@item Documentation incomplete
@item Differentiate between aliases and functions
Allow for a bash-compatible syntax, such as:
@example
alias arg=blah
function arg () @{ blah $* @}
@end example
@item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt
In fact, piping to a process from a looping construct doesn't work in
general. If I change the call to @code{eshell-copy-handles} in
@code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems
to work, but the output occurs after the prompt is displayed. The whole
structured command thing is too complicated at present.
@item Error with @command{bc} in @code{eshell-test}
On some XEmacs system, the subprocess interaction test fails
inexplicably, although @command{bc} works fine at the command prompt.
@item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+
In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that
multiple instances of the @file{*Help*} buffer can exist.
@item Pcomplete sometimes gets stuck
You press @key{TAB}, but no completions appear, even though the
directory has matching files. This behavior is rare.
@item @samp{grep python $<rpm -qa>} doesn't work, but using @samp{*grep} does
This happens because the @code{grep} Lisp function returns immediately,
and then the asynchronous @command{grep} process expects to examine the
temporary file, which has since been deleted.
@item Problem with C-r repeating text
If the text @emph{before point} reads "./run", and you type @kbd{C-r r u
n}, it will repeat the line for every character typed.
@item Backspace doesn't scroll back after continuing (in smart mode)
Hitting space during a process invocation, such as @command{make}, will
cause it to track the bottom of the output; but backspace no longer
scrolls back.
@item It's not possible to fully @code{unload-feature} Eshell
@item Menu support was removed, but never put back
@item Using C-p and C-n with rebind gets into a locked state
This happened a few times in Emacs 21, but has been unreproducible
since.
@item If an interactive process is currently running, @kbd{M-!} doesn't work
@item Use a timer instead of @code{sleep-for} when killing child processes
@item Piping to a Lisp function is not supported
Make it so that the Lisp command on the right of the pipe is repeatedly
called with the input strings as arguments. This will require changing
@code{eshell-do-pipeline} to handle non-process targets.
@item Input redirection is not supported
See the above entry.
@item Problem running @command{less} without arguments on Windows
The result in the Eshell buffer is:
@example
Spawning child process: invalid argument
@end example
Also a new @command{less} buffer was created with nothing in it@dots{}
(presumably this holds the output of @command{less}).
If @command{less.exe} is invoked from the Eshell command line, the
expected output is written to the buffer.
Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el
package and the supplied shell both use the @command{cmdproxy} program
for running shells.
@item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp}
@item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be
@item @samp{mv @var{dir} @var{file}.tar} does not remove directories
This is because the tar option --remove-files doesn't do so. Should it
be Eshell's job?
@item Bind @code{standard-output} and @code{standard-error}
This would be so that if a Lisp function calls @code{print}, everything
will happen as it should (albeit slowly).
@item When an extension module fails to load, @samp{cd /} gives a Lisp error
@item If a globbing pattern returns one match, should it be a list?
@item Make sure syntax table is correct in Eshell mode
So that @kbd{M-DEL} acts in a predictable manner, etc.
@item Allow all Eshell buffers to share the same history and list-dir
@item There is a problem with script commands that output to @file{/dev/null}
If a script file, somewhere in the middle, uses @samp{> /dev/null},
output from all subsequent commands is swallowed.
@item Split up parsing of text after @samp{$} in @file{esh-var.el}
Make it similar to the way that @file{esh-arg.el} is structured.
Then add parsing of @samp{$[?\n]}.
@item After pressing @kbd{M-RET}, redisplay before running the next command
@item Argument predicates and modifiers should work anywhere in a path
@example
/usr/local/src/editors/vim $ vi **/CVS(/)/Root(.)
Invalid regexp: "Unmatched ( or \\("
@end example
With @command{zsh}, the glob above expands to all files named
@file{Root} in directories named @file{CVS}.
@item Typing @samp{echo $@{locate locate@}/bin<TAB>} results in a Lisp error
Perhaps it should interpolate all permutations, and make that the
globbing result, since otherwise hitting return here will result in
``(list of filenames)/bin'', which is never valuable. Thus, one could
@command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}.
In that case, having an alias command name @command{glob} for
@command{identity} would be useful.
@item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp
@item Create @code{eshell-expand-file-name}
This would use a data table to transform things such as @samp{~+},
@samp{...}, etc.
@item Abstract @file{em-smart.el} into @file{smart-scroll.el}
It only really needs: to be hooked onto the output filter and the
pre-command hook, and to have the input-end and input-start markers.
And to know whether the last output group was ``successful.''
@item Allow for fully persisting the state of Eshell
This would include: variables, history, buffer, input, dir stack, etc.
@item Implement D as an argument predicate
It means that files beginning with a dot should be included in the
glob match.
@item A comma in a predicate list should mean OR
At the moment, this is not supported.
@item Error if a glob doesn't expand due to a predicate
An error should be generated only if @code{eshell-error-if-no-glob} is
non-@code{nil}.
@item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur
@item Create @code{eshell-auto-accumulate-list}
This is a list of commands for which, if the user presses @kbd{RET}, the
text is staged as the next Eshell command, rather than being sent to the
current interactive process.
@item Display file and line number if an error occurs in a script
@item @command{wait} doesn't work with process ids at the moment
@item Enable the direct-to-process input code in @file{em-term.el}
@item Problem with repeating @samp{echo $@{find /tmp@}}
With smart display active, if @kbd{RET} is held down, after a while it
can't keep up anymore and starts outputting blank lines. It only
happens if an asynchronous process is involved@dots{}
I think the problem is that @code{eshell-send-input} is resetting the
input target location, so that if the asynchronous process is not done
by the time the next @kbd{RET} is received, the input processor thinks
that the input is meant for the process; which, when smart display is
enabled, will be the text of the last command line! That is a bug in
itself.
In holding down @kbd{RET} while an asynchronous process is running,
there will be a point in between termination of the process, and the
running of @code{eshell-post-command-hook}, which would cause
@code{eshell-send-input} to call @code{eshell-copy-old-input}, and then
process that text as a command to be run after the process. Perhaps
there should be a way of killing pending input between the death of the
process, and the @code{post-command-hook}.
@item Allow for a more aggressive smart display mode
Perhaps toggled by a command, that makes each output block a smart
display block.
@item Create more meta variables
@table @samp
@item $!
The reason for the failure of the last disk command, or the text of the
last Lisp error.
@item $=
A special associate array, which can take references of the form
@samp{$=[REGEXP]}. It indexes into the directory ring.
@end table
@item Eshell scripts can't execute in the background
@item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{@var{name}:-@var{val}@}}
@item Write an @command{info} alias that can take arguments
So that the user can enter @samp{info chmod}, for example.
@item Create a mode @code{eshell-browse}
It would treat the Eshell buffer as a outline. Collapsing the outline
hides all of the output text. Collapsing again would show only the
first command run in each directory
@item Allow other revisions of a file to be referenced using @samp{file@{rev@}}
This would be expanded by @code{eshell-expand-file-name} (see above).
@item Print ``You have new mail'' when the ``Mail'' icon is turned on
@item Implement @kbd{M-|} for Eshell
@item Implement input redirection
If it's a Lisp function, input redirection implies @command{xargs} (in a
way@dots{}). If input redirection is added, also update the
@code{file-name-quote-list}, and the delimiter list.
@item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax
With the handling of @emph{word} specified by an
@code{eshell-special-alist}.
@item In @code{eshell-veal-using-options}, allow a @code{:complete} tag
It would be used to provide completion rules for that command. Then the
macro will automagically define the completion function.
@item For @code{eshell-command-on-region}, apply redirections to the result
So that @samp{+ > 'blah} would cause the result of the @code{+} (using
input from the current region) to be inserting into the symbol
@code{blah}.
If an external command is being invoked, the input is sent as standard
input, as if a @samp{cat <region> |} had been invoked.
If a Lisp command, or an alias, is invoked, then if the line has no
newline characters, it is divided by whitespace and passed as arguments
to the Lisp function. Otherwise, it is divided at the newline
characters. Thus, invoking @code{+} on a series of numbers will add
them; @code{min} would display the smallest figure, etc.
@item Write @code{eshell-script-mode} as a minor mode
It would provide syntax, abbrev, highlighting and indenting support like
@code{emacs-lisp-mode} and @code{shell-mode}.
@item In the history mechanism, finish the @command{bash}-style support
This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate
from @samp{!:1*}.
@item Support the -n command line option for @command{history}
@item Implement @command{fc} in Lisp
@item Specifying a frame as a redirection target should imply the currently active window's buffer
@item Implement @samp{>@var{func-or-func-list}}
This would allow for an ``output translators'', that take a function to
modify output with, and a target. Devise a syntax that works well with
pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase
regexp-quote)} or @samp{>'upcase}).
@item Allow Eshell to read/write to/from standard input and output
This would be optional, rather than always using the Eshell buffer.
This would allow it to be run from the command line (perhaps).
@item Write a @command{help} command
It would call subcommands with @option{--help}, or @option{-h} or
@option{/?}, as appropriate.
@item Implement @command{stty} in Lisp
@item Support @command{rc}'s matching operator, e.g. @samp{~ (@var{list}) @var{regexp}}
@item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list}
Using @command{bg} on a process that is already in the background does
nothing. Specifying redirection targets replaces (or adds) to the list
current being used.
@item Have @command{jobs} print only the processes for the current shell
@item How can Eshell learn if a background process has requested input?
@item Support @samp{2>&1} and @samp{>&} and @samp{2>} and @samp{|&}
The syntax table for parsing these should be customizable, such that the
user could change it to use rc syntax: @samp{>[2=1]}.
@item Allow @samp{$_[-1]}, which would indicate the last element of the array
@item Make @samp{$x[*]} equal to listing out the full contents of @samp{x}
Return them as a list, so that @samp{$_[*]} is all the arguments of the
last command.
@item Copy ANSI code handling from @file{term.el} into @file{em-term.el}
Make it possible for the user to send char-by-char to the underlying
process. Ultimately, I should be able to move away from using term.el
altogether, since everything but the ANSI code handling is already part
of Eshell. Then, things would work correctly on MS-Windows as well
(which doesn't have @file{/bin/sh}, although @file{term.el} tries to use
it).
@item Make the shell spawning commands be visual
That is, make (@command{su}, @command{bash}, @command{telnet},
@command{rlogin}, @command{rsh}, etc.) be part of
@code{eshell-visual-commands}. The only exception is if the shell is
being used to invoke a single command. Then, the behavior should be
based on what that command is.
@item Create a smart viewing command named @command{open}
This would search for some way to open its argument (similar to opening
a file in the Windows Explorer).
@item Alias @command{read} to be the same as @command{open}, only read-only
@item Write a @command{tail} command which uses @code{view-file}
It would move point to the end of the buffer, and then turns on
auto-revert mode in that buffer at frequent intervals---and a
@command{head} alias which assumes an upper limit of
@code{eshell-maximum-line-length} characters per line.
@item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search}
@item Write mesh.c
This would run Emacs with the appropriate arguments to invoke Eshell
only. That way, it could be listed as a login shell.
@item Use an intangible @code{PS2} string for multi-line input prompts
@item Auto-detect when a command is visual, by checking @code{TERMCAP} usage
@item The first keypress after @kbd{M-x watson} triggers `eshell-send-input'
@item Make @kbd{/} electric
So that it automatically expands and corrects pathnames. Or make
pathname completion for Pcomplete auto-expand @samp{/u/i/std<TAB>} to
@samp{/usr/include/std<TAB>}.
@item Write the @command{pushd} stack to disk along with @code{last-dir-ring}
@item Add options to @code{eshell/cat} which would allow it to sort and uniq
@item Implement @command{wc} in Lisp
Add support for counting sentences, paragraphs, pages, etc.
@item Once piping is added, implement @command{sort} and @command{uniq} in Lisp
@item Implement @command{touch} in Lisp
@item Implement @command{comm} in Lisp
@item Implement an @command{epatch} command in Lisp
This would call @code{ediff-patch-file}, or @code{ediff-patch-buffer},
depending on its argument.
@item Have an option such that @samp{ls -l} generates a dired buffer
@item Write a version of @command{xargs} based on command rewriting
That is, @samp{find X | xargs Y} would be indicated using @samp{Y
$@{find X@}}. Maybe @code{eshell-do-pipelines} could be changed to
perform this on-thy-fly rewriting.
@item Write an alias for @command{less} that brings up a @code{view-mode} buffer
Such that the user can press @key{SPC} and @key{DEL}, and then @key{q}
to return to Eshell. It would be equivalent to:
@samp{X > #<buffer Y>; view-buffer #<buffer Y>}.
@item Make @code{eshell-mode} as much a full citizen as @code{shell-mode}
Everywhere in Emacs where @code{shell-mode} is specially noticed, add
@code{eshell-mode} there.
@item Permit the umask to be selectively set on a @command{cp} target
@item Problem using @kbd{M-x eshell} after using @code{eshell-command}
If the first thing that I do after entering Emacs is to run
@code{eshell-command} and invoke @command{ls}, and then use @kbd{M-x
eshell}, it doesn't display anything.
@item @kbd{M-RET} during a long command (using smart display) doesn't work
Since it keeps the cursor up where the command was invoked.
@end table
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
@node Concept Index
@unnumbered Concept Index
@printindex cp
@node Function and Variable Index
@unnumbered Function and Variable Index
@printindex fn
@node Key Index
@unnumbered Key Index
@printindex ky
@bye
@ignore
arch-tag: 776409ba-cb15-42b9-b2b6-d2bdc7ebad01
@end ignore

985
doc/misc/eudc.texi Normal file
View file

@ -0,0 +1,985 @@
\input texinfo.tex
@c %**start of header
@setfilename ../info/eudc
@settitle Emacs Unified Directory Client (EUDC) Manual
@afourpaper
@c %**end of header
@copying
This file documents EUDC v1.30b.
EUDC is the Emacs Unified Directory Client, a common interface to
directory servers using various protocols such as LDAP or the CCSO white
pages directory system (PH/QI)
Copyright @copyright{} 1998, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* EUDC: (eudc). An Emacs client for directory servers (LDAP, PH).
@end direntry
@footnotestyle end
@titlepage
@title{EUDC Manual}
@subtitle{The Emacs Unified Directory Client}
@author by Oscar Figueiredo
@code{1.30b}
@page
@vskip 0pt plus 1fill
@insertcopying
@end titlepage
@ifnottex
@node Top, Overview, (dir), (dir)
@comment node-name, next, previous, up
This manual documents EUDC v1.30b, the Emacs Unified Directory Client.
A common interface to directory servers using various protocols such as
LDAP or the CCSO white pages directory system (PH/QI)
@end ifnottex
@menu
* Overview:: Summary of EUDC features
* Installation:: How to install EUDC
* Usage:: The various usage possibilities explained
* Credits:: Who's done what
* GNU Free Documentation License:: The license for this documentation.
* Command and Function Index::
* Variables Index::
@end menu
@node Overview, Installation, Top, Top
@comment node-name, next, previous, up
@chapter Overview
EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user
interface to access directory servers using different directory
protocols.
Currently supported back-ends are:
@itemize @bullet
@item
LDAP, Lightweight Directory Access Protocol
@item
CCSO PH/QI
@item
BBDB, Big Brother's Insidious Database
@end itemize
The main features of the EUDC interface are:
@itemize @bullet
@item
Queries using a customizable form
@item
Inline query expansion (for instance you can expand a name
to an email address in a mail message buffer using a server as an
address book)
@item
Multiple servers can be tried in turn until a match is found for an
inline query
@item
Fast minibuffer queries for email addresses and phone numbers
@item
Interface to BBDB to let you insert server records into your own BBDB database
(@pxref{Top,,BBDB,bbdb,BBDB Manual})
@end itemize
@menu
* LDAP:: What is LDAP ?
* CCSO PH/QI:: What is CCSO, PH, QI ?
* BBDB:: What is BBDB ?
@end menu
@node LDAP, CCSO PH/QI, Overview, Overview
@comment node-name, next, previous, up
@section LDAP
LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication
protocol for directory applications defined in RFC 1777.
Quoted from RFC 1777:
@quotation
[LDAP] is designed to provide access to the X.500 Directory while not
incurring the resource requirements of the Directory Access Protocol
(DAP). This protocol is specifically targeted at simple management
applications and browser applications that provide simple read/write
interactive access to the X.500 Directory, and is intended to be a
complement to the DAP itself.
@end quotation
LDAP servers usually store (but are not limited to) information about
people such as their name, phone number, email address, office
location, etc@enddots{} More information about LDAP can be found at
@url{http://www.openldap.org/}
EUDC requires external support to access LDAP directory servers
(@pxref{LDAP Requirements})
@node CCSO PH/QI, BBDB, LDAP, Overview
@comment node-name, next, previous, up
@section CCSO PH/QI
The Central Computing Services Office (CCSO) of the University of
Illinois at Urbana Champaign (UIUC) created and freely distributes a
directory system that is currently in use in more than 300 organizations
around the world. The system records information about people such as
their address, phone number, email, academic information or any other
details it was configured to.
The system consists of two parts: a database server traditionally called
@samp{qi} and a command-line client called @samp{ph}.
@url{ftp://uiarchive.cso.uiuc.edu/pub/packages/ph} is the main
distribution site. @url{http://www.uiuc.edu/cgi-bin/ph/lookup?Query=.}
provides a listing of the active @samp{qi} servers.
The original command-line @samp{ph} client that comes with the
@samp{ph/qi} distribution provides additional features like the
possibility to communicate with the server in login-mode which makes it
possible to change records in the database. This is not implemented in
EUDC.
@node BBDB, , CCSO PH/QI, Overview
@comment node-name, next, previous, up
@section BBDB
BBDB is the @dfn{Big Brother's Insidious Database}, a package for Emacs
originally written by Jamie Zawinski which provides rolodex-like
database functionality featuring tight integration with the Emacs mail
and news readers.
It is often used as an enhanced email address book.
EUDC considers BBDB as a directory server back end just like LDAP or
PH/QI servers, though BBDB has no client/server protocol and thus always
resides locally on your machine. The point in this is not to offer an
alternate way to query your BBDB database (BBDB itself provides much
more flexible ways to do that), but rather to offer an interface to your
local directory that is consistent with the interface to external
directories (LDAP, PH/QI). This is particularly interesting when
performing queries on multiple servers.
EUDC also offers a means to insert results from directory queries into
your own local BBDB (@pxref{Creating BBDB Records})
@node Installation, Usage, Overview, Top
@comment node-name, next, previous, up
@chapter Installation
Add the following to your @file{.emacs} init file:
@lisp
(require 'eudc)
@end lisp
This will install EUDC at startup.
After installing EUDC you will find (the next time you launch Emacs) a
new @code{Directory Search} submenu in the @samp{Tools} menu that will
give you access to EUDC.
You may also find it useful to add the following to your @file{.emacs}
initialization file to add a shortcut for email address expansion in
email composition buffers (@pxref{Inline Query Expansion})
@lisp
(eval-after-load
"message"
'(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
(eval-after-load
"sendmail"
'(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline))
@end lisp
@menu
* LDAP Requirements:: EUDC needs external support for LDAP
@end menu
@node LDAP Requirements, , Installation, Installation
@comment node-name, next, previous, up
@section LDAP Requirements
LDAP support is added by means of @file{ldap.el} which is part of Emacs.
@file{ldap.el} needs an external command line utility named
@file{ldapsearch} which is available as part of LDAP toolkits:
@itemize @bullet
@item
Open LDAP Libraries
(@url{http://www.openldap.org/})
@item
University of Michigan's LDAP Client software
(@url{http://www.umich.edu/~dirsvcs/ldap/})
@end itemize
@node Usage, Credits, Installation, Top
@comment node-name, next, previous, up
@chapter Usage
This chapter describes the usage of EUDC. Most functions and
customization options are available through the @samp{Directory Search}
submenu of the @samp{Tools} submenu.
@menu
* Querying Servers:: How queries are performed and handled
* Query Form:: How to use and customize the query form
* Display of Query Results:: Controlling how query results are presented
* Inline Query Expansion:: How to use and customize inline queries
* The Server Hotlist:: How to use and manage the server hotlist
* Multi-server Queries:: How to query multiple servers successively
* Creating BBDB Records:: How to insert query results into your BBDB
* Server/Protocol Locals:: Customizing on a per server/protocol basis
@end menu
@node Querying Servers, Query Form, Usage, Usage
@comment node-name, next, previous, up
@section Querying Servers
EUDC's basic functionality is to let you query a directory server and
return the results back to you. There are several things you may want
to customize in this process.
@menu
* Selecting a Server:: The first thing to do
* Return Attributes:: Configuring what the server should return
* Duplicate Attributes:: What to do when records have duplicate attributes
@end menu
@node Selecting a Server, Return Attributes, Querying Servers, Querying Servers
@subsection Selecting a Server
Before doing any query you will need to set the directory server. You
need to specify the name of the host machine running the server software
and the protocol to use. If you do not set the server in any fashion,
EUDC will ask you for one when you make your first query.
You can set the server by selecting one from your hotlist of servers
(@pxref{The Server Hotlist}) available in the @samp{Server} submenu or
by selecting @samp{New Server} in that same menu.
LDAP servers generally require some configuration before you can perform
queries on them. In particular, the @dfn{search base} must be
configured. If the server you select has no configured search base then
EUDC will propose you to configure it at this point. A customization
buffer will be displayed where you can edit the search base and other
parameters for the server.
@defvar eudc-server
The name or IP address of the remote directory server. A TCP port number
may be specified by appending a colon and a number to the name of the
server. You will not need this unless your server runs on a port other
than the default (which depends on the protocol).
If the directory server resides on your own computer (which is the case
if you use the BBDB back end) then `localhost' is a reasonable value but
it will be ignored anyway.
@end defvar
@defvar eudc-protocol
The directory protocol to use to query the server. Currently supported
protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}.
@end defvar
@deffn Command eudc-set-server
This command accessible from @samp{New Server} submenu lets you specify a
new directory server and protocol.
@end deffn
@node Return Attributes, Duplicate Attributes, Selecting a Server, Querying Servers
@subsection Return Attributes
Directory servers may be configured to return a default set of
attributes for each record matching a query if the query specifies none.
The variable @code{eudc-default-return-attributes} controls the return
attributes you want to see, if different from the server defaults.
@defvar eudc-default-return-attributes
A list of the default attributes to extract from directory entries. If
set to the symbol @code{all} then all available attributes are
returned. A value of @code{nil}, the default, means to return the
default attributes as configured in the server.
@end defvar
The server may return several matching records to a query. Some of the
records may however not contain all the attributes you requested. You can
discard those records.
@defopt eudc-strict-return-matches
If non-@code{nil}, entries that do not contain all the requested return
attributes are ignored. Default is @code{t}.
@end defopt
@node Duplicate Attributes, , Return Attributes, Querying Servers
@subsection Duplicate Attributes
Directory standards may authorize different instances of the same
attribute in a record. For instance the record of a person may contain
several email fields containing different email addresses. When using
a QI directory server this is difficult to distinguish from attributes
having multi-line values such as the postal address that may contain a
line for the street and another one for the zip code and city name. In
both cases, EUDC will consider the attribute duplicated.
EUDC has several methods to deal with duplicated attributes. The
available methods are:
@table @code
@item list
Makes a list with the different values of the duplicate attribute. The
record is returned with only one instance of the attribute with a list
of all the different values as a value. This is the default method that
is used to handle duplicate fields for which no other method has been
specified.
@item first
Discards all the duplicate values of the field keeping only the first
one.
@item concat
Concatenates the different values using a newline as a separator. The
record keeps only one instance of the field the value of which is a
single multi-line string.
@item duplicate
Duplicates the whole record into as many instances as there are different
values for the field. This is the default for the email field. Thus a
record containing 3 different email addresses is duplicated into three
different records each having a single email address. This is
particularly useful in combination with @code{select} as the method to
handle multiple matches in inline expansion queries (@pxref{Inline Query
Expansion}) because you are presented with the 3 addresses in a
selection buffer
@end table
Because a method may not be applicable to all fields, the variable
@code{eudc-duplicate-attribute-handling-method} lets you specify either a
default method for all fields or a method for each individual field.
@defvar eudc-duplicate-attribute-handling-method
A method to handle entries containing duplicate attributes. This is
either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol
@var{method}. The alist form of the variable associates a method to an
individual attribute name; the second form specifies a method applicable
to all attribute names. Available methods are: @code{list},
@code{first}, @code{concat}, and @code{duplicate} (see above). The default is
@code{list}.
@end defvar
@node Query Form, Display of Query Results, Querying Servers, Usage
@comment node-name, next, previous, up
@section Query Form
The simplest way to query your directory server is to use the query
form. You display the query form with the @samp{Query with Form} menu
item or by invoking the command @kbd{M-x eudc-query-form}. The attribute
names presented in this form are defined by the
@code{eudc-query-form-attributes} variable (unless a non-@code{nil}
argument is supplied to @code{eudc-query-form}).
Since the different directory protocols to which EUDC interfaces may
use different names for equivalent attributes, EUDC defines its own set
of attribute names and a mapping between these names and their
protocol-specific equivalent through the variable
@code{eudc-protocol-attributes-translation-alist}. Names currently
defined by EUDC are @code{name}, @code{firstname}, @code{email} and
@code{phone}.
@defvar eudc-query-form-attributes
@findex eudc-get-attribute-list
A list of attributes presented in the query form. Attribute names in
this list should be either EUDC attribute names or valid attribute
names. You can get a list of valid attribute names for the current
protocol with the @samp{List Valid Attribute Names} menu item or the
@kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name},
@code{email} and @code{phone}.
@end defvar
@deffn Command eudc-query-form get-fields-from-server
Display a form to query the directory server. If given a non-@code{nil}
argument the function first queries the server for the existing fields
and displays a corresponding form. Not all protocols may support a
non-@code{nil} argument here.
@end deffn
Since the names of the fields may not be explicit enough or adapted to
be directly displayed as prompt strings in the form, the variable
@code{eudc-user-attribute-names-alist} lets you define more explicit
names for directory attribute names. This variable is ignored if
@code{eudc-use-raw-directory-names} is non-@code{nil}.
@defvar eudc-user-attribute-names-alist
This is an alist of user-defined names for the directory attributes used in
query/response forms. Prompt strings for attributes that are not in this
alist are derived by splitting the attribute name at underscores and
capitalizing the individual words.
@end defvar
@defvar eudc-use-raw-directory-names
If non-@code{nil}, use attributes names as defined in the directory.
Otherwise, directory query/response forms display the user attribute
names defined in @code{eudc-user-attribute-names-alist}.
@end defvar
@node Display of Query Results, Inline Query Expansion, Query Form, Usage
@comment node-name, next, previous, up
@section Display of Query Results
Upon successful completion of a form query, EUDC will display a buffer
containing the results of the query.
The fields that are returned for each record
are controlled by @code{eudc-default-return-attributes} (@pxref{Return
Attributes}).
The display of each individual field can be performed by an arbitrary
function which allows specific processing for binary values, such as
images or audio samples, as well as values with semantics, such as
URLs.
@defvar eudc-attribute-display-method-alist
An alist specifying methods to display attribute values. Each member of
the list is of the form @code{(@var{name} . @var{func})} where
@var{name} is a lowercased string naming a directory attribute
(translated according to @code{eudc-user-attribute-names-alist} if
@code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a
function that will be passed the corresponding attribute values for
display.
@end defvar
This variable has protocol-local definitions (see @pxref{Server/Protocol
Locals}). For instance, it is defined as follows for LDAP:
@lisp
(eudc-protocol-set 'eudc-attribute-display-method-alist
'(("jpegphoto" . eudc-display-jpeg-inline)
("labeledurl" . eudc-display-url)
("audio" . eudc-display-sound)
("labeledurl" . eudc-display-url)
("url" . eudc-display-url))
'ldap)
@end lisp
EUDC provides a set of built-in functions to display binary value types:
@defun eudc-display-generic-binary data
Display a button for unidentified binary @var{data}.
@end defun
@defun eudc-display-url url
Display URL and make it clickable.
@end defun
@defun eudc-display-sound data
Display a button to play the sound @var{data}.
@end defun
@defun eudc-display-jpeg-inline data
Display the JPEG @var{data} inline at point if possible.
@end defun
@defun eudc-display-jpeg-as-button data
Display a button for the JPEG @var{data}.
@end defun
Right-clicking on a binary value button pops up a contextual menu with
options to process the value. Among these are saving the attribute
value to a file or sending it to an external viewer command. External
viewers should expect the value on their standard input and should
display it or perform arbitrary processing on it. Messages sent to
standard output are discarded. External viewers are listed in the
variable @code{eudc-external-viewers} which you can customize.
@defvar eudc-external-viewers
This is a list of viewer program specifications. Each specification is
a list whose first element is a string naming the viewer for unique
identification, the second element is the executable program which
should be invoked and the following elements are arguments that should
be passed to the program.
@end defvar
@node Inline Query Expansion, The Server Hotlist, Display of Query Results, Usage
@comment node-name, next, previous, up
@section Inline Query Expansion
Inline query expansion is a powerful method to get completion from your
directory server. The most common usage is for expanding names to email
addresses in mail message buffers. The expansion is performed by the
command @kbd{M-x eudc-expand-inline} which is available from the
@samp{Expand Inline Query} menu item but can also be conveniently
bound to a key shortcut (@pxref{Installation}). The operation is
controlled by the variables @code{eudc-inline-expansion-format},
@code{eudc-inline-query-format},
@code{eudc-expanding-overwrites-query} and
@code{eudc-multiple-match-handling-method}.
If the query fails for a server, other servers may be tried successively
until one of them finds a match (@pxref{Multi-server Queries}).
@deffn Command eudc-expand-inline replace-p
Query the server and expand the query string before point. The query
string consists of the buffer substring from the point back to the
preceding comma, colon or beginning of
line. @code{eudc-inline-query-format} controls how individual words
are mapped onto directory attribute names. After querying the server
for the given string, the expansion specified by
@code{eudc-inline-expansion-format} is inserted in the buffer at
point. If @var{replace-p} is @code{t} then this expansion replaces the
query string in the buffer. If @code{eudc-expanding-overwrites-query}
is non-@code{nil} then the meaning of @var{replace-p} is negated.
@end deffn
@defvar eudc-inline-query-format
Format of an inline expansion query.
This is actually a list of @var{format}s. A @var{format} is a list of
one or more EUDC attribute names. A @var{format} applies if it contains
as many attributes as individual words in the inline query string. If
several @var{format}s apply then they are tried in order until a match
is found. If @code{nil} all the words will be mapped onto the default
server/protocol attribute name (generally @code{name}).
For instance, use the following
@lisp
(setq eudc-inline-query-format '((name)
(firstname)
(firstname name)))
@end lisp
@noindent
to indicate that single word expansion queries are to be considered as
surnames and if no match is found then they should be tried as first
names. Inline queries consisting of two words are considered as
consisting of a first name followed by a surname. If the query consists
of more than two words, then the first one is considered as the first
name and the remaining words are all considered as surname constituents.
@var{format}s are in fact not limited to EUDC attribute names, you can
use server or protocol specific names in them. It may be safer if you
do so, to set the variable @code{eudc-inline-query-format} in a protocol
or server local fashion (see @pxref{Server/Protocol Locals}).
For instance you could use the following to match up to three words
against the @code{cn} attribute of LDAP servers:
@lisp
(eudc-protocol-set 'eudc-inline-query-format
'((cn)
(cn cn)
(cn cn cn))
'ldap)
@end lisp
@end defvar
@defvar eudc-inline-expansion-format
This variable lets you control exactly what is inserted into the buffer
upon an inline expansion request. It is a list whose first element is a
string passed to @code{format}. Remaining elements are symbols
corresponding to directory attribute names. The corresponding attribute
values are passed as additional arguments to @code{format}. Default is
@code{("%s" email)} but you may want to consider a value like @code{("%s
<%s>" name email)}
@end defvar
@defvar eudc-multiple-match-handling-method
This variable controls what to do when multiple entries match a query
for an inline expansion. Possible values are:
@table @code
@item first
The first match is considered as being the only one, the others are
discarded.
@item select
A selection buffer pops up where you can choose a particular match. This
is the default value of the variable.
@item all
The expansion uses all records successively
@item abort
An error is signaled. The expansion aborts.
@end table
Default is @code{select}
@end defvar
@node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage
@comment node-name, next, previous, up
@section The Server Hotlist
EUDC lets you maintain a list of frequently used servers so that you
can easily switch from one to another. This hotlist appears in the
@samp{Server} submenu. You select a server in this list by clicking on
its name. You can add the current server to the list with the command
@kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable
@code{eudc-server-hotlist} which is stored in and retrieved from the file
designated by @code{eudc-options-file}. EUDC also provides a facility to
edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}).
The hotlist is also used to make queries on multiple servers
successively (@pxref{Multi-server Queries}). The order in which the
servers are tried is the order they appear in the hotlist, therefore it
is important to sort the hotlist appropriately.
@deffn Command eudc-bookmark-server server
Add @var{server} to the hotlist of servers
@end deffn
@deffn Command eudc-bookmark-current-server
Add the current server to the hotlist of servers
@end deffn
@defvar eudc-options-file
The name of a file where EUDC stores its internal variables
(the hotlist and the current server). EUDC will try to load
that file upon initialization so, if you choose a file name
different from the defaults @file{~/.eudc-options}, be sure to set this
variable to the appropriate value @emph{before} EUDC is itself
loaded.
@end defvar
@menu
* The Hotlist Edit Buffer:: An interactive hotlist editing facility
@end menu
@node The Hotlist Edit Buffer, , The Server Hotlist, The Server Hotlist
@comment node-name, next, previous, up
@subsection The Hotlist Edit Buffer
The hotlist edit buffer offers a means to manage a list of frequently
used servers. Commands are available in the context pop-up menu
generally bound to the right mouse button. Those commands also have
equivalent key bindings.
@deffn Command eudc-hotlist-add-server
Bound to @kbd{a}.
Add a new server to the hotlist on the line after point
@end deffn
@deffn Command eudc-hotlist-delete-server
Bound to @kbd{d}.
Delete the server on the line point is on
@end deffn
@deffn Command eudc-hotlist-select-server
Bound to @kbd{s}.
Select the server the point is on as the current directory server for
the next queries
@end deffn
@deffn Command eudc-hotlist-transpose-servers
Bound to @kbd{t}.
Bubble up the server the point is on to the top of the list
@end deffn
@deffn Command eudc-hotlist-quit-edit
Bound to @kbd{q}.
Save the changes and quit the hotlist edit buffer. Use @kbd{x} or
@kbd{M-x kill-buffer} to exit without saving.
@end deffn
@node Multi-server Queries, Creating BBDB Records, The Server Hotlist, Usage
@comment node-name, next, previous, up
@section Multi-server Queries
When using inline query expansion (@pxref{Inline Query Expansion}), EUDC
can try to query successively a sequence of directory servers until one
of them successfully finds a match for the query.
@defvar eudc-inline-expansion-servers
This variable controls which servers are tried and in which order when
trying to perform an inline query. Possible values are:
@table @code
@item current-server
Only the current directory server is tried
@item hotlist
The servers in the hotlist are tried in order until one finds a match
for the query or `eudc-max-servers-to-query' is reached
@item server-then-hotlist
The current server then the servers in the hotlist are tried in the
order they appear in the hotlist until one of them finds a match or
`eudc-max-servers-to-query' is reached. This is the default.
@end table
@end defvar
@defvar eudc-max-servers-to-query
This variable indicates the maximum number of servers to query when
performing a multi-server query. The default, @code{nil}, indicates
that all available servers should be tried.
@end defvar
@node Creating BBDB Records, Server/Protocol Locals, Multi-server Queries, Usage
@comment node-name, next, previous, up
@section Creating BBDB Records
@findex eudc-insert-record-at-point-into-bbdb
@findex eudc-try-bbdb-insert
With EUDC, you can automatically create BBDB records
(@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a
directory server. You do this by moving point to the appropriate
record in a query result display buffer and invoking the command
@kbd{M-x eudc-insert-record-at-point-into-bbdb} with the
keyboard binding @kbd{b}@footnote{This key binding does not actually
call @code{eudc-insert-record-at-point-into-bbdb} but uses
@code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC
cannot update an existing BBDB record and will signal an error if you
try to insert a record matching an existing one.
@findex eudc-batch-export-records-to-bbdb
It is also possible to export to BBDB the whole batch of records
contained in the directory query result with the command
@kbd{M-x eudc-batch-export-records-to-bbdb}.
Because directory systems may not enforce a strict record format, local
server installations may use different attribute names and have
different ways to organize the information. Furthermore BBDB has its own
record structure. For these reasons converting a record from its
external directory format to the BBDB format is a highly customizable
process.
@defvar eudc-bbdb-conversion-alist
The value of this variable should be a symbol naming an alist defining a
mapping between BBDB field names onto directory attribute names records.
This is a protocol-local variable and is initialized upon protocol
switch (@pxref{Server/Protocol Locals}). The alist is made of cells of the
form @code{(@var{bbdb-field} . @var{spec-or-list})}.
@var{bbdb-field} is the name of a field
that must be defined in your BBDB environment (standard field names are
@code{name}, @code{company}, @code{net}, @code{phone}, @code{address}
and @code{notes}).
@var{spec-or-list} is either a single mapping specification or a list of
mapping specifications. Lists of mapping specifications are valid for
the @code{phone} and @code{address} BBDB fields only. @var{spec}s are
actually s-expressions which are evaluated as follows:
@table @asis
@item a string
evaluates to itself
@item a symbol
evaluates to the symbol value. Symbols corresponding to directory
attribute names present in the record evaluate to the value of the field
in the record
@item a form
is evaluated as a function. The argument list may contain attribute
names which evaluate to the corresponding values in the record. The form
evaluation should return something appropriate for the particular
@var{bbdb-field} (see @code{bbdb-create-internal}).
@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as
convenience functions to parse phones and addresses.
@end table
@end defvar
The default value of the PH-specific value of that variable is
@code{eudc-ph-bbdb-conversion-alist}:
@lisp
((name . name)
(net . email)
(address . (eudc-bbdbify-address address "Address"))
(phone . ((eudc-bbdbify-phone phone "Phone")
(eudc-bbdbify-phone office_phone "Office Phone"))))
@end lisp
This means that:
@itemize @bullet
@item
the @code{name} field of the BBDB record gets its value
from the @code{name} attribute of the directory record
@item
the @code{net} field of the BBDB record gets its value
from the @code{email} attribute of the directory record
@item
the @code{address} field of the BBDB record is obtained by parsing the
@code{address} attribute of the directory record with the function
@code{eudc-bbdbify-address}
@item
two @code{phone} fields are created (when possible) in the BBDB record.
The first one has @cite{Phone} for location and its value is obtained by
parsing the @code{phone} attribute of the PH/QI record with the function
@code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location
its value is obtained by parsing the @code{office_phone} attribute of the
PH/QI record with the function @code{eudc-bbdbify-phone}.
@end itemize
@defun eudc-bbdbify-phone phone location
This is a convenience function provided for use in
@code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector
compatible with @code{bbdb-create-internal}. @var{phone} is either a string
supposedly containing a phone number or a list of such strings which are
concatenated. @var{location} is used as the phone location for BBDB.
@end defun
@defun eudc-bbdbify-address addr location
This is a convenience function provided for use in
@code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector
compatible with @code{bbdb-create-internal}. @var{addr} should be an
address string of no more than four lines or a list of lines. The last
line is searched for the zip code, city and state name. @var{location}
is used as the phone location for BBDB.
@end defun
Note that only a subset of the attributes you selected with
@code{eudc-default-return-attributes} and that are actually displayed may
actually be inserted as part of the newly created BBDB record.
@node Server/Protocol Locals, , Creating BBDB Records, Usage
@comment node-name, next, previous, up
@section Server/Protocol Locals
EUDC can be customized independently for each server or directory
protocol. All variables can be given local bindings that are activated
when a particular server and/or protocol becomes active. This is much
like buffer-local bindings but on a per server or per protocol basis.
@menu
* Manipulating local bindings:: Functions to set and query local bindings
@end menu
@node Manipulating local bindings, , Server/Protocol Locals, Server/Protocol Locals
@comment node-name, next, previous, up
@subsection Manipulating local bindings
EUDC offers functions that let you set and query variables on a per
server or per protocol basis.
The following predicates allow you to test the existence of
server/protocol local bindings for a particular variable.
@defun eudc-server-local-variable-p var
Return non-@code{nil} if @var{var} has server-local bindings
@end defun
@defun eudc-protocol-local-variable-p var
Return non-@code{nil} if @var{var} has protocol-local bindings
@end defun
The following functions allow you to set the value of a variable with
various degrees of locality.
@defun eudc-default-set var val
Set the EUDC default value of @var{var} to @var{val}.
The current binding of @var{var} (if local to the current server or
protocol) is not changed.
@end defun
@defun eudc-protocol-set var val &optional protocol
Set the binding of @var{var} local to @var{protocol} to @var{val}. If
omitted, @var{protocol} defaults to the current value of
@code{eudc-protocol}. The current binding of @var{var} is changed only
if @var{protocol} is omitted.
@end defun
@defun eudc-server-set var val &optional server
Set the binding of @var{var} local to @var{server} to @var{val}. If
omitted, @var{server} defaults to the current value of
@code{eudc-server}. The current binding of @var{var} is changed only if
@var{server} is omitted.
@end defun
@defun eudc-set var val
Set the most local (server, protocol or default) binding of @var{var} to
@var{val}. The current binding of @var{var} is also set to @var{val}.
@end defun
The following variables allow you to query the various bindings of a
variable (local or non-local).
@defun eudc-variable-default-value var
Return the default binding of @var{var} (outside of a particular server
or protocol local binding).
Return @code{unbound} if @var{var} has no EUDC default value.
@end defun
@defun eudc-variable-protocol-value var &optional protocol
Return the value of @var{var} local to @var{protocol}. Return
@code{unbound} if @var{var} has no value local to @var{protocol}.
@var{protocol} defaults to @code{eudc-protocol}.
@end defun
@defun eudc-variable-server-value var [server]
Return the value of @var{var} local to @var{server}.
Return @code{unbound} if @var{var} has no value local to @var{server}.
@var{server} defaults to @code{eudc-server}.
@end defun
Changing a protocol-local or server-local value of a variable has no
effect on its current value. The following command is used to
synchronize the current values of variables with their local values
given the current @code{eudc-server} and @code{eudc-protocol}:
@defun eudc-update-local-variables
Update all EUDC variables according to their local settings.
@end defun
@node Credits, GNU Free Documentation License, Usage, Top
@comment node-name, next, previous, up
@chapter Credits
EUDC was written by Oscar Figueiredo based on @file{ph.el} by the
same author.
Thanks to Soren Dayton for his suggestions, his enthusiasm and his help
in testing and proofreading the code and docs of @file{ph.el}.
@node GNU Free Documentation License, Command and Function Index, Credits, Top
@appendix GNU Free Documentation License
@include doclicense.texi
@node Command and Function Index, Variables Index, GNU Free Documentation License, Top
@comment node-name, next, previous, up
@unnumbered Command and Function Index
@printindex fn
@node Variables Index, , Command and Function Index, Top
@comment node-name, next, previous, up
@unnumbered Variables Index
@printindex vr
@setchapternewpage odd
@contents
@bye
@ignore
arch-tag: 1b79460b-4ea1-441d-ab45-05ddd16ef241
@end ignore

5590
doc/misc/faq.texi Normal file
View file

File diff suppressed because it is too large Load diff

762
doc/misc/flymake.texi Normal file
View file

@ -0,0 +1,762 @@
\input texinfo @c -*-texinfo-*-
@comment %**start of header
@setfilename ../info/flymake
@set VERSION 0.3
@set UPDATED April 2004
@settitle GNU Flymake @value{VERSION}
@syncodeindex pg cp
@comment %**end of header
@copying
This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}),
which is a universal on-the-fly syntax checker for GNU Emacs.
Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''
in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* Flymake: (flymake). A universal on-the-fly syntax checker.
@end direntry
@titlepage
@title GNU Flymake
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Pavel Kobiakov(@email{pk_at_work@@yahoo.com})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top GNU Flymake
@end ifnottex
@menu
* Overview of Flymake::
* Installing Flymake::
* Using Flymake::
* Configuring Flymake::
* Flymake Implementation::
* GNU Free Documentation License::
* Index::
@end menu
@node Overview of Flymake
@chapter Overview
@cindex Overview of Flymake
Flymake is a universal on-the-fly syntax checker implemented as an
Emacs minor mode. Flymake runs the pre-configured syntax check tool
(compiler for C++ files, @code{perl} for perl files, etc.) in the
background, passing it a temporary copy of the current buffer, and
parses the output for known error/warning message patterns. Flymake
then highlights erroneous lines (i.e. lines for which at least one
error or warning has been reported by the syntax check tool), and
displays an overall buffer status in the mode line. Status information
displayed by Flymake contains total number of errors and warnings
reported for the buffer during the last syntax check.
@code{flymake-goto-next-error} and @code{flymake-goto-prev-error}
functions allow for easy navigation to the next/previous erroneous
line, respectively.
Calling @code{flymake-display-err-menu-for-current-line} will popup a
menu containing error messages reported by the syntax check tool for
the current line. Errors/warnings belonging to another file, such as a
@code{.h} header file included by a @code{.c} file, are shown in the
current buffer as belonging to the first line. Menu items for such
messages also contain a filename and a line number. Selecting such a
menu item will automatically open the file and jump to the line with
error.
Syntax check is done 'on-the-fly'. It is started whenever
@itemize @bullet
@item buffer is loaded
@item a newline character is added to the buffer
@item some changes were made to the buffer more than @code{0.5} seconds ago (the
delay is configurable).
@end itemize
Flymake is a universal syntax checker in the sense that it's easily
extended to support new syntax check tools and error message
patterns. @xref{Configuring Flymake}.
@node Installing Flymake
@chapter Installing
@cindex Installing Flymake
Flymake is packaged in a single file, @code{flymake.el}.
To install/update Flymake, place @code{flymake.el} to a directory
somewhere on Emacs load path. You might also want to byte-compile
@code{flymake.el} to improve performance.
Also, place the following line in the @code{.emacs} file.
@lisp
(require 'flymake)
@end lisp
You might also map the most frequently used Flymake functions, such as
@code{flymake-goto-next-error}, to some keyboard shortcuts:
@lisp
(global-set-key [f3] 'flymake-display-err-menu-for-current-line)
(global-set-key [f4] 'flymake-goto-next-error)
@end lisp
@node Using Flymake
@chapter Using Flymake
@cindex Using Flymake
@menu
* Flymake mode::
* Running the syntax check::
* Navigating to error lines::
* Viewing error messages::
* Syntax check statuses::
* Troubleshooting::
@end menu
@node Flymake mode
@section Flymake mode
@cindex flymake-mode
Flymake is an Emacs minor mode. To use Flymake, you
must first activate @code{flymake-mode} by using the
@code{flymake-mode} function.
Instead of manually activating @code{flymake-mode}, you can configure
Flymake to automatically enable @code{flymake-mode} upon opening any
file for which syntax check is possible. To do so, place the following
line in @code{.emacs}:
@lisp
(add-hook 'find-file-hook 'flymake-find-file-hook)
@end lisp
@node Running the syntax check
@section Running the syntax check
@cindex Manually starting the syntax check
When @code{flymake-mode} is active, syntax check is started
automatically on any of the three conditions mentioned above. Syntax
check can also be started manually by using the
@code{flymake-start-syntax-check-for-current-buffer} function. This
can be used, for example, when changes were made to some other buffer
affecting the current buffer.
@node Navigating to error lines
@section Navigating to error lines
@cindex Navigating to error lines
After syntax check is completed, lines for which at least one error or
warning has been reported are highlighted, and total number of errors
and warning is shown in the mode line. Use the following functions to
navigate the highlighted lines.
@multitable @columnfractions 0.25 0.75
@item @code{flymake-goto-next-error}
@tab Moves point to the next erroneous line, if any.
@item @code{flymake-goto-prev-error}
@tab Moves point to the previous erroneous line.
@end multitable
These functions treat erroneous lines as a linked list. Therefore,
@code{flymake-goto-next-error} will go to the first erroneous line
when invoked in the end of the buffer.
@node Viewing error messages
@section Viewing error messages
@cindex Viewing error messages
To view error messages belonging to the current line, use the
@code{flymake-display-err-menu-for-current-line} function. If there's
at least one error or warning reported for the current line, this
function will display a popup menu with error/warning texts.
Selecting the menu item whose error belongs to another file brings
forward that file with the help of the
@code{flymake-goto-file-and-line} function.
@node Syntax check statuses
@section Syntax check statuses
@cindex Syntax check statuses
After syntax check is finished, its status is displayed in the mode line.
The following statuses are defined.
@multitable @columnfractions 0.25 0.75
@item Flymake* or Flymake:E/W*
@tab Flymake is currently running. For the second case, E/W contains the
error and warning count for the previous run.
@item Flymake
@tab Syntax check is not running. Usually this means syntax check was
successfully passed (no errors, no warnings). Other possibilities are:
syntax check was killed as a result of executing
@code{flymake-compile}, or syntax check cannot start as compilation
is currently in progress.
@item Flymake:E/W
@tab Number of errors/warnings found by the syntax check process.
@item Flymake:!
@tab Flymake was unable to find master file for the current buffer.
@end multitable
The following errors cause a warning message and switch flymake mode
OFF for the buffer.
@multitable @columnfractions 0.25 0.75
@item CFGERR
@tab Syntax check process returned nonzero exit code, but no
errors/warnings were reported. This indicates a possible configuration
error (for example, no suitable error message patterns for the
syntax check tool).
@item NOMASTER
@tab Flymake was unable to find master file for the current buffer.
@item NOMK
@tab Flymake was unable to find a suitable buildfile for the current buffer.
@item PROCERR
@tab Flymake was unable to launch a syntax check process.
@end multitable
@node Troubleshooting
@section Troubleshooting
@cindex Logging
@cindex Troubleshooting
Flymake uses a simple logging facility for indicating important points
in the control flow. The logging facility sends logging messages to
the @code{*Messages*} buffer. The information logged can be used for
resolving various problems related to Flymake.
Logging output is controlled by the @code{flymake-log-level}
variable. @code{3} is the most verbose level, and @code{-1} switches
logging off.
@node Configuring Flymake
@chapter Configuring and Extending Flymake
@cindex Configuring and Extending Flymake
@menu
* Customizable variables::
* Adding support for a new syntax check tool::
@end menu
Flymake was designed to be easily extended for supporting new syntax
check tools and error message patterns.
@node Customizable variables
@section Customizable variables
@cindex Customizable variables
This section summarizes variables used for Flymake
configuration.
@table @code
@item flymake-log-level
Controls logging output, see @ref{Troubleshooting}.
@item flymake-allowed-file-name-masks
A list of @code{(filename-regexp, init-function, cleanup-function
getfname-function)} for configuring syntax check tools. @xref{Adding
support for a new syntax check tool}.
@item flymake-buildfile-dirs
A list of directories (relative paths) for searching a
buildfile. @xref{Locating the buildfile}.
@item flymake-master-file-dirs
A list of directories for searching a master file. @xref{Locating a
master file}.
@item flymake-get-project-include-dirs-function
A function used for obtaining a list of project include dirs (C/C++
specific). @xref{Getting the include directories}.
@item flymake-master-file-count-limit
@itemx flymake-check-file-limit
Used when looking for a master file. @xref{Locating a master file}.
@item flymake-err-line-patterns
Patterns for error/warning messages in the form @code{(regexp file-idx
line-idx err-text-idx)}. @xref{Parsing the output}.
@item flymake-compilation-prevents-syntax-check
A flag indicating whether compilation and syntax check of the same
file cannot be run simultaneously.
@item flymake-no-changes-timeout
If any changes are made to the buffer, syntax check is automatically
started after @code{flymake-no-changes-timeout} seconds.
@item flymake-gui-warnings-enabled
A boolean flag indicating whether Flymake will show message boxes for
non-recoverable errors. If @code{flymake-gui-warnings-enabled} is
@code{nil}, these errors will only be logged to the @code{*Messages*}
buffer.
@item flymake-start-syntax-check-on-newline
A boolean flag indicating whether to start syntax check after a
newline character is added to the buffer.
@item flymake-errline-face
A custom face for highlighting lines for which at least one error has
been reported.
@item flymake-warnline-face
A custom face for highlighting lines for which at least one warning
and no errors have been reported.
@end table
@node Adding support for a new syntax check tool
@section Adding support for a new syntax check tool
@cindex Adding support for a new syntax check tool
@menu
* Example -- Configuring a tool called directly::
* Example -- Configuring a tool called via make::
@end menu
Syntax check tools are configured using the
@code{flymake-allowed-file-name-masks} list. Each item of this list
has the following format:
@lisp
(filename-regexp, init-function, cleanup-function, getfname-function)
@end lisp
@table @code
@item filename-regexp
This field is used as a key for locating init/cleanup/getfname
functions for the buffer. Items in
@code{flymake-allowed-file-name-masks} are searched sequentially. The
first item with @code{filename-regexp} matching buffer filename is
selected. If no match is found, @code{flymake-mode} is switched off.
@item init-function
@code{init-function} is required to initialize the syntax check,
usually by creating a temporary copy of the buffer contents. The
function must return @code{(list cmd-name arg-list)}. If
@code{init-function} returns null, syntax check is aborted, by
@code{flymake-mode} is not switched off.
@item cleanup-function
@code{cleanup-function} is called after the syntax check process is
complete and should take care of proper deinitialization, which is
usually deleting a temporary copy created by the @code{init-function}.
@item getfname-function
This function is used for translating filenames reported by the syntax
check tool into ``real'' filenames. Filenames reported by the tool
will be different from the real ones, as actually the tool works with
the temporary copy. In most cases, the default implementation
provided by Flymake, @code{flymake-get-real-file-name}, can be used as
@code{getfname-function}.
@end table
To add support for a new syntax check tool, write corresponding
@code{init-function}, and, optionally @code{cleanup-function} and
@code{getfname-function}. If the format of error messages reported by
the new tool is not yet supported by Flymake, add a new entry to
the @code{flymake-err-line-patterns} list.
The following sections contain some examples of configuring Flymake
support for various syntax check tools.
@node Example -- Configuring a tool called directly
@subsection Example -- Configuring a tool called directly
@cindex Adding support for perl
In this example, we will add support for @code{perl} as a syntax check
tool. @code{perl} supports the @code{-c} option which does syntax
checking.
First, we write the @code{init-function}:
@lisp
(defun flymake-perl-init (buffer)
(let* ((temp-file (flymake-init-create-temp-buffer-copy
buffer 'flymake-create-temp-inplace))
(local-file (concat (flymake-build-relative-filename
(file-name-directory
(buffer-file-name
(current-buffer)))
(file-name-directory temp-file))
(file-name-nondirectory temp-file))))
(list "perl" (list "-wc " local-file))))
@end lisp
@code{flymake-perl-init} creates a temporary copy of the buffer
contents with the help of
@code{flymake-init-create-temp-buffer-copy}, and builds an appropriate
command line.
Next, we add a new entry to the
@code{flymake-allowed-file-name-masks}:
@lisp
(setq flymake-allowed-file-name-masks
(cons '(".+\\.pl$"
flymake-perl-init
flymake-simple-cleanup
flymake-get-real-file-name)
flymake-allowed-file-name-masks))
@end lisp
Note that we use standard @code{cleanup-function} and
@code{getfname-function}.
Finally, we add an entry to @code{flymake-err-line-patterns}:
@lisp
(setq flymake-err-line-patterns
(cons '("\\(.*\\) at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]"
2 3 nil 1)
flymake-err-line-patterns))
@end lisp
@node Example -- Configuring a tool called via make
@subsection Example -- Configuring a tool called via make
@cindex Adding support for C (gcc+make)
In this example we will add support for C files syntax checked by
@code{gcc} called via @code{make}.
We're not required to write any new functions, as Flymake already has
functions for @code{make}. We just add a new entry to the
@code{flymake-allowed-file-name-masks}:
@lisp
(setq flymake-allowed-file-name-masks
(cons '(".+\\.c$"
flymake-simple-make-init
flymake-simple-cleanup
flymake-get-real-file-name)
flymake-allowed-file-name-masks))
@end lisp
@code{flymake-simple-make-init} builds the following @code{make}
command line:
@lisp
(list "make"
(list "-s" "-C"
base-dir
(concat "CHK_SOURCES=" source)
"SYNTAX_CHECK_MODE=1"
"check-syntax"))
@end lisp
@code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}.
Thus, @code{Makefile} must contain the @code{check-syntax} target. In
our case this target might look like this:
@verbatim
check-syntax:
gcc -o nul -S ${CHK_SOURCES}
@end verbatim
The format of error messages reported by @code{gcc} is already
supported by Flymake, so we don't have to add a new entry to
@code{flymake-err-line-patterns}.
@node Flymake Implementation
@chapter Flymake Implementation
@cindex Implementation details
@menu
* Determining whether syntax check is possible::
* Making a temporary copy::
* Locating a master file::
* Getting the include directories::
* Locating the buildfile::
* Starting the syntax check process::
* Parsing the output::
* Highlighting erroneous lines::
* Interaction with other modes::
@end menu
Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}.
Flymake first determines whether it is able to do syntax
check. It then saves a copy of the buffer in a temporary file in the
buffer's directory (or in the system temp directory -- for java
files), creates a syntax check command and launches a process with
this command. The output is parsed using a list of error message patterns,
and error information (file name, line number, type and text) is
saved. After the process has finished, Flymake highlights erroneous
lines in the buffer using the accumulated error information.
@node Determining whether syntax check is possible
@section Determining whether syntax check is possible
@cindex Syntax check models
@cindex Master file
Syntax check is considered possible if there's an entry in
@code{flymake-allowed-file-name-masks} matching buffer's filename and
its @code{init-function} returns non-@code{nil} value.
Two syntax check modes are distinguished:
@enumerate
@item
Buffer can be syntax checked in a standalone fashion, that is, the
file (its temporary copy, in fact) can be passed over to the compiler to
do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java)
sources.
@item
Buffer can be syntax checked, but additional file, called master file,
is required to perform this operation. A master file is a file that
includes the current file, so that running a syntax check tool on it
will also check syntax in the current file. Examples are C/C++ (.h,
.hpp) headers.
@end enumerate
These modes are handled inside init/cleanup/getfname functions, see
@ref{Adding support for a new syntax check tool}.
Flymake contains implementations of all functionality required to
support different syntax check modes described above (making
temporary copies, finding master files, etc.), as well as some
tool-specific (routines for @code{make}, @code{Ant}, etc.) code.
@node Making a temporary copy
@section Making a temporary copy
@cindex Temporary copy of the buffer
@cindex Master file
After the possibility of the syntax check has been determined, a
temporary copy of the current buffer is made so that the most recent
unsaved changes could be seen by the syntax check tool. Making a copy
is quite straightforward in a standalone case (mode @code{1}), as it's
just saving buffer contents to a temporary file.
Things get trickier, however, when master file is involved, as it
requires to
@itemize @bullet
@item locate a master file
@item patch it to include the current file using its new (temporary)
name.
@end itemize
Locating a master file is discussed in the following section.
Patching just changes all appropriate lines of the master file so that they
use the new (temporary) name of the current file. For example, suppose current
file name is @code{file.h}, the master file is @code{file.cpp}, and
it includes current file via @code{#include "file.h"}. Current file's copy
is saved to file @code{file_flymake.h}, so the include line must be
changed to @code{#include "file_flymake.h"}. Finally, patched master file
is saved to @code{file_flymake_master.cpp}, and the last one is passed to
the syntax check tool.
@node Locating a master file
@section Locating a master file
@cindex Master file
Master file is located in two steps.
First, a list of possible master files is built. A simple name
matching is used to find the files. For a C++ header @code{file.h},
Flymake searches for all @code{.cpp} files in the directories whose relative paths are
stored in a customizable variable @code{flymake-master-file-dirs}, which
usually contains something like @code{("." "./src")}. No more than
@code{flymake-master-file-count-limit} entries is added to the master file
list. The list is then sorted to move files with names @code{file.cpp} to
the top.
Next, each master file in a list is checked to contain the appropriate
include directives. No more than @code{flymake-check-file-limit} of each
file are parsed.
For @code{file.h}, the include directives to look for are
@code{#include "file.h"}, @code{#include "../file.h"}, etc. Each
include is checked against a list of include directories
(see @ref{Getting the include directories}) to be sure it points to the
correct @code{file.h}.
First matching master file found stops the search. The master file is then
patched and saved to disk. In case no master file is found, syntax check is
aborted, and corresponding status (!) is reported in the mode line.
@node Getting the include directories
@section Getting the include directories
@cindex Include directories (C/C++ specific)
Two sets of include directories are distinguished: system include directories
and project include directories. The former is just the contents of the
@code{INCLUDE} environment variable. The latter is not so easy to obtain,
and the way it can be obtained can vary greatly for different projects.
Therefore, a customizable variable
@code{flymake-get-project-include-dirs-function} is used to provide the
way to implement the desired behavior.
The default implementation, @code{flymake-get-project-include-dirs-imp},
uses a @code{make} call. This requires a correct base directory, that is, a
directory containing a correct @code{Makefile}, to be determined.
As obtaining the project include directories might be a costly operation, its
return value is cached in the hash table. The cache is cleared in the beginning
of every syntax check attempt.
@node Locating the buildfile
@section Locating the buildfile
@cindex Locating the buildfile
@cindex buildfile, locating
@cindex Makefile, locating
Flymake can be configured to use different tools for performing syntax
checks. For example, it can use direct compiler call to syntax check a perl
script or a call to @code{make} for a more complicated case of a
@code{C/C++} source. The general idea is that simple files, like perl
scripts and html pages, can be checked by directly invoking a
corresponding tool. Files that are usually more complex and generally
used as part of larger projects, might require non-trivial options to
be passed to the syntax check tool, like include directories for
C++. The latter files are syntax checked using some build tool, like
@code{make} or @code{Ant}.
All @code{make} configuration data is usually stored in a file called
@code{Makefile}. To allow for future extensions, flymake uses a notion of
buildfile to reference the 'project configuration' file.
Special function, @code{flymake-find-buildfile} is provided for locating buildfiles.
Searching for a buildfile is done in a manner similar to that of searching
for possible master files. A customizable variable
@code{flymake-buildfile-dirs} holds a list of relative paths to the
buildfile. They are checked sequentially until a buildfile is found. In case
there's no build file, syntax check is aborted.
Buildfile values are also cached.
@node Starting the syntax check process
@section Starting the syntax check process
@cindex Syntax check process
The command line (command name and the list of arguments) for launching a process is returned by the
initialization function. Flymake then just calls @code{start-process}
to start an asynchronous process and configures process filter and
sentinel which is used for processing the output of the syntax check
tool.
@node Parsing the output
@section Parsing the output
@cindex Parsing the output
The output generated by the syntax check tool is parsed in the process
filter/sentinel using the error message patterns stored in the
@code{flymake-err-line-patterns} variable. This variable contains a
list of items of the form @code{(regexp file-idx line-idx
err-text-idx)}, used to determine whether a particular line is an
error message and extract file name, line number and error text,
respectively. Error type (error/warning) is also guessed by matching
error text with the '@code{^[wW]arning}' pattern. Anything that was not
classified as a warning is considered an error. Type is then used to
sort error menu items, which shows error messages first.
Flymake is also able to interpret error message patterns missing err-text-idx
information. This is done by merely taking the rest of the matched line
(@code{(substring line (match-end 0))}) as error text. This trick allows
to make use of a huge collection of error message line patterns from
@code{compile.el}. All these error patterns are appended to
the end of @code{flymake-err-line-patterns}.
The error information obtained is saved in a buffer local
variable. The buffer for which the process output belongs is
determined from the process-id@w{}->@w{}buffer mapping updated
after every process launch/exit.
@node Highlighting erroneous lines
@section Highlighting erroneous lines
@cindex Erroneous lines, faces
Highlighting is implemented with overlays and happens in the process
sentinel, after calling the cleanup function. Two customizable faces
are used: @code{flymake-errline-face} and
@code{flymake-warnline-face}. Errors belonging outside the current
buffer are considered to belong to line 1 of the current buffer.
@node Interaction with other modes
@section Interaction with other modes
@cindex Interaction with other modes
@cindex Interaction with compile mode
The only mode flymake currently knows about is @code{compile}.
Flymake can be configured to not start syntax check if it thinks the
compilation is in progress. The check is made by the
@code{flymake-compilation-is-running}, which tests the
@code{compilation-in-progress} variable. The reason why this might be
useful is saving CPU time in case both syntax check and compilation
are very CPU intensive. The original reason for adding this feature,
though, was working around a locking problem with MS Visual C++ compiler.
Flymake also provides an alternative command for starting compilation,
@code{flymake-compile}:
@lisp
(defun flymake-compile ()
"Kill all flymake syntax checks then start compilation."
(interactive)
(flymake-stop-all-syntax-checks)
(call-interactively 'compile))
@end lisp
It just kills all the active syntax check processes before calling
@code{compile}.
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
@node Index
@unnumbered Index
@printindex cp
@bye
@ignore
arch-tag: 9f0db077-5598-49ab-90b9-8df9248a63ec
@end ignore

985
doc/misc/forms.texi Normal file
View file

@ -0,0 +1,985 @@
\input texinfo @c -*-texinfo-*-
@c documentation for forms-mode
@c Written by Johan Vromans, and edited by Richard Stallman
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename ../info/forms
@settitle Forms Mode User's Manual
@syncodeindex vr cp
@syncodeindex fn cp
@syncodeindex ky cp
@iftex
@finalout
@setchapternewpage odd
@end iftex
@c @smallbook
@comment %**end of header (This is for running Texinfo on a region.)
@copying
This file documents Forms mode, a form-editing major mode for GNU Emacs.
Copyright @copyright{} 1989, 1997, 2001, 2002, 2003, 2004,
2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* Forms: (forms). Emacs package for editing data bases
by filling in forms.
@end direntry
@titlepage
@sp 6
@center @titlefont{Forms Mode User's Manual}
@sp 4
@center Forms-Mode version 2
@sp 1
@center for GNU Emacs 22.1
@sp 1
@center April 2007
@sp 5
@center Johan Vromans
@center @i{jvromans@@squirrel.nl}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@ifnottex
@node Top
@top Forms Mode
Forms mode is an Emacs major mode for working with simple textual data
bases in a forms-oriented manner. In Forms mode, the information in
these files is presented in an Emacs window in a user-defined format,
one record at a time. The user can view records or modify their
contents.
Forms mode is not a simple major mode, but requires two files to do its
job: a control file and a data file. The data file holds the
actual data to be presented. The control file describes
how to present it.
@menu
* Forms Example:: An example: editing the password data base.
* Entering and Exiting Forms Mode::
How to visit a file in Forms mode.
* Forms Commands:: Special commands to use while in Forms mode.
* Data File Format:: How to format the data file.
* Control File Format:: How to control forms mode.
* Format Description:: How to define the forms layout.
* Modifying Forms Contents:: How to modify.
* Miscellaneous:: Forms mode messages and other remarks.
* Error Messages:: List of error messages forms mode can produce.
* Long Example:: A more complex control file example.
* GNU Free Documentation License:: The license for this documentation.
* Credits:: Thanks everyone.
* Index:: Index to this manual.
@end menu
@end ifnottex
@node Forms Example
@chapter Forms Example
Let's illustrate Forms mode with an example. Suppose you are looking at
the @file{/etc/passwd} file, and the screen looks like this:
@example
====== /etc/passwd ======
User : root Uid: 0 Gid: 1
Name : Super User
Home : /
Shell: /bin/sh
@end example
As you can see, the familiar fields from the entry for the super user
are all there, but instead of being colon-separated on one single line,
they make up a forms.
The contents of the forms consist of the contents of the fields of the
record (e.g. @samp{root}, @samp{0}, @samp{1}, @samp{Super User})
interspersed with normal text (e.g @samp{User : }, @samp{Uid: }).
If you modify the contents of the fields, Forms mode will analyze your
changes and update the file appropriately. You cannot modify the
interspersed explanatory text (unless you go to some trouble about it),
because that is marked read-only (@pxref{Text Properties,,, elisp, The
Emacs Lisp Reference Manual}).
The Forms mode control file specifies the relationship between the
format of @file{/etc/passwd} and what appears on the screen in Forms
mode. @xref{Control File Format}.
@node Entering and Exiting Forms Mode
@chapter Entering and Exiting Forms Mode
@table @kbd
@findex forms-find-file
@item M-x forms-find-file @key{RET} @var{control-file} @key{RET}
Visit a database using Forms mode. Specify the name of the
@strong{control file}, not the data file!
@findex forms-find-file-other-window
@item M-x forms-find-file-other-window @key{RET} @var{control-file} @key{RET}
Similar, but displays the file in another window.
@end table
The command @code{forms-find-file} evaluates the file
@var{control-file}, and also visits it in Forms mode. What you see in
its buffer is not the contents of this file, but rather a single record
of the corresponding data file that is visited in its own buffer. So
there are two buffers involved in Forms mode: the @dfn{forms buffer}
that is initially used to visit the control file and that shows the
records being browsed, and the @dfn{data buffer} that holds the data
file being visited. The latter buffer is normally not visible.
Initially, the first record is displayed in the forms buffer.
The mode line displays the major mode name @samp{Forms}, followed by the
minor mode @samp{View} if the data base is read-only. The number of the
current record (@var{n}) and the total number of records in the
file(@var{t}) are shown in the mode line as @samp{@var{n}/@var{t}}. For
example:
@example
--%%-Emacs: passwd-demo (Forms View 1/54)----All-------
@end example
If the buffer is not read-only, you may change the buffer to modify the
fields in the record. When you move to a different record, the contents
of the buffer are parsed using the specifications in
@code{forms-format-list}, and the data file is updated. If the record
has fields that aren't included in the display, they are not changed.
@vindex forms-mode-hooks
Entering Forms mode runs the normal hook @code{forms-mode-hooks} to
perform user-defined customization.
To save any modified data, you can use @kbd{C-x C-s}
(@code{forms-save-buffer}). This does not save the forms buffer (which would
be rather useless), but instead saves the buffer visiting the data file.
To terminate Forms mode, you can use @kbd{C-x C-s} (@code{forms-save-buffer})
and then kill the forms buffer. However, the data buffer will still
remain. If this is not desired, you have to kill this buffer too.
@node Forms Commands
@chapter Forms Commands
The commands of Forms mode belong to the @kbd{C-c} prefix, with one
exception: @key{TAB}, which moves to the next field. Forms mode uses
different key maps for normal mode and read-only mode. In read-only
Forms mode, you can access most of the commands without the @kbd{C-c}
prefix, but you must type ordinary letters instead of control
characters; for example, type @kbd{n} instead of @kbd{C-c C-n}.
If your Emacs has been built with X-toolkit support, Forms mode will
provide its own menu with a number of Forms mode commands.
@table @kbd
@findex forms-next-record
@kindex C-c C-n
@item C-c C-n
Show the next record (@code{forms-next-record}). With a numeric
argument @var{n}, show the @var{n}th next record.
@findex forms-prev-record
@kindex C-c C-p
@item C-c C-p
Show the previous record (@code{forms-prev-record}). With a numeric
argument @var{n}, show the @var{n}th previous record.
@findex forms-jump-record
@kindex C-c C-l
@item C-c C-l
Jump to a record by number (@code{forms-jump-record}). Specify
the record number with a numeric argument.
@findex forms-first-record
@kindex C-c <
@item C-c <
Jump to the first record (@code{forms-first-record}).
@findex forms-last-record
@kindex C-c >
@item C-c >
Jump to the last record (@code{forms-last-record}). This command also
recalculates the number of records in the data file.
@findex forms-next-field
@kindex TAB
@item @key{TAB}
@kindex C-c TAB
@itemx C-c @key{TAB}
Jump to the next field in the current record (@code{forms-next-field}).
With a numeric argument @var{n}, jump forward @var{n} fields. If this command
would move past the last field, it wraps around to the first field.
@findex forms-toggle-read-only
@kindex C-c C-q
@item C-c C-q
Toggles read-only mode (@code{forms-toggle-read-only}). In read-only
Forms mode, you cannot edit the fields; most Forms mode commands can be
accessed without the prefix @kbd{C-c} if you use the normal letter
instead (for example, type @kbd{n} instead of @kbd{C-c C-n}). In edit
mode, you can edit the fields and thus change the contents of the data
base; you must begin Forms mode commands with @code{C-c}. Switching
to edit mode is allowed only if you have write access to the data file.
@findex forms-insert-record
@kindex C-c C-o
@item C-c C-o
Create a new record and insert it before the current record
(@code{forms-insert-record}). It starts out with empty (or default)
contents for its fields; you can then edit the fields. With a numeric
argument, the new record is created @emph{after} the current one.
See also @code{forms-modified-record-filter} in @ref{Modifying Forms
Contents}.
@findex forms-delete-record
@kindex C-c C-k
@item C-c C-k
Delete the current record (@code{forms-delete-record}). You are
prompted for confirmation before the record is deleted unless a numeric
argument has been provided.
@findex forms-search-forward
@kindex C-c C-s @var{regexp} @key{RET}
@item C-c C-s @var{regexp} @key{RET}
Search forward for @var{regexp} in all records following this one
(@code{forms-search-forward}). If found, this record is shown.
If you give an empty argument, the previous regexp is used again.
@findex forms-search-backward
@kindex C-c C-r @var{regexp} @key{RET}
@item C-c C-r @var{regexp} @key{RET}
Search backward for @var{regexp} in all records following this one
(@code{forms-search-backward}). If found, this record is shown.
If you give an empty argument, the previous regexp is used again.
@ignore
@findex forms-exit
@kindex C-c C-x
@item C-c C-x
Terminate Forms mode processing (@code{forms-exit}). The data file is
saved if it has been modified.
@findex forms-exit-no-save
@item M-x forms-exit-no-save
Terminates forms mode processing without saving modified data first.
@end ignore
@findex forms-prev-field
@item M-x forms-prev-field
Similar to @code{forms-next-field} but moves backwards.
@findex forms-save-buffer
@item M-x forms-save-buffer
@kindex C-x C-s
@itemx C-x C-s
Forms mode replacement for @code{save-buffer}. When executed in the
forms buffer it will save the contents of the (modified) data buffer
instead. In Forms mode this function will be bound to @kbd{C-x C-s}.
@findex forms-print
@item M-x forms-print
This command can be used to make a formatted print
of the contents of the data file.
@end table
In addition the command @kbd{M-x revert-buffer} is useful in Forms mode
just as in other modes.
@ignore
@vindex forms-forms-scroll
@findex scroll-up
@findex scroll-down
If the variable @code{forms-forms-scrolls} is set to a value other
than @code{nil} (which it is, by default), the Emacs functions
@code{scroll-up} and @code{scroll-down} will perform a
@code{forms-next-record} and @code{forms-prev-record} when in forms
mode. So you can use your favorite page commands to page through the
data file.
@vindex forms-forms-jump
@findex beginning-of-buffer
@findex end-of-buffer
Likewise, if the variable @code{forms-forms-jump} is not @code{nil}
(which it is, by default), Emacs functions @code{beginning-of-buffer}
and @code{end-of-buffer} will perform @code{forms-first-record} and
@code{forms-last-record} when in forms mode.
@end ignore
The following function key definitions are set up in Forms mode
(whether read-only or not):
@table @kbd
@kindex next
@item next
forms-next-record
@kindex prior
@item prior
forms-prev-record
@kindex begin
@item begin
forms-first-record
@kindex end
@item end
forms-last-record
@kindex S-Tab
@findex forms-prev-field
@item S-Tab
forms-prev-field
@end table
@node Data File Format
@chapter Data File Format
@cindex record
@cindex field
@vindex forms-field-sep
Files for use with Forms mode are very simple---each @dfn{record}
(usually one line) forms the contents of one form. Each record consists
of a number of @dfn{fields}, which are separated by the value of the
string @code{forms-field-sep}, which is @code{"\t"} (a Tab) by default.
@vindex forms-read-file-filter
@vindex forms-write-file-filter
If the format of the data file is not suitable enough you can define the
filter functions @code{forms-read-file-filter} and
@code{forms-write-file-filter}. @code{forms-read-file-filter} is called
when the data file is read from disk into the data buffer. It operates
on the data buffer, ignoring read-only protections. When the data file
is saved to disk @code{forms-write-file-filter} is called to cancel the
effects of @code{forms-read-file-filter}. After being saved,
@code{forms-read-file-filter} is called again to prepare the data buffer
for further processing.
@cindex pseudo-newline
@vindex forms-multi-line
Fields may contain text which shows up in the forms in multiple lines.
These lines are separated in the field using a ``pseudo-newline''
character which is defined by the value of the string
@code{forms-multi-line}. Its default value is @code{"\^k"} (a Control-K
character). If it is
set to @code{nil}, multiple line fields are prohibited.
If the data file does not exist, it is automatically created.
@node Control File Format
@chapter Control File Format
@cindex control file
The Forms mode @dfn{control file} serves two purposes. First, it names
the data file to use, and defines its format and properties. Second,
the Emacs buffer it occupies is used by Forms mode to display the forms.
The contents of the control file are evaluated as a Lisp program. It
should set the following Lisp variables to suitable values:
@table @code
@vindex forms-file
@item forms-file
This variable specifies the name of the data file. Example:
@example
(setq forms-file "my/data-file")
@end example
If the control file doesn't set @code{forms-file}, Forms mode
reports an error.
@vindex forms-format-list
@item forms-format-list
This variable describes the way the fields of the record are formatted on
the screen. For details, see @ref{Format Description}.
@vindex forms-number-of-fields
@item forms-number-of-fields
This variable holds the number of fields in each record of the data
file. Example:
@example
(setq forms-number-of-fields 10)
@end example
@end table
If the control file does not set @code{forms-format-list} a default
format is used. In this situation, Forms mode will deduce the number of
fields from the data file providing this file exists and
@code{forms-number-of-records} has not been set in the control file.
The control file can optionally set the following additional Forms mode
variables. Most of them have default values that are good for most
applications.
@table @code
@vindex forms-field-sep
@item forms-field-sep
This variable may be used to designate the string which separates the
fields in the records of the data file. If not set, it defaults to the
string @code{"\t"} (a Tab character). Example:
@example
(setq forms-field-sep "\t")
@end example
@vindex forms-read-only
@item forms-read-only
If the value is non-@code{nil}, the data file is treated read-only. (Forms
mode also treats the data file as read-only if you don't have access to
write it.) Example:
@example
(set forms-read-only t)
@end example
@vindex forms-multi-line
@item forms-multi-line
This variable specifies the @dfn{pseudo newline} separator that allows
multi-line fields. This separator goes between the ``lines'' within a
field---thus, the field doesn't really contain multiple lines, but it
appears that way when displayed in Forms mode. If the value is
@code{nil}, multi-line text fields are prohibited. The pseudo newline
must not be a character contained in @code{forms-field-sep}.
The default value is @code{"\^k"}, the character Control-K. Example:
@example
(setq forms-multi-line "\^k")
@end example
@ignore
@vindex forms-forms-scroll
@item forms-forms-scroll
@xref{Forms Mode Commands}, for details.
@vindex forms-forms-jump
@item forms-forms-jump
@xref{Forms Mode Commands}, for details.
@end ignore
@findex forms-read-file-filter
@item forms-read-file-filter
This variable holds the name of a function to be called after the data
file has been read in. This can be used to transform the contents of the
data file into a format more suitable for forms processing.
If it is @code{nil}, no function is called. For example, to maintain a
gzipped database:
@example
(defun gzip-read-file-filter ()
(shell-command-on-region (point-min) (point-max)
"gzip -d" t t))
(setq forms-read-file-filter 'gzip-read-file-filter)
@end example
@findex forms-write-file-filter
@item forms-write-file-filter
This variable holds the name of a function to be called before writing
out the contents of the data file.
This can be used to undo the effects of @code{forms-read-file-filter}.
If it is @code{nil}, no function is called. Example:
@example
(defun gzip-write-file-filter ()
(make-variable-buffer-local 'require-final-newline)
(setq require-final-newline nil)
(shell-command-on-region (point-min) (point-max)
"gzip" t t))
(setq forms-write-file-filter 'gzip-write-file-filter)
@end example
@findex forms-new-record-filter
@item forms-new-record-filter
This variable holds a function to be called whenever a new record is created
to supply default values for fields. If it is @code{nil}, no function is
called.
@xref{Modifying Forms Contents}, for details.
@findex forms-modified-record-filter
@item forms-modified-record-filter
This variable holds a function to be called whenever a record is
modified, just before updating the Forms data file. If it is
@code{nil}, no function is called.
@xref{Modifying Forms Contents}, for details.
@findex forms-insert-after
@item forms-insert-after
If this variable is not @code{nil}, new records are created @emph{after} the
current record. Also, upon visiting a file, the initial position will be
at the last record instead of the first one.
@findex forms-check-number-of-fields
@item forms-check-number-of-fields
Normally each record is checked to contain the correct number of fields.
Under certain circumstances, this can be undesirable.
If this variable is set to @code{nil}, these checks will be bypassed.
@end table
@node Format Description
@chapter The Format Description
@vindex forms-format-list
The variable @code{forms-format-list} specifies the format of the data
in the data file, and how to convert the data for display in Forms mode.
Its value must be a list of Forms mode @dfn{formatting elements}, each
of which can be a string, a number, a Lisp list, or a Lisp symbol that
evaluates to one of those. The formatting elements are processed in the
order they appear in the list.
@table @var
@item string
A string formatting element is inserted in the forms ``as is,'' as text
that the user cannot alter.
@item number
A number element selects a field of the record. The contents of this
field are inserted in the display at this point. Field numbers count
starting from 1 (one).
@item list
A formatting element that is a list specifies a function call. This
function is called every time a record is displayed, and its result,
which must be a string, is inserted in the display text. The function
should do nothing but returning a string.
@vindex forms-fields
The function you call can access the fields of the record as a list in
the variable
@code{forms-fields}.
@item symbol
A symbol used as a formatting element should evaluate to a string, number,
or list; the value is interpreted as a formatting element, as described
above.
@end table
If a record does not contain the number of fields as specified in
@code{forms-number-of-fields}, a warning message will be printed. Excess
fields are ignored, missing fields are set to empty.
The control file which displays @file{/etc/passwd} file as demonstrated
in the beginning of this manual might look as follows:
@example
;; @r{This demo visits @file{/etc/passwd}.}
(setq forms-file "/etc/passwd")
(setq forms-number-of-fields 7)
(setq forms-read-only t) ; @r{to make sure}
(setq forms-field-sep ":")
;; @r{Don't allow multi-line fields.}
(setq forms-multi-line nil)
(setq forms-format-list
(list
"====== /etc/passwd ======\n\n"
"User : " 1
" Uid: " 3
" Gid: " 4
"\n\n"
"Name : " 5
"\n\n"
"Home : " 6
"\n\n"
"Shell: " 7
"\n"))
@end example
When you construct the value of @code{forms-format-list}, you should
usually either quote the whole value, like this,
@example
(setq forms-format-list
'(
"====== " forms-file " ======\n\n"
"User : " 1
(make-string 20 ?-)
@dots{}
))
@end example
@noindent
or quote the elements which are lists, like this:
@example
(setq forms-format-list
(list
"====== " forms-file " ======\n\n"
"User : " 1
'(make-string 20 ?-)
@dots{}
))
@end example
Forms mode validates the contents of @code{forms-format-list} when you
visit a database. If there are errors, processing is aborted with an
error message which includes a descriptive text. @xref{Error Messages},
for a detailed list of error messages.
If no @code{forms-format-list} is specified, Forms mode will supply a
default format list. This list contains the name of the file being
visited, and a simple label for each field indicating the field number.
@node Modifying Forms Contents
@chapter Modifying The Forms Contents
If @code{forms-read-only} is @code{nil}, the user can modify the fields
and records of the database.
All normal editing commands are available for editing the contents of the
displayed record. You cannot delete or modify the fixed, explanatory
text that comes from string formatting elements, but you can modify the
actual field contents.
@ignore
@c This is for the Emacs 18 version only.
If the contents of the forms cannot be recognized properly, this is
signaled using a descriptive text. @xref{Error Messages}, for more info.
The cursor will indicate the last part of the forms which was
successfully parsed. It's important to avoid entering field contents
that would cause confusion with the field-separating fixed text.
@end ignore
If the variable @code{forms-modified-record-filter} is non-@code{nil},
it is called as a function before the new data is written to the data
file. The function receives one argument, a vector that contains the
contents of the fields of the record.
The function can refer to fields with @code{aref} and modify them with
@code{aset}. The first field has number 1 (one); thus, element 0 of the
vector is not used. The function should return the same vector it was
passed; the (possibly modified) contents of the vector determine what is
actually written in the file. Here is an example:
@example
(defun my-modified-record-filter (record)
;; @r{Modify second field.}
(aset record 2 (current-time-string))
;; @r{Return the field vector.}
record)
(setq forms-modified-record-filter 'my-modified-record-filter)
@end example
If the variable @code{forms-new-record-filter} is non-@code{nil}, its
value is a function to be called to fill in default values for the
fields of a new record. The function is passed a vector of empty
strings, one for each field; it should return the same vector, with
the desired field values stored in it. Fields are numbered starting
from 1 (one). Example:
@example
(defun my-new-record-filter (fields)
(aset fields 5 (login-name))
(aset fields 1 (current-time-string))
fields)
(setq forms-new-record-filter 'my-new-record-filter)
@end example
@node Miscellaneous
@chapter Miscellaneous
@vindex forms-version
The global variable @code{forms-version} holds the version information
of the Forms mode software.
@findex forms-enumerate
It is very convenient to use symbolic names for the fields in a record.
The function @code{forms-enumerate} provides an elegant means to define
a series of variables whose values are consecutive integers. The
function returns the highest number used, so it can be used to set
@code{forms-number-of-fields} also. For example:
@example
(setq forms-number-of-fields
(forms-enumerate
'(field1 field2 field3 @dots{})))
@end example
This sets @code{field1} to 1, @code{field2} to 2, and so on.
Care has been taken to keep the Forms mode variables buffer-local, so it
is possible to visit multiple files in Forms mode simultaneously, even
if they have different properties.
@findex forms-mode
If you have visited the control file in normal fashion with
@code{find-file} or a like command, you can switch to Forms mode with
the command @code{M-x forms-mode}. If you put @samp{-*- forms -*-} in
the first line of the control file, then visiting it enables Forms mode
automatically. But this makes it hard to edit the control file itself,
so you'd better think twice before using this.
The default format for the data file, using @code{"\t"} to separate
fields and @code{"\^k"} to separate lines within a field, matches the
file format of some popular database programs, e.g. FileMaker. So
@code{forms-mode} can decrease the need to use proprietary software.
@node Error Messages
@chapter Error Messages
This section describes all error messages which can be generated by
forms mode. Error messages that result from parsing the control file
all start with the text @samp{Forms control file error}. Messages
generated while analyzing the definition of @code{forms-format-list}
start with @samp{Forms format error}.
@table @code
@item Forms control file error: `forms-file' has not been set
The variable @code{forms-file} was not set by the control file.
@item Forms control file error: `forms-number-of-fields' has not been set
The variable @code{forms-number-of-fields} was not set by the control
file.
@item Forms control file error: `forms-number-of-fields' must be a number > 0
The variable @code{forms-number-of-fields} did not contain a positive
number.
@item Forms control file error: `forms-field-sep' is not a string
@itemx Forms control file error: `forms-multi-line' must be nil or a one-character string
The variable @code{forms-multi-line} was set to something other than
@code{nil} or a single-character string.
@item Forms control file error: `forms-multi-line' is equal to 'forms-field-sep'
The variable @code{forms-multi-line} may not be equal to
@code{forms-field-sep} for this would make it impossible to distinguish
fields and the lines in the fields.
@item Forms control file error: `forms-new-record-filter' is not a function
@itemx Forms control file error: `forms-modified-record-filter' is not a function
The variable has been set to something else than a function.
@item Forms control file error: `forms-format-list' is not a list
The variable @code{forms-format-list} was not set to a Lisp list
by the control file.
@item Forms format error: field number @var{xx} out of range 1..@var{nn}
A field number was supplied in @code{forms-format-list} with a value of
@var{xx}, which was not greater than zero and smaller than or equal to
the number of fields in the forms, @var{nn}.
@item Forms format error: @var{fun} is not a function
The first element of a list which is an element of
@code{forms-format-list} was not a valid Lisp function.
@item Forms format error: invalid element @var{xx}
A list element was supplied in @code{forms-format-list} which was not a
string, number or list.
@ignore
@c This applies to Emacs 18 only.
@c Error messages generated while a modified form is being analyzed.
@item Parse error: not looking at `...'
When re-parsing the contents of a forms, the text shown could not
be found.
@item Parse error: cannot find `...'
When re-parsing the contents of a forms, the text shown, which
separates two fields, could not be found.
@item Parse error: cannot parse adjacent fields @var{xx} and @var{yy}
Fields @var{xx} and @var{yy} were not separated by text, so could not be
parsed again.
@end ignore
@item Warning: this record has @var{xx} fields instead of @var{yy}
The number of fields in this record in the data file did not match
@code{forms-number-of-fields}. Missing fields will be made empty.
@item Multi-line fields in this record - update refused!
The current record contains newline characters, hence can not be written
back to the data file, for it would corrupt it. Probably you inserted a
newline in a field, while @code{forms-multi-line} was @code{nil}.
@item Field separator occurs in record - update refused!
The current record contains the field separator string inside one of the
fields. It can not be written back to the data file, for it would
corrupt it. Probably you inserted the field separator string in a field.
@item Record number @var{xx} out of range 1..@var{yy}
A jump was made to non-existing record @var{xx}. @var{yy} denotes the
number of records in the file.
@item Stuck at record @var{xx}
An internal error prevented a specific record from being retrieved.
@item No write access to @code{"}@var{file}@code{"}
An attempt was made to enable edit mode on a file that has been write
protected.
@item Search failed: @var{regexp}
The @var{regexp} could not be found in the data file. Forward searching
is done from the current location until the end of the file, then
retrying from the beginning of the file until the current location.
Backward searching is done from the current location until the beginning
of the file, then retrying from the end of the file until the current
location.
@item Wrapped
A search completed successfully after wrapping around.
@item Warning: number of records changed to @var{nn}
Forms mode's idea of the number of records has been adjusted to the
number of records actually present in the data file.
@item Problem saving buffers?
An error occurred while saving the data file buffer. Most likely, Emacs
did ask to confirm deleting the buffer because it had been modified, and
you said `no'.
@end table
@node Long Example
@chapter Long Example
The following example exploits most of the features of Forms mode.
This example is included in the distribution as file @file{forms-d2.el}.
@example
;; demo2 -- demo forms-mode -*- emacs-lisp -*-
;; @r{This sample forms exploit most of the features of forms mode.}
;; @r{Set the name of the data file.}
(setq forms-file "forms-d2.dat")
;; @r{Use @code{forms-enumerate} to set field names and number thereof.}
(setq forms-number-of-fields
(forms-enumerate
'(arch-newsgroup ; 1
arch-volume ; 2
arch-issue ; and ...
arch-article ; ... so
arch-shortname ; ... ... on
arch-parts
arch-from
arch-longname
arch-keywords
arch-date
arch-remarks)))
;; @r{The following functions are used by this form for layout purposes.}
;;
(defun arch-tocol (target &optional fill)
"Produces a string to skip to column TARGET.
Prepends newline if needed.
The optional FILL should be a character, used to fill to the column."
(if (null fill)
(setq fill ? ))
(if (< target (current-column))
(concat "\n" (make-string target fill))
(make-string (- target (current-column)) fill)))
;;
(defun arch-rj (target field &optional fill)
"Produces a string to skip to column TARGET\
minus the width of field FIELD.
Prepends newline if needed.
The optional FILL should be a character,
used to fill to the column."
(arch-tocol (- target (length (nth field forms-fields))) fill))
;; @r{Record filters.}
;;
(defun new-record-filter (the-record)
"Form a new record with some defaults."
(aset the-record arch-from (user-full-name))
(aset the-record arch-date (current-time-string))
the-record) ; return it
(setq forms-new-record-filter 'new-record-filter)
;; @r{The format list.}
(setq forms-format-list
(list
"====== Public Domain Software Archive ======\n\n"
arch-shortname
" - " arch-longname
"\n\n"
"Article: " arch-newsgroup
"/" arch-article
" "
'(arch-tocol 40)
"Issue: " arch-issue
" "
'(arch-rj 73 10)
"Date: " arch-date
"\n\n"
"Submitted by: " arch-from
"\n"
'(arch-tocol 79 ?-)
"\n"
"Keywords: " arch-keywords
"\n\n"
"Parts: " arch-parts
"\n\n====== Remarks ======\n\n"
arch-remarks
))
;; @r{That's all, folks!}
@end example
@node Credits
@chapter Credits
Bug fixes and other useful suggestions were supplied by
Harald Hanche-Olsen (@code{hanche@@imf.unit.no}),
@code{cwitty@@portia.stanford.edu},
Jonathan I. Kamens,
Per Cederqvist (@code{ceder@@signum.se}),
Michael Lipka (@code{lipka@@lip.hanse.de}),
Andy Piper (@code{ajp@@eng.cam.ac.uk}),
Frederic Pierresteguy (@code{F.Pierresteguy@@frcl.bull.fr}),
Ignatios Souvatzis
and Richard Stallman (@code{rms@@gnu.org}).
This documentation was slightly inspired by the documentation of ``rolo
mode'' by Paul Davis at Schlumberger Cambridge Research
(@code{davis%scrsu1%sdr.slb.com@@relay.cs.net}).
None of this would have been possible without GNU Emacs of the Free
Software Foundation. Thanks, Richard!
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
@node Index
@unnumbered Index
@printindex cp
@contents
@bye
@ignore
arch-tag: 2ac9810b-aa49-4ea6-8030-d7f1ecd467ed
@end ignore

2307
doc/misc/gnus-faq.texi Normal file
View file

File diff suppressed because it is too large Load diff

29508
doc/misc/gnus.texi Normal file
View file

File diff suppressed because it is too large Load diff

721
doc/misc/gpl.texi Normal file
View file

@ -0,0 +1,721 @@
@c The GNU General Public License.
@center Version 3, 29 June 2007
@c This file is intended to be included within another document,
@c hence no sectioning command or @node.
@display
Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
@end display
@heading Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom
to share and change all versions of a program---to make sure it remains
free software for all its users. We, the Free Software Foundation,
use the GNU General Public License for most of our software; it
applies also to any other work released this way by its authors. You
can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you
have certain responsibilities if you distribute copies of the
software, or if you modify it: responsibilities to respect the freedom
of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too,
receive or can get the source code. And you must show them these
terms so they know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the
manufacturer can do so. This is fundamentally incompatible with the
aim of protecting users' freedom to change the software. The
systematic pattern of such abuse occurs in the area of products for
individuals to use, which is precisely where it is most unacceptable.
Therefore, we have designed this version of the GPL to prohibit the
practice for those products. If such problems arise substantially in
other domains, we stand ready to extend this provision to those
domains in future versions of the GPL, as needed to protect the
freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish
to avoid the special danger that patents applied to a free program
could make it effectively proprietary. To prevent this, the GPL
assures that patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
@heading TERMS AND CONDITIONS
@enumerate 0
@item Definitions.
``This License'' refers to version 3 of the GNU General Public License.
``Copyright'' also means copyright-like laws that apply to other kinds
of works, such as semiconductor masks.
``The Program'' refers to any copyrightable work licensed under this
License. Each licensee is addressed as ``you''. ``Licensees'' and
``recipients'' may be individuals or organizations.
To ``modify'' a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of
an exact copy. The resulting work is called a ``modified version'' of
the earlier work or a work ``based on'' the earlier work.
A ``covered work'' means either the unmodified Program or a work based
on the Program.
To ``propagate'' a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To ``convey'' a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user
through a computer network, with no transfer of a copy, is not
conveying.
An interactive user interface displays ``Appropriate Legal Notices'' to
the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
@item Source Code.
The ``source code'' for a work means the preferred form of the work for
making modifications to it. ``Object code'' means any non-source form
of a work.
A ``Standard Interface'' means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The ``System Libraries'' of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
``Major Component'', in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The ``Corresponding Source'' for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users can
regenerate automatically from other parts of the Corresponding Source.
The Corresponding Source for a work in source code form is that same
work.
@item Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not convey,
without conditions so long as your license otherwise remains in force.
You may convey covered works to others for the sole purpose of having
them make modifications exclusively for you, or provide you with
facilities for running those works, provided that you comply with the
terms of this License in conveying all material for which you do not
control copyright. Those thus making or running the covered works for
you must do so exclusively on your behalf, under your direction and
control, on terms that prohibit them from making any copies of your
copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under the
conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
@item Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such
circumvention is effected by exercising rights under this License with
respect to the covered work, and you disclaim any intention to limit
operation or modification of the work as a means of enforcing, against
the work's users, your or third parties' legal rights to forbid
circumvention of technological measures.
@item Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
@item Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these
conditions:
@enumerate a
@item
The work must carry prominent notices stating that you modified it,
and giving a relevant date.
@item
The work must carry prominent notices stating that it is released
under this License and any conditions added under section 7. This
requirement modifies the requirement in section 4 to ``keep intact all
notices''.
@item
You must license the entire work, as a whole, under this License to
anyone who comes into possession of a copy. This License will
therefore apply, along with any applicable section 7 additional terms,
to the whole of the work, and all its parts, regardless of how they
are packaged. This License gives no permission to license the work in
any other way, but it does not invalidate such permission if you have
separately received it.
@item
If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your work
need not make them do so.
@end enumerate
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
``aggregate'' if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
@item Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms of
sections 4 and 5, provided that you also convey the machine-readable
Corresponding Source under the terms of this License, in one of these
ways:
@enumerate a
@item
Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium customarily
used for software interchange.
@item
Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a written
offer, valid for at least three years and valid for as long as you
offer spare parts or customer support for that product model, to give
anyone who possesses the object code either (1) a copy of the
Corresponding Source for all the software in the product that is
covered by this License, on a durable physical medium customarily used
for software interchange, for a price no more than your reasonable
cost of physically performing this conveying of source, or (2) access
to copy the Corresponding Source from a network server at no charge.
@item
Convey individual copies of the object code with a copy of the written
offer to provide the Corresponding Source. This alternative is
allowed only occasionally and noncommercially, and only if you
received the object code with such an offer, in accord with subsection
6b.
@item
Convey the object code by offering access from a designated place
(gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to copy
the object code is a network server, the Corresponding Source may be
on a different server (operated by you or a third party) that supports
equivalent copying facilities, provided you maintain clear directions
next to the object code saying where to find the Corresponding Source.
Regardless of what server hosts the Corresponding Source, you remain
obligated to ensure that it is available for as long as needed to
satisfy these requirements.
@item
Convey the object code using peer-to-peer transmission, provided you
inform other peers where the object code and Corresponding Source of
the work are being offered to the general public at no charge under
subsection 6d.
@end enumerate
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A ``User Product'' is either (1) a ``consumer product'', which means any
tangible personal property which is normally used for personal,
family, or household purposes, or (2) anything designed or sold for
incorporation into a dwelling. In determining whether a product is a
consumer product, doubtful cases shall be resolved in favor of
coverage. For a particular product received by a particular user,
``normally used'' refers to a typical or common use of that class of
product, regardless of the status of the particular user or of the way
in which the particular user actually uses, or expects or is expected
to use, the product. A product is a consumer product regardless of
whether the product has substantial commercial, industrial or
non-consumer uses, unless such uses represent the only significant
mode of use of the product.
``Installation Information'' for a User Product means any methods,
procedures, authorization keys, or other information required to
install and execute modified versions of a covered work in that User
Product from a modified version of its Corresponding Source. The
information must suffice to ensure that the continued functioning of
the modified object code is in no case prevented or interfered with
solely because modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or
updates for a work that has been modified or installed by the
recipient, or for the User Product in which it has been modified or
installed. Access to a network may be denied when the modification
itself materially and adversely affects the operation of the network
or violates the rules and protocols for communication across the
network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
@item Additional Terms.
``Additional permissions'' are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders
of that material) supplement the terms of this License with terms:
@enumerate a
@item
Disclaiming warranty or limiting liability differently from the terms
of sections 15 and 16 of this License; or
@item
Requiring preservation of specified reasonable legal notices or author
attributions in that material or in the Appropriate Legal Notices
displayed by works containing it; or
@item
Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
@item
Limiting the use for publicity purposes of names of licensors or
authors of the material; or
@item
Declining to grant rights under trademark law for use of some trade
names, trademarks, or service marks; or
@item
Requiring indemnification of licensors and authors of that material by
anyone who conveys the material (or modified versions of it) with
contractual assumptions of liability to the recipient, for any
liability that these contractual assumptions directly impose on those
licensors and authors.
@end enumerate
All other non-permissive additional terms are considered ``further
restrictions'' within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions; the
above requirements apply either way.
@item Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
@item Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or run
a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
@item Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An ``entity transaction'' is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
@item Patents.
A ``contributor'' is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's ``contributor version''.
A contributor's ``essential patent claims'' are all patent claims owned
or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, ``control'' includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a ``patent license'' is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To ``grant'' such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. ``Knowingly relying'' means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is ``discriminatory'' if it does not include within the
scope of its coverage, prohibits the exercise of, or is conditioned on
the non-exercise of one or more of the rights that are specifically
granted under this License. You may not convey a covered work if you
are a party to an arrangement with a third party that is in the
business of distributing software, under which you make payment to the
third party based on the extent of your activity of conveying the
work, and under which the third party grants, to any of the parties
who would receive the covered work from you, a discriminatory patent
license (a) in connection with copies of the covered work conveyed by
you (or copies made from those copies), or (b) primarily for and in
connection with specific products or compilations that contain the
covered work, unless you entered into that arrangement, or that patent
license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
@item No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey
a covered work so as to satisfy simultaneously your obligations under
this License and any other pertinent obligations, then as a
consequence you may not convey it at all. For example, if you agree
to terms that obligate you to collect a royalty for further conveying
from those to whom you convey the Program, the only way you could
satisfy both those terms and this License would be to refrain entirely
from conveying the Program.
@item Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
@item Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions
of the GNU General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies that a certain numbered version of the GNU General Public
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that numbered version or
of any later version published by the Free Software Foundation. If
the Program does not specify a version number of the GNU General
Public License, you may choose any version ever published by the Free
Software Foundation.
If the Program specifies that a proxy can decide which future versions
of the GNU General Public License can be used, that proxy's public
statement of acceptance of a version permanently authorizes you to
choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
@item Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE
DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.
@item Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
@item Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
@end enumerate
@heading END OF TERMS AND CONDITIONS
@heading How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.
@smallexample
@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) @var{year} @var{name of author}
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see @url{http://www.gnu.org/licenses/}.
@end smallexample
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
@smallexample
@var{program} Copyright (C) @var{year} @var{name of author}
This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
This is free software, and you are welcome to redistribute it
under certain conditions; type @samp{show c} for details.
@end smallexample
The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License. Of course, your
program's commands might be different; for a GUI interface, you would
use an ``about box''.
You should also get your employer (if you work as a programmer) or school,
if any, to sign a ``copyright disclaimer'' for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
@url{http://www.gnu.org/licenses/}.
The GNU General Public License does not permit incorporating your
program into proprietary programs. If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library. If this is what you want to do, use
the GNU Lesser General Public License instead of this License. But
first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}.
@ignore
arch-tag: 0c4a2556-f87e-464f-9b1d-efd920fcaf67
@end ignore

4327
doc/misc/idlwave.texi Normal file
View file

File diff suppressed because it is too large Load diff

1503
doc/misc/info.texi Normal file
View file

File diff suppressed because it is too large Load diff

389
doc/misc/makefile.w32-in Normal file
View file

@ -0,0 +1,389 @@
#### -*- Makefile -*- for the Emacs Manual and other documentation.
# Copyright (C) 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
# This file is part of GNU Emacs.
# GNU Emacs is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
# GNU Emacs is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with GNU Emacs; see the file COPYING. If not, write to
# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301, USA.
# Where to find the source code. The source code for Emacs's C kernel is
# expected to be in $(srcdir)/src, and the source code for Emacs's
# utility programs is expected to be in $(srcdir)/lib-src. This is
# set by the configure script's `--srcdir' option.
srcdir=.
infodir = $(srcdir)/../info
# The makeinfo program is part of the Texinfo distribution.
MAKEINFO = makeinfo --force
MULTI_INSTALL_INFO = $(srcdir)\..\nt\multi-install-info.bat
INFO_TARGETS = $(infodir)/emacs $(infodir)/ccmode \
$(infodir)/cl $(infodir)/dired-x $(infodir)/ediff \
$(infodir)/forms $(infodir)/gnus $(infodir)/message \
$(infodir)/sieve $(infodir)/pgg $(infodir)/emacs-mime \
$(infodir)/info $(infodir)/mh-e $(infodir)/reftex \
$(infodir)/sc $(infodir)/vip $(infodir)/viper \
$(infodir)/widget $(infodir)/efaq $(infodir)/ada-mode \
$(infodir)/autotype $(infodir)/calc $(infodir)/idlwave \
$(infodir)/eudc $(infodir)/ebrowse $(infodir)/pcl-cvs \
$(infodir)/woman $(infodir)/eshell $(infodir)/org \
$(infodir)/url $(infodir)/speedbar $(infodir)/tramp \
$(infodir)/ses $(infodir)/smtpmail $(infodir)/flymake \
$(infodir)/newsticker $(infodir)/rcirc $(infodir)/erc
DVI_TARGETS = emacs.dvi calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \
ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \
gnus.dvi message.dvi sieve.dvi pgg.dvi mh-e.dvi \
reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \
ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \
pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \
speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \
newsticker.dvi emacs-xtra.dvi rcirc.dvi erc.dvi
INFOSOURCES = info.texi
# The following rule does not work with all versions of `make'.
.SUFFIXES: .texi .dvi
.texi.dvi:
texi2dvi $<
TEXI2DVI = texi2dvi
ENVADD = $(srcdir)\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \
"MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C
EMACS_XTRA=\
$(srcdir)/arevert-xtra.texi \
$(srcdir)/cal-xtra.texi \
$(srcdir)/dired-xtra.texi \
$(srcdir)/picture-xtra.texi \
$(srcdir)/emerge-xtra.texi \
$(srcdir)/vc-xtra.texi \
$(srcdir)/vc1-xtra.texi \
$(srcdir)/vc2-xtra.texi \
$(srcdir)/fortran-xtra.texi \
$(srcdir)/msdog-xtra.texi
EMACSSOURCES= \
$(srcdir)/emacs.texi \
$(srcdir)/doclicense.texi \
$(srcdir)/screen.texi \
$(srcdir)/commands.texi \
$(srcdir)/entering.texi \
$(srcdir)/basic.texi \
$(srcdir)/mini.texi \
$(srcdir)/m-x.texi \
$(srcdir)/help.texi \
$(srcdir)/mark.texi \
$(srcdir)/killing.texi \
$(srcdir)/regs.texi \
$(srcdir)/display.texi \
$(srcdir)/search.texi \
$(srcdir)/fixit.texi \
$(srcdir)/files.texi \
$(srcdir)/buffers.texi \
$(srcdir)/windows.texi \
$(srcdir)/frames.texi \
$(srcdir)/mule.texi \
$(srcdir)/major.texi \
$(srcdir)/indent.texi \
$(srcdir)/text.texi \
$(srcdir)/programs.texi \
$(srcdir)/building.texi \
$(srcdir)/maintaining.texi \
$(srcdir)/abbrevs.texi \
$(srcdir)/sending.texi \
$(srcdir)/rmail.texi \
$(srcdir)/dired.texi \
$(srcdir)/calendar.texi \
$(srcdir)/misc.texi \
$(srcdir)/custom.texi \
$(srcdir)/trouble.texi \
$(srcdir)/cmdargs.texi \
$(srcdir)/xresources.texi \
$(srcdir)/anti.texi \
$(srcdir)/macos.texi \
$(srcdir)/msdog.texi \
$(srcdir)/gnu.texi \
$(srcdir)/glossary.texi \
$(srcdir)/ack.texi \
$(srcdir)/kmacro.texi \
$(EMACS_XTRA)
info: $(INFO_TARGETS)
dvi: $(DVI_TARGETS)
# Note that all the Info targets build the Info files
# in srcdir. There is no provision for Info files
# to exist in the build directory.
# In a distribution of Emacs, the Info files should be up to date.
# The following target uses an explicit -o switch to work around
# the @setfilename directive in info.texi, which is required for
# the Texinfo distribution.
# Some Windows ports of makeinfo seem to require -o to come before the
# texi filename, contrary to GNU standards.
$(infodir)/dir:
$(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS)
$(infodir)/info: $(INFOSOURCES)
$(MAKEINFO) --no-split -o $@ info.texi
info.dvi: $(INFOSOURCES)
$(ENVADD) $(TEXI2DVI) $(srcdir)/info.texi
$(infodir)/emacs: $(EMACSSOURCES)
$(MAKEINFO) emacs.texi
emacs.dvi: $(EMACSSOURCES)
$(ENVADD) $(TEXI2DVI) $(srcdir)/emacs.texi
# This target is here so you could easily get the list of the *.texi
# files which belong to the Emacs manual (as opposed to the separate
# manuals for CL, CC Mode, Ebrowse, etc.). With this target, you can
# say things like "grep foo `make emacsman`".
emacsman:
@echo $(EMACSSOURCES)
$(infodir)/ccmode: cc-mode.texi
$(MAKEINFO) cc-mode.texi
cc-mode.dvi: cc-mode.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/cc-mode.texi
$(infodir)/ada-mode: ada-mode.texi
$(MAKEINFO) ada-mode.texi
ada-mode.dvi: ada-mode.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/ada-mode.texi
$(infodir)/pcl-cvs: pcl-cvs.texi
$(MAKEINFO) pcl-cvs.texi
pcl-cvs.dvi: pcl-cvs.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/pcl-cvs.texi
$(infodir)/eshell: eshell.texi
$(MAKEINFO) eshell.texi
eshell.dvi: eshell.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/eshell.texi
$(infodir)/cl: cl.texi
$(MAKEINFO) cl.texi
cl.dvi: cl.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/cl.texi
$(infodir)/dired-x: dired-x.texi
$(MAKEINFO) dired-x.texi
dired-x.dvi: dired-x.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/dired-x.texi
$(infodir)/ediff: ediff.texi
$(MAKEINFO) ediff.texi
ediff.dvi: ediff.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/ediff.texi
$(infodir)/flymake: flymake.texi
$(MAKEINFO) flymake.texi
flymake.dvi: flymake.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/flymake.texi
$(infodir)/forms: forms.texi
$(MAKEINFO) forms.texi
forms.dvi: forms.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/forms.texi
# gnus/message/emacs-mime/sieve/pgg are part of Gnus:
$(infodir)/gnus: gnus.texi
$(MAKEINFO) gnus.texi
gnus.dvi: gnus.texi
sed -e "/@iflatex/,/@end iflatex/d" $(srcdir)/gnus.texi > gnustmp.texi
$(ENVADD) $(TEXI2DVI) gnustmp.texi
cp gnustmp.dvi $*.dvi
rm gnustmp.*
#
$(infodir)/message: message.texi
$(MAKEINFO) message.texi
message.dvi: message.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/message.texi
#
$(infodir)/emacs-mime: emacs-mime.texi
$(MAKEINFO) --enable-encoding emacs-mime.texi
emacs-mime.dvi: emacs-mime.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-mime.texi
#
$(infodir)/sieve: sieve.texi
$(MAKEINFO) sieve.texi
sieve.dvi: sieve.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/sieve.texi
#
$(infodir)/pgg: pgg.texi
$(MAKEINFO) pgg.texi
pgg.dvi: pgg.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/pgg.texi
$(infodir)/mh-e: mh-e.texi
$(MAKEINFO) mh-e.texi
mh-e.dvi: mh-e.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/mh-e.texi
$(infodir)/reftex: reftex.texi
$(MAKEINFO) reftex.texi
reftex.dvi: reftex.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/reftex.texi
$(infodir)/sc: sc.texi
$(MAKEINFO) sc.texi
sc.dvi: sc.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/sc.texi
$(infodir)/vip: vip.texi
$(MAKEINFO) vip.texi
vip.dvi: vip.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/vip.texi
$(infodir)/viper: viper.texi
$(MAKEINFO) viper.texi
viper.dvi: viper.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/viper.texi
$(infodir)/widget: widget.texi
$(MAKEINFO) widget.texi
widget.dvi: widget.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/widget.texi
$(infodir)/efaq: faq.texi
$(MAKEINFO) faq.texi
faq.dvi: faq.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/faq.texi
../etc/GNU: gnu1.texi gnu.texi
$(MAKEINFO) --no-headers -o ../etc/GNU gnu1.texi
$(infodir)/autotype: autotype.texi
$(MAKEINFO) autotype.texi
autotype.dvi: autotype.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/autotype.texi
$(infodir)/calc: calc.texi
$(MAKEINFO) calc.texi
calc.dvi: calc.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/calc.texi
# This is produced with --no-split to avoid making files whose
# names clash on DOS 8+3 filesystems
$(infodir)/idlwave: idlwave.texi
$(MAKEINFO) --no-split idlwave.texi
idlwave.dvi: idlwave.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/idlwave.texi
$(infodir)/eudc: eudc.texi
$(MAKEINFO) eudc.texi
eudc.dvi: eudc.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/eudc.texi
$(infodir)/ebrowse: ebrowse.texi
$(MAKEINFO) ebrowse.texi
ebrowse.dvi: ebrowse.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/ebrowse.texi
$(infodir)/woman: woman.texi
$(MAKEINFO) woman.texi
woman.dvi: woman.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/woman.texi
$(infodir)/speedbar: speedbar.texi
$(MAKEINFO) speedbar.texi
speedbar.dvi: speedbar.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/speedbar.texi
$(infodir)/tramp: tramp.texi
$(MAKEINFO) tramp.texi
tramp.dvi: tramp.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/tramp.texi
$(infodir)/ses: ses.texi
$(MAKEINFO) ses.texi
ses.dvi: ses.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/ses.texi
$(infodir)/smtpmail: smtpmail.texi
$(MAKEINFO) smtpmail.texi
smtpmail.dvi: smtpmail.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/smtpmail.texi
emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA)
$(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-xtra.texi
$(infodir)/org: org.texi
$(MAKEINFO) org.texi
org.dvi: org.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/org.texi
$(infodir)/url: url.texi
$(MAKEINFO) url.texi
url.dvi: url.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/url.texi
$(infodir)/newsticker: newsticker.texi
$(MAKEINFO) newsticker.texi
newsticker.dvi: newsticker.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/newsticker.texi
$(infodir)/rcirc: rcirc.texi
$(MAKEINFO) rcirc.texi
rcirc.dvi: rcirc.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/rcirc.texi
$(infodir)/erc: erc.texi
$(MAKEINFO) erc.texi
erc.dvi: erc.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/erc.texi
mostlyclean:
- $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.*
clean: mostlyclean
- $(DEL) *.dvi
- $(DEL) $(infodir)/emacs* $(infodir)/ccmode* \
$(infodir)/cl* $(infodir)/dired-x* \
$(infodir)/ediff* $(infodir)/forms* \
$(infodir)/gnus* $(infodir)/info* \
$(infodir)/message* $(infodir)/mh-e* \
$(infodir)/reftex* $(infodir)/sc* \
$(infodir)/vip* $(infodir)/widget* \
$(infodir)/efaq* $(infodir)/ada-mode* \
$(infodir)/autotype* $(infodir)/calc* \
$(infodir)/idlwave* $(infodir)/eudc* \
$(infodir)/ebrowse* $(infodir)/pcl-cvs* \
$(infodir)/woman* $(infodir)/eshell* \
$(infodir)/speedbar* $(infodir)/tramp* \
$(infodir)/ses* $(infodir)/smtpmail* \
$(infodir)/url* $(infodir)/org* \
$(infodir)/flymake* $(infodir)/newsticker* \
$(infodir)/sieve* $(infodir)/pgg* \
$(infodir)/erc* $(infodir)/rcirc*
distclean: clean
maintainer-clean: distclean
- $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc
# Don't delete these, because they are outside the current directory.
# for file in $(INFO_TARGETS); do rm -f $${file}*; done
# Formerly this directory had texindex.c and getopt.c in it
# and this makefile built them to make texindex.
# That caused trouble because this is run entirely in the source directory.
# Since we expect to get texi2dvi from elsewhere,
# it is ok to expect texindex from elsewhere also.

2362
doc/misc/message.texi Normal file
View file

File diff suppressed because it is too large Load diff

9793
doc/misc/mh-e.texi Normal file
View file

File diff suppressed because it is too large Load diff

290
doc/misc/newsticker.texi Normal file
View file

@ -0,0 +1,290 @@
\input texinfo @c -*-texinfo-*-
@comment %**start of header
@setfilename ../info/newsticker
@set VERSION 1.9
@set UPDATED November 2005
@settitle Newsticker @value{VERSION}
@syncodeindex vr cp
@syncodeindex fn cp
@syncodeindex pg cp
@comment %**end of header
@copying
This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}).
@noindent
Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''
in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* Newsticker: (newsticker). A Newsticker for Emacs.
@end direntry
@titlepage
@title Newsticker -- a Newsticker for Emacs
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Ulf Jasper
@author @email{ulf.jasper@@web.de}
@author @uref{http://de.geocities.com/ulf_jasper}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top Newsticker
@end ifnottex
@menu
* Overview:: General description of newsticker.
* Requirements:: Requirements for using newsticker.
* Installation:: Installing newsticker on your system.
* Usage:: Basic newsticker instructions.
* Configuration:: Customizable newsticker settings.
* Remarks:: Remarks about newsticker.
* GNU Free Documentation License:: The license for this documentation.
* Index:: Variable, function, and concept index.
@end menu
@node Overview
@chapter Overview
Newsticker provides a newsticker for Emacs. A newsticker is a thing
that asynchronously retrieves headlines from a list of news sites,
prepares these headlines for reading, and allows for loading the
corresponding articles in a web browser.
Headlines consist of a title and (possibly) a small description. They
are contained in "RSS" (RDF Site Summary) or "Atom" files. Newsticker
should work with the following RSS formats:
@itemize
@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or
@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}),
@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}),
@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec}
@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}),
@end itemize
@itemize
as well as the following Atom formats:
@item Atom 0.3
@item Atom 1.0 (see
@uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}).
@end itemize
That makes Newsticker.el an "Atom aggregator, "RSS reader", or "RSS
aggregator".
Newsticker provides several commands for reading headlines, navigating
through them, marking them as read/unread, hiding old headlines etc.
Headlines can be displayed as plain text or as rendered HTML.
Headlines can be displayed in the echo area, either scrolling like
messages in a stock-quote ticker, or just changing.
Newsticker allows for automatic processing of headlines by providing
hooks and (sample) functions for automatically downloading images and
enclosed files (as delivered by podcasts, e.g.).
@ifhtml
Here are screen shots of the @uref{newsticker-1.7.png, version 1.7
(current version)} and some older screen shots:
@uref{newsticker-1.6.png, version 1.6},
@uref{newsticker-1.5.png, version 1.5},
@uref{newsticker-1.4.png, version 1.4}
@uref{newsticker-1.3.png, version 1.3},
@uref{newsticker-1.0.png, version 1.0}.
@end ifhtml
@node Requirements
@chapter Requirements
Newsticker can be used with
@uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version
21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}. It
requires an XML-parser (@file{xml.el}) which is part of GNU Emacs. If
you are using XEmacs you want to get the @file{net-utils} package
which contains @file{xml.el} for XEmacs.
Newsticker requires a program which can retrieve files via http and
prints them to stdout. By default Newsticker will use
@uref{http://www.gnu.org/software/wget/wget.html, wget} for this task.
@node Installation
@chapter Installation
As Newsticker is part of GNU Emacs there is no need to perform any
installation steps in order to use Newsticker.
However, if you are using imenu, which allows for navigating with the
help of a menu, you should add the following to your Emacs startup file
(@file{~/.emacs}).
@lisp
(add-hook 'newsticker-mode-hook 'imenu-add-menubar-index)
@end lisp
That's it.
@node Usage
@chapter Usage
@findex newsticker-show-news
The command @code{newsticker-show-news} will display all available
headlines in a special buffer, called @samp{*newsticker*}. It will
also start the asynchronous download of headlines. The modeline in
the @samp{*newsticker*} buffer informs whenever new headlines have
arrived. Clicking mouse-button 2 or pressing RET in this buffer on a
headline will call @code{browse-url} to load the corresponding news
story in your favourite web browser.
@findex newsticker-start-ticker
@findex newsticker-stop-ticker
The scrolling, or flashing of headlines in the echo area, can be
started with the command @code{newsticker-start-ticker}. It can be
stopped with @code{newsticker-stop-ticker}.
@findex newsticker-start
@findex newsticker-stop
If you just want to start the periodic download of headlines use the
command @code{newsticker-start}. Calling @code{newsticker-stop} will
stop the periodic download, but will call
@code{newsticker-stop-ticker} as well.
@node Configuration
@chapter Configuration
All Newsticker options are customizable, i.e. they can be changed with
Emacs customization methods: Call the command
@code{customize-group} and enter @samp{newsticker} for the customization
group.
All Newsticker options have reasonable default values, so that in most
cases it is not necessary to customize settings before starting Newsticker
for the first time.
Newsticker options are organized in the following groups.
@itemize
@item
@code{newsticker-feed} contains options that define which news
feeds are retrieved and how this is done.
@itemize
@item
@vindex newsticker-url-list
@code{newsticker-url-list} defines the list of headlines which are
retrieved.
@item
@vindex newsticker-retrieval-interval
@code{newsticker-retrieval-interval} defines how often headlines
are retrieved.
@end itemize
@item
@code{newsticker-headline-processing} contains options that define
how the retrieved headlines are processed.
@itemize
@item
@vindex newsticker-keep-obsolete-items
@code{newsticker-keep-obsolete-items} decides whether unread
headlines that have been removed from the feed are kept in the
Newsticker cache.
@end itemize
@item
@code{newsticker-layout} contains options that define how the
buffer for reading news headlines is formatted.
@itemize
@item
@vindex newsticker-heading-format
@code{newsticker-item-format} defines how the title of a headline
is formatted.
@end itemize
@item
@code{newsticker-ticker} contains options that define how headlines
are shown in the echo area.
@itemize
@item
@vindex newsticker-display-interval
@vindex newsticker-scroll-smoothly
@code{newsticker-display-interval} and
@code{newsticker-scroll-smoothly} define how headlines are shown in
the echo area.
@end itemize
@item
@code{newsticker-hooks} contains options for hooking other Emacs
commands to newsticker functions.
@itemize
@item
@vindex newsticker-new-item-functions
@code{newsticker-new-item-functions} allows for automatic
processing of headlines. See `newsticker-download-images', and
`newsticker-download-enclosures' for sample functions.
@end itemize
@item
@code{newsticker-miscellaneous} contains other Newsticker options.
@end itemize
Please have a look at the customization buffers for the complete list
of options.
@node Remarks
@chapter Remarks
This newsticker is designed do its job silently in the background
without disturbing you. However, it is probably impossible to prevent
such a tool from slightly attenuating your Editor's responsiveness
every once in a while.
Byte-compiling newsticker.el is recommended.
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
@node Index
@unnumbered Index
@printindex cp
@bye
@ignore
arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0
@end ignore

7931
doc/misc/org.texi Normal file
View file

File diff suppressed because it is too large Load diff

1443
doc/misc/pcl-cvs.texi Normal file
View file

File diff suppressed because it is too large Load diff

498
doc/misc/pgg.texi Normal file
View file

@ -0,0 +1,498 @@
\input texinfo @c -*-texinfo-*-
@setfilename ../info/pgg
@set VERSION 0.1
@copying
This file describes PGG, an Emacs interface to various PGP implementations.
Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007 Free Software
Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License.''
@end quotation
@end copying
@dircategory Emacs
@direntry
* PGG: (pgg). Emacs interface to various PGP implementations.
@end direntry
@settitle PGG @value{VERSION}
@titlepage
@title PGG
@author by Daiki Ueno
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@page
@node Top
@top PGG
This manual describes PGG. PGG is an interface library between Emacs
and various tools for secure communication. PGG also provides a simple
user interface to encrypt, decrypt, sign, and verify MIME messages.
@menu
* Overview:: What PGG is.
* Prerequisites:: Complicated stuff you may have to do.
* How to use:: Getting started quickly.
* Architecture::
* Parsing OpenPGP packets::
* GNU Free Documentation License:: The license for this documentation.
* Function Index::
* Variable Index::
@end menu
@node Overview
@chapter Overview
PGG is an interface library between Emacs and various tools for secure
communication. Even though Mailcrypt has similar feature, it does not
deal with detached PGP messages, normally used in PGP/MIME
infrastructure. This was the main reason why I wrote the new library.
PGP/MIME is an application of MIME Object Security Services (RFC1848).
The standard is documented in RFC2015.
@node Prerequisites
@chapter Prerequisites
PGG requires at least one implementation of privacy guard system.
This document assumes that you have already obtained and installed them
and that you are familiar with its basic functions.
By default, PGG uses GnuPG. If you are new to such a system, I
recommend that you should look over the GNU Privacy Handbook (GPH)
which is available at @uref{http://www.gnupg.org/documentation/}.
When using GnuPG, we recommend the use of the @code{gpg-agent}
program, which is distributed with versions 2.0 and later of GnuPG.
This is a daemon to manage private keys independently from any
protocol, and provides the most secure way to input and cache your
passphrases (@pxref{Caching passphrase}). By default, PGG will
attempt to use @code{gpg-agent} if it is running. @xref{Invoking
GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
PGG also supports Pretty Good Privacy version 2 or version 5.
@node How to use
@chapter How to use
The toplevel interface of this library is quite simple, and only
intended to use with public-key cryptographic operation.
To use PGG, evaluate following expression at the beginning of your
application program.
@lisp
(require 'pgg)
@end lisp
If you want to check existence of pgg.el at runtime, instead you can
list autoload setting for desired functions as follows.
@lisp
(autoload 'pgg-encrypt-region "pgg"
"Encrypt the current region." t)
(autoload 'pgg-encrypt-symmetric-region "pgg"
"Encrypt the current region with symmetric algorithm." t)
(autoload 'pgg-decrypt-region "pgg"
"Decrypt the current region." t)
(autoload 'pgg-sign-region "pgg"
"Sign the current region." t)
(autoload 'pgg-verify-region "pgg"
"Verify the current region." t)
(autoload 'pgg-insert-key "pgg"
"Insert the ASCII armored public key." t)
(autoload 'pgg-snarf-keys-region "pgg"
"Import public keys in the current region." t)
@end lisp
@menu
* User Commands::
* Selecting an implementation::
* Caching passphrase::
* Default user identity::
@end menu
@node User Commands
@section User Commands
At this time you can use some cryptographic commands. The behavior of
these commands relies on a fashion of invocation because they are also
intended to be used as library functions. In case you don't have the
signer's public key, for example, the function @code{pgg-verify-region}
fails immediately, but if the function had been called interactively, it
would ask you to retrieve the signer's public key from the server.
@deffn Command pgg-encrypt-region start end recipients &optional sign passphrase
Encrypt the current region between @var{start} and @var{end} for
@var{recipients}. When the function were called interactively, you
would be asked about the recipients.
If encryption is successful, it replaces the current region contents (in
the accessible portion) with the resulting data.
If optional argument @var{sign} is non-@code{nil}, the function is
request to do a combined sign and encrypt. This currently is
confirmed to work with GnuPG, but might not work with PGP or PGP5.
If optional @var{passphrase} is @code{nil}, the passphrase will be
obtained from the passphrase cache or user.
@end deffn
@deffn Command pgg-encrypt-symmetric-region &optional start end passphrase
Encrypt the current region between @var{start} and @var{end} using a
symmetric cipher. After invocation you are asked for a passphrase.
If optional @var{passphrase} is @code{nil}, the passphrase will be
obtained from the passphrase cache or user.
symmetric-cipher encryption is currently only implemented for GnuPG.
@end deffn
@deffn Command pgg-decrypt-region start end &optional passphrase
Decrypt the current region between @var{start} and @var{end}. If
decryption is successful, it replaces the current region contents (in
the accessible portion) with the resulting data.
If optional @var{passphrase} is @code{nil}, the passphrase will be
obtained from the passphrase cache or user.
@end deffn
@deffn Command pgg-sign-region start end &optional cleartext passphrase
Make the signature from text between @var{start} and @var{end}. If the
optional third argument @var{cleartext} is non-@code{nil}, or the
function is called interactively, it does not create a detached
signature. In such a case, it replaces the current region contents (in
the accessible portion) with the resulting data.
If optional @var{passphrase} is @code{nil}, the passphrase will be
obtained from the passphrase cache or user.
@end deffn
@deffn Command pgg-verify-region start end &optional signature fetch
Verify the current region between @var{start} and @var{end}. If the
optional third argument @var{signature} is non-@code{nil}, it is treated
as the detached signature file of the current region.
If the optional 4th argument @var{fetch} is non-@code{nil}, or the
function is called interactively, we attempt to fetch the signer's
public key from the key server.
@end deffn
@deffn Command pgg-insert-key
Retrieve the user's public key and insert it as ASCII-armored format.
@end deffn
@deffn Command pgg-snarf-keys-region start end
Collect public keys in the current region between @var{start} and
@var{end}, and add them into the user's keyring.
@end deffn
@node Selecting an implementation
@section Selecting an implementation
Since PGP has a long history and there are a number of PGP
implementations available today, the function which each one has differs
considerably. For example, if you are using GnuPG, you know you can
select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on
the other hand the version 2 of PGP only supports IDEA.
Which implementation is used is controlled by the @code{pgg-scheme}
variable. If it is @code{nil} (the default), the value of the
@code{pgg-default-scheme} variable will be used instead.
@defvar pgg-scheme
Force specify the scheme of PGP implementation. The value can be set to
@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}.
@end defvar
@defvar pgg-default-scheme
The default scheme of PGP implementation. The value should be one of
@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}.
@end defvar
@node Caching passphrase
@section Caching passphrase
When using GnuPG (gpg) as the PGP scheme, we recommend using a program
called @code{gpg-agent} for entering and caching
passphrases@footnote{Actually, @code{gpg-agent} does not cache
passphrases but private keys. On the other hand, from a user's point
of view, this technical difference isn't visible.}.
@defvar pgg-gpg-use-agent
If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible.
The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG
is not the current PGP scheme, PGG's own passphrase-caching mechanism
is used (see below).
@end defvar
To use @code{gpg-agent} with PGG, you must first ensure that
@code{gpg-agent} is running. For example, if you are running in the X
Window System, you can do this by putting the following line in your
@file{.xsession} file:
@smallexample
eval "$(gpg-agent --daemon)"
@end smallexample
For more details on invoking @code{gpg-agent}, @xref{Invoking
GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}.
Whenever you perform a PGG operation that requires a GnuPG passphrase,
GnuPG will contact @code{gpg-agent}, which prompts you for the
passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so
that subsequent uses will not require you to enter the passphrase
again. (This cache usually expires after a certain time has passed;
you can change this using the @code{--default-cache-ttl} option when
invoking @code{gpg-agent}.)
If you are running in a X Window System environment, @code{gpg-agent}
prompts for a passphrase by opening a graphical window. However, if
you are running Emacs on a text terminal, @code{gpg-agent} has trouble
receiving input from the terminal, since it is being sent to Emacs.
One workaround for this problem is to run @code{gpg-agent} on a
different terminal from Emacs, with the @code{--keep-tty} option; this
tells @code{gpg-agent} use its own terminal to prompt for passphrases.
When @code{gpg-agent} is not being used, PGG prompts for a passphrase
through Emacs. It also has its own passphrase caching mechanism,
which is controlled by the variable @code{pgg-cache-passphrase} (see
below).
There is a security risk in handling passphrases through PGG rather
than @code{gpg-agent}. When you enter your passphrase into an Emacs
prompt, it is temporarily stored as a cleartext string in the memory
of the Emacs executable. If the executable memory is swapped to disk,
the root user can, in theory, extract the passphrase from the
swapfile. Furthermore, the swapfile containing the cleartext
passphrase might remain on the disk after the system is discarded or
stolen. @code{gpg-agent} avoids this problem by using certain tricks,
such as memory locking, which have not been implemented in Emacs.
@defvar pgg-cache-passphrase
If non-@code{nil}, store passphrases. The default value of this
variable is @code{t}. If you are worried about security issues,
however, you could stop the caching of passphrases by setting this
variable to @code{nil}.
@end defvar
@defvar pgg-passphrase-cache-expiry
Elapsed time for expiration in seconds.
@end defvar
If your passphrase contains non-ASCII characters, you might need to
specify the coding system to be used to encode your passphrases, since
GnuPG treats them as a byte sequence, not as a character sequence.
@defvar pgg-passphrase-coding-system
Coding system used to encode passphrase.
@end defvar
@node Default user identity
@section Default user identity
The PGP implementation is usually able to select the proper key to use
for signing and decryption, but if you have more than one key, you may
need to specify the key id to use.
@defvar pgg-default-user-id
User ID of your default identity. It defaults to the value returned
by @samp{(user-login-name)}. You can customize this variable.
@end defvar
@defvar pgg-gpg-user-id
User ID of the GnuPG default identity. It defaults to @samp{nil}.
This overrides @samp{pgg-default-user-id}. You can customize this
variable.
@end defvar
@defvar pgg-pgp-user-id
User ID of the PGP 2.x/6.x default identity. It defaults to
@samp{nil}. This overrides @samp{pgg-default-user-id}. You can
customize this variable.
@end defvar
@defvar pgg-pgp5-user-id
User ID of the PGP 5.x default identity. It defaults to @samp{nil}.
This overrides @samp{pgg-default-user-id}. You can customize this
variable.
@end defvar
@node Architecture
@chapter Architecture
PGG introduces the notion of a "scheme of PGP implementation" (used
interchangeably with "scheme" in this document). This term refers to a
singleton object wrapped with the luna object system.
Since PGG was designed for accessing and developing PGP functionality,
the architecture had to be designed not just for interoperability but
also for extensiblity. In this chapter we explore the architecture
while finding out how to write the PGG backend.
@menu
* Initializing::
* Backend methods::
* Getting output::
@end menu
@node Initializing
@section Initializing
A scheme must be initialized before it is used.
It had better guarantee to keep only one instance of a scheme.
The following code is snipped out of @file{pgg-gpg.el}. Once an
instance of @code{pgg-gpg} scheme is initialized, it's stored to the
variable @code{pgg-scheme-gpg-instance} and will be reused from now on.
@lisp
(defvar pgg-scheme-gpg-instance nil)
(defun pgg-make-scheme-gpg ()
(or pgg-scheme-gpg-instance
(setq pgg-scheme-gpg-instance
(luna-make-entity 'pgg-scheme-gpg))))
@end lisp
The name of the function must follow the
regulation---@code{pgg-make-scheme-} follows the backend name.
@node Backend methods
@section Backend methods
In each backend, these methods must be present. The output of these
methods is stored in special buffers (@ref{Getting output}), so that
these methods must tell the status of the execution.
@deffn Method pgg-scheme-lookup-key scheme string &optional type
Return keys associated with @var{string}. If the optional third
argument @var{type} is non-@code{nil}, it searches from the secret
keyrings.
@end deffn
@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase
Encrypt the current region between @var{start} and @var{end} for
@var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign
and encrypt. If encryption is successful, it returns @code{t},
otherwise @code{nil}.
@end deffn
@deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase
Encrypt the current region between @var{start} and @var{end} using a
symmetric cipher and a passphrases. If encryption is successful, it
returns @code{t}, otherwise @code{nil}. This function is currently only
implemented for GnuPG.
@end deffn
@deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase
Decrypt the current region between @var{start} and @var{end}. If
decryption is successful, it returns @code{t}, otherwise @code{nil}.
@end deffn
@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase
Make the signature from text between @var{start} and @var{end}. If the
optional third argument @var{cleartext} is non-@code{nil}, it does not
create a detached signature. If signing is successful, it returns
@code{t}, otherwise @code{nil}.
@end deffn
@deffn Method pgg-scheme-verify-region scheme start end &optional signature
Verify the current region between @var{start} and @var{end}. If the
optional third argument @var{signature} is non-@code{nil}, it is treated
as the detached signature of the current region. If the signature is
successfully verified, it returns @code{t}, otherwise @code{nil}.
@end deffn
@deffn Method pgg-scheme-insert-key scheme
Retrieve the user's public key and insert it as ASCII-armored format.
On success, it returns @code{t}, otherwise @code{nil}.
@end deffn
@deffn Method pgg-scheme-snarf-keys-region scheme start end
Collect public keys in the current region between @var{start} and
@var{end}, and add them into the user's keyring.
On success, it returns @code{t}, otherwise @code{nil}.
@end deffn
@node Getting output
@section Getting output
The output of the backend methods (@ref{Backend methods}) is stored in
special buffers, so that these methods must tell the status of the
execution.
@defvar pgg-errors-buffer
The standard error output of the execution of the PGP command is stored
here.
@end defvar
@defvar pgg-output-buffer
The standard output of the execution of the PGP command is stored here.
@end defvar
@defvar pgg-status-buffer
The rest of status information of the execution of the PGP command is
stored here.
@end defvar
@node Parsing OpenPGP packets
@chapter Parsing OpenPGP packets
The format of OpenPGP messages is maintained in order to publish all
necessary information needed to develop interoperable applications.
The standard is documented in RFC 2440.
PGG has its own parser for the OpenPGP packets.
@defun pgg-parse-armor string
List the sequence of packets in @var{string}.
@end defun
@defun pgg-parse-armor-region start end
List the sequence of packets in the current region between @var{start}
and @var{end}.
@end defun
@defvar pgg-ignore-packet-checksum
If non-@code{nil}, don't check the checksum of the packets.
@end defvar
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
@node Function Index
@unnumbered Function Index
@printindex fn
@node Variable Index
@unnumbered Variable Index
@printindex vr
@summarycontents
@contents
@bye
@c End:
@ignore
arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85
@end ignore

768
doc/misc/rcirc.texi Normal file
View file

@ -0,0 +1,768 @@
\input texinfo
@c %**start of header
@setfilename ../info/rcirc
@settitle rcirc Manual
@c %**end of header
@copying
Copyright @copyright{} 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license is
included in the section entitled ``GNU Free Documentation License'' in
the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* Rcirc: (rcirc). Internet Relay Chat (IRC) client.
@end direntry
@titlepage
@title rcirc Manual
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@ifnottex
@node Top, Basics, (dir), (dir)
@top rcirc Manual
@end ifnottex
@code{rcirc} is an Emacs IRC client.
IRC (Internet Relay Chat) is a multi-user chat protocol. Users
communicate with each other in real-time. Communication occurs both in
topic channels which are collections of many users, or privately, with
just one other user.
@menu
* Basics::
* Reference::
* Hacking and Tweaking::
* GNU Free Documentation License::
* Key Index::
* Variable Index::
* Index::
@detailmenu
--- The Detailed Node Listing ---
Basics
* Internet Relay Chat::
* Getting started with rcirc::
Reference
* rcirc commands::
* Useful IRC commands::
* Configuration::
Hacking and Tweaking
* Skipping /away messages using handlers::
* Using fly spell mode::
* Scrolling conservatively::
* Changing the time stamp format::
* Defining a new command::
* Reconnecting after you have lost the connection::
@end detailmenu
@end menu
@node Basics, Reference, Top, Top
@chapter Basics
This chapter contains a brief introduction to IRC (Internet Relay Chat),
and a quick tutorial on @code{rcirc}.
@menu
* Internet Relay Chat::
* Getting started with rcirc::
@end menu
@node Internet Relay Chat, Getting started with rcirc, Basics, Basics
@section Internet Relay Chat
@cindex internet relay chat
@cindex irc
@cindex channel
@dfn{Internet Relay Chat} (IRC) is a form of instant communication over the
Internet. It is mainly designed for group (many-to-many) communication
in discussion forums called channels, but also allows one-to-one
communication.
@cindex instant messaging, comparison
@cindex server
@cindex network
Contrary to most Instant Messenger (IM) systems, users usually don't
connect to a central server. Instead, users connect to a random server
in a network, and the servers share information between them.
Here's a typical example:
@cindex redirection to random servers
When you connect to the Freenode network
(@code{http://freenode.net/}), you point your IRC client at the
server @code{irc.freenode.net}. That server will redirect your client
to a random server on the network, such as @code{zelazny.freenode.net}.
@cindex channel name
@cindex # starts a channel name
Once you're connected, you can send messages to all other users
connected to the same network, and you can join all channels on the same
network. You might join the @code{#emacs} and the @code{#rcirc}
channels, for example. (Typically, channel names begin with a hash
character.)
Once you have joined a channel, anything you type will be broadcast to
all the other users on the same channel.
@cindex addressing other people
@cindex other people, addressing them
@cindex talk to other people
If you want to address someone specifically, for example as an answer to
a question, it is customary to prefix the message with the nick followed
by a colon, like this:
@example
deego: fsbot rules!
@end example
@cindex nick completion
@cindex completion of nicks
@kindex TAB
Since this is so common, you can use @key{TAB} to do nick completion.
@node Getting started with rcirc, , Internet Relay Chat, Basics
@section Getting started with rcirc
@cindex getting started
@cindex connecting to a server
@cindex irc command
Use the command @kbd{M-x irc} to connect using the defaults.
@xref{Configuration}, if you want to change the defaults.
Use @kbd{C-u M-x irc} if you don't want to use the defaults, eg. if you
want to connect to a different network, or connect to the same network
using a different nick. This will prompt you for four things:
@table @asis
@cindex server, connecting
@cindex Freenode network
@item IRC server
What server do you want to connect to? All the servers in a particular
network are equivalent. Some networks use a round-robin system where a
single server redirects new connections to a random server in the
network. @code{irc.freenode.net} is such a server for the Freenode
network. Freenode provides the network ``for the Free and Open Source
Software communities, for not-for-profit organisations and for related
communities and organizations.''
@cindex port, connecting
@cindex 6667, default IRC port
@item IRC port
All network connections require a port. Just as web servers and clients
use port 80 per default, IRC uses port 6667 per default. You rarely
have to use a different port.
@cindex nick, connecting
@cindex changing nick
@cindex name changes
@item IRC nick
@vindex user-login-name
Every users needs a handle on-line. You will automatically be assigned
a slightly different nick if your chosen nick is already in use. If
your @code{user-login-name} is @code{alex}, and this nick is already
in use, you might for example get assigned the nick @code{alex`}.
@cindex channels, connecting
@cindex initial channels
@cindex startup channels
@item Channels
A space separated list of channels you want to join when connecting.
You don't need to join any channels, if you just want to have one-to-one
conversations with friends on the same network. If you're new to the
Freenode network, join @code{#emacs}, the channel about all things
Emacs, or join @code{#rcirc}, the channel about @code{rcirc}.
@end table
@cindex server buffer
When you have answered these questions, @code{rcirc} will create a server
buffer, which will be named something like @code{*irc.freenode.net*},
and a channel buffer for each of the channels you wanted to join.
@kindex RET
@cindex talking
@cindex communicating
To talk in a channel, just type in what you want to say in a channel
buffer, and press @key{RET}.
@kindex C-c C-c
@cindex multiline messages
@cindex messages, multiple lines
@cindex pasting multiple lines
@cindex edit message before sending
If you want to paste multiple lines, such as source code, you can use
@kbd{C-c C-c} to edit your message in a separate buffer. Use @kbd{C-c
C-c} to finish editing. You still need to press @key{RET} to send it,
though. Generally, IRC users don't like people pasting more than around
four lines of code, so use with care.
@node Reference, Hacking and Tweaking, Basics, Top
@chapter Reference
@cindex reference
This is the reference section of the manual. It is not complete. For
complete listings of @code{rcirc} features, use Emacs built-in
documentation.
@menu
* rcirc commands::
* Useful IRC commands::
* Configuration::
@end menu
@node rcirc commands, Useful IRC commands, Reference, Reference
@section rcirc commands
@cindex rcirc commands
@cindex commands
@kindex C-h m
This is a list of commands that you may use in @code{rcirc}. It is not
complete. For a complete listing, press @kbd{C-h m} in an @code{rcirc}
buffer.
In addition to using regular Emacs key bindings, you can call them by
typing them into an @code{rcirc} buffer.
@cindex call commands
@cindex typing commands
@cindex commands
For instance, instead of using the command @kbd{C-c C-j} to join a new
channel, you may type this in an @code{rcirc} buffer, and press @key{RET}:
@example
/join #emacs
@end example
@cindex / starts a command
@cindex messages starting with a slash disappear
@cindex disappearing messages if starting with a slash
@cindex slash hides message
This is why you cannot start a message with a slash. You will have to
precede the command with a space, or rewrite your message in order to
send it to a channel.
@cindex multiple words as parameters
@cindex string delimiters
@cindex quotes
@cindex double-quotes
Many commands take parameters. IRC commands usually ignore string
delimiters. Neither quote nor double-quote have special meanings in
IRC.
@example
/nick "alex schroeder"
@end example
This will try to change your nick to @code{"alex}. Usually this will
fail because the double quote character is not a legal character for
nicks.
@cindex case insensitive commands
These commands are case insensitive.
@cindex new command
@cindex unknown command
@cindex command unknown
If a command isn't known by @code{rcirc}, it will simply be sent along to the
server. There is a list of some useful commands like that in the next
section.
@table @kbd
@item C-c C-j
@kindex C-c C-j
@cindex /join
@cindex join channels
@cindex other channels
@cindex rooms, joining
@cindex discussion, joining
This joins a channel such as @code{#rcirc} or @code{#emacs}. On most
networks, anybody can create new channels. If you want to talk with
some friends, for example, all you have to do is agree on a valid
channel name and join that channel. (Also @code{/join #emacs}.)
@item C-c C-p
@kindex C-c C-p
@cindex /part
@cindex part a channel
@cindex leave a channel
@cindex disconnect from a channel
@cindex stop talking on a channel
@cindex kill channel buffer
This leaves the current channel. You can optionally provide a reason
for parting. When you kill a channel buffer, you automatically part the
corresponding channel. (Also @code{/part you are too weird!}.)
@item C-c C-r
@kindex C-c C-r
@cindex /nick
@cindex change name
@cindex nick changing
@cindex rename yourself
@cindex other name
This changes your nick to some other name. Your nick must be unique
across the network. Most networks don't allow too many nick changes in
quick succession, and have restrictions on the valid characters in nick
names. (Also @code{/nick alex-test})
@item C-c C-w
@kindex C-c C-w
@cindex /whois
@cindex who are these people
@cindex identifying people
@cindex channels other people are on
@cindex what channels people are on
Gives you some basic information about a nick. This often includes what
other channels people are on. (Also @code{/whois fsbot}.)
@item C-c C-q
@kindex C-c C-q
@cindex /query
@cindex starting a private conversation
@cindex one-to-one conversation
@cindex talk privately
@cindex private conversation
@cindex contact one person only
@cindex query a person
Starts a one-to-one conversation with another person on the same
network. A new buffer will be created for this conversation. It works
like a channel with only two members. (Also @code{/query fsbot}.)
@item C-c @key{RET}
@kindex C-c RET
@cindex /msg
@cindex single message
@cindex message sending
This sends a single message to a nick. Like with @kbd{C-c C-q}, a new
buffer is created, where the response from the other party will show
up. (Also @code{/msg nickserv identify secret}.)
@item C-c C-x
@kindex C-c C-x
@cindex /quit
@cindex quit
@cindex disconnect
@cindex kill connection
@cindex connection end
@cindex part all channels
@cindex end connection
@cindex server buffer killing
@cindex reason for quitting
This disconnects from the server and parts all channels. You can
optionally provide a reason for quitting. When you kill the server
buffer, you automatically quit the server and part all channels. (Also
@code{/quit ZZZzzz...}.)
@end table
Some commands may not have a key binding, but only be available as typed
commands, such as:
@table @code
@item /ignore
@cindex /ignore
@cindex ignoring other people
@cindex trolls, ignoring
@cindex hide some posts
@cindex idiots online
This command toggles the ignore status of a nick, if you provide one.
If you don't provide a nick, the command lists all the nicks you are
ignoring. All messages by ignored nicks are---you guessed it---ignored.
Since only ``operators'' can kick people from channels, the
ignore command is often the only way to deal with some of the more
obnoxious fellows online. Example: @code{/ignore xah}.
@end table
@node Useful IRC commands, Configuration, rcirc commands, Reference
@section Useful IRC commands
@cindex irc commands
@cindex commands
As mentioned, if a command isn't known by @code{rcirc}, it will simply be sent
along to the server. Some such commands are available on nearly all IRC
servers, such as:
@table @code
@item /away
@cindex /away
@cindex away status
@cindex pause status
@cindex unavailable status
@cindex set away status
This sets your status as ``being away'' if you provide a reason, or sets
your status as ``being back'' if you do not. People can use the
@kbd{C-c C-w} command to check your status. Example: @code{/away food}.
@end table
@cindex irc resources
@cindex help about irc
Typical IRC servers implement many more commands. You can read more
about the fantastic world of IRC online at
@uref{http://www.irchelp.org/, the Internet Relay Chat (IRC) help
archive}.
@node Configuration, , Useful IRC commands, Reference
@section Configuration
@cindex configuring rcirc
These are some variables you can change to configure @code{rcirc} to your
liking.
@table @code
@item rcirc-default-server
@vindex rcirc-default-server
the default server to connect to.
@item rcirc-default-port
@vindex rcirc-default-port
the default port to connect to.
@item rcirc-default-nick
@vindex rcirc-default-nick
the default nick to use.
@end table
@example
(setq rcirc-default-server "irc.mozilla.org"
rcirc-default-port 6666
rcirc-default-nick "alx")
@end example
@vindex rcirc-default-user-full-name
@cindex full name
@cindex real name
@cindex surname
@code{rcirc-default-user-full-name} is used to set your ``real name'' on
IRC. It defaults to @code{user-full-name}. If you want to hide your
full name, you might want to set it to some pseudonym.
@example
(setq rcirc-default-user-full-name "Curious Minds Want To Know")
@end example
@vindex rcirc-startup-channels-alist
@cindex channels, configuration
@cindex initial channels, configuration
@cindex startup channels, configuration
@code{rcirc-startup-channels-alist} is the alist of channels to join
when connecting to a particular network. An alist is a list of lists.
Each sublist starts with a regular expression that is compared to the
server address you're connecting to. The remaining sublist items are
the channels to join.
@example
(setq rcirc-startup-channels-alist
'(("\\.freenode\\.net$" "#emacs" "#rcirc" "#wiki")))
@end example
Note the subtle problem, here --- IRC clients connect to servers, and
there is no way of knowing which servers belong to a particular network.
In the example above we're exploiting a naming convention used by within
the Freenode network --- all servers within the network have a host in
the @code{freenode.net} domain.
@vindex rcirc-authinfo
@cindex authentification
@cindex identification
@cindex nickserv
@cindex login
@code{rcirc-authinfo} is an alist used to automatically identify
yourself on networks. Each sublist starts with a regular expression
that is compared to the server address you're connecting to. The second
element in the list is a symbol representing the method to use, followed
by the arguments this method requires.
Here is an example to illustrate how you would set it:
@example
(setq rcirc-authinfo
'(("freenode" nickserv "bob" "p455w0rd")
("freenode" chanserv "bob" "#bobland" "passwd99")
("bitlbee" bitlbee "robert" "sekrit")))
@end example
And here are the valid method symbols and the arguments they require:
@table @code
@item nickserv
@cindex nickserv authentification
Use this symbol if you need to identify yourself as follows when
connecting to a network: @code{/msg nickserv identify secret}. The
necessary arguments are the nickname you want to use this for, and the
password to use.
Before you can use this method, you will have to register your nick and
pick a password for it. Contact @code{nickserv} and check out the
details. (Using @code{/msg nickserv help}, for example.)
@item chanserv
@cindex chanserv authentification
Use this symbol if you need to identify yourself as follows if you want
to join a particular channel: @code{/msg chanserv identify #underground
secret}. The necessary arguments are the nickname and channel you want
to use this for, and the password to use.
Before you can use this method, a channel contact must tell you about
the password to use. Contact @code{chanserv} and check out the details.
(Using @code{/msg chanserv help}, for example.)
@item bitlbee
@cindex bitlbee authentification
Use this symbol if you need to identify yourself in the Bitlbee channel
as follows: @code{identify secret}. The necessary arguments are the
nickname you want to use this for, and the password to use.
@cindex gateway to other IM services
@cindex instant messaging, other services
@cindex Jabber
@cindex AIM
@cindex ICQ
@cindex MSN
@cindex Yahoo!
Bitlbee acts like an IRC server, but in fact it is a gateway to a lot of
other instant messaging services. You can either install Bitlbee
locally or use a public Bitlbee server. There, you need to create an
account with a password. This is the nick and password you need to
provide for the bitlbee authentification method.
Later, you will tell Bitlbee about your accounts and passwords on all
the other instant messaging services, and Bitlbee will log you in. All
@code{rcirc} needs to know, is the login to your Bitlbee account. Don't
confuse the Bitlbee account with all the other accounts.
@end table
@kindex C-c C-SPC
@vindex rcirc-track-minor-mode
@cindex switching channels
@cindex tracking activity
@cindex active channel
@cindex abbreviated channel names
@cindex modeline tracks activity
Most people want a notification when something is said on a channel they
have joined, particularly if they have been addressed directly. There
is a global minor mode that will do this kind of tracking for you. All
you need to do is switch it on using @kbd{M-x rcirc-track-minor-mode}.
To make this permanent, add the following to your init file:
@example
(rcirc-track-minor-mode 1)
@end example
When other people say things in buffers that are currently buried (no
window is showing them), the mode line will now show you the abbreviated
channel or nick name. Use @kbd{C-c C-@key{SPC}} to switch to these
buffers.
@vindex rcirc-mode-hook
If you prefer not to load @code{rcirc} immediately, you can delay the
activation of this mode:
@example
(add-hook 'rcirc-mode-hook
(lambda ()
(rcirc-track-minor-mode 1)))
@end example
@node Hacking and Tweaking, GNU Free Documentation License, Reference, Top
@chapter Hacking and Tweaking
@cindex hacking and tweaking
Here are some examples of stuff you can do to configure @code{rcirc}.
@menu
* Skipping /away messages using handlers::
* Using fly spell mode::
* Scrolling conservatively::
* Changing the time stamp format::
* Defining a new command::
* Reconnecting after you have lost the connection::
@end menu
@node Skipping /away messages using handlers, Using fly spell mode, Hacking and Tweaking, Hacking and Tweaking
@section Skipping @code{/away} messages using handlers
@cindex /away messages
@cindex handlers
@cindex status codes
The IRC protocol specifies how certain events are signaled from server
to client. These events have numbers and are dealt with using so-called
handlers. You can override existing handlers by exploiting the naming
convention adopted for @code{rcirc}.
Here's how to stop @code{rcirc} from printing @code{/away} messages.
Since @code{rcirc} doesn't define a 301 handler, you don't need to
require @code{rcirc} before defining the handler:
@example
(defun rcirc-handler-301 (process cmd sender args)
"/away message handler.")
@end example
@node Using fly spell mode, Scrolling conservatively, Skipping /away messages using handlers, Hacking and Tweaking
@section Using fly spell mode
@cindex fly spell
@cindex spelling
@cindex spell-checking as you type
@cindex automatic spelling
@vindex rcirc-mode-hook
The following code activates Fly Spell Mode
for @code{rcirc} buffers:
@example
(add-hook 'rcirc-mode-hook (lambda ()
(flyspell-mode 1)))
@end example
@xref{Spelling, , Flyspell mode, emacs, The GNU Emacs Manual},
for details.
@node Scrolling conservatively, Changing the time stamp format, Using fly spell mode, Hacking and Tweaking
@section Scrolling conservatively
@cindex input line
@cindex scrolling
@vindex scroll-conservatively
@vindex rcirc-mode-hook
IRC buffers are constantly growing. If you want to see as much as
possible at all times, you would want the prompt at the bottom of the
window when possible. The following snippet uses a local value for
@code{scroll-conservatively} to achieve this:
@example
(add-hook 'rcirc-mode-hook
(lambda ()
(set (make-local-variable 'scroll-conservatively)
8192)))
@end example
@xref{Scrolling, , Scrolling conservatively, emacs, The GNU Emacs
Manual}, for details.
@node Changing the time stamp format, Defining a new command, Scrolling conservatively, Hacking and Tweaking
@section Changing the time stamp format
@cindex time stamp
@cindex date time
@cindex format time stamp
@vindex rcirc-time-format
@code{rcirc-time-format} is the format used for the time stamp. Here's
how to include the date in the time stamp:
@example
(setq rcirc-time-format "%Y-%m-%d %H:%M ")
@end example
@node Defining a new command, Reconnecting after you have lost the connection, Changing the time stamp format, Hacking and Tweaking
@section Defining a new command
@cindex defining commands
@cindex commands, defining
@cindex new commands, defining
Here's a simple new command, @code{/sv}. With it, you can boast about
your IRC client. It shows how you can use @code{defun-rcirc-command} to
define new commands.
We're waiting for the definition of this command until @code{rcirc} is loaded
because @code{defun-rcirc-command} is not yet available, and without
@code{rcirc} loaded, the command wouldn't do us much good anyway.
@smallexample
(eval-after-load 'rcirc
'(defun-rcirc-command sv (arg)
"Boast about rcirc."
(interactive "i")
(rcirc-send-message process target
(concat "I use " rcirc-id-string))))
@end smallexample
@node Reconnecting after you have lost the connection, , Defining a new command, Hacking and Tweaking
@section Reconnecting after you have lost the connection
@cindex reconnecting
@cindex disconnecting servers, reconnecting
If you're chatting from a laptop, then you might be familiar with this
problem: When your laptop falls asleep and wakes up later, your IRC
client doesn't realise that it has been disconnected. It takes several
minutes until the client decides that the connection has in fact been
lost. The simple solution is to use @kbd{M-x rcirc}. The problem is
that this opens an @emph{additional} connection, so you'll have two
copies of every channel buffer --- one dead and one live.
The real answer, therefore, is a @code{/reconnect} command:
@smallexample
(eval-after-load 'rcirc
'(defun-rcirc-command reconnect (arg)
"Reconnect the server process."
(interactive "i")
(unless process
(error "There's no process for this target"))
(let* ((server (car (process-contact process)))
(port (process-contact process :service))
(nick (rcirc-nick process))
channels query-buffers)
(dolist (buf (buffer-list))
(with-current-buffer buf
(when (eq process (rcirc-buffer-process))
(remove-hook 'change-major-mode-hook
'rcirc-change-major-mode-hook)
(if (rcirc-channel-p rcirc-target)
(setq channels (cons rcirc-target channels))
(setq query-buffers (cons buf query-buffers))))))
(delete-process process)
(rcirc-connect server port nick
rcirc-default-user-name
rcirc-default-user-full-name
channels))))
@end smallexample
@node GNU Free Documentation License, Key Index, Hacking and Tweaking, Top
@appendix GNU Free Documentation License
@include doclicense.texi
@node Key Index, Variable Index, GNU Free Documentation License, Top
@unnumbered Key Index
@printindex ky
@node Variable Index, Index, Key Index, Top
@unnumbered Variable Index
@printindex vr
@node Index, , Variable Index, Top
@unnumbered Index
@printindex cp
@bye
@ignore
arch-tag: 2589e562-3843-4ffc-8c2f-477cbad57c01
@end ignore

5898
doc/misc/reftex.texi Normal file
View file

File diff suppressed because it is too large Load diff

2533
doc/misc/sc.texi Normal file
View file

File diff suppressed because it is too large Load diff

982
doc/misc/ses.texi Normal file
View file

@ -0,0 +1,982 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename ../info/ses
@settitle SES: Simple Emacs Spreadsheet
@setchapternewpage off
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@c %**end of header
@copying
This file documents SES: the Simple Emacs Spreadsheet.
Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007
Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* SES: (ses). Simple Emacs Spreadsheet
@end direntry
@finalout
@titlepage
@title SES
@subtitle Simple Emacs Spreadsheet
@author Jonathan A. Yavner
@author @email{jyavner@@member.fsf.org}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@c ===================================================================
@ifnottex
@node Top, Sales Pitch, (dir), (dir)
@comment node-name, next, previous, up
@top SES: Simple Emacs Spreadsheet
@display
SES is a major mode for GNU Emacs to edit spreadsheet files, which
contain a rectangular grid of cells. The cells' values are specified
by formulas that can refer to the values of other cells.
@end display
@end ifnottex
To report bugs, send email to @email{jyavner@@member.fsf.org}.
@menu
* Sales Pitch:: Why use SES?
* The Basics:: Basic spreadsheet commands
* Advanced Features:: Want to know more?
* For Gurus:: Want to know @emph{even more}?
* Index:: Concept, Function and Variable Index
* Acknowledgements:: Acknowledgements
* GNU Free Documentation License:: The license for this documentation.
@end menu
@c ===================================================================
@node Sales Pitch, The Basics, Top, Top
@comment node-name, next, previous, up
@chapter Sales Pitch
@cindex features
@itemize @bullet
@item Create and edit simple spreadsheets with a minimum of fuss.
@item Full undo/redo/autosave.
@item Immune to viruses in spreadsheet files.
@item Cell formulas are straight Emacs Lisp.
@item Printer functions for control of cell appearance.
@item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc.
@item ``Spillover'' of lengthy cell values into following blank cells.
@item Header line shows column letters or a selected row.
@item Completing-read for entering symbols as cell values.
@item Cut, copy, and paste can transfer formulas and printer functions.
@item Import and export of tab-separated values or tab-separated formulas.
@item Plaintext, easily-hacked file format.
@end itemize
@c ===================================================================
@node The Basics, Advanced Features, Sales Pitch, Top
@comment node-name, next, previous, up
@chapter The Basics
@cindex basic commands
@findex ses-jump
@findex ses-mark-row
@findex ses-mark-column
@findex ses-mark-whole-buffer
@findex set-mark-command
@findex keyboard-quit
A @dfn{cell identifier} is a symbol with a column letter and a row
number. Cell B7 is the 2nd column of the 7th row. For very wide
spreadsheets, there are two column letters: cell AB7 is the 28th
column of the 7th row.
@table @kbd
@item j
Moves point to cell, specified by identifier (@code{ses-jump}).
@end table
Point is always at the left edge of a cell, or at the empty endline.
When mark is inactive, the current cell is underlined. When mark is
active, the range is the highlighted rectangle of cells (SES always
uses transient mark mode). Drag the mouse from A1 to A3 to create the
range A1-A2. Many SES commands operate only on single cells, not
ranges.
@table @kbd
@item C-SPC
@itemx C-@@
Set mark at point (@code{set-mark-command}).
@item C-g
Turn off the mark (@code{keyboard-quit}).
@item M-h
Highlight current row (@code{ses-mark-row}).
@item S-M-h
Highlight current column (@code{ses-mark-column}).
@item C-x h
Highlight all cells (@code{mark-whole-buffer}).
@end table
@menu
* Formulas::
* Resizing::
* Printer functions::
* Clearing cells::
* Copy/cut/paste::
* Customizing SES::
@end menu
@node Formulas, Resizing, The Basics, The Basics
@section Cell formulas
@cindex formulas
@cindex formulas, entering
@findex ses-read-cell
@findex ses-read-symbol
@findex ses-edit-cell
@findex ses-recalculate-cell
@findex ses-recalculate-all
To enter a number into the current cell, just start typing:
@table @kbd
@item 0..9
Self-insert a digit (@code{ses-read-cell}).
@item -
Self-insert a negative number (@code{ses-read-cell}).
@item .
Self-insert a fractional number (@code{ses-read-cell}).
@item "
Self-insert a quoted string. The ending double-quote
is inserted for you (@code{ses-read-cell}).
@item (
Self-insert an expression. The right-parenthesis is inserted for you
(@code{ses-read-cell}). To access another cell's value, just use its
identifier in your expression. Whenever the other cell is changed,
this cell's formula will be reevaluated. While typing in the
expression, you can use @kbd{M-@key{TAB}} to complete symbol names.
@item ' @r{(apostrophe)}
Enter a symbol (ses-read-symbol). SES remembers all symbols that have
been used as formulas, so you can type just the beginning of a symbol
and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it.
@end table
To enter something else (e.g., a vector), begin with a digit, then
erase the digit and type whatever you want.
@table @kbd
@item RET
Edit the existing formula in the current cell (@code{ses-edit-cell}).
@item C-c C-c
Force recalculation of the current cell or range (@code{ses-recalculate-cell}).
@item C-c C-l
Recalculate the entire spreadsheet (@code{ses-recalculate-all}).
@end table
@node Resizing, Printer functions, Formulas, The Basics
@section Resizing the spreadsheet
@cindex resizing spreadsheets
@findex ses-insert-row
@findex ses-insert-column
@findex ses-delete-row
@findex ses-delete-column
@findex ses-set-column-width
@findex ses-forward-or-insert
@findex ses-append-row-jump-first-column
Basic commands:
@table @kbd
@item C-o
(@code{ses-insert-row})
@item M-o
(@code{ses-insert-column})
@item C-k
(@code{ses-delete-row})
@item M-k
(@code{ses-delete-column})
@item w
(@code{ses-set-column-width})
@item TAB
Moves point to the next rightward cell, or inserts a new column if
already at last cell on line, or inserts a new row if at endline
(@code{ses-forward-or-insert}).
@item C-j
Linefeed inserts below the current row and moves to column A
(@code{ses-append-row-jump-first-column}).
@end table
Resizing the spreadsheet (unless you're just changing a column width)
relocates all the cell-references in formulas so they still refer to
the same cells. If a formula mentioned B1 and you insert a new first
row, the formula will now mention B2.
If you delete a cell that a formula refers to, the cell-symbol is
deleted from the formula, so @code{(+ A1 B1 C1)} after deleting the third
column becomes @code{(+ A1 B1)}. In case this is not what you wanted:
@table @kbd
@item C-_
@itemx C-x u
Undo previous action (@code{(undo)}).
@end table
@node Printer functions, Clearing cells, Resizing, The Basics
@section Printer functions
@cindex printer functions
@findex ses-read-cell-printer
@findex ses-read-column-printer
@findex ses-read-default-printer
@findex ses-center
@findex ses-center-span
@findex ses-dashfill
@findex ses-dashfill-span
@findex ses-tildefill-span
Printer functions convert binary cell values into the print forms that
Emacs will display on the screen.
A printer can be a format string, like @samp{"$%.2f"}. The result
string is right-aligned within the print cell. To get left-alignment,
use parentheses: @samp{("$%.2f")}. A printer can also be a
one-argument function (a symbol or a lambda), whose result is a string
(right-aligned) or list of one string (left-aligned). While typing in
a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols.
Each cell has a printer. If @code{nil}, the column-printer for the cell's
column is used. If that is also @code{nil}, the default-printer for the
spreadsheet is used.
@table @kbd
@item p
Enter a printer for current cell or range (@code{ses-read-cell-printer}).
@item M-p
Enter a printer for the current column (@code{ses-read-column-printer}).
@item C-c C-p
Enter the default printer for the spreadsheet
(@code{ses-read-default-printer}).
@end table
The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer
history, which is preloaded with the set of all printers used in this
spreadsheet, plus the standard printers.
The standard printers are suitable only for cells, not columns or
default, because they format the value using the column-printer (or
default-printer if @code{nil}) and then center the result:
@table @code
@item ses-center
Just centering.
@item ses-center-span
Centering with spill-over to following blank cells.
@item ses-dashfill
Centering using dashes (-) instead of spaces.
@item ses-dashfill-span
Centering with dashes and spill-over.
@item ses-tildefill-span
Centering with tildes (~) and spill-over.
@end table
@node Clearing cells, Copy/cut/paste, Printer functions, The Basics
@section Clearing cells
@cindex clearing commands
@findex ses-clear-cell-backward
@findex ses-clear-cell-forward
These commands set both formula and printer to @code{nil}:
@table @kbd
@item DEL
Clear cell and move left (@code{ses-clear-cell-backward}).
@item C-d
Clear cell and move right (@code{ses-clear-cell-forward}).
@end table
@node Copy/cut/paste, Customizing SES, Clearing cells, The Basics
@section Copy, cut, and paste
@cindex copy
@cindex cut
@cindex paste
@findex kill-ring-save
@findex mouse-set-region
@findex mouse-set-secondary
@findex ses-kill-override
@findex yank
@findex clipboard-yank
@findex mouse-yank-at-click
@findex mouse-yank-at-secondary
@findex ses-yank-pop
The copy functions work on rectangular regions of cells. You can paste the
copies into non-SES buffers to export the print text.
@table @kbd
@item M-w
@itemx [copy]
@itemx [C-insert]
Copy the highlighted cells to kill ring and primary clipboard
(@code{kill-ring-save}).
@item [drag-mouse-1]
Mark a region and copy it to kill ring and primary clipboard
(@code{mouse-set-region}).
@item [M-drag-mouse-1]
Mark a region and copy it to kill ring and secondary clipboard
(@code{mouse-set-secondary}).
@item C-w
@itemx [cut]
@itemx [S-delete]
The cut functions do not actually delete rows or columns---they copy
and then clear (@code{ses-kill-override}).
@item C-y
@itemx [S-insert]
Paste from kill ring (@code{yank}). The paste functions behave
differently depending on the format of the text being inserted:
@itemize @bullet
@item
When pasting cells that were cut from a SES buffer, the print text is
ignored and only the attached formula and printer are inserted; cell
references in the formula are relocated unless you use @kbd{C-u}.
@item
The pasted text overwrites a rectangle of cells whose top left corner
is the current cell. If part of the rectangle is beyond the edges of
the spreadsheet, you must confirm the increase in spreadsheet size.
@item
Non-SES text is usually inserted as a replacement formula for the
current cell. If the formula would be a symbol, it's treated as a
string unless you use @kbd{C-u}. Pasted formulas with syntax errors
are always treated as strings.
@end itemize
@item [paste]
Paste from primary clipboard or kill ring (@code{clipboard-yank}).
@item [mouse-2]
Set point and paste from primary clipboard (@code{mouse-yank-at-click}).
@item [M-mouse-2]
Set point and paste from secondary clipboard (@code{mouse-yank-secondary}).
@item M-y
Immediately after a paste, you can replace the text with a preceding
element from the kill ring (@code{ses-yank-pop}). Unlike the standard
Emacs yank-pop, the SES version uses @code{undo} to delete the old
yank. This doesn't make any difference?
@end table
@node Customizing SES, , Copy/cut/paste, The Basics
@section Customizing SES
@cindex customizing
@vindex enable-local-eval
@vindex ses-mode-hook
@vindex safe-functions
@vindex enable-local-eval
By default, a newly-created spreadsheet has 1 row and 1 column. The
column width is 7 and the default printer is @samp{"%.7g"}. Each of these
can be customized. Look in group ``ses''.
After entering a cell value, point normally moves right to the next
cell. You can customize @code{ses-after-entry-functions} to move left or
up or down. For diagonal movement, select two functions from the
list.
@code{ses-mode-hook} is a normal mode hook (list of functions to
execute when starting SES mode for a buffer).
The variable @code{safe-functions} is a list of possibly-unsafe
functions to be treated as safe when analysing formulas and printers.
@xref{Virus protection}. Before customizing @code{safe-functions},
think about how much you trust the person who's suggesting this
change. The value @code{t} turns off all anti-virus protection. A
list-of-functions value might enable a ``gee whiz'' spreadsheet, but it
also creates trapdoors in your anti-virus armor. In order for virus
protection to work, you must always press @kbd{n} when presented with
a virus warning, unless you understand what the questionable code is
trying to do. Do not listen to those who tell you to customize
@code{enable-local-eval}---this variable is for people who don't wear
safety belts!
@c ===================================================================
@node Advanced Features, For Gurus, The Basics, Top
@chapter Advanced Features
@cindex advanced features
@findex ses-read-header-row
@table @kbd
@item C-c M-C-h
(@code{ses-set-header-row}). The header line at the top of the SES
window normally shows the column letter for each column. You can set
it to show a copy of some row, such as a row of column titles, so that
row will always be visible. Default is to set the current row as the
header; use C-u to prompt for header row. Set the header to row 0 to
show column letters again.
@item [header-line mouse-3]
Pops up a menu to set the current row as the header, or revert to
column letters.
@end table
@menu
* The print area::
* Ranges in formulas::
* Sorting by column::
* Standard formula functions::
* More on cell printing::
* Import and export::
* Virus protection::
* Spreadsheets with details and summary::
@end menu
@node The print area, Ranges in formulas, Advanced Features, Advanced Features
@section The print area
@cindex print area
@findex widen
@findex ses-renarrow-buffer
@findex ses-reprint-all
A SES file consists of a print area and a data area. Normally the
buffer is narrowed to show only the print area. The print area is
read-only except for special SES commands; it contains cell values
formatted by printer functions. The data area records the formula and
printer functions, etc.
@table @kbd
@item C-x n w
Show print and data areas (@code{widen}).
@item C-c C-n
Show only print area (@code{ses-renarrow-buffer}).
@item S-C-l
@itemx M-C-l
Recreate print area by reevaluating printer functions for all cells
(@code{ses-reprint-all}).
@end table
@node Ranges in formulas, Sorting by column, The print area, Advanced Features
@section Ranges in formulas
@cindex ranges
@findex ses-insert-range-click
@findex ses-insert-range
@findex ses-insert-ses-range-click
@findex ses-insert-ses-range
@vindex from
@vindex to
A formula like
@lisp
(+ A1 A2 A3)
@end lisp
is the sum of three specific cells. If you insert a new second row,
the formula becomes
@lisp
(+ A1 A3 A4)
@end lisp
and the new row is not included in the sum.
The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of
the values in a rectangle of cells. If your formula is
@lisp
(apply '+ (ses-range A1 A3))
@end lisp
and you insert a new second row, it becomes
@lisp
(apply '+ (ses-range A1 A4))
@end lisp
and the new row is included in the sum.
While entering or editing a formula in the minibuffer, you can select
a range in the spreadsheet (using mouse or keyboard), then paste a
representation of that range into your formula. Suppose you select
A1-C1:
@table @kbd
@item [S-mouse-3]
Inserts "A1 B1 C1" @code{(ses-insert-range-click})
@item C-c C-r
Keyboard version (@code{ses-insert-range}).
@item [C-S-mouse-3]
Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}).
@item C-c C-s
Keyboard version (@code{ses-insert-ses-range}).
@end table
If you delete the @var{from} or @var{to} cell for a range, the nearest
still-existing cell is used instead. If you delete the entire range,
the formula relocator will delete the ses-range from the formula.
If you insert a new row just beyond the end of a one-column range, or
a new column just beyond a one-row range, the new cell is included in
the range. New cells inserted just before a range are not included.
@node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features
@section Sorting by column
@cindex sorting
@findex ses-sort-column
@findex ses-sort-column-click
@table @kbd
@item C-c M-C-s
Sort the cells of a range using one of the columns
(@code{ses-sort-column}). The rows (or partial rows if the range
doesn't include all columns) are rearranged so the chosen column will
be in order.
@item [header-line mouse-2]
The easiest way to sort is to click mouse-2 on the chosen column's header row
(@code{ses-sort-column-click}).
@end table
The sort comparison uses @code{string<}, which works well for
right-justified numbers and left-justified strings.
With prefix arg, sort is in descending order.
Rows are moved one at a time, with relocation of formulas. This works
well if formulas refer to other cells in their row, not so well for
formulas that refer to other rows in the range or to cells outside the
range.
@node Standard formula functions, More on cell printing, Sorting by column, Advanced Features
@section Standard formula functions
@cindex standard formula functions
@cindex *skip*
@cindex *error*
@findex ses-delete-blanks
@findex ses-average
@findex ses+
Oftentimes you want a calculation to exclude the blank cells. Here
are some useful functions to call from your formulas:
@table @code
@item (ses-delete-blanks &rest @var{args})
Returns a list from which all blank cells (value is either @code{nil} or
'*skip*) have been deleted.
@item (ses+ &rest @var{args})
Sum of non-blank arguments.
@item (ses-average @var{list})
Average of non-blank elements in @var{list}. Here the list is passed
as a single argument, since you'll probably use it with @code{ses-range}.
@end table
@node More on cell printing, Import and export, Standard formula functions, Advanced Features
@section More on cell printing
@cindex cell printing, more
@findex ses-truncate-cell
@findex ses-recalculate-cell
Special cell values:
@itemize
@item nil prints the same as "", but allows previous cell to spill over.
@item '*skip* replaces nil when the previous cell actually does spill over;
nothing is printed for it.
@item '*error* indicates that the formula signaled an error instead of
producing a value: the print cell is filled with hash marks (#).
@end itemize
If the result from the printer function is too wide for the cell and
the following cell is @code{nil}, the result will spill over into the
following cell. Very wide results can spill over several cells. If
the result is too wide for the available space (up to the end of the
row or the next non-@code{nil} cell), the result is truncated if the cell's
value is a string, or replaced with hash marks otherwise.
SES could get confused by printer results that contain newlines or
tabs, so these are replaced with question marks.
@table @kbd
@item C-c C-t
Confine a cell to its own column (@code{ses-truncate-cell}). This
allows you to move point to a rightward cell that would otherwise be
covered by a spill-over. If you don't change the rightward cell, the
confined cell will spill over again the next time it is reprinted.
@item C-c C-c
When applied to a single cell, this command displays in the echo area any
formula error or printer error that occurred during
recalculation/reprinting (@code{ses-recalculate-cell}).
@end table
When a printer function signals an error, the default printer
@samp{"%s"} is substituted. This is useful when your column printer
is numeric-only and you use a string as a cell value.
@node Import and export, Virus protection, More on cell printing, Advanced Features
@section Import and export
@cindex import and export
@cindex export, and import
@findex ses-export-tsv
@findex ses-export-tsf
@table @kbd
@item x t
Export a range of cells as tab-separated values (@code{ses-export-tsv}).
@item x T
Export a range of cells as tab-separated formulas (@code{ses-export-tsf}).
@end table
The exported text goes to the kill ring --- you can paste it into
another buffer. Columns are separated by tabs, rows by newlines.
To import text, use any of the yank commands where the text to paste
contains tabs and/or newlines. Imported formulas are not relocated.
@node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features
@section Virus protection
@cindex virus protection
Whenever a formula or printer is read from a file or is pasted into
the spreadsheet, it receives a ``needs safety check'' marking. Later,
when the formula or printer is evaluated for the first time, it is
checked for safety using the @code{unsafep} predicate; if found to be
``possibly unsafe'', the questionable formula or printer is displayed
and you must press Y to approve it or N to use a substitute. The
substitute always signals an error.
Formulas or printers that you type in are checked immediately for
safety. If found to be possibly unsafe and you press N to disapprove,
the action is canceled and the old formula or printer will remain.
Besides viruses (which try to copy themselves to other files),
@code{unsafep} can also detect all other kinds of Trojan horses, such as
spreadsheets that delete files, send email, flood Web sites, alter
your Emacs settings, etc.
Generally, spreadsheet formulas and printers are simple things that
don't need to do any fancy computing, so all potentially-dangerous
parts of the Emacs Lisp environment can be excluded without cramping
your style as a formula-writer. See the documentation in @file{unsafep.el}
for more info on how Lisp forms are classified as safe or unsafe.
@node Spreadsheets with details and summary, , Virus protection, Advanced Features
@section Spreadsheets with details and summary
@cindex details and summary
@cindex summary, and details
A common organization for spreadsheets is to have a bunch of ``detail''
rows, each perhaps describing a transaction, and then a set of
``summary'' rows that each show reduced data for some subset of the
details. SES supports this organization via the @code{ses-select}
function.
@table @code
@item (ses-select @var{fromrange} @var{test} @var{torange})
Returns a subset of @var{torange}. For each member in @var{fromrange}
that is equal to @var{test}, the corresponding member of @var{torange}
is included in the result.
@end table
Example of use:
@lisp
(ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5)))
@end lisp
This computes the average of the B column values for those rows whose
A column value is the symbol 'Smith.
Arguably one could specify only @var{fromrange} plus
@var{to-row-offset} and @var{to-column-offset}. The @var{torange} is
stated explicitly to ensure that the formula will be recalculated if
any cell in either range is changed.
File @file{etc/ses-example.el} in the Emacs distribution is an example of a
details-and-summary spreadsheet.
@c ===================================================================
@node For Gurus, Index, Advanced Features, Top
@chapter For Gurus
@cindex advanced features
@menu
* Deferred updates::
* Nonrelocatable references::
* The data area::
* Buffer-local variables in spreadsheets::
* Uses of defadvice in SES::
@end menu
@node Deferred updates, Nonrelocatable references, For Gurus, For Gurus
@section Deferred updates
@cindex deferred updates
@cindex updates, deferred
@vindex run-with-idle-timer
To save time by avoiding redundant computations, cells that need
recalculation due to changes in other cells are added to a set. At
the end of the command, each cell in the set is recalculated once.
This can create a new set of cells that need recalculation. The
process is repeated until either the set is empty or it stops changing
(due to circular references among the cells). In extreme cases, you
might see progress messages of the form ``Recalculating... (@var{nnn}
cells left)''. If you interrupt the calculation using @kbd{C-g}, the
spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or
@kbd{C-c C-l} to fix it.
To save even more time by avoiding redundant writes, cells that have
changes are added to a set instead of being written immediately to the
data area. Each cell in the set is written once, at the end of the
command. If you change vast quantities of cells, you might see a
progress message of the form ``Writing... (@var{nnn} cells left)''.
These deferred cell-writes cannot be interrupted by @kbd{C-g}, so
you'll just have to wait.
SES uses @code{run-with-idle-timer} to move the cell underline when
Emacs will be scrolling the buffer after the end of a command, and
also to narrow and underline after @kbd{C-x C-v}. This is visible as
a momentary glitch after C-x C-v and certain scrolling commands. You
can type ahead without worrying about the glitch.
@node Nonrelocatable references, The data area, Deferred updates, For Gurus
@section Nonrelocatable references
@cindex nonrelocatable references
@cindex references, nonrelocatable
@kbd{C-y} relocates all cell-references in a pasted formula, while
@kbd{C-u C-y} relocates none of the cell-references. What about mixed
cases?
You can use
@lisp
(symbol-value 'B3)
@end lisp
to make an @dfn{absolute reference}. The formula relocator skips over
quoted things, so this will not be relocated when pasted or when
rows/columns are inserted/deleted. However, B3 will not be recorded
as a dependency of this cell, so this cell will not be updated
automatically when B3 is changed.
The variables @code{row} and @code{col} are dynamically bound while a
cell formula is being evaluated. You can use
@lisp
(ses-cell-value row 0)
@end lisp
to get the value from the leftmost column in the current row. This
kind of dependency is also not recorded.
@node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus
@section The data area
@cindex data area
@findex ses-reconstruct-all
Begins with an 014 character, followed by sets of cell-definition
macros for each row, followed by column-widths, column-printers,
default-printer, and header-row. Then there's the global parameters
(file-format ID, numrows, numcols) and the local variables (specifying
SES mode for the buffer, etc.)
When a SES file is loaded, first the numrows and numcols values are
loaded, then the entire data area is @code{eval}ed, and finally the local
variables are processed.
You can edit the data area, but don't insert or delete any newlines
except in the local-variables part, since SES locates things by
counting newlines. Use @kbd{C-x C-e} at the end of a line to install
your edits into the spreadsheet data structures (this does not update
the print area, use e.g. @kbd{C-c C-l} for that).
The data area is maintained as an image of spreadsheet data
structures that area stored in buffer-local variables. If the data
area gets messed up, you can try reconstructing the data area from the
data structures:
@table @kbd
@item C-c M-C-l
(@code{ses-reconstruct-all}).
@end table
@node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus
@section Buffer-local variables in spreadsheets
@cindex buffer-local variables
@cindex variables, buffer-local
You can add additional local variables to the list at the bottom of
the data area, such as hidden constants you want to refer to in your
formulas.
You can override the variable @code{symbolic-formulas} to be a list of
symbols (as parenthesized strings) to show as completions for the '
command. This initial completions list is used instead of the actual
set of symbols-as-formulas in the spreadsheet.
For examples of these, see file @file{etc/ses-example.ses}.
If (for some reason) you want your formulas or printers to save data
into variables, you must declare these variables as buffer-locals in
order to avoid a virus warning.
You can define functions by making them values for the fake local
variable @code{eval}. Such functions can then be used in your
formulas and printers, but usually each @code{eval} is presented to
the user during file loading as a potential virus --- this can get
annoying.
You can define functions in your @file{.emacs} file. Other people can
still read the print area of your spreadsheet, but they won't be able
to recalculate or reprint anything that depends on your functions. To
avoid virus warnings, each function used in a formula needs
@lisp
(put 'your-function-name 'safe-function t)
@end lisp
@node Uses of defadvice in SES, , Buffer-local variables in spreadsheets, For Gurus
@section Uses of defadvice in SES
@cindex defadvice
@cindex undo-more
@cindex copy-region-as-kill
@cindex yank
@table @code
@item undo-more
Defines a new undo element format (@var{fun} . @var{args}), which
means ``undo by applying @var{fun} to @var{args}''. For spreadsheet
buffers, it allows undos in the data area even though that's outside
the narrowing.
@item copy-region-as-kill
When copying from the print area of a spreadsheet, treat the region as
a rectangle and attach each cell's formula and printer as 'ses
properties.
@item yank
When yanking into the print area of a spreadsheet, first try to yank
as cells (if the yank text has 'ses properties), then as tab-separated
formulas, then (if all else fails) as a single formula for the current
cell.
@end table
@c ===================================================================
@node Index, Acknowledgements, For Gurus, Top
@unnumbered Index
@printindex cp
@c ===================================================================
@node Acknowledgements, GNU Free Documentation License, Index, Top
@chapter Acknowledgements
Coding by:
@quotation
Jonathan Yavner @email{jyavner@@member.fsf.org}@*
Stefan Monnier @email{monnier@@gnu.org}
@end quotation
@noindent
Texinfo manual by:
@quotation
Jonathan Yavner @email{jyavner@@member.fsf.org}@*
Brad Collins <brad@@chenla.org>
@end quotation
@noindent
Ideas from:
@quotation
Christoph Conrad @email{christoph.conrad@@gmx.de}@*
CyberBob @email{cyberbob@@redneck.gacracker.org}@*
Syver Enstad @email{syver-en@@online.no}@*
Ami Fischman @email{fischman@@zion.bpnetworks.com}@*
Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@*
Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@*
Yusong Li @email{lyusong@@hotmail.com}@*
Juri Linkov @email{juri@@jurta.org}@*
Harald Maier @email{maierh@@myself.com}@*
Alan Nash @email{anash@@san.rr.com}@*
François Pinard @email{pinard@@iro.umontreal.ca}@*
Pedro Pinto @email{ppinto@@cs.cmu.edu}@*
Stefan Reichör @email{xsteve@@riic.at}@*
Oliver Scholz @email{epameinondas@@gmx.de}@*
Richard M. Stallman @email{rms@@gnu.org}@*
Luc Teirlinck @email{teirllm@@dms.auburn.edu}@*
J. Otto Tennant @email{jotto@@pobox.com}@*
Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr}
@end quotation
@c ===================================================================
@node GNU Free Documentation License, , Acknowledgements, Top
@appendix GNU Free Documentation License
@include doclicense.texi
@bye
@ignore
arch-tag: 10a4ee1c-7ef4-4c06-8b7a-f975e39f0dec
@end ignore

369
doc/misc/sieve.texi Normal file
View file

@ -0,0 +1,369 @@
\input texinfo @c -*-texinfo-*-
@setfilename ../info/sieve
@settitle Emacs Sieve Manual
@synindex fn cp
@synindex vr cp
@synindex pg cp
@copying
This file documents the Emacs Sieve package, for server-side mail filtering.
Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007
Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* Sieve: (sieve). Managing Sieve scripts in Emacs.
@end direntry
@iftex
@finalout
@end iftex
@setchapternewpage odd
@titlepage
@title Emacs Sieve Manual
@author by Simon Josefsson
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@node Top
@top Sieve Support for Emacs
This manual documents the Emacs Sieve package.
It is intended as a users manual for Sieve Mode and Manage Sieve, and
as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp
API.
Sieve is a language for server-side filtering of mail. The language
is documented in RFC 3028. This manual does not attempt to document
the language, so keep RFC 3028 around.
A good online Sieve resources is @uref{http://www.cyrusoft.com/sieve/}.
@menu
* Installation:: Getting ready to use the package.
* Sieve Mode:: Editing Sieve scripts.
* Managing Sieve:: Managing Sieve scripts on a remote server.
* Examples :: A few Sieve code snippets.
* Manage Sieve API :: Interfacing to the Manage Sieve Protocol API.
* Standards:: A summary of RFCs and working documents used.
* GNU Free Documentation License:: The license for this documentation.
* Index:: Function and variable index.
@end menu
@node Installation
@chapter Installation
@cindex Install
@cindex Setup
The Sieve package should come with your Emacs version, and should be
ready for use directly.
However, to manually set up the package you can put the following
commands in your @code{~/.emacs}:
@lisp
(autoload 'sieve-mode "sieve-mode")
@end lisp
@lisp
(setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode)
auto-mode-alist))
@end lisp
@node Sieve Mode
@chapter Sieve Mode
Sieve mode provides syntax-based indentation, font-locking support and
other handy functions to make editing Sieve scripts easier.
Use @samp{M-x sieve-mode} to switch to this major mode. This command
runs the hook @code{sieve-mode-hook}.
@vindex sieve-mode-map
@vindex sieve-mode-syntax-table
Sieve mode is derived from @code{c-mode}, and is very similar except
for the syntax of comments. The keymap (@code{sieve-mode-map}) is
inherited from @code{c-mode}, as are the variables for customizing
indentation. Sieve mode has its own abbrev table
(@code{sieve-mode-abbrev-table}) and syntax table
(@code{sieve-mode-syntax-table}).
In addition to the editing utility functions, Sieve mode also contains
bindings to manage Sieve scripts remotely. @xref{Managing Sieve}.
@table @kbd
@item C-c RET
@kindex C-c RET
@findex sieve-manage
@cindex manage remote sieve script
Open a connection to a remote server using the Managesieve protocol.
@item C-c C-l
@kindex C-c C-l
@findex sieve-upload
@cindex upload sieve script
Upload the Sieve script to the currently open server.
@end table
@node Managing Sieve
@chapter Managing Sieve
Manage Sieve is a special mode used to display Sieve scripts available
on a remote server. It can be invoked with @kbd{M-x sieve-manage
RET}, which queries the user for a server and if necessary, user
credentials to use.
When a server has been successfully contacted, the Manage Sieve buffer
looks something like:
@example
Server : mailserver:2000
2 scripts on server, press RET on a script name edits it, or
press RET on <new script> to create a new script.
<new script>
ACTIVE .sieve
template.siv
@end example
One of the scripts are highlighted, and standard point navigation
commands (@kbd{<up>}, @kbd{<down>} etc) can be used to navigate the
list.
The following commands are available in the Manage Sieve buffer:
@table @kbd
@item m
@kindex m
@findex sieve-activate
Activates the currently highlighted script.
@item u
@kindex u
@findex sieve-deactivate
Deactivates the currently highlighted script.
@item C-M-?
@kindex C-M-?
@findex sieve-deactivate-all
Deactivates all scripts.
@item r
@kindex r
@findex sieve-remove
Remove currently highlighted script.
@item RET
@item mouse-2
@item f
@kindex RET
@kindex mouse-2
@kindex f
@findex sieve-edit-script
Bury the server buffer and download the currently highlighted script
into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).
@item o
@kindex o
@findex sieve-edit-script-other-window
Create a new buffer in another window containing the currently
highlighted script for editing in Sieve mode (@pxref{Sieve Mode}).
@item q
@kindex q
@findex sieve-bury-buffer
Bury the Manage Sieve buffer without closing the connection.
@item ?
@item h
@kindex ?
@kindex h
@findex sieve-help
Displays help in the minibuffer.
@end table
@node Examples
@chapter Examples
If you are not familiar with Sieve, this chapter contains a few simple
code snippets that you can cut'n'paste and modify at will, until you
feel more comfortable with the Sieve language to write the rules from
scratch.
The following complete Sieve script places all messages with a matching
@samp{Sender:} header into the given mailbox. Many mailing lists uses
this format. The first line makes sure your Sieve server understands
the @code{fileinto} command.
@example
require "fileinto";
if address "sender" "owner-w3-beta@@xemacs.org" @{
fileinto "INBOX.w3-beta";
@}
@end example
A few mailing lists do not use the @samp{Sender:} header, but does
contain some unique identifier in some other header. The following is
not a complete script, it assumes that @code{fileinto} has already been
required.
@example
if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
fileinto "INBOX.auc-tex";
@}
@end example
At last, we have the hopeless mailing lists that does not have any
unique identifier and you are forced to match on the @samp{To:} and
@samp{Cc} headers. As before, this snippet assumes that @code{fileinto}
has been required.
@example
if address ["to", "cc"] "kerberos@@mit.edu" @{
fileinto "INBOX.kerberos";
@}
@end example
@node Manage Sieve API
@chapter Manage Sieve API
The @file{sieve-manage.el} library contains low-level functionality
for talking to a server with the @sc{managesieve} protocol.
A number of user-visible variables exist, which all can be customized
in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):
@table @code
@item sieve-manage-default-user
@vindex sieve-manage-default-user
Sets the default username.
@item sieve-manage-default-port
@vindex sieve-manage-default-port
Sets the default port to use, the suggested port number is @code{2000}.
@item sieve-manage-log
@vindex sieve-manage-log
If non-@code{nil}, should be a string naming a buffer where a protocol trace
is dumped (for debugging purposes).
@end table
The API functions include:
@table @code
@item sieve-manage-open
@findex sieve-manage-open
Open connection to managesieve server, returning a buffer to be used
by all other API functions.
@item sieve-manage-opened
@findex sieve-manage-opened
Check if a server is open or not.
@item sieve-manage-close
@findex sieve-manage-close
Close a server connection.
@item sieve-manage-authenticate
@findex sieve-manage-authenticate
Authenticate to the server.
@item sieve-manage-capability
@findex sieve-manage-capability
Return a list of capabilities the server supports.
@item sieve-manage-listscripts
@findex sieve-manage-listscripts
List scripts on the server.
@item sieve-manage-havespace
@findex sieve-manage-havespace
Return non-@code{nil} if the server has room for a script of given
size.
@item sieve-manage-getscript
@findex sieve-manage-getscript
Download script from server.
@item sieve-manage-putscript
@findex sieve-manage-putscript
Upload script to server.
@item sieve-manage-setactive
@findex sieve-manage-setactive
Indicate which script on the server should be active.
@end table
@node Standards
@chapter Standards
The Emacs Sieve package implements all or parts of a small but
hopefully growing number of RFCs and drafts documents. This chapter
lists the relevant ones. They can all be fetched from
@uref{http://quimby.gnus.org/notes/}.
@table @dfn
@item RFC3028
Sieve: A Mail Filtering Language.
@item draft-martin-managesieve-03
A Protocol for Remotely Managing Sieve Scripts
@end table
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi
@node Index
@unnumbered Index
@printindex cp
@summarycontents
@contents
@bye
@c End:
@ignore
arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3
@end ignore

427
doc/misc/smtpmail.texi Normal file
View file

@ -0,0 +1,427 @@
\input texinfo @c -*-texinfo-*-
@setfilename ../info/smtpmail
@settitle Emacs SMTP Library
@syncodeindex vr fn
@copying
Copyright @copyright{} 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''
in the Emacs manual.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* SMTP: (smtpmail). Emacs library for sending mail via SMTP.
@end direntry
@titlepage
@title{Emacs SMTP Library}
@subtitle{An Emacs package for sending mail via SMTP}
@author{Simon Josefsson, Alex Schroeder}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top Emacs SMTP Library
@insertcopying
@end ifnottex
@menu
* How Mail Works:: Brief introduction to mail concepts.
* Emacs Speaks SMTP:: How to use the SMTP library in Emacs.
* Authentication:: Authenticating yourself to the server.
* Queued delivery:: Sending mail without an internet connection.
* Server workarounds:: Mail servers with special requirements.
* Debugging:: Tracking down problems.
* GNU Free Documentation License:: The license for this documentation.
Indices
* Index:: Index over variables and functions.
@end menu
@node How Mail Works
@chapter How Mail Works
@cindex SMTP
@cindex MTA
On the internet, mail is sent from mail host to mail host using the
simple mail transfer protocol (SMTP). To send and receive mail, you
must get it from and send it to a mail host. Every mail host runs a
mail transfer agent (MTA) such as Exim that accepts mails and passes
them on. The communication between a mail host and other clients does
not necessarily involve SMTP, however. Here is short overview of what
is involved.
@cindex MUA
The mail program --- also called a mail user agent (MUA) ---
usually sends outgoing mail to a mail host. When your computer is
permanently connected to the internet, it might even be a mail host
itself. In this case, the MUA will pipe mail to the
@file{/usr/lib/sendmail} application. It will take care of your mail
and pass it on to the next mail host.
@cindex ISP
When you are only connected to the internet from time to time, your
internet service provider (ISP) has probably told you which mail host
to use. You must configure your MUA to use that mail host. Since you
are reading this manual, you probably want to configure Emacs to use
SMTP to send mail to that mail host. More on that in the next
section.
@cindex MDA
Things are different when reading mail. The mail host responsible
for your mail keeps it in a file somewhere. The messages get into the
file by way of a mail delivery agent (MDA) such as procmail. These
delivery agents often allow you to filter and munge your mails before
you get to see it. When your computer is that mail host, this file is
called a spool, and sometimes located in the directory
@file{/var/spool/mail/}. All your MUA has to do is read mail from the
spool, then.
@cindex POP3
@cindex IMAP
When your computer is not always connected to the internet, you
must get the mail from the remote mail host using a protocol such as
POP3 or IMAP. POP3 essentially downloads all your mail from the mail
host to your computer. The mail is stored in some file on your
computer, and again, all your MUA has to do is read mail from the
spool.
When you read mail from various machines, downloading mail from the
mail host to your current machine is not convenient. In that case,
you will probably want to use the IMAP protocol. Your mail is kept on
the mail host, and you can read it while you are connected via IMAP to
the mail host.
@cindex Webmail
So how does reading mail via the web work, you ask. In that case,
the web interface just allows you to remote-control a MUA on the web
host. Whether the web host is also a mail host, and how all the
pieces interact is completely irrelevant. You usually cannot use
Emacs to read mail via the web, unless you use software that parses
the ever-changing HTML of the web interface.
@node Emacs Speaks SMTP
@chapter Emacs Speaks SMTP
Emacs includes a package for sending your mail to a SMTP server and
have it take care of delivering it to the final destination, rather
than letting the MTA on your local system take care of it. This can
be useful if you don't have a MTA set up on your host, or if your
machine is often disconnected from the internet.
Sending mail via SMTP requires configuring your mail user agent
(@pxref{Mail Methods,,,emacs}) to use the SMTP library. How to do
this should be described for each mail user agent; for the default
mail user agent the variable @code{send-mail-function} (@pxref{Mail
Sending,,,emacs}) is used; for the Message and Gnus user agents the
variable @code{message-send-mail-function} (@pxref{Mail
Variables,,,message}) is used.
@example
;; If you use the default mail user agent.
(setq send-mail-function 'smtpmail-send-it)
;; If you use Message or Gnus.
(setq message-send-mail-function 'smtpmail-send-it)
@end example
Before using SMTP you must find out the hostname of the SMTP server
to use. Your system administrator should provide you with this
information, but often it is the same as the server you receive mail
from.
@table @code
@item smtpmail-smtp-server
@vindex smtpmail-smtp-server
@vindex SMTPSERVER
The variable @code{smtpmail-smtp-server} controls the hostname of
the server to use. It is a string with an IP address or hostname. It
defaults to the contents of the @env{SMTPSERVER} environment
variable, or, if empty, the contents of
@code{smtpmail-default-smtp-server}.
@item smtpmail-default-smtp-server
@vindex smtpmail-default-smtp-server
The variable @code{smtpmail-default-smtp-server} controls the
default hostname of the server to use. It is a string with an IP
address or hostname. It must be set before the SMTP library is
loaded. It has no effect if set after the SMTP library has been
loaded, or if @code{smtpmail-smtp-server} is defined. It is usually
set by system administrators in a site wide initialization file.
@end table
The following example illustrates what you could put in
@file{~/.emacs} to set the SMTP server name.
@example
;; Send mail using SMTP via mail.example.org.
(setq smtpmail-smtp-server "mail.example.org")
@end example
@cindex Mail Submission
SMTP is normally used on the registered ``smtp'' TCP service port 25.
Some environments use SMTP in ``Mail Submission'' mode, which uses
port 587. Using other ports is not uncommon, either for security by
obscurity purposes, port forwarding, or otherwise.
@table @code
@item smtpmail-smtp-service
@vindex smtpmail-smtp-service
The variable @code{smtpmail-smtp-service} controls the port on the
server to contact. It is either a string, in which case it will be
translated into an integer using system calls, or an integer.
@end table
The following example illustrates what you could put in
@file{~/.emacs} to set the SMTP service port.
@example
;; Send mail using SMTP on the mail submission port 587.
(setq smtpmail-smtp-service 587)
@end example
@node Authentication
@chapter Authentication
@cindex SASL
@cindex CRAM-MD5
@cindex LOGIN
@cindex STARTTLS
@cindex TLS
@cindex SSL
Many environments require SMTP clients to authenticate themselves
before they are allowed to route mail via a server. The two following
variables contains the authentication information needed for this.
The first variable, @code{smtpmail-auth-credentials}, instructs the
SMTP library to use a SASL authentication step, currently only the
CRAM-MD5 and LOGIN mechanisms are supported and will be selected in
that order if the server support both.
The second variable, @code{smtpmail-starttls-credentials}, instructs
the SMTP library to connect to the server using STARTTLS. This means
the protocol exchange may be integrity protected and confidential by
using the Transport Layer Security (TLS) protocol, and optionally also
authentication of the client and server.
TLS is a security protocol that is also known as SSL, although
strictly speaking, SSL is an older variant of TLS. TLS is backwards
compatible with SSL. In most mundane situations, the two terms are
equivalent.
The TLS feature uses the elisp package @file{starttls.el} (see it for
more information on customization), which in turn require that at
least one of the following external tools are installed:
@enumerate
@item
The GNUTLS command line tool @samp{gnutls-cli}, you can get it from
@url{http://www.gnu.org/software/gnutls/}. This is the recommended
tool, mainly because it can verify the server certificates.
@item
The @samp{starttls} external program, you can get it from
@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}.
@end enumerate
It is not uncommon to use both these mechanisms, e.g., to use STARTTLS
to achieve integrity and confidentiality and then use SASL for client
authentication.
@table @code
@item smtpmail-auth-credentials
@vindex smtpmail-auth-credentials
The variable @code{smtpmail-auth-credentials} contains a list of
hostname, port, username and password tuples. When the SMTP library
connects to a host on a certain port, this variable is searched to
find a matching entry for that hostname and port. If an entry is
found, the authentication process is invoked and the credentials are
used.
The hostname field follows the same format as
@code{smtpmail-smtp-server} (i.e., a string) and the port field the
same format as @code{smtpmail-smtp-service} (i.e., a string or an
integer). The username and password fields, which either can be
@code{nil} to indicate that the user is prompted for the value
interactively, should be strings with the username and password,
respectively, information that is normally provided by system
administrators.
@item smtpmail-starttls-credentials
@vindex smtpmail-starttls-credentials
The variable @code{smtpmail-starttls-credentials} contains a list of
tuples with hostname, port, name of file containing client key, and
name of file containing client certificate. The processing is similar
to the previous variable. The client key and certificate may be
@code{nil} if you do not wish to use client authentication.
@end table
The following example illustrates what you could put in
@file{~/.emacs} to enable both SASL authentication and STARTTLS. The
server name (@code{smtpmail-smtp-server}) is @var{hostname}, the
server port (@code{smtpmail-smtp-service}) is @var{port}, and the
username and password are @var{username} and @var{password}
respectively.
@example
;; Authenticate using this username and password against my server.
(setq smtpmail-auth-credentials
'(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}")))
;; Note that if @var{port} is an integer, you must not quote it as a
;; string. Normally @var{port} should be the integer 25, and the example
;; become:
(setq smtpmail-auth-credentials
'(("@var{hostname}" 25 "@var{username}" "@var{password}")))
;; Use STARTTLS without authentication against the server.
(setq smtpmail-starttls-credentials
'(("@var{hostname}" "@var{port}" nil nil)))
@end example
@node Queued delivery
@chapter Queued delivery
@cindex Dialup connection
If you connect to the internet via a dialup connection, or for some
other reason don't have permanent internet connection, sending mail
will fail when you are not connected. The SMTP library implements
queued delivery, and the following variable control its behavior.
@table @code
@item smtpmail-queue-mail
@vindex smtpmail-queue-mail
The variable @code{smtpmail-queue-mail} controls whether a simple
off line mail sender is active. This variable is a boolean, and
defaults to @code{nil} (disabled). If this is non-@code{nil}, mail is
not sent immediately but rather queued in the directory
@code{smtpmail-queue-dir} and can be later sent manually by invoking
@code{smtpmail-send-queued-mail} (typically when you connect to the
internet).
@item smtpmail-queue-dir
@vindex smtpmail-queue-dir
The variable @code{smtpmail-queue-dir} specifies the name of the
directory to hold queued messages. It defaults to
@file{~/Mail/queued-mail/}.
@end table
@findex smtpmail-send-queued-mail
The function @code{smtpmail-send-queued-mail} can be used to send
any queued mail when @code{smtpmail-queue-mail} is enabled. It is
typically invoked interactively with @kbd{M-x
smtpmail-send-queued-mail RET} when you are connected to the internet.
@node Server workarounds
@chapter Server workarounds
Some SMTP servers have special requirements. The following variables
implement support for common requirements.
@table @code
@item smtpmail-local-domain
@vindex smtpmail-local-domain
The variable @code{smtpmail-local-domain} controls the hostname sent
in the first @code{EHLO} or @code{HELO} command sent to the server.
It should only be set if the @code{system-name} function returns a
name that isn't accepted by the server. Do not set this variable
unless your server complains.
@item smtpmail-sendto-domain
@vindex smtpmail-sendto-domain
The variable @code{smtpmail-sendto-domain} makes the SMTP library
add @samp{@@} and the specified value to recipients specified in the
message when they are sent using the @code{RCPT TO} command. Some
configurations of sendmail requires this behavior. Don't bother to
set this unless you have get an error like:
@example
Sending failed; SMTP protocol error
@end example
when sending mail, and the debug buffer (@pxref{Debugging})) contains
an error such as:
@example
RCPT TO: @var{someone}
501 @var{someone}: recipient address must contain a domain
@end example
@end table
@node Debugging
@chapter Debugging
Sometimes delivery fails, often with the generic error message
@samp{Sending failed; SMTP protocol error}. Enabling one or both of
the following variables and inspecting a trace buffer will often give
clues to the reason for the error.
@table @code
@item smtpmail-debug-info
@vindex smtpmail-debug-info
The variable @code{smtpmail-debug-info} controls whether to print
the SMTP protocol exchange in the minibuffer, and retain the entire
exchange in a buffer @samp{*trace of SMTP session to @var{server}*},
where @var{server} is the name of the mail server to which you send
mail.
@item smtpmail-debug-verb
@vindex smtpmail-debug-verb
The variable @code{smtpmail-debug-verb} controls whether to send the
@code{VERB} token to the server. The @code{VERB} server instructs the
server to be more verbose, and often also to attempt final delivery
while your SMTP session is still running. It is usually only useful
together with @code{smtpmail-debug-info}. Note that this may cause
mail delivery to take considerable time if the final destination
cannot accept mail.
@end table
@node GNU Free Documentation License
@chapter GNU Free Documentation License
@include doclicense.texi
@node Index
@chapter Index
@section Concept Index
@printindex cp
@section Function and Variable Index
@printindex fn
@contents
@bye
@ignore
arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f
@end ignore

1261
doc/misc/speedbar.texi Normal file
View file

File diff suppressed because it is too large Load diff

8662
doc/misc/texinfo.tex Normal file
View file

File diff suppressed because it is too large Load diff

3297
doc/misc/tramp.texi Normal file
View file

File diff suppressed because it is too large Load diff

62
doc/misc/trampver.texi Normal file
View file

@ -0,0 +1,62 @@
@c -*-texinfo-*-
@c texi/trampver.texi. Generated from trampver.texi.in by configure.
@c In the Tramp CVS, the version number is auto-frobbed from
@c configure.ac, so you should edit that file and run
@c "autoconf && ./configure" to change the version number.
@set trampver 2.1.11-pre
@c Other flags from configuration
@set instprefix /usr/local
@set lispdir /usr/local/share/emacs/site-lisp
@set infodir /usr/local/info
@c Formatting of the tramp program name consistent.
@set tramp @sc{tramp}
@c Whether or not describe gateway methods.
@ifclear noemacsgw
@set emacsgw
@end ifclear
@c Some flags which make the text independent on the (X)Emacs flavor.
@c "emacs" resp "xemacs" are set in the Makefile. Default is "emacs".
@ifclear emacs
@ifclear xemacs
@set emacs
@end ifclear
@end ifclear
@c Emacs values.
@ifset emacs
@set emacsname GNU Emacs
@set emacsdir emacs
@set ftppackagename Ange-FTP
@set prefix /
@set prefixhop
@set postfix :
@set postfixhop :
@set emacsothername XEmacs
@set emacsotherdir xemacs
@set emacsotherfilename tramp-xemacs.html
@set japanesemanual tramp_ja-emacs.html
@end ifset
@c XEmacs counterparts.
@ifset xemacs
@set emacsname XEmacs
@set emacsdir xemacs
@set ftppackagename EFS
@set prefix /[
@set prefixhop [
@set postfix ]
@set postfixhop /
@set emacsothername GNU Emacs
@set emacsotherdir emacs
@set emacsotherfilename tramp-emacs.html
@set japanesemanual tramp_ja-xemacs.html
@end ifset
@ignore
arch-tag: e0fe322c-e06b-46eb-bb5b-d091b521f41c
@end ignore

1202
doc/misc/url.texi Normal file
View file

File diff suppressed because it is too large Load diff

1958
doc/misc/vip.texi Normal file
View file

File diff suppressed because it is too large Load diff

4579
doc/misc/viper.texi Normal file
View file

File diff suppressed because it is too large Load diff

1855
doc/misc/widget.texi Normal file
View file

File diff suppressed because it is too large Load diff

1439
doc/misc/woman.texi Normal file
View file

File diff suppressed because it is too large Load diff