[Monotone-commits-diffs] net.venge.monotone: 22e265afd50acffb5e025ef66ec039d6b04e338b

[code]

revision:            22e265afd50acffb5e025ef66ec039d6b04e338b
date:                2011-01-15T16:40:15
author:              address@hidden
branch:              net.venge.monotone
changelog:
monotone.texi: Review rest of Lua Reference hooks

* tests/changelog_editor/__driver__.lua: fix comment

* monotone.texi: Review rest of Lua Reference hooks, clean up command 
descriptions affected by the hooks.

manifest:
format_version "1"

new_manifest [5e1aad3492628cc1a7dedd8a64f0ab9acf7b1b6e]

old_revision [1777fd15b6f742120616a1fedf2a2ca65b2686d2]

patch "monotone.texi"
 from [cd68099e77a06f12f568fa5df94ed8bf93f030dc]
   to [638aac30f2d2d53db88329e2cef160b6f291e75a]

patch "tests/changelog_editor/__driver__.lua"
 from [5e7b3272a2620ff1f924cdf20c4b853f07eaa4e3]
   to [0eccf936ef1688640f00aba6c786ad14c3ddb3cf]
============================================================
--- monotone.texi	cd68099e77a06f12f568fa5df94ed8bf93f030dc
+++ monotone.texi	638aac30f2d2d53db88329e2cef160b6f291e75a
@@ -3795,10 +3795,10 @@ @section Managed Databases
 Monotone searches for this file name in common locations and internally
 expands it to a full path once it found an unambigious match.
 
-Some commands, most noticable @address@hidden clone}} and
address@hidden@ref{mtn setup}}, work out of the box without that any
address@hidden option is needed; they fall back on a managed ``default''
-database and even initialize that in case it is not existant.
+Some commands, such as @address@hidden clone}} and @address@hidden
+setup}}, work without a @option{--db} option; they fall back on a
+managed ``default'' database and even initialize that in case it is
+not existant.
 
 To keep an overview of managed databases and their workspaces, the commands
 @address@hidden list databases}} and @address@hidden list workspaces}}
@@ -4918,6 +4918,9 @@ @chapter Command Reference
 Many options can be specified by a single character; see the online
 help for those.
 
+The Lua hook @address@hidden can change the
+default value for any option.
+
 Revision arguments to commands may be selectors or hex ids.
 
 @menu
@@ -4981,10 +4984,10 @@ @subsection Global Options
 workspace).
 
 @item --date-format <arg>
-strftime(3) format specification for printing dates. The default
-format is @code{%x} for dates, @code{%X} for times, @code{%x %X} for
-both. This can also be overridden by the @ref{get_date_format_spec}
-hook.
address@hidden(3)} format specification for printing dates. The
+default format is given by the @address@hidden hook;
+the default hook returns @code{%x} for dates, @code{%X} for times,
address@hidden %X} for both.
 
 @item --db <arg>
 Set the database to use; defaults to the database specified in the
@@ -5070,7 +5073,9 @@ @subsection Global Options
 a configuration file is needed.
 
 @item --no-format-dates
-Print date certs exactly as stored in the database.
+Don't use the format provided by a previous @option{--date-format},
+nor the format returned by @address@hidden; instead,
+print dates in the format ``yyyy-mm-ddThh:mm:ss''.
 
 @item --[no-]standard-rcfiles
 Do not load the standard rcfiles, which are
@@ -5130,7 +5135,9 @@ @subsection Common Options
 @ftable @command
 @address@hidden --author
 Override the author cert for a commit; normally, the author is the
-name of the key used for the commit. See @ref{--key}.
+local name of the key used for the commit. See
address@hidden@ref{get_author}}, @address@hidden,
address@hidden@ref{get_local_key_name}}.
 
 @address@hidden --branch
 Specify the branch for a command. This normally defaults to the
@@ -5235,7 +5242,7 @@ @section Tree
 not be the newest revisions, in terms of time, but synchronization of
 computer clocks is not reliable, so monotone usually ignores time.
 
address@hidden mtn import address@hidden address@hidden [--[no-]dry-run] @var{dir}
address@hidden address@hidden mtn import address@hidden address@hidden [--[no-]dry-run] @var{dir}
 @itemx mtn import address@hidden address@hidden [--[no-]dry-run] @var{dir}
 See the online help for more options.
 
@@ -5247,6 +5254,10 @@ @section Tree
 branch already exists, any missing files are dropped and any unknown
 files are added before committing.
 
+If neither @option{--message} nor @option{--message-file} is given,
+the Lua hook @address@hidden is called to provide a commit
+comment, with text formatted as in @address@hidden commit}}.
+
 If @option{--dry-run} is given, no commit is done.
 
 Roughly speaking, @command{mtn import} does the following:
@@ -5562,7 +5573,7 @@ @section Workspace
 
    @end table
 
address@hidden mtn commit
address@hidden address@hidden mtn commit
 @itemx mtn commit address@hidden address@hidden address@hidden
 @itemx mtn commit address@hidden address@hidden
 @itemx mtn ci
@@ -5614,9 +5625,10 @@ @section Workspace
 
 The default definition of @code{edit_comment} invokes the user's
 editor (specified by the environment variables @code{VISUAL} and
address@hidden, or @code{editor, vi}, or @code{notepad} on Windows),
-with text formatted as follows:
address@hidden, or @code{editor, vi}, or @code{notepad} on Windows).
 
address@hidden formats the input to @code{edit_comment} as follows:
+
 @smallexample
 @group
 <contents of _MTN/log>
@@ -5660,6 +5672,13 @@ @section Workspace
 is aborted, and the entire file is saved in @file{_MTN/commit},
 so the user may recover.
 
+The date is formatted with the spec provided by @option{--date-format}
+or Lua hook @address@hidden When the date field is
+parsed, the same spec is used. Therefore this spec must be supported
+by the operating system function for parsing dates; if not, the
+monotone internal format of ``yyyy-mm-ddThh:mm:ss'' is used for both
+formatting and parsing.
+
 @item
 The rest of the text is ignored.
 @end itemize
@@ -6553,20 +6572,23 @@ @section Informative
 If one or more files are given, the command will only log the revisions
 where those files are changed.
 
address@hidden mtn manpage [--formatted/--plain] [--[no-]hidden]
address@hidden address@hidden mtn manpage [--formatted/--plain] [--[no-]hidden]
 The manpage command generates a complete (and if monotone is available
 in your language, also localized) manual page for all available commands,
 including all user-defined Lua commands.
 
-If the command's output is directly written to a terminal, its output is
-automatically formatted using @command{nroff} and displayed in the
address@hidden pager.  If the auto-detection does not work for you for
-some reason, you can enforce the formatting by giving the @option{--formatted}
-option to the command and the @option{--plain} option to achieve the
-opposite, i.e. plain, unformatted troff output.  If you wish to use a
-different formatter or pager, please have a look at the
address@hidden Lua hook.
+The default for @option{--formatted/--plain} depends on whether
address@hidden manpage} is run from a terminal, or from a shell
+script. From a terminal, the default is @option{--formatted}; from a
+script, it is @option{--plain}.
 
+If @option{--formatted}, the output is formatted and displayed using
+the command given by the Lua hook
address@hidden@ref{get_man_page_formatter_command}} (defaults to
address@hidden | less}).
+
+If @option{--plain}, the output is nroff markup.
+
 The option @option{--hidden} additionally enables the output of hidden
 commands and options, which is deactivated by default.
 
@@ -6629,10 +6651,11 @@ @section Review
 
 See @ref{--update}.
 
address@hidden mtn comment @var{rev} address@hidden
address@hidden address@hidden mtn comment @var{rev} address@hidden
 
 This adds a new comment to a committed revision.  If @var{comment} is
-not provided, it is read from @code{stdin}.
+not provided, it is obtained from the Lua hook
address@hidden@ref{edit_comment}}; the hook is passed an empty string.
 
 This command is a synonym for @command{mtn cert @var{rev} comment
 @var{comment}}.
@@ -7276,7 +7299,7 @@ @section Automation
 @end table
 
 
address@hidden mtn automate branches
address@hidden automate address@hidden mtn automate branches
 
 @table @strong
 @item Arguments:
@@ -10968,7 +10991,7 @@ @section Automation
 @item mtn automate sync
 See @address@hidden automate pull}}
 
address@hidden mtn automate tags address@hidden
address@hidden automate address@hidden mtn automate tags address@hidden
 
 @table @strong
 @item Arguments:
@@ -11459,7 +11482,7 @@ @subsection Common Data Types
 argument in the same format, described here.
 
 @ftable @code
address@hidden key_identity
address@hidden@item key_identity
 
 @smallexample
 @group
@@ -11595,7 +11618,7 @@ @subsection Event Notifications and Trig
 The revision id that the cert is attached to.
 
 @item key_identity
-The key that the cert is signed with.
+The key that the cert is signed with; see @address@hidden
 
 @item name
 The name of the cert.
@@ -11618,7 +11641,7 @@ @subsection Event Notifications and Trig
 
 @table @var
 @item key_identity
-The identity of the key received.
+The identity of the key received; see @address@hidden
 
 @item session_id
 Identifies the current netsync session.
@@ -11699,7 +11722,8 @@ @subsection Event Notifications and Trig
 
 @item note_mtn_startup (...)
 
-Called by monotone when it is first started.
+Called by monotone when it is first started, after all command
+completion and option processing, before the command starts executing.
 
 There is no default definition of this hook.
 
@@ -11786,20 +11810,21 @@ @subsection User Defaults
 
 @end table
 
address@hidden get_default_command_options(@var{command})
address@hidden@item get_default_command_options(@var{command})
+Called after a command is completed, before the workspace options are
+loaded, and before the command line options are processed.
 
-Returns a table of program options, either valid for the given command or
-valid global options. The @var{command} argument is given as a table of command
-parts, i.e. for commands with subcommands like @command{automate} or @command{db}
-this argument contains at least two elements.
+Returns a table of options. The options must be valid for the given
+command or global options. The returned option values overwrite the
+standard default options values; workspace and command line options
+override the new defaults as usual.
 
-Note that there is no way to "override" these default options via a given
-command-line option once they've been set. This is especially true if you
-specify options with arguments in this hook such as
address@hidden@var{path}} - no subsequent command-line argument or
address@hidden option argument will be able to replace or remove the
-already excluded @var{path}.
+The argument is a table containing the command keywords, indexed by
+the integer position of the keyword in the command. For example,
address@hidden list branches} passes a table @code{(1 => "list", 2 => "branches")}.
 
+The default definition of this hook returns an empty table.
+
 Simple example which enables recursive directory scanning for @command{mtn add}
 by default:
 @smallexample
@@ -11815,31 +11840,45 @@ @subsection User Defaults
 @end smallexample
 
 @address@hidden get_passphrase (@var{key_identity})
+Called whenever monotone needs to use a private key.
 
-Returns a string which is the passphrase used to encrypt the private
-half of @var{key_identity} in your key store, using the @sc{TripleDES} symmetric
-cipher.  This hook has no default definition. If
-this hook is not defined or returns false, monotone will prompt you for
-a passphrase each time it needs to use a private key.
+Returns a string which must match the passphrase used to encrypt the
+private @address@hidden in your key store.
 
+This hook has no default definition.
+
+If this hook is not defined or returns false, and ssh keys are not
+enabled (see @address@hidden ssh_agent_export}}), monotone will
+prompt you for a passphrase each time it needs to use a private key.
+
 @address@hidden get_local_key_name (@var{key_identity})
 
-Return the local alias for the given key. The @var{id} and @var{given_name}
-fields of @var{key_identity} will be populated, and the @var{name} field
-will not be. The return value indicates what the @var{name} field should
-contain. The default implementation make this the same as @var{given_name}.
+Called whenever monotone retrieves a key from the keystore or
+database, or completes a user-provided key, to provide the local alias
+(the @var{name} field in @address@hidden).
 
+Returns the local alias for the given @var{key_identity}. The
address@hidden and @var{given_name} fields of @var{key_identity} will be
+populated, and the @var{name} field will not be. The return value
+indicates what the @var{name} field should contain.
+
+The default implementation of this hook returns @var{given_name}.
+
 @address@hidden get_author (@var{branchname}, @var{key_identity})
 
-Returns a string which is used as a value for automatically generated
address@hidden certificates when you commit changes to
address@hidden with the keypair identity @var{key_identity}.  Generally
-this hook remains undefined, and monotone selects your signing key name
-for the author certificate. You can use this hook to override that
-choice, if you like.
+Called by any command that needs an author name for an
+author cert for a commit, if @address@hidden is not given.
 
-This hook has no default definition, but a couple of possible
-definitions might be:
+Returns a string which is the author name. If it returns nil, the key
+local name (as provided by @address@hidden) is used
+for the author name.
+
address@hidden is the branch for the commit,
address@hidden@ref{key_identity}} is the key.
+
+There is no default definition for this hook; it returns nil.
+
+Example definitions:
 @smallexample
 @group
 function get_author(branchname, key_identity)
@@ -11864,27 +11903,24 @@ @subsection User Defaults
 @end smallexample
 
 @address@hidden get_default_database_locations ()
+Called whenever monotone converts a database name to an absolute path.
 
-Returns a table of paths where monotone should look for managable
-databases.  The command @address@hidden list databases}} searches all these
-paths for valid monotone databases and outputs details on each one.
+Returns a table of paths where monotone should look for @ref{Managed
+Databases}.
 
 The default implementation returns a table with a single entry,
 @file{$HOME/.monotone/databases} on Unix and
 @file{%APPDATA%\monotone\databases} on Windows.
 
 @address@hidden get_default_database_alias ()
+Called whenever monotone converts a database name to an absolute path.
 
-Returns the alias of the managed database which should be used as default
-for commands like @command{clone} or @command{setup} if these are missing
-an explicit database option.  This alias and the first path found in the
address@hidden hook form the complete path
-of this default database.
+Returns the alias of the managed database which should be used as
+default. See @ref{Managed Databases}.
 
 The default implementation returns @code{:default.mtn}.
 
 @address@hidden get_default_database_glob ()
-
 Returns a pattern to let monotone distinguish a valid from an invalid
 database file name. This pattern is used in two places:
 
@@ -11899,25 +11935,23 @@ @subsection User Defaults
 The default implementation returns @address@hidden,address@hidden
 
 @address@hidden edit_comment (@var{user_log_message})
+Called by @address@hidden comment}}, @address@hidden commit}},
address@hidden@ref{mtn import}} when a comment is not provided on the
+command line.
 
-Returns a log entry for a given set of changes, described in
address@hidden  The user_log_message is identical to the
-output of @command{mtn status}. This hook is intended to interface
-with some sort of editor, so that you can interactively document each
-change you make. Values for @code{author}, @code{date}, @code{branch}
-and the @code{changelog} are extracted from the result and used to
-generate these certificates when you commit changes.
+Returns a commit comment for the command.  @var{user_log_message}
+depends on the calling command; see the command definitions.
 
-The contents of @file{_MTN/log} are read and passed as as the
address@hidden value in @var{user_log_message}. This allows you to
-document your changes as you proceed instead of waiting until you are
-ready to commit. Upon a successful commit, the contents of
address@hidden/log} are erased setting the system up for another
-edit/commit cycle.
+This hook is intended to interface with some sort of editor, so that
+you can interactively document each change you make.
 
-For the default definition of this hook, see @ref{Default hooks}.
+The default definition of @code{edit_comment} invokes the user's
+editor (specified by the environment variables @code{VISUAL} and
address@hidden, or @code{editor, vi}, or @code{notepad} on
+Windows). See @ref{Default hooks}.
 
 @item persist_phrase_ok ()
+Called whenever a passphrase is provided to decrypt a private key.
 
 Returns @code{true} if you want monotone to remember the passphrase of
 a private key for the duration of a single command, or @code{false} if
@@ -11926,82 +11960,82 @@ @subsection User Defaults
 quick succession, unless you are very concerned about security you
 probably want this hook to return @code{true}.
 
-The default definition of this hook is:
address@hidden
address@hidden
-function persist_phrase_ok()
-        return true
-end
address@hidden group
address@hidden smallexample
+The default definition of this hook returns @code{true}.
 
 @item use_inodeprints ()
+Called when creating a new workspace.
 
 Returns @code{true} if you want monotone to automatically enable
address@hidden support in all workspaces.  Only affects working
-copies created after you modify the hook.
address@hidden support in the workspace.
 
-The default definition of this hook is:
address@hidden
address@hidden
-function use_inodeprints()
-        return false
-end
address@hidden group
address@hidden smallexample
+The default definition of this hook returns @code{false}.
 
 @address@hidden ignore_file (@var{filename})
+Called by many monotone commands when considering whether to process a
+file in a workspace.
 
-Returns @code{true} if @var{filename} should be ignored while adding,
-dropping, or moving files. Otherwise returns @code{false}. This is
-most important when performing recursive actions on directories, which
-may affect multiple files simultaneously.
+Returns @code{true} if @var{filename} should be ignored by the
+command, @code{false} otherwise.
 
+This is most important when performing recursive actions on
+directories; if @code{ignore_file} returns @code{true} for a
+directory, all files under that directory will be ignored.
+
+In some commands, @option{--no-ignore} will cause this hook to not be
+called.
+
 The default definition of this hook recognises a number of common file
 types and extensions for temporary and generated file types that users
 typically don't want to track. In addition, if the file
 @file{.mtn-ignore} exists in the root workspace directory, this hook
 will read a list of regular expressions from the file, one per line,
-and ignore all files matching one of these expressions. For the
-default definition of this hook, see @ref{Default hooks}.
+and ignore all files matching one of these expressions. See
address@hidden hooks}.
 
 @address@hidden ignore_branch (@var{branchname})
 
-Returns @code{true} if @var{branchname} should be ignored while listing
-branches. Otherwise returns @code{false}. This hook has no default
-definition, therefore the default behavior is to list all branches.
+Called by @address@hidden automate branches}}, @address@hidden
+automate tags}}, @address@hidden list branches}}.
 
+Returns @code{true} if @var{branchname} should be ignored by the
+command, otherwise returns @code{false}.
+
+This hook has no default definition; it acts as if it returns false.
+
 @address@hidden get_date_format_spec (@var{wanted})
+Called by commands that display dates, when neither
address@hidden nor @option{--no-format-dates} is given.
 
-Returns a @code{strftime} format specification, which @command{mtn
-log} and similar commands will use to format dates, unless instructed
-otherwise.  The default definition returns @samp{%x} for long and short
+Returns a @code{strftime} format specification.
+
+If an empty string is returned, monotone uses the date format
+``yyyy-mm-ddThh:mm:ss''.
address@hidden see dates.cc date_t::as_iso_8601_extended
+
+The default definition returns @samp{%x} for long and short
 date formats, @samp{%X} for long and short time formats and @samp{%x %X}
 for long and short date time formats, which is equivalent to @samp{22/05/09},
 @samp{09:06:14} and @samp{22/05/09 09:06:14} in an English locale.
 
 @var{wanted} can be one of @samp{date_long}, @samp{date_short},
address@hidden, @samp{time_short}, @samp{date_time_long} and
address@hidden, though only @samp{date_short} and
address@hidden are currently used.
address@hidden, @samp{time_short}, @samp{date_time_long},
address@hidden
 
-The @samp{date_time_long} format is used by the @command{status},
address@hidden and @command{log} commands to format revision dates
-for printing. This format must preserve a date passed through a
-formatting and parsing cycle. Otherwise the @command{status} command
-will issue warnings that the format is unsuitable and the
address@hidden command will abort.
address@hidden@item get_man_page_formatter_command ()
+Called by @address@hidden manpage}}, if @option{--formatted} is specified.
 
address@hidden@item get_man_page_formatter_command ()
+Returns a command string that is passed to the operating system
+function @code{popen} to format man pages. The input to the pipe is
address@hidden markup.
 
-Specifies the command chain which should be executed if the
address@hidden command is executed interactively. The default is
-to call the @command{nroff} formatter and pipe that output into the
address@hidden pager.
+Note that on the native Windows build of monotone, @code{popen} runs
+the @command{cmd.exe} shell to execute the command string. On Unix and
+Windows Cygwin, @code{popen} runs the @command{sh} shell.
 
-Note that on the native Windows build of monotone, the command
-specified by this hook is run in the @command{cmd.exe} shell. On Unix
-and Cygwin, it is run in the @command{sh} shell.
+The default hook returns a string that runs @command{nroff} and pipes
+that output into the @command{less} pager, with appropriate
+options. On Windows native, the default hook assumes that Cygwin or
+equivalent is installed, and includes @code{sh} in the command string.
 
 @end ftable
 
============================================================
--- tests/changelog_editor/__driver__.lua	5e7b3272a2620ff1f924cdf20c4b853f07eaa4e3
+++ tests/changelog_editor/__driver__.lua	0eccf936ef1688640f00aba6c786ad14c3ddb3cf
@@ -104,7 +104,7 @@ if ostype == "Windows" then
 check(mtn("commit", "--date-format", "%Y-%m-%d", "--rcfile=changelog.lua"), 0, false, true)
 if ostype == "Windows" then
    -- date parsing never works on Win32, so
-   -- get_default_command_options specifies --no-format-dates, and
+   -- CMD_PRESET_OPTIONS(commit) specifies --no-format-dates, and
    -- we don't get a warning message.
 else
    check(qgrep("warning: .* using default instead", "stderr"))