[MERGE] Add two new help topics

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

John Arbash Meinel wrote:
> I think we want to be more explicit about "shared repository" versus
> just "repository". Also having the term "shared repository" might help
> distinguish it from darcs/git/hg which just use the term "repository" to
> mean *everything*.

Longer term, I'm reconsidering the decision to call them "Repositories".
 At the time I suggested it, I don't think anyone realized it was
becoming an ambiguous term.  Perhaps "Archive" would be better, at least
for the user-visible "Shared Repository".  Because Archive doesn't mean
anything to darcs/git/hg/svn/cvs users, it leaves us free to define it.
 (And the term is a good match for Arch users, if any are left.)

>> +To create a shared repository use the init-repository command (or the alias
>> +init-repo). This command takes as an argument the location of the repository
>> +to create. This means that 'bzr init-repository repo' will create a directory
>> +named 'repo', which contains a shared repository. Any new branches that are
>> +created in this directory will then be 'in' the repository, and use it for
>> +storage.
> 
> ^- do we need "will then be 'in' the repository"?

That's actually a mild contradiction of our model.  Branches use
repositories, but repositories are essentially unaware of their branches.

>> +Related commands:
>> +
>> +  init-repository   Create a shared repository. Use --no-trees to create one
>> +                    in which new branches wont get a working tree.
>> +"""

Needs an apostrophe in "won't".

>> +_working_trees = \
>> +"""Working Trees
>> +
>> +A working tree is the contents of a branch checked out on disk so that you can
>> +see the files and edit them. The working tree is where you make changes to a
>> +branch, and when you commit the current state of the working tree is the
>> +snapshot that is recorded in the commit.

Since "checkout" is more specific that "working tree", I think it is a
shame to describe "working tree" in terms of "checked out".

> When you push a branch to a remote system, a working tree will not be
> created. If one is already present the files will not be updated. The

Comma needed: "If one is already present, ..."

> branch information will be updated and the working tree will be marked
> as out-of-date. Updating a working tree remotely is difficult, as there
> may be uncommitted changes or content conflicts that are difficult to
> deal with remotely.

I think the original is more accurate.  The issue is that updating the
working tree would *cause* content conflicts, not that they may already
be present.

>> +If you have a branch with a working tree that you do not want the 'remove-tree'
>> +command will remove the tree if it is safe.

Needs a comma after "do not want, ..."

>> +If you want to have a working tree on a remote machine that you push to you
>> +can either run 'bzr update' in the remote branch after each push, or use some
>> +other method to update the tree during the push. There is an 'rspush' plugin
>> +that will update the working tree using rsync as well as doing a push. There
>> +is also a 'push-and-update' plugin that automates running 'bzr update' via SSH
>> +after each push.
> 
> ^- I'm not sure about having plugins mentioned in bzr core... If the
> functionality is that important, maybe it should be core.

I would rather mention plugins in the core than put either one of these
plugins into the core.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGI85Z0F+nu1YWqI0RAuPhAJwMzVztuOfrnj5oUNEd5xWI2sXcRgCeJCQc
l+wfbC9fimAjgC2eoFENDNo=
=+KHE
-----END PGP SIGNATURE-----