document about stacked branch

[Andrew Bennetts]

INADA Naoki wrote:
> http://doc.bazaar.canonical.com/bzr.2.3/en/user-guide/stacked.html#limitations-of-stacked-branches
> 
> On this page, https://bugs.launchpad.net/bzr/+bug/375013 is referenced
> as a limitation.
> And one paragraph is commented out because of the bug.
> 
> This bug was fixed. Can someone update the doc?
> (I doesn't want to do because I am not good at writing English.)

Thanks for pointing that out.  I'll fix it up.

> Additionaly, I feel an example in the document doesn't describes when
> --stacked option is useful.
> 
>    bzr push --stacked-on sftp://host/project --stacked
> sftp://host/user/stacked-branch
> 
> This should be
> 
>   bzr branch bzr+ssh://example.com/project/trunk my-branch
>   cd my-branch
>   (working on my-branch)
>   bzr push --stacked bzr+ssh://example.com/~/stacked-branch
> 
> Any thoughts?

The existing example is definitely useful.  Is your concern that
--stacked is redundant there because it also uses --stacked-on?

Your suggested example is ok, but depends on your local my-branch
having a usable public_location defined (otherwise the pushed branch
will be stacked on a URL unreachable by most people,
file:///.../my-branch).  So to be a workable example people can follow
we need to make sure they also do the necessary configuration.  I'll
have a stab at it, but I'm not sure I can explain it concisely enough to
be good documentation.

-Andrew.