[PATCH 2 of 5] Improve English for hg commands

[Greg Ward]

On Fri, Jun 5, 2009 at 6:02 AM, timeless<timeless at gmail.com> wrote:
> # HG changeset patch
> # User timeless <timeless at gmail.com>
> # Date 1244202641 -7200
> # Node ID 42f0b0bab4b61179546b419bcef8f2a8d0be0cc7
> # Parent  7d1cbb86d3a13bb70fe4cbbf17fa8517f2e5db81
> Improve English for hg commands
[...]
>     Without the -a/--text option, annotate will avoid processing files
>     it detects as binary. With -a, annotate will generate an
> -    annotation anyway, probably with undesirable results.
> +    annotation of the file anyway, the results will probably be
> +    neither useful nor desirable.

Run-on sentence.  How about:

     Without the -a/--text option, annotate will avoid processing files
     it detects as binary. With -a, annotate will generate an
     annotate of the file anyway, although the results will probably be
     neither useful nor desirable.

or

     Without the -a/--text option, annotate will avoid processing files
     it detects as binary. With -a, annotate will annotate the file
     anyway, although the results will probably be neither useful
     nor desirable.

>  def archive(ui, repo, dest, **opts):
> -    '''create unversioned archive of a repository revision
> +    '''create an unversioned archive of a repository revision

I think the original is valid "telegraph English", which is generally
appropriate in this sort of context.  But your change is fine too.

>     By default, the revision used is the parent of the working
>     directory; use -r/--rev to specify a different revision.
>
>     To specify the type of archive to create, use -t/--type. Valid
> -    types are:
> +    types include:
>
>     "files" (default): a directory full of files
>     "tar": tar archive, uncompressed

Here I disagree.  The help should be a definitive list of available
archive types, not a sample of the most popular ones.  Your change
implies the latter.

>     If you back out a changeset other than the tip, a new head is
>     created. This head will be the new tip and you should merge this
> -    backout changeset with another head (current one by default).
> +    backout changeset with another head.

The original is inconsistent: it uses "back out" as the verb, and
"backout" as the adjective.  IMHO it should be "backout" all around,
since that's the command we're talking about.

>     If you supply a command it will be used for automatic bisection.
> -    Its exit status will be used as flag to mark revision as bad or
> -    good. In case exit status is 0 the revision is marked as good, 125
> +    Its exit status will be used as flag to mark revision as good or
> +    bad. In case exit status is 0 the revision is marked as good, 125
>     - skipped, 127 (command not found) - bisection will be aborted;
> -    any other status bigger than 0 will mark revision as bad.
> +    any other status greater than 0 will mark revision as bad.

Gaaak.  The original here is barely coherent.  Your change improves
matters, but not enough.  Consider this:

    If you supply a command, it will be used for automatic bisection.
    Its exit status will be used as to mark revisions as good or bad:
    status 0 means good, 125 means to skip the revision, 127
    (command not found) will abort the bisection, and any other
    non-zero exit status means the revision is bad.

>     With no argument, show the current branch name. With one argument,
> -    set the working directory branch name (the branch does not exist
> -    in the repository until the next commit). It is recommended to use
> -    the 'default' branch as your primary development branch.
> +    set the working directory branch name (the branch will not exist
> +    in the repository until the next commit). Standard practice
> +    dictates that primary development take place on the 'default'
> +    branch.

"Dictates" is a bit strong; how about "recommends"?

>     It is possible to specify an ssh:// URL as the destination, but no
>     .hg/hgrc and working directory will be created on the remote side.
> -    Look at the help text for URLs for important details about ssh://
> -    URLs.
> +    Please see the help text for URLs for important details about
> +    ssh:// URLs.

Or even better:

    Please see the help text for URLs for important details about
    ssh:// URLs ("hg help urls").

>     Commit changes to the given files into the repository. Unlike a
>     centralized RCS, this operation is a local operation. See hg push
> -    for means to actively distribute your changes.
> +    for a means to actively distribute your changes.

Instead of "a means", how about "a way"?

> -    With a path, do a lookup in another repository.
> +    Specifying a path to a repository root or mercurial bundle will
> +    cause lookup to operate on that repository/bundle.

"Mercurial" should be capitalized in this context.

> @@ -1774,8 +1777,8 @@ def incoming(ui, repo, source="default",
>     """show new changesets found in source
>
>     Show new changesets found in the specified path/URL or the default
> -    pull location. These are the changesets that would be pulled if a
> -    pull was requested.
> +    pull location. These are the changesets that would have been pulled
> +    if a pull at the time you issued this command.

Something got mangled.  I think you meant

    These are the changesets that would have been pulled
    if a you had requested a pull when you issued this command.

> @@ -1855,20 +1858,20 @@ def init(ui, dest=".", **opts):
>  def locate(ui, repo, *pats, **opts):
>     """locate files matching specific patterns
>
> -    Print all files under Mercurial control whose names match the
> -    given patterns.
> +    Print files in the working directory whose names match the given
> +    patterns.

Not true.  I just tested 'hg locate' with tip of crew and the original
text accurately describes its behaviour.  Perhaps you meant

    Print all files under Mercurial control in the working directory
    whose names match the given patterns.

?

>     If no patterns are given to match, this command prints all file
> -    names.
> +    names in the working directory.

or maybe "the names of all files in the working directory under
Mercurial control"?  It's a mouthful, but accurate.

>     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.
> +    contain white space as multiple files.

In my experience, "whitespace" is generally one word... like "filename".

>     """
>     end = opts.get('print0') and '\0' or '\n'
>     rev = opts.get('rev') or None
> @@ -1907,13 +1910,13 @@ def log(ui, repo, *pats, **opts):
>
>     By default this command outputs: changeset id and hash, tags,
>     non-trivial parents, user, date and time, and a summary for each
> -    commit. When the -v/--verbose switch is used, the list of changed
> -    files and full commit message is shown.
> +    commit. When the -v/--verbose switch is used, the full commit
> +    message and list of changed files are shown.

IMHO the original is more accurate, since "-v" shows files before the
commit message.

> @@ -2211,14 +2214,17 @@ def postincoming(ui, repo, modheads, opt
>  def pull(ui, repo, source="default", **opts):
>     """pull changes from the specified source
>
> -    Pull changes from a remote repository to the local one.
> +    Pull changes from a remote repository to a local one.

> -    Use hg incoming if you want to see what will be added by the next
> -    pull without actually adding the changes to the repository.
> +    Use hg incoming if you want to see what would have been added by a
> +    pull at the time you issued this command. If you then decide to
> +    added those changes to the repository, you should use pull -r X
> +    where X is the last changeset listed by hg incoming.

Better advice would be "use incoming --bundle, then unbundle if you
like what you see".  (Uses less bandwidth, goes faster.)

I just ran out of steam, and did not review your remaining changes.
Maybe tomorrow.

Greg