1.0 Installation instructions

1.1 Foreword

License: This material may be distributed only subject to
the terms and conditions set forth in GNU General Public
License v2 or later; or, at your option, distributed under the
terms of GNU Free Documentation License version 1.2 or later
(GNU FDL).

Emacs Tiny Tools is a collection of libraries and packages,
which are designed to be OS and X/Emacs platform independent.
E.g. configure load-path automatically, URL handler,
easy-delete, mail complete and many more. This file is
README.txt included in Emacs Tiny Tools kit. It contains
instructions how to install a cross platform Emacs/XEmacs/
Unix/Win32 compatible utilities for wide variety of tasks:
diff/patch; searching, replacing, caching files, automatic
load-path setup and more.

1.2 Unpacking

Extract the package and it will create directory according to
the version number. Under Windows platform: create directories
manually e.g. on C:\home\elisp and use some suitable
archiver program. A Windows
environment variable
HOME must alse be defined to point to suitable location, like
C:\home.

1.4 Advanced install – using tinypath

1.4.1 Personal install using tinypath

The following lines below will configure Emacs to be aware of
all lisp paths under $HOME/elisp or $HOME/lisp, so
whatever magic you used to do to keep your load-path up to
date is no longer needed. The Lisp package path variable
load-path is periodically kept up to date without manual
tweaking.

;; $HOME/.emacs
;; This line loads package "tinypath.el"
(load "~/elisp/packages/tiny-tools/lisp/tiny/tinypath")
;; ... rest of the startup
;; End of example

When the tinypath.el package is active, you can pretty much put
packages or individual lisp files anywhere, provided that they
reside under $HOME/elisp. you can create or delete directories
and move files around to organize your lisp files. The only
restriction is that you do not use any symlinks; not to directories
or not to files (reason is explained in file tinypath.el).
Let's suppose the hierarchy of lisp files look something like this:

Now, perhaps you see an utility.el in gnu.emacs.sources that
you would like to use. How do you install it? Just drop it in,
say, to $HOME/elisp/other/ directory and call M-xtinypath-cache-regenerate. After that Emacs knows the
package in next Emacs sessions. You still have to add relevant
lines to your Emacs startup which make the package active.
Look inside utility.el and its setup instructions, something
like:

(load "utility")
(utility-install) ;; or whatever is needed to activate it

1.4.2 Site wide install using tinypath

If you are administering the current host and you have both
XEmacs and Emacs installations; plus you have lot of extra
Emacs packages that are available form the Net, you need to
tell the different locations where the installed lisp
directories are. In this case, you have to set the
tinypath-:load-path-root. In previous personal installation
example, this was automatically determined.

After the code below, user have access to all packages
installed to your system, no matter where they reside. The
load-path is configured porperly at Emacs startup and you,
the admin, can concentrate on getting your hand on the most
prospective lisp packages. Just drop them anywhere, move them
around, the changes will be noticed automatically.

1.6 Minimal install

If you are tight of space or otherwise do not need all the
tools or if you're only interested in specific package, a
minimum installation is possible. The basic idea is to include
libraries + needed package(s).

1.7 Optional step - compiling files

FIXME: <under construction>

1.8 Submitting bug reports

IT IS IMPORTANT THAT YOU USE NON-COMPILED FILES AND SUBMIT THE
BACKTRACE. Send a bug report by using package's contact
functions. The XXX below refers to the function prefix, like
tinyurl for package tinyurl.el:

M-x load-library RET package.el RET # load non-compiled
M-x turn-on-emacs-debug RET # From tinyliba.el
... repeat what you did until the point of error ...
M-x XXX-submit-bug-report << prefer this if it exists >>
M-x XXX-submit-feedback
... and copy paste any relevant information, like the lisp
... error buffer *Backtrace* that might have been generated.

2.0 Project information

2.1 What does prefix "tiny" mean

The first package made was tinyappend.el, a simple utility to
gather selected areas of text somewhere convenient. Since then the
prefix "tiny" has been preserved in front of every lisp file. The
word has no other meaning.

2.2 Thank you section

The life with Emacs evolved in the direction called "Tiny Tools";
modules that got initially written in the past years starting with
Emacs 18.59 and after that with 19.28. The current code is aimed to
be XEmacs/Emacs Unix/Win32 platform independent. The cross platform
could not be possible without following testers that patiently kept
reporting bugs and making improvement suggestions. Most sincere
thanks to you all.

Henk SPG <tank AT xs4all.nl> who had courage to take early v1.6x
TinyPgp in XEmacs. I got very good feedback and bug tracing
assistance from him.

Samuel Tardieu <sam AT inf.enst.fr> has been a key figure
in testing the PGP interfaces with 2.6.x and 5.x in Unix.

Dan Rich <drich AT cisco.com> who assisted me with solving the
XEmacs 20-21.x incompatibility problems. The correction cycle
rolled out changes that caused rewriting my other packages too.
In addition he suggested many other new features I didn't think
of before. He cleared many problems by talking to XEmacs 20.x
maintainers and if that's not all, he also made sure the
packages worked in VM. I'm very happy that Dan came into
picture.

Sami Khoury <skhoury AT omnisig.com> tried every new tiny tools
release and reported any byte compiler errors with latest Emacs
releases. He also suggested many improvements, many new
features to add and sent patches. Without Sami, I would have
not been able to know how things work in Emacs 20.x and 21.x.
Sami was the ears and eyes in the bleeding edge Emacs
development till the FSF opened their Emacs CVS server.

David x callaway <dxc AT xprt.net> joined the team somewhere 2000-10
and kept asking, suggesting and reporting improvements in rapid
fashion. That's what is needed to make all tools better. Thank
you David, Don't stop bugging the maintainer smile.

Luis Miguel Hernanz Iglesias <luish AT germinus.com> got
interested in 2000-10 and was fascinated with the TinyPath
(new utility) which made Emacs lisp package path configuration
a joy. He joined the development and sent lof of patches and
squeezed many bugs from TinyPath. I'm impressed!

3.0 Further reading – about loading packages

3.1 Dynamic byte compilation note

Please read these instructions with some salt, because the
they may not be 100% accurate for later Emacs versions.
Feel free to suggest corrections to this text.

All the files in Tiny Tools kit turn on the dynamic byte
compilation flag, which appeared in Emacs 19.29 and XEmacs 19.14.
That's something you don't have to worry about, but I think you are
would be interested in hearing, that it has some nice benefits over
the normal compilation. If you say

(require 'tinylibm)

the statement used to mean "load library tinylibm". All functions
were imported into emacs in a whip. But that's different now with
dynamically compiled files. Now it means "load STUBS from library
tinylibm". The STUBS are pointers in a table to all the rest of the
functions in the library. So, the functions are not actually loaded
to your Emacs; neither does your Emacs suffer from sudden memory
bloat.

When the actual function is called, Emacs automatically substitutes
the STUB with the function definition by loading it from the
library. Just that function, not the others. That's the benefit of
the dynamic byte compilation in a nutshell.

By the way, if you happen to need some function from the libraries,
don't do this:

(require 'tinylimt) ;; mail tools

Donotdothis either, if you need something from the main
library:

(require 'tinylib)

The correct way to let your emacs know about all the existing
library functions, is to load the m library. It will define
all the necessary autoloads to rest of the function and you don't
have to worry about the location of a particular function

3.2 Autoloads

When you install packages, try to avoid loading them from your
$HOME/.emacs like this

(require 'tinytab) ;; TAB minor mode

Because it means that the whole package is loaded (or STUBS) if you
do have many require commands, your Emacs startup time grows
proportionally. You hate slow Emacs startup; right? Okay, there is
much better way to load files; called autoload. It means that you
tell Emacs; that "function exists in package xxx". When function or
feature is called (and the autoload triggers), Emacs loads function
from the package. Some day you don't use some feature in your emacs,
sometimes you use, and Emacs grows and loads the packages when you
happen to need them. No need to use require to have it all at once.

Now, if you read carefully the installation section from every
package and prefer copying the autoload setup instead, you will
have the most optimized way to install the package to your .emacs.
If some package doesn't have autoload choice, complain immediately
to the Author. The package writer should have thought the autoload
possibility too. There may also be a note that package can't be
autoloaded, so in that case there is no other possibility that to
require it. For even more slicker and faster Emacs startup
sequence, see package TinyLoad which you can uset to optimise
lisp file loadings even more.

3.3 Customizing packages

Emacs releases come with the package defcustom.el bundled.
If you have limited lisp skills or if you want an easy
interface to packages' variables, then you can customize the
modules. The group is completed when you press tab key:

M-x customize-group RET group RET

This file has been automatically generated from plain text file with
t2html
Last updated: 2008-09-15 15:20