@c -*- mode: texinfo -*-
\input texinfo

@c $Id: emacs-goodies-el.texi,v 1.104 2016/11/06 20:08:20 psg Exp $
@c %**start of header
@setfilename info/emacs-goodies-el
@settitle Emacs-Goodies-el
@documentencoding ISO-8859-1
@c %**end of header

@dircategory Emacs
@direntry
* Emacs-Goodies-el: (emacs-goodies-el). Miscellaneous add-ons for Emacs
@end direntry

@c Version variables.
@set EDITION 40.0
@set UPDATED 31 Jul 2018

@ifinfo
This is Edition @value{EDITION}, last updated @value{UPDATED}, of
@cite{Emacs-Goodies-el}.
@end ifinfo

@titlepage
@title Emacs-Goodies-el: Miscellaneous add-ons for Emacs
@subtitle A manual for what's in this package.
@author Peter S. Galbraith
@end titlepage

@node Top, all, (dir), (dir)
@top The Emacs-Goodies-el Package Setup

This manual describes the Emacs-Goodies-el package and its setup.  A
quick descriptions of elisp files contained in this package can be found
in the file @file{/usr/share/doc/emacs-goodies-el/README.Debian.gz}.

All packaged files are installed, setup and ready to use if they don't
override standard Emacs commands, modes, or settings.

Some extra package installation and setup is done if you customize the
variable @code{emacs-goodies-el-defaults} to t (its aggressive state).
These will override standard Emacs defaults, but in a good
(uncontroversial) way.  The only affected package is currently
@ref{ff-paths}.

To customize setup of all customizable packages on a finer-grain
basis, do:
@example
@kbd{M-x} customize-group @key{RET} emacs-goodies-el @key{RET}
@end example

In the following document, when we speak of customizing a variable, we
mean to use the Emacs custom interface, such as in:
@example
@kbd{M-x} customize-variable @key{RET} some-variable @key{RET}
@end example
When we speak of customizing a group, it's as the example above for the
group @code{emacs-goodies-el}.

The following files are documented so far.  Eventually, all files will
be documented.

@menu
* all::                         Edit all lines matching a given regexp
* dict::                        Emacs interface to dict client
* dir-locals::                  Local variables for a directory tree
* ff-paths::                    Searches certain paths to find files
* muttrc-mode::                 Major mode to edit muttrc under Emacs
* projects::                    Project-based buffer name management
* tld::                         TLD (Top Level Domain) lookup tool
* twiddle::                     Cute mode-line display hack
* xrdb-mode::                   Mode for editing X resource database files

@end menu

This work compiles GPL'ed documentation from the various elisp files
in /usr/share/emacs/site-lisp/emacs-goodies-el/.  As a derived work
from GPL'ed works, this text is also licensed under the GPL V2 (See
/usr/share/common-licenses/GPL-2) and is edited by Peter S. Galbraith
@email{psg@@debian.org}.


@node all, dict, Top, Top
@chapter all - Edit all lines matching a given regexp.

This is an implementation of the xedit @code{all} command for GNU Emacs.

It works mostly like @code{occur} except that changes to the
@code{*All*} buffer are propagated back to the original buffer.

Type @kbd{M-x all} to try it out.

@node dict, dir-locals, all, Top
@chapter dict - Emacs interface to dict client

Removed in emacs-goodies-el V36.0; Use dictionary-el instead.

@node dir-locals, ff-paths, dict, Top
@chapter dir-locals - local variables for a directory tree

It can be useful to specify local variables directory-wide, e.g. to
define CC mode styles consistently.  This library implements such a
scheme, controlled by the global minor mode @code{dir-locals-mode}.

Place a file named @code{.emacs-locals} (or the value of
@code{dir-locals-file-name}) in the directory root.  This should specify
local variables in the usual way.  The values it sets are inherited
when a file in the directory tree is found.  Local variables
specified in the found file override the directory-wide ones.

However, `eval' pseudo-variables specified in the file are
evaluated (assuming `enable-local-eval' is true) _before_ any
directory-wide processing, and they are evaluated in a scratch
buffer, so that they are only useful for side effects on local
variables.  `mode' pseudo-variables which specify minor modes
toggle those modes for files within the directory.  If
.emacs-locals specifies a major mode, it doesn't propagate, but any
local variables and minor modes its hook sets will; thus it should
normally not specify a major mode.  The `coding' pseudo-variable
will not propagate from .emacs-locals.

For example, with dir-locals mode on, placing this in .emacs-locals
at the top-level of the Linux source tree would set the C
indentation style appropriately for files within the tree:

@example
  Local variables:
  c-file-style: "linux"
  End:
@end example

Another possible use is, say, setting change-log parameters in
different trees for which the Emacs 22 development source broke use
of change-log-mode-hook.

@node ff-paths, muttrc-mode, dir-locals, Top
@chapter ff-paths - searches certain paths to find files.

This code allows you to use C-x C-f normally most of the time, except that
if the requested file doesn't exist, it is checked against a list of
patterns for special paths to search for a file of the same name.

@noindent Examples:
@itemize @bullet
 @item a file extension of @file{.bib} will cause to search the path
defined in $BSTINPUTS or $BIBINPUTS for the file you requested.
 @item a file extension of @file{.h} will cause the @file{/usr/include/}
and @file{/usr/local/include/} directory trees to be searched.
 @item a file extension of @file{.sty} causes a search of TEXINPUTS and
of all directories below @file{"/usr/share/texmf/tex/}
 @item a file extension of @file{.el} causes a search of the path set in
the emacs variable @code{load-path}.
 @item If the aboves searches don't return a match, the filename is
searched for using the @file{locate} command (if available on your
system).
 @item gzip-compressed files (@file{.gz}) will also be found by ff-paths
if the package jka-compr is present.  If you use some other package,
simply set the @code{ff-paths-gzipped} variable to t:
@end itemize

If one file is found, or many files of the same name are found, then the
*completions* buffer is displayed with all possibilities, including the
non-existing path you first provided.  Selecting it creates the new
file.

This package runs as a find-file-not-found-hooks hook, and so will
happily live alongside other such file-finding mechanisms (e.g.
PC-look-for-include-file PC-try-load-many-files vc-file-not-found-hook)

The patterns to test against filenames and the associated paths to search
for these files can be modified by the user by editing the variable
@code{ff-paths-list}

I suggest that you use ffap.el by Michelangelo Grigni <mic@@cs.ucsd.edu>,
now part of GNU Emacs.  His package will guess the filename from the
text under the editing point.  It will search for an existing file in
various places before you even get the "File: " prompt.  ff-paths will
provide itself to ffap as an additional tool to locate the file before
you ever see a prompt.  ff-paths behaves slightly differently with ffap
than it does with find-file: if the file path selected under point by
ffap does not exist, it is not shown in the completions buffer along
with existing paths.  If only one existing path is found for said file,
it is placed in the minibuffer at the ffap prompt.  Also, since using
the `locate' command is fairly aggressive, it is not used in the ffap
toolkit.

@noindent Installation:

ff-paths installs itself as a hook in find-file-not-found-hooks for
find-file.  If ffap is installed, ff-paths installs itself as a
toolbox hook in ffap-alist.

To use it, customize the variable @code{ff-paths-install}.

To also enable ffap, customize the variable @code{ff-paths-use-ffap}.

Both of the above are enabled if you customize the variable
@code{emacs-goodies-el-defaults} to t (its aggressive state).

You may alter various settings of @code{ff-paths} using the
customization group @code{ff-paths}.

@node muttrc-mode, projects, ff-paths, Top
@chapter muttrc-mode - Major mode to edit muttrc under Emacs

@noindent Author: Laurent Pelecq <laurent.pelecq@@soleil.org>

This mode first goal is to provide syntax highlighting with
font-lock. The basic fontification appears on strings, comments,
command names and variables. Additional fontification for commands
arguments can be enabled through the customization buffer.

To customize it, execute @command{M-x customize-group RET muttrc RET}

By default, help on command/variable is displayed automatically
while executing a command to modify them. Disable this feature if
you have problems with.

The main commands are:

@table @samp
@item C-x c
muttrc-insert-command
@item C-x s
muttrc-set-variable
@item C-x S
muttrc-unset-variable
@end table

Type @key{C-h m} for all key bindings.

@noindent BUGS:

Multiline commands are not properly handled and can lead to unexpected
result.

@node projects, tld, muttrc-mode, Top
@chapter projects - Project-based buffer name management

@noindent Author: Erik Naggum <erik@@naggum.no>

Managing a large number of buffers that visit files in many directories
(such as both local and remote copies of sources) can be confusing when
there are files with similar or even identical names and the buffers end
up being named foobar.cl<19> or like unintuitiveness.  This package
introduces the concept of PROJECT ROOTS that allow the programmer to
define what looks suspiciously like logical pathname hosts from Common
Lisp and get abbreviated yet meaningful buffer names in the modeline.

Commands include @code{project-add}, which takes a project name and a directory
(which conveniently defaults to the current directory), @code{project-remove}
(which completes on existing projects), and @code{project-list}, which lists the
current projects in a rudimentary table.  @code{project-update-buffer-names} is
called automatically when either @code{project-add} or @code{roject-remove} changes
the project list, but may also be called by the user as a command.

Variables include @code{project-root-alist}, which contains the list of current
projects and their root directories, and two variables that control the
naming of buffers: @code{project-buffer-name-directory-limit}, the uppper limit
on the number of characters in the last few directory elements in the
pathname that makes up the buffer name and
@code{project-buffer-name-directory-prefix}, the string prepended to buffer
names that would be too long.

Internal functions include @code{project-buffer-name}, which computes the
buffer name from the filename argument, @code{project-root-alist}, which
computes a sorted list of projects on their directories and maintains a
cache because this operation is expensive, and a redefinition of the
function @code{create-file-buffer}, which is called to create new file-visiting
buffers.  Note that the latter may still produce ...<n>, if truly
identical buffer names are requested.  This may happen if you call dired
on a filename and then visit the same file.  Use @key{C-x C-v M-p} instead.

This file is modified on Debian by Peter Galbraith. I like the concept
of prefixing certain buffer names with a project name, but not
renaming all unrelated buffers with the full directory path.  This
breaks MH-E mail folder names for example.  So I'm introducing the
variable @code{project-rename-all-buffers} with a default of nil.  You may
customize this to obtain the old behaviour.

@node tld, twiddle, projects, Top
@chapter tld - TLD (Top Level Domain) lookup tool.

@noindent Author: Dave Pearson <davep@@davep.org>

tld.el provides a command for looking up TLDs (Top Level Domain),
either by searching for a specific TLD or by searching country
names.

@noindent One command is provided:

@table @samp
@item tld
Search the TLD list.
@end table

@node twiddle, xrdb-mode, tld, Top
@chapter twiddle - Cute mode-line display hack.

@noindent Author: Noah Friedman <friedman@@splode.com>

Inspired by a similar hack by Jim Blandy <jimb@@cyclic.com>.

There are two user commands of interest: @command{twiddle-start} and
@command{twiddle-compile}:

@table @samp
@item twiddle-start
Start a mode line display hack.
If called interactively with a prefix argument, prompt for the name of
a hack to run.
@item twiddle-compile
Like \\[compile], but run a twiddle hack during compilation.
@end table

If you write new twiddles, try to minimize or avoid consing, since those
functions are called constantly.

@node xrdb-mode,  , twiddle, Top
@chapter xrdb-mode - Mode for editing X resource database files

@noindent Author: Barry A. Warsaw <barry@@python.org>

This file provides a major mode for editing X resource database files
(e.g. .Xdefaults, .Xenvironment, .Xresources).  It includes font-lock
definitions and commands for controlling indentation, re-indenting by
subdivisions, and loading and merging into the the resource database.

The mode should load automatically for appropriate files after having
customized @code{xrdb-mode-setup-auto-mode-alist}, or invoke it
using @command{xrdb-mode}.
