doc/README

shelve: refactor option combination check to easily add new ones

Before this patch, the name of a newly added option had to be added
into each string that was passed to the "checkopt()" internal
function: these are white-space-separated list of un-acceptable option
names (= "black list" for the specified "opt").

This new option had to be added into multiple strings because each
option could belong to only one action of "create", "cleanup",
"delete" or "list".

In addition to this redundancy, each string passed to "checkopt()" was
already too long to include a new one.

This patch refactors option combination check to make it easier to add
a new option in a subsequent patch.

New "checkopt()" only takes one action ("cleanup", "delete" or
"list"), and checks whether all explicitly activated options are
allowed for it or not (if specified action is activated in "opts").

The "date" entry is listed in "allowables", but commented out,
because:

  - "date" shouldn't be checked for test

    checking "date" causes unexpected failure of "test-shelve.t",
    because "run-test.py" puts "[default] shelve = --date '0 0'" into
    hgrc.

  - explicitly listing it can advertise that ignoring it is intentional

This patch doesn't choose "white list" for the specified "opt", to
avoid treating global options.

Mercurial's documentation is kept in reStructuredText format, which is
a simple plain text format that's easy to read and edit:

  http://docutils.sourceforge.net/rst.html

It's also convertible to a variety of other formats including standard
UNIX man page format and HTML. You'll need to install Docutils:

  http://docutils.sourceforge.net/

Use the Makefile in this directory to generate the man and HTML pages.