error in doc/hg.1.txt

TK Soh teekaysoh at yahoo.com
Mon Aug 8 07:21:56 CDT 2005


--- Thomas Arendsen Hein <thomas at intevation.de> wrote:
> * TK Soh <teekaysoh at yahoo.com> [20050807 13:48]:

[...]

> > IMO, the arguments to command options should use the same
> all-capital-letter
> > convention also. Let me know if you want me to clean them up.
> 
> Just do here what you think is the best way for the man page. Final
> decision is still Matt's.

I think I will leave this till later, just so that it doesn't hinder the
changes that have been made.

> > I also noticed the online help for some commands, such as annotate, aren't
> > observing the same convention. Probably need to clean up too.
> 
> Online help is 'hg help annotate' or some web page?

I was refering to 'hg help annotate', sorry for the confusion. Maybe we should
call it run-time help?

> 'hg help annotate' looks good to me, maybe you've misread the --rev
> long option.

Currently 'hg help annotate' give this:

    hg annotate [-r REV] [-u] [-n] [-c] FILE...

which I thought perhaps should be changed to the 'standard' format:

    hg [OPTION]... FILE...

> > -'hg' [-v -d -q -y] <command> [command options] [files]
> > +'hg' [global options] <command> [command options] [files]
> 
> Maybe better:
> hg [COMMAND] [OPTION]... [ARGUMENT]...
> 
> Global options can be specified directly after 'hg', but they can be
> after the command, too. But I don't think the user needs to know
> this details. If he puts all options after the command, everything
> will be fine.
> 
> > -add [options] [files ...]::
> > +add [OPTION]... [FILE]::
> 
> It's [FILE]..., because you can specify more than one file.
> 
> > +annotate [OPTION]... [FILE]...::
> 
> Here better FILE..., because you have to give at least one file.
> 
> > -import [-p <n> -b <base> -q] <patches>::
> > +import [OPTION]... PATCH ...::
> 
> PATCH... (without space)
> 
> Additionally this is an example where there are only few options, so
> hg import [-p NUM] [-b BASE] PATCH...
> would have given more useful information.

For now most commands have rather short list of options. But for simplicity,
I'd like to suggest we use the "COMMAND [OPTION]... [ARGS]..." convention,
which should make things easier as the list of options grow longer, or more
commands are added.

> > -locate [options] [files]::
> > +locate [OPTION]... [FILE]::
> 
> [PATTERN]...
> Though this may be true for many commands, now that the new walking
> code is more used.

I've updated these in the patch.

> > +pull [OPTION]... [SOURCE]::
> > +    Pull changes from repository SOURCE to a local one.
> 
> Looks much better than before, as SOURCE may be local, too.
> 
> I didn't apply this yet as you said it is only a draft. Just say if
> you think it is ready to be included.

I knew there'd be more changes, so I called it a draft. Anyway, I have attached
the 'official' patch for commit if you're okay with it, else let me know if
there's more to fix.



		
____________________________________________________
Start your day with Yahoo! - make it your home page 
http://www.yahoo.com/r/hs 
 
-------------- next part --------------
# HG changeset patch
# User tksoh at users.sourceforge.net
# Node ID 6369cd3013564b2ed3472ec6958ebde08b8e8521
# Parent  9c918287d10b4018e27f9148e247e68ff5fe952c
Updated manpage to standardise on command synopsises, etc.

Updated manpage to use standard Unix style on command 
sypnosises. Also added some missing options and made a 
few corrections here and there.

diff -r 9c918287d10b -r 6369cd301356 doc/hg.1.txt
--- a/doc/hg.1.txt	Thu Aug  4 21:31:25 2005
+++ b/doc/hg.1.txt	Mon Aug  8 11:57:58 2005
@@ -8,25 +8,25 @@
 
 SYNOPSIS
 --------
-'hg' [-v -d -q -y] <command> [command options] [files]
+'hg' COMMAND [OPTION]... [ARGUMENT]...
 
 DESCRIPTION
 -----------
 The hg(1) command provides a command line interface to the Mercurial system.
 
-OPTIONS
--------
-
---debug, -d::
+GLOBAL_OPTIONS
+--------------
+
+--debug::
     enable debugging output
 
---quiet, -q::
+-q, --quiet::
     suppress output
 
---verbose, -v::
+-v, --verbose::
     enable additional output
 
---noninteractive, -y::
+-y, --noninteractive::
     do not prompt, assume 'yes' for any required answers
 
 COMMAND ELEMENTS
@@ -52,7 +52,7 @@
 COMMANDS
 --------
 
-add [options] [files ...]::
+add [OPTION]... [FILE]...::
     Schedule files to be version controlled and added to the repository.
     
     The files will be added to the repository at the next commit.
@@ -60,33 +60,41 @@
     If no names are given, add all files in the current directory and
     its subdirectories.
 
-addremove [options] [files ...]::
+    Options:
+    -I, --include <pat>   include names matching the given patterns
+    -X, --exclude <pat>   exclude names matching the given patterns
+
+addremove [OPTION]... [FILE]...::
     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] [files ...]::
+    Options:
+    -I, --include <pat>   include names matching the given patterns
+    -X, --exclude <pat>   exclude names matching the given patterns
+
+annotate [OPTION]... [FILE]...::
     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.
     
-    options:
+    Options:
     -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
+    -r, --rev <rev>       annotate the specified revision
     -u, --user            list the author
     -c, --changeset       list the changeset
     -n, --number          list the revision number (default)
 
-cat <file> [revision]::
-    Output to stdout the given revision for the specified file.
+cat FILE [REV]::
+    Output to stdout the revision REV for file FILE.
 
     If no revision is given then the tip is used.
 
-clone [-U] <source> [dest]::
-    Create a copy of an existing repository in a new directory.
+clone [OPTION]... SOURCE [DEST]::
+    Create a copy of an existing repository SOURCE in a new directory DEST.
 
     If no destination directory name is specified, it defaults to the
     basename of the source.
@@ -97,10 +105,10 @@
     For efficiency, hardlinks are used for cloning whenever the
     source and destination are on the same filesystem.
 
-    options:
+    Options:
     -U, --noupdate   do not update the new working directory
 
-commit [options] [files...]::
+commit [OPTION]... [FILE]...::
     Commit changes to the given files into the repository.
     
     If a list of files is omitted, all changes reported by "hg status"
@@ -110,23 +118,22 @@
     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>  show the commit message for the given file
+    -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> file as a copy or rename of a <source> one
+copy SOURCE DEST::
+    Mark file DEST as a copy or rename of SOURCE
     
     This command takes effect for the next commit.
 
-diff [-r revision] [-r revision] [files ...]::
+diff [OPTION]... [-r REV1 [-r REV2]] [FILE]...::
     Show differences between revisions for the specified files.
     
     Differences between files are shown using the unified diff format.
@@ -137,11 +144,11 @@
     revisions are specified, the working directory files are compared
     to its parent.
 
-    options:
+    Options:
     -I, --include <pat>  include names matching the given patterns
     -X, --exclude <pat>  exclude names matching the given patterns
 
-export [-o filespec] [revision] ...::
+export [OPTION]... [REV]...::
     Print the changeset header and diffs for one or more revisions.
 
     The information shown in the changeset header is: author,
@@ -160,13 +167,12 @@
     %r   zero-padded changeset revision number
 
     Options:
-
     -o, --output <filespec>   print output to file with formatted named
 
-forget [options] [files]::
+forget [OPTION]... [FILE]...::
     Undo an 'hg add' scheduled for the next commit.
 
-    options:
+    Options:
     -I, --include <pat>  include names matching the given patterns
     -X, --exclude <pat>  exclude names matching the given patterns
 
@@ -186,10 +192,10 @@
 
     aliases: id
 
-import [-p <n> -b <base> -q] <patches>::
+import [OPTION]... PATCH...::
     Import a list of patches and commit them individually.
 
-    options:
+    Options:
     -p, --strip <n>   directory strip option for patch. This has the same
                       meaning as the correnponding patch option
     -b <path>         base directory to read patches from
@@ -199,7 +205,7 @@
 init::
     Initialize a new repository in the current directory.
 
-locate [options] [files]::
+locate [OPTION]... [PATTERN]...::
     Print all files under Mercurial control whose names match the
     given patterns.
 
@@ -215,15 +221,14 @@
     This will avoid the problem of "xargs" treating single filenames
     that contain white space as multiple file names.
 
-    options:
-
+    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] [file]::
+log [OPTION]... [FILE]::
     Print the revision history of the specified file or the entire project.
 
     By default this command outputs: changeset id and hash, tags,
@@ -231,7 +236,7 @@
     -v switch adds some more detail, such as changed files, manifest
     hashes or message signatures.
 
-    options:
+    Options:
     -r, --rev <A>, ...  When a revision argument is given, only this file or
                         changelog revision is displayed. With two revision
                         arguments all revisions in this range are listed.
@@ -241,8 +246,8 @@
 
     aliases: history
 
-manifest [revision]::
-    Print a list of version controlled files for the given revision.
+manifest [REV]::
+    Print a list of version controlled files for revision REV.
 
     The manifest is the list of files being version controlled. If no revision
     is given then the tip is used.
@@ -250,18 +255,18 @@
 parents::
     Print the working directory's parent revisions.
 
-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.
-
-    options:
+pull [OPTION]... [SOURCE]::
+    Pull changes from repository SOURCE to a local one.
+
+    This finds all changes from the repository at SOURCE and adds 
+    them to the local repository. By default, this does not update 
+    the copy of the project in the working directory.
+
+    Options:
     -u, --update   update the working directory to tip after pull
 
-push <destination>::
-    Push changes from the local repository to the given destination.
+push [OPTION]... [DEST]::
+    Push changes from the local repository to destination DEST.
     
     This is the symmetrical operation for pull. It helps to move
     changes from the current repository to a different one. If the
@@ -275,19 +280,29 @@
 
       ssh://[user@]host[:port]/path
 
-rawcommit [-p -d -u -F -m -l]::
+rawcommit [OPTION]...::
     Lowlevel commit, for use in helper scripts.
     
     This command is not intended to be used by normal users, as it is
     primarily useful for importing from other SCMs.
 
+    Options:
+    -p --parent <parent>  parent changeset
+    -d --date <datecode>  record datecode as commit date
+    -u --user <user>      record user as commiter
+    -F --files <files>    list of file to commit
+    -m --message <text>   use <text> as commit message
+    -t --text <text>      use <text> as commit message
+                          (deprecated: use -m)
+    -l --logfile <file>   read the commit message from <file>
+
 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 [files ...]::
+remove FILE...::
     Schedule the indicated files for removal from the repository.
     
     This command shedules the files to be removed at the next commit.
@@ -296,7 +311,7 @@
 
     aliases: rm
 
-revert [names ...]::
+revert [OPTION]... [NAME]...::
     Revert any uncommitted modifications made to the named files or
     directories.  This restores the contents of the affected files to
     an unmodified state.
@@ -310,20 +325,20 @@
     If no arguments are given, all files in the current directory and
     its subdirectories are reverted.
 
-    options:
+    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]::
+serve [OPTION]...::
     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:
+    Options:
     -A, --accesslog <file>   name of access log file to write to
     -E, --errorlog <file>    name of error log file to write to
     -a, --address <addr>     address to use
@@ -332,7 +347,7 @@
     -t, --templatedir <path> web templates to use
     -6, --ipv6               use IPv6 in addition to IPv4
 
-status [options] [files]::
+status [OPTION]... [FILE]...::
     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.
@@ -344,13 +359,12 @@
     R = removed
     ? = not tracked
 
-    options:
-
+    Options:
     -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>.
+tag [OPTION]... NAME [REV]::
+    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
@@ -363,7 +377,7 @@
     similarly to other project files and can be hand-edited if
     necessary.
 
-    options:
+    Options:
     -l, --local           make the tag local
     -m, --message <text>  message for tag commit log entry
     -d, --date <datecode> datecode for commit
@@ -394,7 +408,7 @@
     a change is visible for pull by other users, undoing it locally is
     ineffective.
 
-update [-m -C] [revision]::
+update [OPTION]... [REV]::
     Update the working directory to the specified revision.
 
     By default, update will refuse to run if doing so would require
@@ -404,7 +418,7 @@
 
     With the -C option, local changes will be lost.
     
-    options:
+    Options:
     -m, --merge       allow merging of branches
     -C, --clean       overwrite locally modified files
 


More information about the Mercurial mailing list