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

[Ian Clatworthy]

John Arbash Meinel wrote:
> 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.
>
>   
Aaron suggested a better wording for this sentence as well. I'm changing 
the text to reflect his wording (similar to this).
>>  
>>      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.
>
>   
It might be. My question when reading the man page was "When would I 
ever want to use this option?" One or more examples is sufficient in the 
help text IMO. A more detailed user guide can cover each use case in 
more depth.
> 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.
>
>
>   
I'm happy to go with whatever approach people prefer. A detailed 
explanation of an option in the help text is commonly done as best I can 
tell. Getting a good concise explanation against the option is equally 
important (and it could be better in this case?). I didn't want to move 
the detailed explanation as the text immediately against the option 
though. Is that OK?
>>      """
>>      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.
>
>   
Yes, your text is much better. I'll use it with minor changes to the 
last sentence.
> ...
>
>   
>> -    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.
>
>   
My preference is to be officially correct. Firstly, the "normal" form 
for words like this are less jarring for most readers in text because 
they mentally expect them to look that way. Secondly, core help text has 
a habit of getting re-used in dozens of derived documents, books, etc 
and it's best to fix it once than expect each document/book author to 
run into it on each spell check, etc.

> 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).
>
>   
I think your choices were good ones. FWIW, the code still has this in it:

    except UnicodeEncodeError:
        zipf.close()
        os.remove(dest)
        from bzrlib.errors import BzrError
        raise BzrError("Can't export non-ascii filenames to zip")

Zip file export is broken in other ways though w.r.t. permission 
setting. See https://bugs.beta.launchpad.net/bzr/+bug/97671.
>>  
>>       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
> =:->
>
>   
So my challenge here is knowing what to document. Ideally I'd like to 
document expected behaviour and record deviations from that as bugs if 
they haven't been already. If appropriate, the expected behaviour 
documentation can be supplemented with notes on current limitations.

I still need those far more intimate with the commit code to give me the 
preferred text. :-(

Ian C.