[RFC] [MERGE] Help text updates

James Westby jw+debian at jameswestby.net
Mon Oct 29 21:49:28 GMT 2007


On (29/10/07 20:16), Matthew Revell wrote:
> Hi guys,
> 
> I've made an initial stab at rewriting some of the Bazaar help texts
> in builtins.py. A merge directive is attached.

Hi Matthew,

Thanks for the changes, a few review comments for your perusal inline.

>  class cmd_status(Command):
> -    """Display status summary.
> -
> -    This reports on versioned and unknown files, reporting them
> -    grouped by state.  Possible states are:
> -
> +    """Display a summary of files and directories whose status has recently changed.

I'm not sure about "recently", something is still reported as changed
even if it was done 5 years ago.

> +    
> +    If no arguments are specified, shows summary for entire working 
> +    directory against previous revision.

Against its basis tree actually, but I wouldn't want to explain that
here, so just 

  If no arguments are specified it shows the summary for the entire
  working directory. This summary shows the changes that were made
  since the last revision.

> +
> +    Examples:
> +    
> +    bzr status
> +    	Shows changes between current and previous revisions.

     Shows changes between the current and previous revision.

> +    	
> +    bzr status -r 123 -r 321
> +    	Shows changes between revisions 123 and 321.

     Shows the changes?

Wouldn't 'bzr status -r123..321' be more idiomatic?

> +    	
> +    bzr status foo.txt -r 123 --short
> +    	Uses Subversion-style flags to show changes to foo.txt between
> +    	current revision and revision 123.

I'm not sure about "Subversion-style", perhaps "short status flags", or
just "status flags". Also "show the changes", and "between the current".
Perhaps pointing to 'bzr help status-flags' here would be useful.

> -        File kind has been changed (e.g. from file to directory).
> +        File type has changed (e.g. from a file to a directory).

I'm unsure about this change, but not against it necessarily.

> +    See bzr help status-flags for an explanation of the short,
> +    Subversion-style, status flags.

Ah, this seems a little disconnected, but perhaps more prominent. Also
"short, Subversion-style, status flags" seems like a good phrasing to
me.

>  class cmd_cat_revision(Command):
> -    """Write out metadata for a revision.
> +    """Display metadata for the specified revision.
>      
> -    The revision to print can either be specified by a specific
> -    revision identifier, or you can use --revision.
> +    Accepts either a revision ID or --revision (see bzr help revisionspec for details).

Long line.

Also is it worth clarifying that the revision id can be as an argument,
as it is always possible to use --revision to specify one.

> +    'bzr add' recursively versions all unknown files.

'bzr add' with no arguments?

> +    """Show all files, directories and symlinks in the current working copy or a specified revision.

A long line.

> +
> +	Examples:
> +	
> +	bzr inventory --kind file
> +		Show files only.
> +
> +	bzr inventory --show ids docs/

'show-ids'

>  class cmd_checkout(Command):
> -    """Create a new checkout of an existing branch.
> +    """Create a local copy of an existing branch, requiring commits to be pushed back to a central location.

Another long line.

>  class cmd_init(Command):
> -    """Make a directory into a versioned branch.
> +    """Create an branch in an existing directory.

'an' -> 'a'.

> +    """Use the standard output to write a file's contents as they were at the specificed revision.

'specified'

> +<<<<<<< TREE
> +    This command checks for problems in the branch storage to detect
> +    data corruption or bzr bugs.
> +
> +    Output fields:
> +
> +        revisions: This is just the number of revisions checked.  It doesn't
> +            indicate a problem.
> +        versionedfiles: This is just the number of versionedfiles checked.  It
> +            doesn't indicate a problem.
> +        unreferenced ancestors: Texts that are ancestors of other texts, but
> +            are not properly referenced by the revision ancestry.  This is a
> +            subtle problem that Bazaar can work around.
> +        unique file texts: This is the total number of unique file contents
> +            seen in the checked revisions.  It does not indicate a problem.
> +        repeated file texts: This is the total number of repeated texts seen
> +            in the checked revisions.  Texts can be repeated when their file
> +            entries are modified, but the file contents are not.  It does not
> +            indicate a problem.
> +=======
>      This command checks various invariants about the branch storage to
>      detect data corruption or bzr bugs.
>  
> @@ -2353,6 +2380,7 @@
>              in the checked revisions.  Texts can be repeated when their file
>              entries are modified, but the file contents are not.  It does not
>              indicate a problem.
> +>>>>>>> MERGE-SOURCE

Merge conflicts.

>  class cmd_merge(Command):
> -    """Perform a three-way merge.
> +    """Merge one branch into another.

'Merge another branch in to this one.'?

>  class cmd_unbind(Command):
> -    """Convert the current checkout into a regular branch.
> +    """Convert the current branch into a checkout of the specified branch.

That sounds like the help of 'bind', not 'unbind'.

> +    geoffery  matthew.revell at canonical.com-20071015133817-uhq7ocbhmzf66cwc
> +    maurice   matthew.revell at canonical.com-20071017160447-ixu0cj9ahsx7lu6z

Has the code to change this been merged yet?

Thanks,

James

-- 
  James Westby   --    GPG Key ID: B577FE13    --     http://jameswestby.net/
  seccure key - (3+)k7|M*edCX/.A:n*N!>|&7U.L#9E)Tu)T0>AM - secp256r1/nistp256



More information about the bazaar mailing list