make some terms in documentation more clear

Bug #230734 reported by Saša Janiška on 2008-05-15
0
Affects Status Importance Assigned to Milestone
Bazaar
Medium
Unassigned

Bug Description

Hi!

I'm quite new with Bazaar and while reading user-guide and other online docs I found some spots which should be, imho, more clear and less ambiguous.

1) User-guide (http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html#core-concepts) says:

1.2.5 Repository

A repository is simply a store of revisions. In the simplest case, each branch has its own repository.
In other cases, it makes sense for branches to share a repository in order to optimize disk usage.

which implies, according to my understanding that repository belongs to 'higher' order in the sense
that several branches can share the single repository, right?

However, online docs for Branch (http://bazaar-vcs.org/Branch) states:

a) "...If the repository is shared with other branches, it is called a repository branch..."

while the RepositoryBranch (http://bazaar-vcs.org/RepositoryBranch) says:

b) "A repository branch is a branch that lives within a repository."

Being non-native English speaker, the wording in a) is, at least to me, a bit misleading, i.e. saying that
"...repository is shared with other branches..." could imply that 'repository' is SHARED with 'branches',
while it is the other way around: 'branches' SHARE the 'repository, right?

I'm sorry if I understood something wrong, pls. clarify!

The other thing is:

2) doc for the Branch (http://bazaar-vcs.org/Branch) says:

"...A working tree in a different location from its branch is called a checkout."

which sounds good, but it links to Checkout (http://bazaar-vcs.org/Checkout)
page where there is:

"A checkout is essentially a working tree that is linked to a branch at a different location."

definition.

Why not being (more) consistent and say something along the:

"A checkout is essentially a working tree in a different location that is linked to a branch." ?

Those are fundamental concepts required for a potential bzr user to grasp and it is important
to spell them as clearly as possible.

Sincerely,
Gour

Martin Pool (mbp) on 2008-06-17
Changed in bzr:
importance: Undecided → Medium
status: New → Confirmed
Samuel Bronson (naesten) wrote :

You do realize that those pages are on a wiki, right?

You can change them to make them clearer...

Saša Janiška (gour) wrote :

@Samuel: No, I'm not. I thought official user-manual is not wiki stuff.

Sincerely,
Gour

doc.bazaar-vcs.org is built from the tree; the others are on a wiki.

--
Martin <http://launchpad.net/~mbp/>

Jelmer Vernooij (jelmer) on 2017-11-08
tags: added: check-for-breezy
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers