[MERGE] Minor help fixes for add, commit, export

[John Arbash Meinel]

Ian Clatworthy wrote:
> Changes following clarifications from Martin and Robert.
> 
> Ian C.

...

>      Since a lightweight checkout is little more than a working tree
>      this will refuse to run against one.
> +
> +    To get the working tree created again holding the last checked in files,
> +    use "bzr checkout".
>      """

maybe:

  Use "bzr checkout" to restore the working tree.

>  
>      takes_args = ['location?']
> @@ -338,7 +341,10 @@
>  
>      --file-ids-from will try to use the file ids from the supplied path.
>      It looks up ids trying to find a matching parent directory with the
> -    same filename, and then by pure path.
> +    same filename, and then by pure path. This option is rarely needed
> +    but can be useful when adding the same logical file into two
> +    branches that will be merged later (without showing the two different
> +    adds as a conflict).

It is also useful when merging another project into a subdirectory of
this one. But I'm not sure if that is worth expanding upon.

Also, there is a related bug on this, which could be closed after a
documentation update.

I don't seem to be able to find it. But the specific complaint was that
"Lookup file ids from here" was a bad help text for the option.

It might be better to update the option text, rather than just the
command text.


>      """
>      takes_args = ['file*']
>      takes_options = ['no-recurse', 'dry-run', 'verbose',
> @@ -1922,13 +1928,13 @@
>      given, try to find the format with the extension. If no extension
>      is found exports to a directory (equivalent to --format=dir).
>  
> -    Root may be the top directory for tar, tgz and tbz2 formats. If none
> +    Root may be the top directory for formats other than dir. If none
>      is given, the top directory will be the root name of the file.

This is still a bit confusing (to me, at least).

"If root is supplied, it will be used as the root directory inside
container formats (tar, zip, etc). If it is not supplied it will default
to the exported filename. (It has no effect for --format=dir)."

I don't think my version is perfect either, but maybe it will give you
ideas.

...

> -    Note: export of tree with non-ascii filenames to zip is not supported.
> +    Note: Export of tree with non-ASCII filenames to zip is not supported.

Do we want to capitalize ASCII and UTF-8 in all of our documentation? It
is "officially" correct. But I always felt that it was over-stressing
those words.

Also, technically we do support non-ASCII filenames. They are just
encoded as UTF-8. See an earlier mailing list discussion with Alexander
Belchenko. Who advocated that we use OEM encoding...
This has positives and negatives. If you use OEM encoding, it means that
you can create a zip file, and extract that zip file on the local
filesystem. But it also means that you cannot pass that zip file to any
system which uses a different OEM encoding. (For example, Russian
Windows versus US Windows will break non-ASCII filenames).

I went for 'UTF-8' because it seemed a way to get it to work everywhere,
as long as the 3rd-party tools could be updated to support a real
encoding (rather than the mess that is code-pages).

AFAIK, there is no way to put the filename codepage in a zip header. So
it will always break at some point.

I went for cross-system compatibility, at the expense of local-system
compatibility. I would be okay with switching this. (I was originally
opposed on the basis that just because other tools are broken, we
shouldn't cause bzr to generate "mangled" zip files, but I can give in
to pragmatism).

>  
>       Supported formats       Autodetected by extension
>       -----------------       -------------------------
> @@ -2035,9 +2041,7 @@
>      committed.  If a directory is specified then the directory and everything 
>      within it is committed.
>  
> -    A selected-file commit may fail in some cases where the committed
> -    tree would be invalid, such as trying to commit a file in a
> -    newly-added directory that is not itself committed.
> +    Note: A selected-file commit after a merge is not yet supported.
>      """
>      # TODO: Run hooks on tree to-be-committed, and after commit.

I agree with Aaron. That there are more ways than just after-merge that
will break. But I just realized I don't know what they are :)

Because if you do:

mkdir -p foo/bar/baz
touch foo/bar/baz/x
touch foo/y
bzr add

bzr commit -m "test" foo/bar/baz/x

bzr will be "smart" enough to realize that it needs to add 'foo',
'foo/bar', 'foo/bar/baz', so that it can add 'x'. But it will also not
add 'foo/y' because it wasn't specified.

So the text as written was indeed wrong. It didn't talk about
commit-after-merge, and it lists a case that doesn't fail.

So at the moment, I prefer the fix, but it might be nice if we could
find any other cases that would block.

...

So a couple of comments, but I think the changes are generally good.

John
=:->