1.1 --- a/en/hgext.tex	Sun May 27 09:57:17 2007 -0700
     1.2 +++ b/en/hgext.tex	Mon Sep 10 19:38:41 2007 +0200
     1.3 @@ -349,6 +349,82 @@
     1.4  Once you've enabled the extension, you will have a new command
     1.5  available, named \hgxcmd{patchbomb}{email}.
     1.6  
     1.7 +The safest and best way to invoke the \hgxcmd{patchbomb}{email}
     1.8 +command is to \emph{always} run it first with the
     1.9 +\hgxopt{patchbomb}{email}{-n} option.  This will show you what the
    1.10 +command \emph{would} send, without actually sending anything.  Once
    1.11 +you've had a quick glance over the changes and verified that you are
    1.12 +sending the right ones, you can rerun the same command, with the
    1.13 +\hgxopt{patchbomb}{email}{-n} option removed.
    1.14 +
    1.15 +The \hgxcmd{patchbomb}{email} command accepts the same kind of
    1.16 +revision syntax as every other Mercurial command.  For example, this
    1.17 +command will send every revision between 7 and \texttt{tip},
    1.18 +inclusive.
    1.19 +\begin{codesample2}
    1.20 +  hg email -n 7:tip
    1.21 +\end{codesample2}
    1.22 +You can also specify a \emph{repository} to compare with.  If you
    1.23 +provide a repository but no revisions, the \hgxcmd{patchbomb}{email}
    1.24 +command will send all revisions in the local repository that are not
    1.25 +present in the remote repository.  If you additionally specify
    1.26 +revisions or a branch name (the latter using the
    1.27 +\hgxopt{patchbomb}{email}{-b} option), this will constrain the
    1.28 +revisions sent.
    1.29 +
    1.30 +It's perfectly safe to run the \hgxcmd{patchbomb}{email} command
    1.31 +without the names of the people you want to send to: if you do this,
    1.32 +it will just prompt you for those values interactively.  (If you're
    1.33 +using a Linux or Unix-like system, you should have enhanced
    1.34 +\texttt{readline}-style editing capabilities when entering those
    1.35 +headers, too, which is useful.)
    1.36 +
    1.37 +When you are sending just one revision, the \hgxcmd{patchbomb}{email}
    1.38 +command will by default use the first line of the changeset
    1.39 +description as the subject of the single email message it sends.
    1.40 +
    1.41 +If you send multiple revisions, the \hgxcmd{patchbomb}{email} command
    1.42 +will usually send one message per changeset.  It will preface the
    1.43 +series with an introductory message, in which you should describe the
    1.44 +purpose of the series of changes you're sending.
    1.45 +
    1.46 +\subsection{Changing the behaviour of patchbombs}
    1.47 +
    1.48 +Not every project has exactly the same conventions for sending changes
    1.49 +in email; the \hgext{patchbomb} extension tries to accommodate a
    1.50 +number of variations through command line options.
    1.51 +\begin{itemize}
    1.52 +\item You can write a subject for the introductory message on the
    1.53 +  command line using the \hgxopt{patchbomb}{email}{-s} option.  This
    1.54 +  takes one argument, the text of the subject to use.
    1.55 +\item To change the email address from which the messages originate,
    1.56 +  use the \hgxopt{patchbomb}{email}{-f} option.  This takes one
    1.57 +  argument, the email address to use.
    1.58 +\item The default behaviour is to send unified diffs (see
    1.59 +  section~\ref{sec:mq:patch} for a description of the format), one per
    1.60 +  message.  You can send a binary bundle instead with the
    1.61 +  \hgxopt{patchbomb}{email}{-b} option.  
    1.62 +\item Unified diffs are normally prefaced with a metadata header.  You
    1.63 +  can omit this, and send unadorned diffs, with the
    1.64 +  \hgxopt{patchbomb}{email}{--plain} option.
    1.65 +\item Diffs are normally sent ``inline'', in the same body part as the
    1.66 +  description of a patch.  This makes it easiest for the largest
    1.67 +  number of readers to quote and respond to parts of a diff, as some
    1.68 +  mail clients will only quote the first MIME body part in a message.
    1.69 +  If you'd prefer to send the description and the diff in separate
    1.70 +  body parts, use the \hgxopt{patchbomb}{email}{-a} option.
    1.71 +\item Instead of sending mail messages, you can write them to an
    1.72 +  \texttt{mbox}-format mail folder using the
    1.73 +  \hgxopt{patchbomb}{email}{-m} option.  That option takes one
    1.74 +  argument, the name of the file to write to.
    1.75 +\item If you would like to add a \command{diffstat}-format summary to
    1.76 +  each patch, and one to the introductory message, use the
    1.77 +  \hgxopt{patchbomb}{email}{-d} option.  The \command{diffstat}
    1.78 +  command displays a table containing the name of each file patched,
    1.79 +  the number of lines affected, and a histogram showing how much each
    1.80 +  file is modified.  This gives readers a qualitative glance at how
    1.81 +  complex a patch is.
    1.82 +\end{itemize}
    1.83  
    1.84  %%% Local Variables: 
    1.85  %%% mode: latex