"bzr help svn-layout" incomplete

[Samuel Bronson]

It seems to me that "bzr help svn-layout" should provide (or link to) explanations (and/or illustrations) of the layouts supported by bzr-svn, including such details as how paths are formed and the treatment of "project" names.

Directory tree diagrams, like those in http://doc.bazaar.canonical.com/latest/en/user-guide/shared_repository_layouts.html, would be extremely helpful in this regard.

(It really isn't pleasant to have to extract this information from the source code.)

[Jelmer Vernooij (jelmer)]

On Thu, 2010-05-27 at 21:25 +0000, Samuel Bronson wrote:
> It seems to me that "bzr help svn-layout" should provide explanations
> for all of the layouts supported by bzr-svn, including such details as
> how paths are formed and the treatment of "project" names...
>
> It really isn't pleasant to have to extract this information from the
> source code.

This is a topic that I think is hard to explain in roughly 30 lines of
text. If you can, patches welcome. :-) I think this is something that
probably should be documented in the bzr-svn section of the user
reference.

Cheers,

Jelmer

[Samuel Bronson (naesten)]

Okay, I have to admit that what I want to see is not going to fit in 30 lines! I've revised the title and description of this bug accordingly: linking would be fine too; the real point is that doing "bzr help svn-layout" should help the user find the information, not that the information necessarily be displayed immediately.

What do I mean by "linking", given that console output does not normally support arbitrary hyperlinks? Well, a URL works, as would a path relative to an easy-to-find directory (especially if a command to find this directory is also supplied). For a link to the user guide, I would suggest linking to the "latest" online version as I have in the description: if the user is working offline and has her own copy of the guide, she can probably figure out what part of that to paste onto the end of her local URL to get to the page in question without much difficulty; and if she's on the net, she'd probably not want to have to hunt up a base URL on her own.

Honestly, though, even putting a good text file in the source tree and mentioning the path in the help text (along with a hint about "bzr plugins -v") would be a big improvement!

[Jelmer Vernooij (jelmer)]

The bzr user documentation is probably the right place for a better explanation of this. I don't have any plans to work on this myself, but patches are welcome.

I don't really see why the project bit would have to be documented - it's really an internal thing that shouldn't be relevant to users.