This is patcher.info, produced by makeinfo version 4.6 from
patcher.texi.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Patcher: (patcher). Automatic archive-based projects maintenance.
END-INFO-DIR-ENTRY

   This file contains the documentation for Patcher version 3.7, an
XEmacs package for automating the maintenance of archive-based projects.

   Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 Didier Verna.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License Version 1.2, as
published by the Free Software Foundation; with the Invariant Sections
being just this one, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the file `COPYING.DOC'.


File: patcher.info,  Node: Top,  Next: Copying,  Up: (dir)

Patcher
*******

Patcher is an XEmacs package designed to automate and ease the
maintenance of archive-based projects. It provides assistance in
building, reporting and committing patches, as well as in handling the
corresponding ChangeLog entries, for example by creating skeletons.

   This info file documents Patcher version 3.7.

* Menu:

* Copying::          The GNU General Public License
* Introduction::     What Patcher is all about
* Distribution::     How to obtain and install Patcher
* Requirements::     What you need to get Patcher running
* Quick Start::      For the brave and the impatient
* User Manual::      A step-by-step guide to using Patcher
* Variables Index::
* Functions Index::
* Keystrokes Index::

   Patcher is developed by Didier Verna <didier@xemacs.org>.


File: patcher.info,  Node: Copying,  Next: Introduction,  Prev: Top,  Up: Top

Copying
*******

Patcher is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License version 2, as published by
the Software Foundation.

   Patcher 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, write to the Free Software Foundation,
Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


File: patcher.info,  Node: Introduction,  Next: Distribution,  Prev: Copying,  Up: Top

Introduction
************

When a project becomes important in size, or when the development is
performed cooperatively by several people across the Internet, it is a
common practice to help maintaining it by using a development control
system. Such tools (CVS, PRCS, to name a few) usually work by
maintaining a centralized project archive (also called a repository)
that keeps track of the history of the changes, lets you develop
different "branches" at the same time and perform operations like
merges between these different project branches.

   In such "archive-based" maintenance models, making the project evolve
usually involves repeatedly the same few steps, some of which can be
tedious: you work on your local copy of the project; once you're
satisfied with your changes, you create a patch by diffing your local
copy against the project's archive; then (or progressively), you
construct the ChangeLog entries. Finally, you propose your changes by
sending a mail to the developers list with your patch and the ChangeLog
entries included, hoping that your proposition will be accepted. If
you're one of the maintainers, you will still probably send the message
to the list, simply announcing the modification, and immediately commit
the patch with an informative log message.

   Patcher is an XEmacs package designed to automate this process.
Patcher can't work on the project for you. However, as soon as you give
it some basic knowledge on the project structure and repository, it can
automatically build a patch by comparing your local copy with the
repository, create ChangeLog entries, prepare a mail announcing the
changes, and even commit the patch for you with a informative log
message. All of this is done in just a few keystrokes. Additionally,
Patcher can perform some sanity checks, like verifying that your local
copy is up-to-date, that you did not forget some ChangeLog entries, that
the commit operation went well and so on.

   If you're brave and impatient, and want to start using the basics of
Patcher as soon as possible, see *Note Quick Start::. It is recommended
to read it anyway, since it gives an overview of how Patcher works. If
you know the basics and want a more detailed guide, see *Note User
Manual::.

   Enjoy using Patcher !


File: patcher.info,  Node: Distribution,  Next: Requirements,  Prev: Introduction,  Up: Top

Distribution
************

Patcher is available either as a standalone package, or as part of the
standard `xemacs-devel' XEmacs package.

   You can get `xemacs-devel' in three different ways:
   * You can install `xemacs-devel' from within XEmacs via the package
     user interface (accessible from the `Tools' menu or via `M-x
     list-packages').

   * You can also download the `xemacs-devel-<version>-pkg.tar.gz'
     tarball from `ftp://ftp.xemacs.org/pub/xemacs/packages/', and
     unpack it where you put the other packages.

   * `xemacs-devel' sources are available from the XEmacs CVS
     repository. The module name is `xemacs-devel'. See
     `http://www.xemacs.org/Develop/cvsaccess.html' for more information
     about the XEmacs CVS repository.

   I also provide Patcher as a standalone package. This is mainly for my
personal usage (when developing and debugging new versions) but you
might want to use it if you're not interested in the rest of
`xemacs-devel'. The standalone version of Patcher can be found at
`http://www.lrde.epita.fr/~didier/comp/development/software.php'.  You
will also find different inlined versions of this documentation at that
place.


File: patcher.info,  Node: Requirements,  Next: Quick Start,  Prev: Distribution,  Up: Top

Requirements
************

Patcher currently works only with XEmacs 21.4 or later. I'm not sure it
works with earlier versions of XEmacs, but I'm sure it does *not* work
with GNU Emacs (see below).

   Patcher might also have some other requirements, depending on how
you use it:

   * If you let Patcher create ChangeLogs for you (*note ChangeLogs
     Handling::), you will need the `add-log' library from the
     `xemacs-base' package, version 1.48 or later, installed on your
     system. That's actually the may reason for Patcher not being able
     to run in GNU Emacs, though I have not tried to port it yet.

   * If you want to send mails from Patcher (*note Mail Methods::), you
     will need a mail user agent. Patcher currently supports
     `compose-mail', `sendmail', `message' and `Gnus' natively.


File: patcher.info,  Node: Quick Start,  Next: User Manual,  Prev: Requirements,  Up: Top

Quick Start
***********

In this chapter, we quickly setup the basic Patcher configuration for
hacking on XEmacs. Adapt the example as you wish. Let's make some
assumptions first:

   * You own a computer.

   * You have the `add-log' library from the `xemacs-base' package,
     version 1.48 or later, installed on your system.

   * You're using XEmacs from the CVS repository.

   * Your local copy of the repository is located in
     `/usr/local/src/XEmacs-21.5'.

   * Your local copy of the repository is up-to-date, but you've done
     some hacking in the sources that you'd like to submit.

   * Since you're lazy, you didn't write the ChangeLog entries yet.

* Menu:

* Setting up Patcher::     Making Patcher aware of your project
* Calling Patcher::        Preparing a patch and a message
* Filling the ChangeLogs:: Patcher only creates skeletons
* Filling the Message::    You should insert the ChangeLog entries
* Committing the Patch::   Applying your modifications to the archive
* Sending the Message::    Telling people about your modifications


File: patcher.info,  Node: Setting up Patcher,  Next: Calling Patcher,  Prev: Quick Start,  Up: Quick Start

Setting up Patcher
==================

The first thing to do is to make patcher aware of your "XEmacs" project.
Put this in your `.emacs' file:

     (setq patcher-projects
           '(("XEmacs" "/usr/local/src/XEmacs-21.5"
              :to-address "xemacs-patches@xemacs.org")
             ))

   As you can imagine, `patcher-projects' is a user option in which you
store information about the projects you want to manage with Patcher.
It is actually a list of what's called "project descriptors".  Here's
the meaning of the only project descriptor we have in the example
above: we have a project named "XEmacs", located in
`/usr/local/src/XEmacs-21.5' and for which emails should be sent to
<xemacs-patches@xemacs.org>.

   Note the particular syntax for specifying the mailing address. This
is what's called a "project option". Contrary to the project's name and
directory, which are mandatory and always appear as the first and second
elements of a project descriptor, project options are optional and can
appear in any order.


File: patcher.info,  Node: Calling Patcher,  Next: Filling the ChangeLogs,  Prev: Setting up Patcher,  Up: Quick Start

Calling Patcher
===============

Now you want to build a patch with your changes, and prepare a message
to submit them. The way Patcher works is currently to setup the message
first, and then to control all subsequent operations from there. In
other words, to create a patch, you actually ask Patcher to prepare a
mail. Type this:

     M-x patcher-mail

   First, you're prompted (with completion) for a project name (the
first element of each project descriptor, remember ?). We currently
only have an "XEmacs" project, so hitting `TAB' will directly fill the
minibuffer in with this only choice. Then, you're prompted for a subject
line that will be used in the mail. Say something sensible.

   Three operations are now executed in turn:

  1. Patcher prepares a mail buffer. The message will be sent to the
     address you specified with the `:to-address' project option, and
     the subject line now reads "[PATCH] something sensible".

  2. Patcher now builds the patch. The command used to do this is `cvs
     -q diff -u' (this is also a project option). Upon successful
     completion of this command (we assume that's indeed the case), the
     patch is inserted into the mail buffer. Some information about the
     patch is provided just above it (the command used, the files
     affected and so on).

  3. Finally, Patcher generates ChangeLog skeletons from what it
     understands of the patch. This involves visiting the appropriate
     ChangeLog files, and creating initial entries.


File: patcher.info,  Node: Filling the ChangeLogs,  Next: Filling the Message,  Prev: Calling Patcher,  Up: Quick Start

Filling the ChangeLogs
======================

Patcher has just created initial ChangeLog entries for you. You must now
browse through the ChangeLog file(s) and fill the entries as you see
fit. Once you're done, you can very well save the ChangeLog buffers.
However, don't kill them ! Don't even think about it. Patcher still
needs them. Now, please return to the mail buffer.


File: patcher.info,  Node: Filling the Message,  Next: Committing the Patch,  Prev: Filling the ChangeLogs,  Up: Quick Start

Filling the message
===================

Now that you're satisfied with your ChangeLog entries and you've
returned to the mail buffer, you want to write some explanation text in
the message. I'll let you do that. You also want to insert the ChangeLog
entries corresponding to your patch, since they are usually much more
readable than the patch itself.

   Inserting your ChangeLog entries in the mail buffer is as simple as
typing `C-c C-p i'. This actually calls the function
`patcher-insert-change-logs', which places them just above the patch,
with a short information line (per ChangeLog file) on top.


File: patcher.info,  Node: Committing the Patch,  Next: Sending the Message,  Prev: Filling the Message,  Up: Quick Start

Committing the Patch
====================

If you have commit access to your project, you should read this.
Otherwise, you may directly see *Note Sending the Message::.

   Committing your changes involves three steps: preparing the commit
command, preparing the commit log message, and actually committing the
changes. Although Patcher can do all of this in one shot, it lets you
control each step by default.

   In order to start the commit process, simply type `C-c C-p c'. This
calls the function `patcher-commit-change'. Congratulations. You've
just been transported to a new buffer, the `*Patcher Log Message*'
buffer. This buffer lets you edit the log message that will accompany
your commit. Note that the message is initialized with the subject line
of your mail. This is also a project option.

   Once you're satisfied with the log message, type `C-c C-c'. This
calls the function `patcher-logmsg-commit', which computes the commit
command to use. The command is displayed in a special buffer, the
`*Patcher Commit Command*' buffer. The default commit command is `cvs
commit', which of course is also a project option. Note that Patcher
stores the log message in a temporary file and uses the `-F' `cvs
commit' option. Finally, note that Patcher has automatically appended
the affected ChangeLog files to the commit command.

   At this point, you have the opportunity to abort the commit
operation.  Otherwise, answer positively and the commit will be
executed. If you had not previously saved the ChangeLog files, Patcher
will do it for you just before committing.


File: patcher.info,  Node: Sending the Message,  Prev: Committing the Patch,  Up: Quick Start

Sending the Message
===================

Sending the message has actually nothing to do with Patcher. It depends
on the method you use for sending mails, but will usually be done via a
`C-c C-c' command of some sort. On thing to note however: if you've
committed your changes via Patcher, the message has been slightly
modified: the subject line now reads "[COMMIT] something sensible"
instead of "[PATCH] ...", and a short commit notice has been inserted
just at the beginning of the message's body.

   That's it. That was easy. Congratulations on your first shot at
Patcher, anyway ! Of course, Patcher is much more powerful and
customizable than what has been described in this chapter. For a
complete documentation on how to use and customize Patcher, please
refer to *Note User Manual::.


File: patcher.info,  Node: User Manual,  Next: Variables Index,  Prev: Quick Start,  Up: Top

User Manual
***********

This chapter provides a step-by-step guide to using Patcher. Everything
there is to know about Patcher is here, though the features are
introduced progressively.

   All user options that are going to be presented in this manual can be
found in the `patcher' customization group, or a subgroup of it.

* Menu:

* Project Descriptors::  The project specification mechanism
* Mail Preparation::     Customizing Patcher messages
* Patch Generation::     Specifying how a patch is to be constructed
* ChangeLogs Handling::  How Patcher behaves with respect to ChangeLogs
* Project Check In::     Committing your changes from Patcher
* Mail Sending::         Sending the message and cleaning up the place
* More On Commands::     Error handling and other generalities
* More On Subprojects::  Defining permanent subprojects


File: patcher.info,  Node: Project Descriptors,  Next: Mail Preparation,  Prev: User Manual,  Up: User Manual

Project Descriptors
===================

Projects specifications are stored in `patcher-projects'. This user
option is actually a list of "project descriptors". Each project
descriptor has the following form: `(NAME DIR :OPTION VALUE ...)'

   NAME is a string naming your project, DIR is a string specifying the
directory in which it resides. The remainder of a project descriptor is
a sequence of zero or more option/value pairs, that we call "project
options". All option names start with a colon. The type of a value
depends on the corresponding option. For example, there is a project
option named `:to-address', whose value should be a string giving the
email address to which you want to send Patcher messages.

   When Patcher needs the value for a particular project option, it
looks for it directly in the project descriptor, but also in other
places.  This process is described below.

* Menu:

* Themes::                 Collections of options
* Project inheritance::    Getting options from other projects
* Fallbacks::              Default values for project options
* Retrieval::              The process of getting an option's value
* Inheritance or theme ?:: The proper way to factor out option values


File: patcher.info,  Node: Themes,  Next: Project inheritance,  Up: Project Descriptors

Themes
------

If you have several projects sharing the same option set, you might want
to setup a theme. Themes are named collections of project options.

   Themes are stored in the `patcher-themes' user option. This option
is a list of themes. Each theme has the following form: `(NAME :OPTION
VALUE ...)'.

   NAME is the theme's name (a symbol). The remainder of the list is a
sequence of zero or more option/value pairs, just like in project
descriptors.

   In order to use a theme in a given project, a `:themes' project
option is provided. It is a list of theme names (symbols). Use this
option in your project descriptor, and the project will implicitly
inherit all options from the corresponding theme.

   One important note: as `:themes' is a project option, it can appear
in a theme. In other words, themes can inherit from other themes. When
Patcher tries to retrieve an option, the themes tree is traversed in
depth first.

   Because themes can contain themes, a bogus setting might lead to an
infinite loop (a cycle in a theme graph). To prevent this, the
`patcher-max-theme-depth' user option is provided. It represents the
expected maximum theme nesting level, and defaults to 8.


File: patcher.info,  Node: Project inheritance,  Next: Fallbacks,  Prev: Themes,  Up: Project Descriptors

Project inheritance
-------------------

When two projects are very similar, you might want to use the project
inheritance mechanism described below.

   There is a special project option called `:inheritance'. This option
must be a list of project names (strings). The inheritance of a project
defines a list of projects from which to inherit options.

   One important note: inherited projects might have their own
`:inheritance' option set to other projects in turn. In other words,
the project inheritance can be more than one level deep. When Patcher
tries to retrieve an option, the inheritance tree is traversed in depth
first.

   Because inherited projects can inherit from projects, a bogus setting
might lead to an infinite loop (a cycle in a project graph). To prevent
this, the `patcher-max-inheritance-depth' user option is provided.  It
represents the expected maximum project inheritance level, and defaults
to 8.

   The `:inheritance' project option is somewhat special in the sense
that it can't appear in a theme. We will encounter other exceptions
later in this manual.


File: patcher.info,  Node: Fallbacks,  Next: Retrieval,  Prev: Project inheritance,  Up: Project Descriptors

Fallbacks
---------

For each existing project option, Patcher also has a "fallback" user
option with a default value that would be shared among all (or some of)
your projects. The name of the fallback is obtained by replacing the
colon in the project option's name with the prefix `patcher-default-'.
For example, the fallback corresponding to the `:to-address' project
option is named `patcher-default-to-address'.

   The `:inheritance' project option is also special in the sense that
it doesn't have a corresponding fallback. We will encounter other
exceptions later in this manual.

   In the remainder of this manual, we will rarely mention the fallbacks
again. When we introduce a new project option, just remember that it
always has a corresponding fallback (well, not always, as you just
discovered).


File: patcher.info,  Node: Retrieval,  Next: Inheritance or theme ?,  Prev: Fallbacks,  Up: Project Descriptors

Retrieval
---------

When Patcher needs the value of a particular project option, it looks
for it in the following manner:

   * First, it looks directly in the project descriptor to see if the
     option is given.

   * If that fails, it next tries the given themes, if any. This
     involves recursively traversing the project's themes tree. Options
     successfully retrieved in themes are said to be "themed".

   * If that still fails, it then tries the inherited projects, if any.
     This involves recursively traversing the project's inheritance
     tree. Options successfully retrieved in inherited projects are
     said to be "inherited". Note that in turn, such options could have
     been actually themed in the inherited project.

   * If that fails again, it finally falls back to the value given in
     the corresponding fallback (if it exists). In such a case, the
     option is said to be "fallbacked".

   Note that a value of `nil' for a project option *is an actual
value*. It is not equivalent to an option being unset. As a
consequence, if Patcher finds a project option with a value of `nil'
somewhere, it will use it and stop the search, even if a non nil value
could be retrieved later from a theme, an inherited project or a
fallback. This provides you with a way to annihilate themed, inherited
or fallbacked options.


File: patcher.info,  Node: Inheritance or theme ?,  Prev: Retrieval,  Up: Project Descriptors

Inheritance or theme ?
----------------------

At that point, you might be wondering why the themes and inheritance
concepts were both designed, since they actually perform very similar
tasks. Good question. Here is a good answer.

   Projects might share options for different reasons. For example, my
"XEmacs" (source) and "XEmacs Packages" projects share many options
(`To:' address, `From:' address, diff and commit commands and so on)
because they both relate to XEmacs. On the other hand I have personal
but totally unrelated projects that share the same commands because
they are all handled through a local PRCS archive.

   In other words, you should rather use the inheritance mechanism when
projects relate to each other, and the theme mechanism for settings that
are orthogonal the projects they apply to.


File: patcher.info,  Node: Mail Preparation,  Next: Patch Generation,  Prev: Project Descriptors,  Up: User Manual

Mail Preparation
================

Patcher currently uses the mail buffers as "master" buffers for
controlling all operations: building a patch, creating the ChangeLog
entries, committing... all is done from the mail buffer.

   To start using Patcher on a certain project, you call the function
`patcher-mail'. This function will interactively prompt you for the
name of the project and for a (mail) subject line. Patcher starts
working on the project (by first creating the patch) after the message
is prepared. Because of this, we'll start by reviewing the mail-related
customizations you might want to setup.

* Menu:

* Mail Methods::          Using a particular mailer
* Message Customization:: Specifying initial contents for messages


File: patcher.info,  Node: Mail Methods,  Next: Message Customization,  Prev: Mail Preparation,  Up: Mail Preparation

Mail Methods
------------

Since there are different mail packages working in XEmacs, Patcher
supports different methods for preparing messages. You can specify the
method you prefer in the `:mail-method' project option. The value must
be a symbol.

* Menu:

* Standard Mail Methods:: Patcher supports standard mail packages
* Fake Mail Method::      Patcher supports not sending mails
* Other Mail Methods::    Patcher supports everything


File: patcher.info,  Node: Standard Mail Methods,  Next: Fake Mail Method,  Prev: Mail Methods,  Up: Mail Methods

Standard Mail Methods
.....................

`compose-mail'
     This is the default. It is implemented via the function
     `patcher-mail-compose-mail' which calls `compose-mail' to prepare
     the message. If you are not familiar with `compose-mail', you
     might also want to throw an eye to the user option
     `mail-user-agent'. If your project does not specify an address to
     send the message to (*note Message Customization::), it is
     prompted for.

`sendmail'
     A direct interface to the `mail' function from the `sendmail'
     package. It is implemented via the function
     `patcher-mail-sendmail'. If your project does not specify an
     address to send the message to (*note Message Customization::), it
     is prompted for.

`message'
     A direct interface to the `message-mail' function from the
     `message' library (it is part of `Gnus'). It is implemented via
     the function `patcher-mail-message'. If your project does not
     specify an address to send the message to (*note Message
     Customization::), it is prompted for.

`gnus'
     A direct interface to the `gnus-post-news' function from the
     `Gnus' package (it can also send mails...). It is implemented via
     the function `patcher-mail-gnus'. This mail method is interesting
     when you maintain a special mail group for messages that you send
     with Patcher, most probably because they are sent to some
     mailing-list, such as <xemacs-patches@xemacs.org>.

     This method uses a Gnus group name and acts as if you had type `C-u
     a' on that group in the `*Group*' buffer, hence honoring the group
     parameters and posting-styles. If your project does not specify a
     Gnus group name (*note Message Customization::), it is prompted
     for.

   This last mail method is special in the sense that it requires a
running Gnus session to work. If that's needed, Patcher can start Gnus
for you in several ways, according to the following user options:

`patcher-mail-run-gnus'
     If `nil', Patcher will never start Gnus and abort the operation
     instead. If `t', Patcher will always start Gnus when needed. If
     `'prompt', Patcher will ask you what (you want) to do. This is the
     default behavior.

`patcher-mail-run-gnus-other-frame'
     Used when Patcher has to start Gnus by itself. If `nil', continue
     using the current frame. If `t', start Gnus in another frame (this
     is the default). If `'follow', start Gnus in another frame, and use
     this new frame to prepare the Patcher mail.


File: patcher.info,  Node: Fake Mail Method,  Next: Other Mail Methods,  Prev: Standard Mail Methods,  Up: Mail Methods

Fake Mail Method
................

At that point, you might be wondering why the mail method is a project
option and not simply a user option, since you probably only use one
mail agent at all. Right. But you might one day work on projects for
which you don't need to send messages at all. This could happen if you
start using Patcher on a project of your own for instance. For that
reason, there is a `fake' mail method available. It is implemented via
the `patcher-mail-fake' function and calls no particular mail user
agent. Once you type `C-c C-c' to virtually send the fake message, it
only performs some cleanup.

   All right. But did we really need this fake method ? I mean, one
could use the usual mail method, and simply not send the message in the
end.  Huh, yeah, ok... Actually, it is very probable that in a future
release of Patcher, the mail buffer won't be the master buffer anymore,
and mail sending will be just another optional step in the process. In
that case, the mail method is likely to move away from project option
to standard user option.


File: patcher.info,  Node: Other Mail Methods,  Prev: Fake Mail Method,  Up: Mail Methods

Other Mail Methods
..................

If you're not satisfied with the provided mail methods (but really, you
should; or, give me a `vm' one), you can provide your own. Here's what
to do: set your `:mail-method' project option to, say, `foo', and write
your own function which must be named `patcher-mail-foo'.

   This function must take two arguments (a project descriptor and a
string containing the subject of the message), and prepare a mail
buffer. If you want to do this, you should see how it's done for the
built-in methods.


File: patcher.info,  Node: Message Customization,  Prev: Mail Methods,  Up: Mail Preparation

Message Customization
---------------------

When preparing a message, Patcher can fill some parts of it for you.
Here's a list of mail-related project options.

`:user-name'
     The name (your name) to use when composing the message. It will
     affect the `From:' header. This option is used by all mail methods
     but `fake'. If not given, `user-full-name' is used.

`:user-mail'
     The mail (your mail) address to use when composing the message. It
     will affect the `From:' header. This option is used by all mail
     methods but `fake'. If not given, `user-mail-address' is used.

`:to-address'
     The address to send messages to (a string). This option is used by
     all mail methods but `gnus' and `fake'. If not given, it is
     prompted for when calling `patcher-mail'.

`:gnus-group'
     The Gnus group name to use for posting messages (a string). This
     option is used only by the `gnus' mail method. If not given, it is
     prompted for when calling `patcher-mail'.

     Note that if you configured your name and mail in Gnus, for
     instance through posting styles, these configurations take
     precedence over the corresponding Patcher options.

`:subject-prefix'
     A prefix for the subject line of messages. It can be `nil' or a
     string. By default, "[PATCH]" is used. This part of subjects is
     never prompted for. A `%n' occurring in this string will be
     replaced with the project name. Also, a space is inserted between
     the prefix and the remainder of the subject, when appropriate.

`:subject'
     A default value for prompted subjects (a string). A `%n' occurring
     in this string will be replaced with the project's name (*note
     Subproject Naming::). Please note that this is used *only* to
     provide a default value for prompted subjects. Subjects are
     *always* prompted for.

`:mail-prologue'
     A prologue to insert just at the top of a message body (a string).


File: patcher.info,  Node: Patch Generation,  Next: ChangeLogs Handling,  Prev: Mail Preparation,  Up: User Manual

Patch Generation
================

Patcher creates patches by diffing your local copy of the project
against the repository. This is done automatically after preparing a
message, so you shouldn't normally bother to do it manually. That
situation might still happen from time to time, like, if you further
modify the sources, or if the initial operation failed for some reason
(*note More On Commands::).

   The way to (re)generate the patch manually is to call
`patcher-generate-diff' from the mail buffer. This function is bound to
`C-c C-p d' in this buffer. You can both customize the diff command
used to (re)generate the patch, and restrict the diff to a subset of
the project's files.

   When possible, Patcher also tries to check that your project is
up-to-date with respect to the archive, and will inform you otherwise.

* Menu:

* Diff Command::        Specifying the command to generate the patch
* After Diff Hook::     Tweaking the diff output
* Diff Line Filter::    Omitting lines from the diff output
* Patch Restriction::   Specifying the files affected by the patch
* Patcher Instances::   You can have several instances of Patcher
* Diff Prologue::       A header is inserted above the patch

   By the way, (re)generating the patch does not necessarily mean that
it is directly inserted into the mail buffer. This also depends on the
ChangeLogs behavior (*note ChangeLogs Handling::).


File: patcher.info,  Node: Diff Command,  Next: After Diff Hook,  Prev: Patch Generation,  Up: Patch Generation

Diff Command
------------

The diff command used to generate the patch is specified by the
`:diff-command' project option. By default, the command used is `cvs -q
diff -u'. You can also punctually change this command by calling
`patcher-mail' or `patcher-generate-diff' with a prefix argument.
Patcher will then prompt you for a new command and use it exclusively
for this particular patch.

   For detail about the format of this option, see *Note Patch
Restriction::.  See also *Note More On Commands::.


File: patcher.info,  Node: After Diff Hook,  Next: Diff Line Filter,  Prev: Diff Command,  Up: Patch Generation

After Diff Hook
---------------

Sometimes, you might want to tweak a little the diff output before doing
anything with it, for instance, before generating ChangeLog skeletons
(*note ChangeLogs Handling::), or simply inserting it into the mail
buffer.

   In order to do that, you might want to use the `:after-diff-hook'
project option. It should be a list of function names (symbols) that
will be called after each diff output. Each function should take two
optional arguments delimiting a region to process (no arguments means
process the whole buffer) and work in the current buffer. The point is
originally placed at the beginning of the region, and the buffer
excursion is saved for you.

   Note: Patcher provides a special function named
`patcher-prcs-diff-convert' that can be used in this hook in order to
convert PRCS diff output to a traditional one.


File: patcher.info,  Node: Diff Line Filter,  Next: Patch Restriction,  Prev: After Diff Hook,  Up: Patch Generation

Diff Line Filter
----------------

When generating a global diff, that is, without specifying the files
affected by the patch explicitly (*note Patch Restriction::), some
uninformative lines might be present in the output. A typical example is
files present in your local copy but unknown to the CVS server. Such
files are indicated by a question mark in diff outputs.

   Patcher has a project option named `:diff-line-filter' that lets
filter out such unwanted lines when inserting the diff in the mail
buffer. This must be a regular expression matching a whole line. Caution
however: do not put beginning or end of lines markers in your regexp.
Patcher will do it for you.

   By default, the value is `"\\? .*"', which excludes files unknown to
the CVS server.


File: patcher.info,  Node: Patch Restriction,  Next: Patcher Instances,  Prev: Diff Line Filter,  Up: Patch Generation

Patch Restriction
-----------------

Sometimes, you don't want to generate a global patch, but instead work
on a subset of the project's files. Patcher understands this concept as
working on a "subproject".

   Instead of calling `patcher-mail', you rather call
`patcher-mail-subproject'. This function behaves exactly like the
former, except that it will also prompt you for the files affected by
the patch. You can specify files as well as directories, use wildcards,
just as you would construct a command line diff.

   Two important things are to be kept in mind when working on
subprojects:
   * It is not necessary (it is even forbidden) to specify the ChangeLog
     files. Patcher will automatically find them for you. In other
     words, only specify source files, not ChangeLog files.

   * Don't mistake the prefix argument of `patcher-mail',
     `patcher-mail-subproject' and `patcher-generate-diff' as a way to
     specify files. It is not meant for that. It is meant only to
     temporarily modify the diff command itself, not the files to which
     it applies.

   When working on a subproject, Patcher uses the same diff command as
the one used for the whole project, that is, the value of the
`:diff-command' project option. In the case of a subproject however,
Patcher has to know where to put the files on the command line (even if
it's usually the last part of it). This is done with the special
construct `%f': a `%f' appearing in the diff command will be replaced
with the specified files (and the computed ChangeLog files) for a
subproject, and will simply be removed when working on the whole
project.

   As an example, given that the default diff command used by Patcher is
`cvs -q diff -u', you should know understand that the default value for
`patcher-default-diff-command' is `cvs -q diff -u %f'. Do you ?

   There is another special construct available in this command: a `%n'
will be replaced with the project's name (*note Subproject Naming::).
This is useful in commands with weird options syntax, like PRCS.

   For a more advanced way of handling subprojects, see *Note More On
Subprojects::.


File: patcher.info,  Node: Patcher Instances,  Next: Diff Prologue,  Prev: Patch Restriction,  Up: Patch Generation

Patcher Instances
-----------------

The concept of subprojects brings up the question of having Patcher
working on different patches at the same time. It is possible under some
conditions:

   * You can have as many simultaneous Patcher instances as you want on
     different projects (you would not define two projects sharing the
     same directory, would you ?).

   * You can have as many simultaneous Patcher instances as you want on
     the same project, as long as there is no overlapping between each
     subproject. This means that you can't have source files, or even
     ChangeLog files in common.

   This last point will be subject to improvements in the future.


File: patcher.info,  Node: Diff Prologue,  Prev: Patcher Instances,  Up: Patch Generation

Diff Prologue
-------------

Patcher can (and does) insert a special prologue just above a patch in
the message in preparation. This prologue gives information such as the
diff command used, the files affected and so on.

   The function used to generate this prologue can be specified with the
`:diff-prologue-function' project option. A value of `nil' means don't
insert any prologue. By default, the internal function
`patcher-default-diff-prologue' is used. If you want to provide your
own, here how to do it.

   Your function should take one argument indicating the kind of diff (a
symbol), and perform insertion at current point in the current buffer.
The possible values for the argument are:

`sources'
     indicates a source diff only,

`change-logs'
     indicates a ChangeLog diff only,

`mixed'
     indicates a diff on both source and ChangeLog files.

   The following variables are bound (when appropriate) when this
function is executed:

`name'
     the name of the current Patcher project,

`source-diff'
     the command used to create a source diff,

`change-log-diff'
     the command used to create a ChangeLog diff,

`source-files'
     sources files affected by the current patch,

`change-log-files'
     ChangeLog files affected by the current patch.

   In the case of a mixed diff, a `nil' value for `change-log-diff'
indicates that the same command was used for both the source and
ChangeLog files.


File: patcher.info,  Node: ChangeLogs Handling,  Next: Project Check In,  Prev: Patch Generation,  Up: User Manual

ChangeLogs Handling
===================

ChangeLogs management in Patcher involves two aspects: how ChangeLog
entries are created, and how they appear in the messages. Both aspects
can be customized beyond your craziest dreams.

* Menu:

* ChangeLogs Updating::   How Patcher deals with ChangeLogs
* ChangeLogs Appearance:: How ChangeLogs appear in messages
* ChangeLogs Prologue::   A header is inserted above the ChangeLogs


File: patcher.info,  Node: ChangeLogs Updating,  Next: ChangeLogs Appearance,  Prev: ChangeLogs Handling,  Up: ChangeLogs Handling

ChangeLogs Action
-----------------

The way Patcher deals with ChangeLogs is controlled via the
`:change-logs-updating' project option. Its value must be a symbol from
the following:

`automatic'
     This is the default. Each time you (re)generate a diff, Patcher
     (re)creates ChangeLog skeletons in the appropriate ChangeLog
     files, by analyzing the generated diff. You then have to fill the
     entries manually.  *Caution*: the diff analysis is not done by
     Patcher directly, but by the function `patch-to-change-log' from
     the `add-log' library from the `xemacs-base' package. Only
     standard diff and cvs diff output are currently supported, both in
     unified format only.

`manual'
     Patcher assumes that you create ChangeLog entries manually, as you
     write code, so it won't create ChangeLogs skeletons. It is
     important to understand that in this situation, ChangeLog entries
     *must* have been written *before* you call Patcher. Patcher won't
     let you write them in the process.

`none'
     The project doesn't have ChangeLog files. Patcher won't try to
     create ChangeLog entries, and won't expect that you have written
     some either.

   If you're working in `automatic' updating mode, Patcher has two
other project options that give you some control on the created entries:
`:change-logs-user-name' and `:change-logs-user-mail'. As you might
expect, these are strings defining your name and mail address for
ChangeLog entries'headers. When `nil', Patcher lets the function
`patch-to-change-log' decide what to use (most probably what the user
options `user-full-name' and `user-mail-address' say).

   Here's a last point to mention about the `automatic' updating mode.
In order to build the ChangeLog skeletons, the source files must be
visited. Patcher has a `:kill-source-files-after-diffing' project
option that lets you decide whether you want to kill the source buffers
just after diffing or not. The value can be either `nil' or `t'. By
default, the behavior is to preserve the source files, since you might
need them for reference when filling the ChangeLog entries.

   If you're working in `manual' updating mode, Patcher might still
need to know the affected ChangeLog files (for the commit process) and
your exact ChangeLog entries in each of these files (for insertion in
the message). The ChangeLog files are automatically deduced from the
patch. When that's required, however, you will be presented with each
ChangeLog file in turn, and invited to precise the number of ChangeLog
entries concerning this patch. These entries must of course appear at
the top of the file.

   Finally, note that an updating mode of `none' is the only case where
ChangeLog files are regarded as normal ones if present. As a
consequence, that is a case where it is not forbidden to list them
explicitly as part of a subproject (*note Patch Restriction::),
although I don't see why you would want to do that.


File: patcher.info,  Node: ChangeLogs Appearance,  Next: ChangeLogs Prologue,  Prev: ChangeLogs Updating,  Up: ChangeLogs Handling

ChangeLogs Appearance
---------------------

When Patcher has to deal with ChangeLog files, you insert ChangeLog
entries in the message buffer by calling the function
`patcher-insert-change-logs'. It is bound to `C-c C-p i' in the mail
buffer. Note that if ChangeLogs are written in advance, you don't have
to do that, as Patcher will do it automatically. You have to call this
function by hand only in `automatic' updating mode (*note ChangeLogs
Updating::).

   In all circumstances however, you can use this function to
*reinsert* the ChangeLog entries into the mail buffer. That might come
in handy if you further modified them after the initial insertion (it's
never too late to fix a typo).

   The appearance of ChangeLog entries in the message is controlled by
the `:change-logs-appearance' project option. Its value must be a
symbol from the following:

`verbatim'
     This is the default. ChangeLog entries appear just as text in the
     message, above the patch. Most people prefer this kind of
     appearance since it is the most readable.

`packed'
     ChangeLog entries appear as a patch (they are diff'ed against the
     archive). This patch is however distinct from the source patch, and
     appears above it.

`patch'
     ChangeLog entries appear as a patch (they are diff'ed against the
     archive), and this patch is integrated into the source patch. In
     other words, the message looks like a global patch integrating
     both the sources and the ChangeLogs.

   When the ChangeLogs appearance is either `packed' or `patch', the
diff command used to generate the patch is controlled by the
`:change-logs-diff-command' project option. The value can be the symbol
`diff', meaning that the same diff command is to be used as for the
sources (*note Diff Command::), or it can be a string specifying an
alternate command.

   When diffing ChangeLog files, it is strongly recommended that you
remove contexts from the diff, because otherwise, ChangeLog patches
often fail to apply correctly.

   As in the case of the `:diff-command' project option (*note Patch
Restriction::), a `%f' serves to indicate where to put the ChangeLog
files on the diff command line, and a `%n' is replaced with the
project's name (*note Subproject Naming::). See also *Note More On
Commands::.

   Given these two remarks, you should now understand why the default
value for `patcher-default-change-logs-diff-command' is `cvs -q diff -U
0 %f'.


File: patcher.info,  Node: ChangeLogs Prologue,  Prev: ChangeLogs Appearance,  Up: ChangeLogs Handling

ChangeLogs Prologue
-------------------

ChangeLog prologues are small pieces of informative text that Patcher
adds above each ChangeLog insertion in the mail buffer.

   When the ChangeLogs appearance is `verbatim', Patcher inserts one
prologue per ChangeLog file. The prologue's contents is controlled by
the `:change-logs-prologue' project option (a string). A `%f' appearing
in this string will be replaced with the ChangeLog filename.  The
default value for `patcher-default-change-logs-prologue' is `"%f
addition:"'.

   When the ChangeLogs appearance is `packed', Patcher inserts only one
prologue for the whole ChangeLogs patch. When `patch', there is a
single prologue for both the ChangeLogs and the sources. For
customizing the prologue in both of these cases, see *Note Diff
Prologue::.


File: patcher.info,  Node: Project Check In,  Next: Mail Sending,  Prev: ChangeLogs Handling,  Up: User Manual

Project Check In
================

If you have the privilege to commit your changes yourself, you might do
so directly from the mail buffer, as the last operation before actually
sending the message. This is done by calling the function
`patcher-commit-change' which is bound to `C-c C-p c' in the mail
buffer.

   Committing directly from Patcher has the advantage that both the
commit command line and the commit log message (*note Log Message
Handling::) are constructed automatically. Of course, you still have an
in-depth control on the commit process.

* Menu:

* Commit Command::       Specifying the command to commit the patch
* Log Message Handling:: Building a commit log message
* Commit Operation::     Actually committing your changes


File: patcher.info,  Node: Commit Command,  Next: Log Message Handling,  Prev: Project Check In,  Up: Project Check In

Commit Command
--------------

The command used to to commit a patch is specified by the
`:commit-command' project option (a string). You can also temporarily
change the command in question by calling `patcher-commit-change' with
a prefix argument. As usual, note that this prefix argument is not
meant to modify the affected files on the command line. It's meant only
to punctually modify the commit command itself. The affected files are
computed automatically by Patcher.

   The commit command accepts (and maybe requires) special constructs:

   * A `%n' occurring in the string will be replaced with the project's
     name (*note Subproject Naming::).

   * A `%f' occurring in the string will be replaced with the files
     affected by the patch (ChangeLogs included, this time), or
     discarded if the patch is global.

   * A `%s' occurring in the string will be replaced with the name of a
     file containing the commit log message (*note Log Message
     Handling::).  This file is a temporary file handled by Patcher.

   * A `%S' occurring in the string will be replaced with the commit log
     message itself (*note Log Message Handling::). Since the intent
     here is to use the message as a command-line argument, it is
     quoted against shell expansion.

   Please note that a `%f' is required in your commit commands, unless
you know for sure that you will never ever work on a subproject (*note
Patch Restriction::). But you never know that. Besides, you should
always also provide either a `%s' or a `%S', unless your archival
software does not support log messages.

   Given that, you should now understand why the default value for
`patcher-default-commit-command' is `cvs commit -F %s %f'.


File: patcher.info,  Node: Log Message Handling,  Next: Commit Operation,  Prev: Commit Command,  Up: Project Check In

Log Message Handling
--------------------

Most project management tools understand the concept of a "log
message": a short yet informative message that accompany the commit
operation, which is also stored in the repository.

   Before a commit operation, Patcher always builds an initial log
message, based on certain elements under your control (*note Log
Message Elements::). Afterwards, you can decide on whether you want
some further (manual) edition of log message, or whether you want to
commit immediately.

   The `:edit-log-message' project option lets you specify this
behavior. If `t' (the default), you will be able to manually edit the
log message. If `nil', Patcher will proceed directly to the commit
operation.

   Please note that Patcher stores log messages in temporary files that
will be used later by the commit command.

* Menu:

* Log Message Elements:: Elements Patcher can add automatically
* Log Message Editing::  Manually modifying the log message


File: patcher.info,  Node: Log Message Elements,  Next: Log Message Editing,  Prev: Log Message Handling,  Up: Log Message Handling

Log Message Elements
....................

Patcher has the ability to initialize the log message with different
elements. These elements are specified with the `:log-message-items'
project option. Its value is either `nil', meaning that you don't want
any initialization, or a list of symbols specifying the elements you
desire. The available items are:

`subject'
     The subject of the message. The subject's prefix is automatically
     removed.

`compressed-change-logs'
     The "compressed" ChangeLog entries. Only the most important part
     of the ChangeLogs is preserved, so the entries appear in a more
     compact fashion.

`change-logs'
     The raw ChangeLog entries.

   By default, only the message's subject is used. When using more than
one item, they appear in the order specified above. If anything appears
before the raw ChangeLog entries, a separator string is used. This
string is specified by the `:change-logs-separator' project option.  By
default the string looks like "-- ChangeLog entries follow: --".


File: patcher.info,  Node: Log Message Editing,  Prev: Log Message Elements,  Up: Log Message Handling

Log Message Editing
...................

If so required, Patcher lets you manually edit the log message after
having initialized it. Log message edition happens in a special buffer,
the `*Patcher Log Message*' buffer.

   While editing this buffer, commands to insert the items described in
*Note Log Message Elements:: are at your disposal. These commands
perform insertion at point:

`patcher-logmsg-insert-subject'
     Bound to `C-c C-p s'. Insert the message's subject (sans the
     prefix).

`patcher-logmsg-insert-compressed-change-logs'
     Bound to `C-c C-p c'. Insert the compressed ChangeLog entries.

`patcher-logmsg-insert-change-logs'
     Bound to `C-c C-p l'. Insert the raw ChangeLog entries. Use a
     prefix argument if you also want the ChangeLogs separator string
     to be inserted.

   In addition to these commands, you can also completely reinitialize
the log message according to the specified items, by calling the
function `patcher-logmsg-init-message', bound to `C-c C-p i'. Caution:
this command first erases the buffer.

   Finally, once you're happy with your log message, you proceed to the
commit operation by calling the function `patcher-logmsg-commit', bound
to `C-c C-c'.


File: patcher.info,  Node: Commit Operation,  Prev: Log Message Handling,  Up: Project Check In

Commit Operation
----------------

The commit operation occurs after typing `C-c C-p c' from the mail
buffer, if you have not required log message edition, or after typing
`C-c C-c' from the `*Patcher Log Message*' buffer otherwise.

   At that point, Patcher has constructed a proper commit command. You
still have an option to abort the process, though: the
`:confirm-commits' project option lets you specify whether to require
confirmation before committing. If `t' (the default), Patcher will
display the constructed commit command and ask for a confirmation
before proceeding. If `nil', Patcher will commit immediately.

   After the commit operation, Patcher changes some parts of the mail
buffer in the following manner:

   * The subject prefix is changed to that specified by the
     `:subject-committed-prefix' project option (a string), unless it is
     `nil'. By default, "[COMMIT]" is used.

   * A commit notice is added right at the beginning of the message's
     body.  This notice is specified by the `:committed-notice' project
     option.  It can be `nil' or a string. By default, it reads "NOTE:
     this patch has been committed.".


File: patcher.info,  Node: Mail Sending,  Next: More On Commands,  Prev: Project Check In,  Up: User Manual

Mail Sending
============

Sending the message will most probably be done by typing `C-c C-c' in
the mail buffer. This is also the case when you're using the fake mail
method, by the way.

* Menu:

* Before Sending:: Patcher does some checkings
* After Sending::  patcher does some cleanup


File: patcher.info,  Node: Before Sending,  Next: After Sending,  Prev: Mail Sending,  Up: Mail Sending

Before Sending
--------------

There are circumstances in which Patcher will perform some checkings on
your message when you send it, just before it is actually sent:

   * ChangeLogs insertion

     In case of manual ChangeLog insertion (*note ChangeLogs
     Appearance::), Patcher can check that you have indeed inserted the
     ChangeLog entries before sending the message. This behavior is
     controlled by the `patcher-mail-check-change-logs-insertion' user
     option. A value of `nil' means never check (the message will be
     sent as-is). A value of t means check, and abort the sending if
     the ChangeLog entries are missing. A value of `ask' (the default)
     means ask for your opinion on this terrible matter.

   * Commit Operation

     Patcher has a `:commit-privilege' project option; a boolean
     specifying whether you're likely to commit your changes by
     yourself.

     In case of commit privilege, Patcher can check that you have indeed
     committed your changes before sending the message. This behavior is
     controlled by the `patcher-mail-check-commit-action' user option. A
     value of `nil' means never check (the message will be sent as-is).
     A value of t means check, and abort the sending if the commit
     operation has not been performed. A value of `ask' (the default)
     means ask for your opinion on this rather unfortunate situation.

   Two notes on these checkings:

   * For uninteresting technical reasons, Patcher does not currently
     (and will probably never) offer you an automatic ChangeLogs
     insertion or commit operation, at mail sending time, but just
     abort the sending process in some circumstances. That's not a big
     deal though.

   * For other uninteresting technical reasons, these checkings require
     a native knowledge of your mail user agent. Patcher does not
     currently support all mail user agents on earth (I'll add them on
     demand however).  If that's the case, you will be warned and
     invited to send me a message.  Also, you can send me one on April
     21st: it's my birthday.


File: patcher.info,  Node: After Sending,  Prev: Before Sending,  Up: Mail Sending

After Sending
-------------

After sending the message, Patcher also performs some cleanup
operations, that you can customize. The cleanup is controlled by the
following project options. Each one is a boolean option which defaults
to `t'.

`:kill-source-files-after-sending'
     Whether to kill source files after sending the message. If `nil',
     the source files will remain visited.

`:kill-change-logs-after-sending'
     Whether to kill ChangeLog files after sending the message. If
     `nil', the ChangeLog files will remain visited.


File: patcher.info,  Node: More On Commands,  Next: More On Subprojects,  Prev: Mail Sending,  Up: User Manual

More On Commands
================

This section deals with information that apply to all commands used by
Patcher (diff and commit operations).

* Menu:

* Prefixing Commands::  Bypassing a firewall
* Error Handling::      Dealing with errors


File: patcher.info,  Node: Prefixing Commands,  Next: Error Handling,  Up: More On Commands

Prefixing Commands
------------------

If you're working on a distant archive and you're behind a firewall, you
might need to prefix all your commands with something like `runsocks'.
Of course, this can be done manually in all your command settings, but
Patcher offers you a simpler way to do it.

   There is a project option named `:pre-command' which can be used for
this kind of thing. It must be a string that will be prepended to all
operations performed by Patcher.


File: patcher.info,  Node: Error Handling,  Prev: Prefixing Commands,  Up: More On Commands

Error Handling
--------------

From time to time, commands may fail for different reasons. Patcher
tracks the failures in these commands and lets you know when that
happens. The `:failed-command-regexp' project option lets you specify a
regular expression to match with the output of an aborted command. By
default, the value is `"^cvs \\[[^]]* aborted\\]"'.


File: patcher.info,  Node: More On Subprojects,  Prev: More On Commands,  Up: User Manual

More On Subprojects
===================

We've already seen how to work punctually on a subproject, that is, on a
subset of a project's files (*note Patch Restriction::). If you happen
to work more than once on the same project subset, it will quickly
become annoying to have to specify explicitly the same files over and
over again. Patcher offers you a way to _permanently_ define
subprojects.

* Menu:

* Defining Subprojects::  Storing subprojects definitions
* Subproject Naming::     When different projects have the same name
* Command Directory::     For non local revision control systems


File: patcher.info,  Node: Defining Subprojects,  Next: Subproject Naming,  Up: More On Subprojects

Defining Subprojects
--------------------

The user option `patcher-subprojects' stores a list of "subproject
descriptors". A subproject descriptor is almost the same as a project
descriptor, with a few exceptions:

   * Instead of the project directory field (the second field in a
     project descriptor), you rather specify the name of the project
     this subproject is based on.

   * In addition to the standard project options we've already seen, two
     subproject options are available:
    `:subdirectory'
          This lets you specify a subdirectory of the original
          project's directory in which the whole subproject resides.

    `:files'
          This lets you specify a list of files or directories
          composing the subproject. Each file specification can contain
          wildcards. If a `:subdirectory' subproject option is given,
          these files or directories should be relative to this
          subdirectory. Otherwise, they should be relative to the
          parent project's directory.

     Please note that these subproject options have no corresponding
     fallback (that would be meaningless). They can't appear in a theme
     either.

   * Subprojects don't have an `:inheritance' mechanism. Instead, they
     implicitly inherit from their base project (which in turn can
     inherit from other projects).

   Here are some important remarks about subprojects:

   * A subproject with neither a `:subdirectory' nor a `:files' option
     is exactly the same as the base project, apart from project
     options that you would override.

   * Permanent subprojects are designed to work with the function
     `patcher-mail'. You don't need to use `patcher-mail-subproject'
     any more.

   * Because of that, projects and subprojects can't have names in
     common. If that happens to be the case, Patcher will blindly use a
     subproject rather than a project of that name

   * What happens if you use `patcher-mail-subproject' on a permanent
     subproject ? You punctually work on a subsubproject...


File: patcher.info,  Node: Subproject Naming,  Next: Command Directory,  Prev: Defining Subprojects,  Up: More On Subprojects

Subproject Naming
-----------------

As you already know, Patcher distinguishes projects by their NAME field
in the `patcher-projects' and `patcher-subprojects' user options. This
is problematic, however, if you define different patcher projects for a
single physical project, and the commands require the project's name.
That might for instance be the case with PRCS (decidedly) weird options
syntax.

   To remedy this problem, patcher provides a `:name' project option.
If set, it will actually be used for all `%n' substitutions where the
project's name (in the Patcher sense) would normally be used.

   If you want to use the project's name in the Patcher sense,
regardless of the value of the `:name' option, use `%N' instead of `%n'.


File: patcher.info,  Node: Command Directory,  Prev: Subproject Naming,  Up: More On Subprojects

Command Directory
-----------------

Some revision control systems, like CVS, work on a per-file basis. Some
others, like PRCS, work only globally. This has an important implication
for subprojects being sudirectories of other projects. Indeed, while
CVS, for instance, can be executed anywhere, PRCS can only be run in the
base project's root directory.

   If you want to define projects for which the revision control system
can be executed in only one directory, Patcher provides you with the
`:command-directory' project option (a string). This directory can be
specified relative to the project's directory (but note that it must go
upwards).

   All commands (diff and commit ones) will be executed from there.
Also, note that the command directory does not change the way you might
specify files. Patcher modifies all needed paths automatically to handle
the command directory properly.


File: patcher.info,  Node: Variables Index,  Next: Functions Index,  Prev: User Manual,  Up: Top

Variables Index
***************

* Menu:

* :after-diff-hook:                      After Diff Hook.
* :change-logs-appearance:               ChangeLogs Appearance.
* :change-logs-diff-command:             ChangeLogs Appearance.
* :change-logs-prologue:                 ChangeLogs Prologue.
* :change-logs-separator:                Log Message Elements.
* :change-logs-updating:                 ChangeLogs Updating.
* :change-logs-user-mail:                ChangeLogs Updating.
* :change-logs-user-name:                ChangeLogs Updating.
* :command-directory:                    Command Directory.
* :commit-command:                       Commit Command.
* :commit-privilege:                     Before Sending.
* :committed-notice:                     Commit Operation.
* :confirm-commits:                      Commit Operation.
* :diff-command <1>:                     ChangeLogs Appearance.
* :diff-command <2>:                     Diff Command.
* :diff-command:                         Patch Restriction.
* :diff-line-filter:                     Diff Line Filter.
* :diff-prologue-function <1>:           ChangeLogs Prologue.
* :diff-prologue-function:               Diff Prologue.
* :edit-log-message:                     Log Message Handling.
* :failed-command-regexp:                Error Handling.
* :files:                                Defining Subprojects.
* :gnus-group <1>:                       Standard Mail Methods.
* :gnus-group:                           Message Customization.
* :inheritance <1>:                      Project inheritance.
* :inheritance <2>:                      Retrieval.
* :inheritance:                          Defining Subprojects.
* :kill-change-logs-after-sending:       After Sending.
* :kill-source-files-after-diffing:      ChangeLogs Updating.
* :kill-source-files-after-sending:      After Sending.
* :log-message-items:                    Log Message Elements.
* :mail-method <1>:                      Other Mail Methods.
* :mail-method:                          Mail Methods.
* :name:                                 Subproject Naming.
* :pre-command:                          Prefixing Commands.
* :subdirectory:                         Defining Subprojects.
* :subject:                              Message Customization.
* :subject-committed-prefix:             Commit Operation.
* :subject-prefix:                       Message Customization.
* :themes <1>:                           Retrieval.
* :themes:                               Themes.
* :to-address <1>:                       Fallbacks.
* :to-address <2>:                       Message Customization.
* :to-address <3>:                       Project Descriptors.
* :to-address:                           Calling Patcher.
* :user-mail:                            Message Customization.
* :user-name:                            Message Customization.
* mail-user-agent:                       Standard Mail Methods.
* patcher-default-after-diff-hook:       After Diff Hook.
* patcher-default-change-logs-appearance: ChangeLogs Appearance.
* patcher-default-change-logs-diff-command: ChangeLogs Appearance.
* patcher-default-change-logs-prologue:  ChangeLogs Prologue.
* patcher-default-change-logs-separator: Log Message Elements.
* patcher-default-change-logs-updating:  ChangeLogs Updating.
* patcher-default-change-logs-user-mail: ChangeLogs Updating.
* patcher-default-change-logs-user-name: ChangeLogs Updating.
* patcher-default-command-directory:     Command Directory.
* patcher-default-commit-command:        Commit Command.
* patcher-default-commit-privilege:      Before Sending.
* patcher-default-committed-notice:      Commit Operation.
* patcher-default-confirm-commits:       Commit Operation.
* patcher-default-diff-command <1>:      ChangeLogs Appearance.
* patcher-default-diff-command <2>:      Patch Restriction.
* patcher-default-diff-command:          Diff Command.
* patcher-default-diff-line-filter:      Diff Line Filter.
* patcher-default-diff-prologue-function <1>: ChangeLogs Prologue.
* patcher-default-diff-prologue-function: Diff Prologue.
* patcher-default-edit-log-message:      Log Message Handling.
* patcher-default-failed-command-regexp: Error Handling.
* patcher-default-gnus-group <1>:        Standard Mail Methods.
* patcher-default-gnus-group:            Message Customization.
* patcher-default-kill-change-logs-after-sending: After Sending.
* patcher-default-kill-source-files-after-diffing: ChangeLogs Updating.
* patcher-default-kill-source-files-after-sending: After Sending.
* patcher-default-log-message-items:     Log Message Elements.
* patcher-default-mail-method <1>:       Mail Methods.
* patcher-default-mail-method:           Other Mail Methods.
* patcher-default-name:                  Subproject Naming.
* patcher-default-pre-command:           Prefixing Commands.
* patcher-default-subject:               Message Customization.
* patcher-default-subject-committed-prefix: Commit Operation.
* patcher-default-subject-prefix:        Message Customization.
* patcher-default-themes <1>:            Retrieval.
* patcher-default-themes:                Themes.
* patcher-default-to-address <1>:        Fallbacks.
* patcher-default-to-address <2>:        Message Customization.
* patcher-default-to-address <3>:        Project Descriptors.
* patcher-default-to-address:            Calling Patcher.
* patcher-default-user-mail:             Message Customization.
* patcher-default-user-name:             Message Customization.
* patcher-mail-check-change-logs-insertion: Before Sending.
* patcher-mail-check-commit-action:      Before Sending.
* patcher-mail-run-gnus:                 Standard Mail Methods.
* patcher-mail-run-gnus-other-frame:     Standard Mail Methods.
* patcher-max-inheritance-depth:         Project inheritance.
* patcher-max-theme-depth:               Themes.
* patcher-projects <1>:                  Project Descriptors.
* patcher-projects <2>:                  Subproject Naming.
* patcher-projects:                      Setting up Patcher.
* patcher-subprojects <1>:               Subproject Naming.
* patcher-subprojects:                   Defining Subprojects.
* patcher-themes <1>:                    Retrieval.
* patcher-themes:                        Themes.
* user-full-name:                        ChangeLogs Updating.
* user-mail-address:                     ChangeLogs Updating.


File: patcher.info,  Node: Functions Index,  Next: Keystrokes Index,  Prev: Variables Index,  Up: Top

Functions Index
***************

* Menu:

* compose-mail:                          Standard Mail Methods.
* gnus-post-news:                        Standard Mail Methods.
* mail:                                  Standard Mail Methods.
* message-mail:                          Standard Mail Methods.
* patch-to-change-log:                   ChangeLogs Updating.
* patcher-commit-change <1>:             Committing the Patch.
* patcher-commit-change <2>:             Commit Command.
* patcher-commit-change:                 Project Check In.
* patcher-default-diff-prologue <1>:     ChangeLogs Prologue.
* patcher-default-diff-prologue:         Diff Prologue.
* patcher-generate-diff <1>:             Patch Restriction.
* patcher-generate-diff:                 Patch Generation.
* patcher-insert-change-logs <1>:        ChangeLogs Appearance.
* patcher-insert-change-logs:            Filling the Message.
* patcher-logmsg-commit <1>:             Log Message Editing.
* patcher-logmsg-commit:                 Committing the Patch.
* patcher-logmsg-init-message:           Log Message Editing.
* patcher-logmsg-insert-change-logs:     Log Message Editing.
* patcher-logmsg-insert-compressed-change-logs: Log Message Editing.
* patcher-logmsg-insert-subject:         Log Message Editing.
* patcher-mail <1>:                      Mail Preparation.
* patcher-mail <2>:                      Defining Subprojects.
* patcher-mail <3>:                      Patch Restriction.
* patcher-mail <4>:                      Calling Patcher.
* patcher-mail:                          Diff Command.
* patcher-mail-compose-mail:             Standard Mail Methods.
* patcher-mail-fake:                     Fake Mail Method.
* patcher-mail-gnus:                     Standard Mail Methods.
* patcher-mail-message:                  Standard Mail Methods.
* patcher-mail-sendmail:                 Standard Mail Methods.
* patcher-mail-subproject <1>:           Patch Restriction.
* patcher-mail-subproject:               Defining Subprojects.
* patcher-prcs-diff-convert:             After Diff Hook.


File: patcher.info,  Node: Keystrokes Index,  Prev: Functions Index,  Up: Top

Keystrokes Index
****************

* Menu:

* C-c C-c <1>:                           Log Message Editing.
* C-c C-c <2>:                           Committing the Patch.
* C-c C-c:                               Commit Operation.
* C-c C-p c <1>:                         Commit Operation.
* C-c C-p c <2>:                         Project Check In.
* C-c C-p c <3>:                         Log Message Editing.
* C-c C-p c:                             Committing the Patch.
* C-c C-p d:                             Patch Generation.
* C-c C-p i <1>:                         Filling the Message.
* C-c C-p i <2>:                         Log Message Editing.
* C-c C-p i:                             ChangeLogs Appearance.
* C-c C-p l:                             Log Message Editing.
* C-c C-p s:                             Log Message Editing.



Tag Table:
Node: Top760
Node: Copying1614
Node: Introduction2302
Node: Distribution4667
Node: Requirements5949
Node: Quick Start6860
Node: Setting up Patcher8018
Node: Calling Patcher9163
Node: Filling the ChangeLogs10792
Node: Filling the Message11293
Node: Committing the Patch12029
Node: Sending the Message13734
Node: User Manual14626
Node: Project Descriptors15567
Node: Themes16900
Node: Project inheritance18192
Node: Fallbacks19393
Node: Retrieval20317
Node: Inheritance or theme ?21787
Node: Mail Preparation22703
Node: Mail Methods23564
Node: Standard Mail Methods24126
Node: Fake Mail Method26785
Node: Other Mail Methods27977
Node: Message Customization28606
Node: Patch Generation30651
Node: Diff Command32177
Node: After Diff Hook32799
Node: Diff Line Filter33778
Node: Patch Restriction34664
Node: Patcher Instances36922
Node: Diff Prologue37724
Node: ChangeLogs Handling39248
Node: ChangeLogs Updating39793
Node: ChangeLogs Appearance42893
Node: ChangeLogs Prologue45479
Node: Project Check In46385
Node: Commit Command47249
Node: Log Message Handling49097
Node: Log Message Elements50197
Node: Log Message Editing51366
Node: Commit Operation52687
Node: Mail Sending53945
Node: Before Sending54347
Node: After Sending56556
Node: More On Commands57187
Node: Prefixing Commands57545
Node: Error Handling58114
Node: More On Subprojects58569
Node: Defining Subprojects59261
Node: Subproject Naming61435
Node: Command Directory62307
Node: Variables Index63303
Node: Functions Index69780
Node: Keystrokes Index71959

End Tag Table
