5. User Manual

This chapter provides a step-by-step guide to using Patcher. Everything there is to know about Patcher is here, but 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.

5.1 Project Descriptors		The project specification mechanism
5.2 Mail Preparation		Customizing Patcher messages
5.3 Patch Generation		Specifying how a patch is to be constructed
5.4 ChangeLogs Handling		How Patcher behaves with respect to ChangeLogs
5.5 Project Check In		Committing your changes from Patcher
5.6 Mail Sending		Sending the message and cleaning up the place
5.7 Error Handling		Tracking when commands fail
5.8 Subprojects Handling		Defining permanent subprojects

5.1 Project Descriptors

Projects specifications are stored in the patcher-projects user option. This variable 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. All option names start with a colon. The type of the 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.

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 variable is obtained by replacing the colon in the project option's name with the prefix patcher-default-. For example, the variable corresponding to the :to-address project option is named patcher-default-to-address.

There is a special project option called :inheritance. This option must be a list of strings which correspond to project names. The inheritance of a project defines a list of projects from which to inherit options. Note that this project option is special in the sense that it doesn't have a corresponding fallback variable (that would be meaningless).

When Patcher needs the value of a particular option, it first looks in the project descriptor to see if the option is given. If that fails, it recursively looks in the options of all inherited projects. If that still fails, it finally falls back to the value given in the corresponding fallback variable.

Note that a value of nil for a project option is a real value. It does not mean that the option is unset. As a consequence, if Patcher finds a project option with a value of nil, it will use it, even if the fallback variable as a non nil value. This provides you with a way to annihilate default values for some projects.

In the remainder of this manual, we will rarely mention the fallback variables again. When we introduce a new project option, just remember that it always has a corresponding fallback.

5.2 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.

5.2.1 Mail Methods		Using a particular mailer
5.2.2 Message Customization		Specifying initial contents for messages

5.2.1 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 thanks to the :mail-method project option. The value must be a symbol.

5.2.1.1 Standard Mail Methods		Patcher supports standard mail packages
5.2.1.2 Fake Mail Method		Patcher supports not sending mails
5.2.1.3 Other Mail Methods		Patcher supports everything

5.2.1.1 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 (see section 5.2.2 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 (see section 5.2.2 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 (see section 5.2.2 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 (see section 5.2.2 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 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).

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.

5.2.1.2 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 at 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 options to standard user options.

5.2.1.3 Other Mail Methods

If you're not satisfied with the provided mail methods (but really, you should), 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.

5.2.2 Message Customization

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

: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 when calling patcher-mail.

:gnus-group

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

: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 name. 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).

5.3 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 (see section 5.7 Error Handling).

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.

5.3.1 Diff Command		Specifying the command to generate the patch
5.3.2 After Diff Hook		Tweaking the diff output
5.3.3 Diff Line Filter		Omitting lines from the diff output
5.3.4 Patch Restriction		Specifying the files affected by the patch
5.3.5 Patcher Instances		You can have several instances of Patcher
5.3.6 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 (see section 5.4 ChangeLogs Handling).

5.3.1 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 section 5.3.4 Patch Restriction.

5.3.2 After Diff Hook

Sometimes, you might want to tweak a little the diff output before doint anything with it, for instance, before generating ChangeLog skeletons (see section 5.4 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 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.

5.3.3 Diff Line Filter

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.

5.3.4 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 like 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 ?

For a more advanced way of handling subprojects, see 5.8 Subprojects Handling.

5.3.5 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.

5.3.6 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 (symbol) argument indicating the kind of diff, and perform insertion at current point in 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.

5.4 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 to suit your needs.

5.4.1 ChangeLogs Action		How Patcher deals with ChangeLogs
5.4.2 ChangeLogs Appearance		How ChangeLogs appear in messages
5.4.3 ChangeLogs Prologue		A header is inserted above the ChangeLogs

5.4.1 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. I hope however to extend this to other tools, PRCS in particular.

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 not given, Patcher lets the function patch-to-change-log decide what to use (most probably what the variables 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 (see section 5.3.4 Patch Restriction), although I don't see why you would want to do that.

5.4.2 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 (see section 5.4.1 ChangeLogs Action).

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 'diff, meaning that the same diff command is to be used as for the sources (see section 5.3.1 Diff Command), or it can be a string specifying an alternate command.

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

As in the case of the :diff-command project option (see section 5.3.4 Patch Restriction), a %f serves to indicate where to put the ChangeLog files on the diff command line.

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'.

5.4.3 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 5.3.6 Diff Prologue.

5.5 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 check in command line and the commit log message (see section 5.5.2 Log Message Handling) are constructed automatically. Of course, you still have an in-depth control on the commit process.

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

5.5.1 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 %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 (see section 5.5.2 Log Message Handling).

• A %S occurring in the string will be replaced with the commit log message itself (see section 5.5.2 Log Message Handling).

Please note that a %f is required in your commit commands, unless you know for sure that you will never ever work on a subprojet (see section 5.3.4 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'.

5.5.2 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 (see section 5.5.2.1 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.

5.5.2.1 Log Message Elements		Elements Patcher can add automatically
5.5.2.2 Log Message Editing		Manually modifying the log message

5.5.2.1 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: ---".

5.5.2.2 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 5.5.2.1 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'.

5.5.3 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 stored the log message in a temporary file, and 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. It can be nil, or a string. 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.".

5.6 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.

5.6.1 Before Sending		Patcher does some checkings
5.6.2 After Sending		patcher does some cleanup

5.6.1 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 (see section 5.4.2 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 aborts the sending if the ChangeLog entries are missing. A value of ask (the default) means ask the user what to do.

• 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 commited 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 aborts the sending if the checkin has not been done. A value of ask (the default) means ask the user what to do.

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, but just aborts 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.

5.6.2 After Sending

After sending the message, Patcher also performs some cleanup operations, that you can customize. The cleaning up 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 stay visited.

:kill-change-logs-after-sending

Whether to kill ChangeLog files after sending the message. If nil, the ChangeLog files will stay visited.

5.7 Error Handling

From time to time, diff or commit commands may fail for different reasons. Patcher tracks the failures in these commands and let 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\\]".

5.8 Subprojects Handling

We've already seen how to work punctually on a subproject, that is, on a subset of a project's files (see section 5.3.4 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: the variable 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 base project's directory.

  Please note that these subproject options have no corresponding fallback variables (that would be meaningless).

• 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. Put it differently, this is a way of defining different "flavors" (sets of options) for the same project.

• 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

• Exercise: what happens if you use patcher-mail-subproject on a permanent subproject ? Solution: you punctually work on a subsubproject...