Commits

Didier Verna committed ce7a0dc

Update documentation on ephemeral ChangeLogs.

ChangeLog entries:

2012-01-13 Didier Verna <didier@xemacs.org>

* doc/patcher.texi (ChangeLogs Status): Document the
'ephemeral-change-logs built-in themes. Reflect the fact that
there's now only one ephemeral ChangeLog file located at the
project's base directory.

Comments (0)

Files changed (1)

 @c Author:        Didier Verna <didier@xemacs.org>
 @c Maintainer:    Didier Verna <didier@xemacs.org>
 @c Created:       Sun Apr 21 21:34:06 2002
-@c Last Revision: Fri Jan 13 08:58:37 2012
+@c Last Revision: Fri Jan 13 09:35:26 2012
 
 @c This file is part of Patcher.
 
 @c Definitions
 @c ====================================================================
 @set VERSION 4.0 pre 1
+
 @macro copyrightdate
 Copyright @copyright{} 2010, 2011, 2012 Didier Verna.@*
 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2007, @c
 2008, 2009 Didier Verna.
 @end macro
 
+@macro etc
+@i{etc.}
+@end macro
+
 
 
 @c ====================================================================
 @findex patcher-version
 @kindex C-c C-p v
 At any time, and in any buffer related to a Patcher project (mail,
-ChangeLog etc.), you can query the current version of Patcher by calling
-the function @code{patcher-version}, bound to @kbd{C-c C-p v}.
+ChangeLog @etc{}), you can query the current version of Patcher by
+calling the function @code{patcher-version}, bound to @kbd{C-c C-p v}.
 
 @menu
 * Starting Up::         Patcher entry points
 @vindex :change-log-file-name
 A value of @code{ephemeral} on the other hand means that your ChangeLog
 entries exist only temporarily, to be used in the commit log message
-and/or inserted verbatim in the mail. Patcher does this by creating
-temporary ChangeLog files (named after the @code{:change-log-file-name}
-project option) and getting rid of them after the mail is sent. As a
-result, everything works just as if the ChangeLog files were real:
-ChangeLog entries can be generated automatically or written manually,
-you can navigate through them on a per-directory basis, whatever.
-
-The only restriction is that you cannot diff them because they are not
-really part of the project, so their appearance can only be
-@code{verbatim}. Also, when you set a project to ephemeral ChangeLogs,
-beware to use ChangeLog file names that don't conflict with existing
-files (old ChangeLog files may for example be renamed
+and/or inserted verbatim in the mail. Patcher does this by creating a
+temporary ChangeLog file (named after the @code{:change-log-file-name}
+project option) in the project's base directory, and getting rid of it
+after the mail is sent. As a result, everything works just as if the
+ChangeLog file was real: ChangeLog entries can be generated
+automatically or written manually @etc{}
+
+The only restriction is that you cannot diff the ephemeral ChangeLog
+entries because they are not really part of the project, so their
+appearance can only be @code{verbatim}. Also, when you use an ephemeral
+ChangeLog, beware to use a file name that doesn't conflict with existing
+files (old ChangeLog files may for example be renamed to
 @file{ChangeLog.dead}).
 
+Because there's only one, virtual, ephemeral ChangeLog file located at
+the project's base directory, the default value for the ChangeLogs
+prologue doesn't work very well in the ephemeral case. It doesn't make
+sense to refer to the file itself, since it's only temporary. A simpler
+prologue like ``ChangeLog entries:'' would suffice. Patcher provides a
+built-in theme called @samp{ephemeral-change-logs} that you can use to
+both set the ChangeLog status to @samp{ephemeral} and modify the
+prologue at the same time.
+
 One final note: if you use the @code{git-index} built-in theme with
 ephemeral ChangeLogs, don't use it in conjunction with
 @code{git-index-automatic-change-logs}, even if the ChangeLogs entries