generate hg manpage from commands.py docstring

gendoc.py is a script generating a part of the manpage (the commands
help and options) from the docstring in commands.py.
It avoids duplicating the doc between the doc/ directory and the docstrings.
To generate the manpage, 'make doc' will create all the necessary intermediate
files.

doc/gendoc.py

@@ -0,0 +1,92 b''
+import sys, textwrap
+# import from the live mercurial repo
+sys.path.insert(0, "..")
+from mercurial.commands import table, globalopts
+from mercurial.i18n import gettext as _
+
+def get_desc(docstr):
+    if not docstr:
+        return "", ""
+    # sanitize
+    docstr = docstr.strip("\n")
+    docstr = docstr.rstrip()
+    shortdesc = docstr.splitlines()[0].strip()
+
+    i = docstr.find("\n")
+    if i != -1:
+        desc = docstr[i+2:]
+    else:
+        desc = "    %s" % shortdesc
+    return (shortdesc, desc)
+
+def get_opts(opts):
+    for shortopt, longopt, default, desc in opts:
+        allopts = []
+        if shortopt:
+            allopts.append("-%s" % shortopt)
+        if longopt:
+            allopts.append("--%s" % longopt)
+        desc += default and _(" (default: %s)") % default or ""
+        yield(", ".join(allopts), desc)
+
+def get_cmd(cmd):
+    d = {}
+    attr = table[cmd]
+    cmds = cmd.lstrip("^").split("|")
+
+    d['synopsis'] = attr[2]
+    d['cmd'] = cmds[0]
+    d['aliases'] = cmd.split("|")[1:]
+    d['desc'] = get_desc(attr[0].__doc__)
+    d['opts'] = list(get_opts(attr[1]))
+    return d
+
+
+def show_doc(ui):
+    def bold(s, text=""):
+        ui.write("%s\n%s\n%s\n" % (s, "="*len(s), text))
+    def underlined(s, text=""):
+        ui.write("%s\n%s\n%s\n" % (s, "-"*len(s), text))
+
+    # print options
+    underlined(_("OPTIONS"))
+    for optstr, desc in get_opts(globalopts):
+        ui.write("%s::\n    %s\n\n" % (optstr, desc))
+
+    # print cmds
+    underlined(_("COMMANDS"))
+    h = {}
+    for c, attr in table.items():
+            f = c.split("|")[0]
+            f = f.lstrip("^")
+            h[f] = c
+    cmds = h.keys()
+    cmds.sort()
+
+    for f in cmds:
+            if f.startswith("debug"): continue
+            d = get_cmd(h[f])
+            # synopsis
+            ui.write("%s::\n" % d['synopsis'].replace("hg ","", 1))
+            # description
+            ui.write("%s\n\n" % d['desc'][1])
+            # options
+            opt_output = list(d['opts'])
+            if opt_output:
+                opts_len = max([len(line[0]) for line in opt_output])
+                ui.write(_("    options:\n"))
+                for optstr, desc in opt_output:
+                    if desc:
+                        s = "%-*s  %s" % (opts_len, optstr, desc)
+                    else:
+                        s = optstr
+                    s = textwrap.fill(s, initial_indent=4 * " ",
+                                      subsequent_indent=(6 + opts_len) * " ")
+                    ui.write("%s\n" % s)
+                ui.write("\n")
+            # aliases
+            if d['aliases']:
+                ui.write(_("    aliases: %s\n\n") % " ".join(d['aliases']))
+
+if __name__ == "__main__":
+    show_doc(sys.stdout)

doc/Makefile

@@ -8,6 +8,12 b' man: $(MAN)'
 
 html: $(HTML)
 
+hg.1.txt: hg.1.gendoc.txt
+	touch hg.1.txt
+
+hg.1.gendoc.txt:
+	python gendoc.py > $@
+
 %: %.xml
 	xmlto man $*.xml
 

doc/hg.1.txt

@@ -14,42 +14,6 b' DESCRIPTION'
 -----------
 The hg(1) command provides a command line interface to the Mercurial system.
 
-OPTIONS
--------
-
--R, --repository::
-    repository root directory
-
---cwd::
-    change working directory
-
--y, --noninteractive::
-    do not prompt, assume 'yes' for any required answers
-
--q, --quiet::
-    suppress output
-
--v, --verbose::
-    enable additional output
-
---debug::
-    enable debugging output
-
---traceback::
-    print traceback on exception
-
---time::
-    time how long the command takes
-
---profile::
-    print command execution profile
-
---version::
-    output version information and exit
-
--h, --help::
-    display help and exit
-
 COMMAND ELEMENTS
 ----------------
 
@@ -70,593 +34,8 b' repository path::'
     fast and the old-http:// protocol which is much slower but does not
     require a special server on the web host.
 
-COMMANDS
---------
 
-add [options] [files ...]::
-    Schedule files to be version controlled and added to the repository.
-
-    The files will be added to the repository at the next commit.
-
-    If no names are given, add all files in the current directory and
-    its subdirectories.
-
-addremove [options] [files ...]::
-    Add all new files and remove all missing files from the repository.
-
-    New files are ignored if they match any of the patterns in .hgignore. As
-    with add, these changes take effect at the next commit.
-
-annotate [-r <rev> -u -n -c -d] [files ...]::
-    List changes in files, showing the revision id responsible for each line
-
-    This command is useful to discover who did a change or when a change took
-    place.
-
-    Without the -a option, annotate will avoid processing files it
-    detects as binary. With -a, annotate will generate an annotation
-    anyway, probably with undesirable results.
-
-    options:
-    -a, --text            treat all files as text
-    -I, --include <pat>   include names matching the given patterns
-    -X, --exclude <pat>   exclude names matching the given patterns
-    -r, --revision <rev>  annotate the specified revision
-    -u, --user            list the author
-    -d, --date            list the commit date
-    -c, --changeset       list the changeset
-    -n, --number          list the revision number (default)
-
-bundle <file> <other>::
-    (EXPERIMENTAL)
-
-    Generate a compressed changegroup file collecting all changesets
-    not found in the other repository.
-
-    This file can then be transferred using conventional means and
-    applied to another repository with the unbundle command. This is
-    useful when native push and pull are not available or when
-    exporting an entire repository is undesirable. The standard file
-    extension is ".hg".
-
-    Unlike import/export, this exactly preserves all changeset
-    contents including permissions, rename data, and revision history.
-
-cat [options] <file ...>::
-    Print the specified files as they were at the given revision.
-    If no revision is given then the tip is used.
-
-    Output may be to a file, in which case the name of the file is
-    given using a format string.  The formatting rules are the same as
-    for the export command, with the following additions:
-
-    %s   basename of file being printed
-    %d   dirname of file being printed, or '.' if in repo root
-    %p   root-relative path name of file being printed
-
-    options:
-    -I, --include <pat>       include names matching the given patterns
-    -X, --exclude <pat>       exclude names matching the given patterns
-    -o, --output <filespec>   print output to file with formatted name
-    -r, --rev <rev>           print the given revision
-
-clone [options] <source> [dest]::
-    Create a copy of an existing repository in a new directory.
-
-    If no destination directory name is specified, it defaults to the
-    basename of the source.
-
-    The location of the source is added to the new repository's
-    .hg/hgrc file, as the default to be used for future pulls.
-
-    For efficiency, hardlinks are used for cloning whenever the source
-    and destination are on the same filesystem.  Some filesystems,
-    such as AFS, implement hardlinking incorrectly, but do not report
-    errors.  In these cases, use the --pull option to avoid
-    hardlinking.
-
-    See pull for valid source format details.
-
-    options:
-    -U, --noupdate   do not update the new working directory
-    --pull           use pull protocol to copy metadata
-    -e, --ssh        specify ssh command to use
-    --remotecmd      specify hg command to run on the remote side
-
-commit [options] [files...]::
-    Commit changes to the given files into the repository.
-
-    If a list of files is omitted, all changes reported by "hg status"
-    from the root of the repository will be commited.
-
-    The HGEDITOR or EDITOR environment variables are used to start an
-    editor to add a commit comment.
-
-    Options:
-
-    -A, --addremove       run addremove during commit
-    -I, --include <pat>   include names matching the given patterns
-    -X, --exclude <pat>   exclude names matching the given patterns
-    -m, --message <text>  use <text> as commit message
-    -l, --logfile <file>  read the commit message from <file>
-    -d, --date <datecode> record datecode as commit date
-    -u, --user <user>     record user as commiter
-
-    aliases: ci
-
-copy <source ...> <dest>::
-    Mark dest as having copies of source files.  If dest is a
-    directory, copies are put in that directory.  If dest is a file,
-    there can only be one source.
-
-    By default, this command copies the contents of files as they
-    stand in the working directory.  If invoked with --after, the
-    operation is recorded, but no copying is performed.
-
-    This command takes effect in the next commit.
-
-    NOTE: This command should be treated as experimental. While it
-    should properly record copied files, this information is not yet
-    fully used by merge, nor fully reported by log.
-
-    Options:
-    -A, --after           record a copy that has already occurred
-    -I, --include <pat>   include names matching the given patterns
-    -X, --exclude <pat>   exclude names matching the given patterns
-    -f, --force           forcibly copy over an existing managed file
-
-    aliases: cp
-
-diff [-a] [-r revision] [-r revision] [files ...]::
-    Show differences between revisions for the specified files.
-
-    Differences between files are shown using the unified diff format.
-
-    When two revision arguments are given, then changes are shown
-    between those revisions. If only one revision is specified then
-    that revision is compared to the working directory, and, when no
-    revisions are specified, the working directory files are compared
-    to its parent.
-
-    Without the -a option, diff will avoid generating diffs of files
-    it detects as binary. With -a, diff will generate a diff anyway,
-    probably with undesirable results.
-
-    options:
-    -a, --text              treat all files as text
-    -I, --include <pat>     include names matching the given patterns
-    -p, --show-function     show which function each change is in
-    -X, --exclude <pat>     exclude names matching the given patterns
-    -w, --ignore-all-space  ignore white space when comparing lines
-
-export [-o filespec] [revision] ...::
-    Print the changeset header and diffs for one or more revisions.
-
-    The information shown in the changeset header is: author,
-    changeset hash, parent and commit comment.
-
-    Output may be to a file, in which case the name of the file is
-    given using a format string.  The formatting rules are as follows:
-
-    %%   literal "%" character
-    %H   changeset hash (40 bytes of hexadecimal)
-    %N   number of patches being generated
-    %R   changeset revision number
-    %b   basename of the exporting repository
-    %h   short-form changeset hash (12 bytes of hexadecimal)
-    %n   zero-padded sequence number, starting at 1
-    %r   zero-padded changeset revision number
-
-    Without the -a option, export will avoid generating diffs of files
-    it detects as binary. With -a, export will generate a diff anyway,
-    probably with undesirable results.
-
-    options:
-    -a, --text                treat all files as text
-    -o, --output <filespec>   print output to file with formatted name
-
-forget [options] [files]::
-    Undo an 'hg add' scheduled for the next commit.
-
-    options:
-    -I, --include <pat>  include names matching the given patterns
-    -X, --exclude <pat>  exclude names matching the given patterns
-
-grep [options] pattern [files]::
-    Search revisions of files for a regular expression.
-
-    This command behaves differently than Unix grep.  It only accepts
-    Python/Perl regexps.  It searches repository history, not the
-    working directory.  It always prints the revision number in which
-    a match appears.
-
-    By default, grep only prints output for the first revision of a
-    file in which it finds a match.  To get it to print every revision
-    that contains a change in match status ("-" for a match that
-    becomes a non-match, or "+" for a non-match that becomes a match),
-    use the --all flag.
-
-    options:
-    -0, --print0              end fields with NUL
-    -I, --include <pat>       include names matching the given patterns
-    -X, --exclude <pat>       exclude names matching the given patterns
-        --all                 print all revisions that match
-    -i, --ignore-case         ignore case when matching
-    -l, --files-with-matches  print only filenames and revs that match
-    -n, --line-number         print matching line numbers
-    -r <rev>, --rev <rev>     search in given revision range
-    -u, --user                print user who committed change
-
-heads::
-    Show all repository head changesets.
-
-    Repository "heads" are changesets that don't have children
-    changesets. They are where development generally takes place and
-    are the usual targets for update and merge operations.
-
-identify::
-    Print a short summary of the current state of the repo.
-
-    This summary identifies the repository state using one or two parent
-    hash identifiers, followed by a "+" if there are uncommitted changes
-    in the working directory, followed by a list of tags for this revision.
-
-    aliases: id
-
-import [-p <n> -b <base> -f] <patches>::
-    Import a list of patches and commit them individually.
-
-    If there are outstanding changes in the working directory, import
-    will abort unless given the -f flag.
-
-    If a patch looks like a mail message (its first line starts with
-    "From " or looks like an RFC822 header), it will not be applied
-    unless the -f option is used.  The importer neither parses nor
-    discards mail headers, so use -f only to override the "mailness"
-    safety check, not to import a real mail message.
-
-    options:
-    -p, --strip <n>   directory strip option for patch. This has the same
-                      meaning as the corresponding patch option
-    -b <path>         base directory to read patches from
-    -f, --force       skip check for outstanding uncommitted changes
-
-    aliases: patch
-
-incoming [-p] [source]::
-    Show new changesets found in the specified repo or the default
-    pull repo. These are the changesets that would be pulled if a pull
-    was requested.
-
-    Currently only local repositories are supported.
-
-    options:
-    -p, --patch           show patch
-
-    aliases: in
-
-init [dest]::
-    Initialize a new repository in the given directory.  If the given
-    directory does not exist, it is created.
-
-    If no directory is given, the current directory is used.
-
-locate [options] [files]::
-    Print all files under Mercurial control whose names match the
-    given patterns.
-
-    This command searches the current directory and its
-    subdirectories.  To search an entire repository, move to the root
-    of the repository.
-
-    If no patterns are given to match, this command prints all file
-    names.
-
-    If you want to feed the output of this command into the "xargs"
-    command, use the "-0" option to both this command and "xargs".
-    This will avoid the problem of "xargs" treating single filenames
-    that contain white space as multiple filenames.
-
-    options:
-
-    -0, --print0         end filenames with NUL, for use with xargs
-    -f, --fullpath       print complete paths from the filesystem root
-    -I, --include <pat>  include names matching the given patterns
-    -r, --rev <rev>      search the repository as it stood at rev
-    -X, --exclude <pat>  exclude names matching the given patterns
-
-log [-r revision ...] [-p] [files]::
-    Print the revision history of the specified files or the entire project.
-
-    By default this command outputs: changeset id and hash, tags,
-    parents, user, date and time, and a summary for each commit. The
-    -v switch adds some more detail, such as changed files, manifest
-    hashes or message signatures.
-
-    options:
-    -I, --include <pat>   include names matching the given patterns
-    -X, --exclude <pat>   exclude names matching the given patterns
-    -b, --branch          show branches
-    -k, --keyword <str>   search for keywords
-    -l, --limit <num>     print no more than this many changes
-    -M, --no-merges       do not show merges
-    -m, --only-merges     only show merges
-    -r, --rev <A>         show the specified revision or range
-    -p, --patch           show patch
-
-    aliases: history
-
-manifest [revision]::
-    Print a list of version controlled files for the given revision.
-
-    The manifest is the list of files being version controlled. If no revision
-    is given then the tip is used.
-
-outgoing [-p] [dest]::
-    Show changesets not found in the specified destination repo or the
-    default push repo. These are the changesets that would be pushed
-    if a push was requested.
-
-    See pull for valid source format details.
-
-    options:
-    -p, --patch           show patch
-
-    aliases: out
-
-parents::
-    Print the working directory's parent revisions.
-
-paths [NAME]::
-    Show definition of symbolic path name NAME. If no name is given, show
-    definition of available names.
-
-    Path names are defined in the [paths] section of /etc/mercurial/hgrc
-    and $HOME/.hgrc.  If run inside a repository, .hg/hgrc is used, too.
-
-pull <repository path>::
-    Pull changes from a remote repository to a local one.
-
-    This finds all changes from the repository at the specified path
-    or URL and adds them to the local repository. By default, this
-    does not update the copy of the project in the working directory.
-
-    Valid URLs are of the form:
-
-      local/filesystem/path
-      http://[user@]host[:port][/path]
-      https://[user@]host[:port][/path]
-      ssh://[user@]host[:port][/path]
-
-    SSH requires an accessible shell account on the destination machine
-    and a copy of hg in the remote path.  With SSH, paths are relative
-    to the remote user's home directory by default; use two slashes at
-    the start of a path to specify it as relative to the filesystem root.
-
-    options:
-    -u, --update   update the working directory to tip after pull
-    -e, --ssh    specify ssh command to use
-    --remotecmd  specify hg command to run on the remote side
-
-push <destination>::
-    Push changes from the local repository to the given destination.
-
-    This is the symmetrical operation for pull. It helps to move
-    changes from the current repository to a different one. If the
-    destination is local this is identical to a pull in that directory
-    from the current one.
-
-    By default, push will refuse to run if it detects the result would
-    increase the number of remote heads. This generally indicates the
-    the client has forgotten to sync and merge before pushing.
-
-    Valid URLs are of the form:
-
-      local/filesystem/path
-      ssh://[user@]host[:port][/path]
-
-    SSH requires an accessible shell account on the destination
-    machine and a copy of hg in the remote path.
-
-    options:
-
-    -f, --force  force update
-    -e, --ssh    specify ssh command to use
-    --remotecmd  specify hg command to run on the remote side
-
-rawcommit [-p -d -u -F -m -l]::
-    Lowlevel commit, for use in helper scripts. (DEPRECATED)
-
-    This command is not intended to be used by normal users, as it is
-    primarily useful for importing from other SCMs.
-
-    This command is now deprecated and will be removed in a future
-    release, please use debugsetparents and commit instead.
-
-recover::
-    Recover from an interrupted commit or pull.
-
-    This command tries to fix the repository status after an interrupted
-    operation. It should only be necessary when Mercurial suggests it.
-
-remove [options] [files ...]::
-    Schedule the indicated files for removal from the repository.
-
-    This command schedules the files to be removed at the next commit.
-    This only removes files from the current branch, not from the
-    entire project history.  If the files still exist in the working
-    directory, they will be deleted from it.
-
-    aliases: rm
-
-rename <source ...> <dest>::
-    Mark dest as copies of sources; mark sources for deletion.  If
-    dest is a directory, copies are put in that directory.  If dest is
-    a file, there can only be one source.
-
-    By default, this command copies the contents of files as they
-    stand in the working directory.  If invoked with --after, the
-    operation is recorded, but no copying is performed.
-
-    This command takes effect in the next commit.
-
-    NOTE: This command should be treated as experimental. While it
-    should properly record rename files, this information is not yet
-    fully used by merge, nor fully reported by log.
-
-    Options:
-    -A, --after        record a rename that has already occurred
-    -f, --force        forcibly copy over an existing managed file
-
-    aliases: mv
-
-revert [names ...]::
-    The revert command has two modes of operation.
-
-    In its default mode, it reverts any uncommitted modifications made
-    to the named files or directories.  This restores the contents of
-    the affected files to an unmodified state.
-
-    Using the -r option, it reverts the given files or directories to
-    their state as of an earlier revision.  This can be helpful to "roll
-    back" some or all of a change that should not have been committed.
-
-    Revert modifies the working directory.  It does not commit any
-    changes, or change the parent of the current working directory.
-
-    If a file has been deleted, it is recreated.  If the executable
-    mode of a file was changed, it is reset.
-
-    If a directory is given, all files in that directory and its
-    subdirectories are reverted.
-
-    If no arguments are given, all files in the current directory and
-    its subdirectories are reverted.
-
-    options:
-    -r, --rev <rev>       revision to revert to
-    -n, --nonrecursive    do not recurse into subdirectories
-
-root::
-    Print the root directory of the current repository.
-
-serve [options]::
-    Start a local HTTP repository browser and pull server.
-
-    By default, the server logs accesses to stdout and errors to
-    stderr.  Use the "-A" and "-E" options to log to files.
-
-    options:
-    -A, --accesslog <file>   name of access log file to write to
-    -d, --daemon             run server in background, as a daemon
-    -E, --errorlog <file>    name of error log file to write to
-    -a, --address <addr>     address to use
-    -p, --port <n>           port to use (default: 8000)
-    -n, --name <name>        name to show in web pages (default: working dir)
-    --pid-file <file>        write server process ID to given file
-    -t, --templatedir <path> web templates to use
-    -6, --ipv6               use IPv6 in addition to IPv4
-
-status [options] [files]::
-    Show changed files in the working directory.  If no names are
-    given, all files are shown.  Otherwise, only files matching the
-    given names are shown.
-
-    The codes used to show the status of files are:
-
-    M = changed
-    A = added
-    R = removed
-    ? = not tracked
-
-    options:
-
-    -m, --modified       show only modified files
-    -a, --added          show only added files
-    -r, --removed        show only removed files
-    -u, --unknown        show only unknown (not tracked) files
-    -n, --no-status      hide status prefix
-    -0, --print0         end filenames with NUL, for use with xargs
-    -I, --include <pat>  include names matching the given patterns
-    -X, --exclude <pat>  exclude names matching the given patterns
-
-tag [-l -m <text> -d <datecode> -u <user>] <name> [revision]::
-    Name a particular revision using <name>.
-
-    Tags are used to name particular revisions of the repository and are
-    very useful to compare different revision, to go back to significant
-    earlier versions or to mark branch points as releases, etc.
-
-    If no revision is given, the tip is used.
-
-    To facilitate version control, distribution, and merging of tags,
-    they are stored as a file named ".hgtags" which is managed
-    similarly to other project files and can be hand-edited if
-    necessary.
-
-    options:
-    -l, --local           make the tag local
-    -m, --message <text>  message for tag commit log entry
-    -d, --date <datecode> datecode for commit
-    -u, --user <user>     user for commit
-
-    Note: Local tags are not version-controlled or distributed and are
-    stored in the .hg/localtags file. If there exists a local tag and
-    a public tag with the same name, local tag is used.
-
-tags::
-    List the repository tags.
-
-    This lists both regular and local tags.
-
-tip [-p]::
-    Show the tip revision.
-
-    options:
-    -p, --patch      show patch
-
-unbundle <file>::
-    (EXPERIMENTAL)
-
-    Apply a compressed changegroup file generated by the bundle
-    command.
-
-undo::
-    Undo the last commit or pull transaction.
-
-    Roll back the last pull or commit transaction on the
-    repository, restoring the project to its earlier state.
-
-    This command should be used with care. There is only one level of
-    undo and there is no redo.
-
-    This command is not intended for use on public repositories. Once
-    a change is visible for pull by other users, undoing it locally is
-    ineffective.
-
-update [-m -C] [revision]::
-    Update the working directory to the specified revision.
-
-    By default, update will refuse to run if doing so would require
-    merging or discarding local changes.
-
-    With the -m option, a merge will be performed.
-
-    With the -C option, local changes will be lost.
-
-    options:
-    -m, --merge       allow merging of branches
-    -C, --clean       overwrite locally modified files
-
-    aliases: up checkout co
-
-verify::
-    Verify the integrity of the current repository.
-
-    This will perform an extensive check of the repository's
-    integrity, validating the hashes and checksums of each entry in
-    the changelog, manifest, and tracked files, as well as the
-    integrity of their crosslinks and indices.
+include::hg.1.gendoc.txt[]
 
 FILE NAME PATTERNS
 ------------------