[patch] bzr documentation clean-up

[Aaron Bentley]

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

Brad Crittenden wrote:
> The files in the doc directory were edited for grammar, spelling,
> formatting, and clarity.  Some new content was added to tutorial.txt.

Thanks, Brad

> @@ -87,16 +87,19 @@
>    % bzr init-repo --no-trees sftp://centralhost/srv/bzr/
>  
>  You can think of this step as similar to setting up a new cvsroot, or
> -subversion repository.
> -
> -
> -Versioning an existing project
> -==============================
> +subversion repository.  The {{{--no-trees}}} option tells bzr to not
> +populate the directory with a working tree.  This is appropriate since
> +no one will be making changes directly in the branches within the
> +central repository.

Could use a comma after "appropriate".

> +Placing an existing project into Bazaar
> +=======================================

I think 'placing..into Bazaar' is unclear.  "Putting an existing project
into source control"?  (Actually, we should make sure the entire
document talks either about version control or source control, but not
both.)

>  Now that we have a repository, let's create a versioned project. Most of
>  the time, you will already have some code that you are working with,
>  that you now want to version using Bazaar_. If the code was originally
> -in source control, there are many ways to convert the project to Bazaar_
> +in source control there are many ways to convert the project to Bazaar_

The comma should not be removed.  "If the code was originally in source
control" is an introductory clause.


> @@ -289,20 +297,20 @@
>  Shared Repository
>  -----------------
>  
> -Bazaar_ has the concept of a "Shared Repository". This is similar to the
> -concept of other RCS's repository. Such as in Subversion, where you have a
> -remote repository, which is where all of the history is stored, and
> -locally you don't have any history information, only a checkout of the
> -working tree files. Note that "Shared" in this context means shared
> -between branches. It *may* be shared between people, but standalone
> -branches can also be shared between people.
> +Bazaar_ has the concept of a "Shared Repository". This is similar to
> +the concept of a repository in other RCSs. For example, in Subversion

Nothing to do with your edit, but some popular RCSes now blur the
distinction between Repository and Working Tree.  We probably want to
say, "This is similar to the traditional concept of a repository in
RCSes like CVS and Subversion".

>  In Bazaar_ terms, a "Shared Repository" is a location where multiple
> -branches can **share** their revision history information. Because Bazaar_
> -wants to support decentralized workflows, it is possible for every branch
> -to maintain its own revision history information. But this is often
> -inefficient, since related branches share history, and they might as well
> -share the storage as well.
> +branches can **share** their revision history information. In order to
> +support decentralized workflows, it is possible for every branch to
> +maintain its own revision history information. But this is often

"store" is probably clearer than "maintain" here.

> === modified file doc/configuration.txt
> --- doc/configuration.txt
> +++ doc/configuration.txt
> @@ -6,10 +6,10 @@
>  
>  Location of configuration file
>  ==============================
> -Each user gets a pair of configurations files in $HOME/.bazaar. The first
> -one, named bazaar.conf, includes default configuration options. The other
> -file, locations.conf, contains configuration information for specific
> -branch locations.
> +Each user gets a pair of configurations files in ``$HOME/.bazaar``. The first
> +one, named ``bazaar.conf``, includes default configuration options. The other
> +file, ``locations.conf``, contains configuration information for specific
> +branch locations.  These files are sometimes referred to as ``ini files``.
>  
>  General Format
>  ==============
> @@ -25,15 +25,15 @@
>  Section Headers
>  ---------------
>  A section header is a word enclosed in brackets that starts at the begining
> -of a line, typical section headers look like this::
> +of a line.  A typical section headers look like this::

I think you want "Typical section headers..." or else "A typical section
header looks..."

> @@ -87,12 +86,12 @@
>  The main configuration file, bazaar.conf
>  ----------------------------------------
>  
> -The main configuration file, $HOME/.bazaar/bazaar.conf, only allows one
> -section called '''[DEFAULT]'''. This default section contains the default
> +The main configuration file, ``$HOME/.bazaar/bazaar.conf``, only allows one
> +section called ``[DEFAULT]``. This default section contains the default
>  configuration options for all branches. The default section can be
> -overriden by providing a branch specific section in locations.conf.
> +overriden by providing a branch specific section in ``locations.conf``.

Should be "branch-specific", I think.

>  recurse
>  -------
> -Only useful in locations.conf. Defines whether or not the configuration for
> +Only useful in ``locations.conf``. Defines whether or not the configuration for
>  this section applies to subdirectories:
>  
>  true
> -    (default) This section applies to subdirectories as well
> +    (default) This section applies to subdirectories.

I think this subtly changes the meaning.  Options will always apply to
location that matches exactly.  The recurse setting causes options to
apply to both exact matches, and subdirectories of exact matches.
Leaving out "as well" suggests that the section applies to
subdirectories alone, and not to exact matches.

> @@ -186,34 +184,33 @@
>  ================
>  
>  These options apply only to branches that use the "experimental-branch6"
> -format.  They are usually set in .bzr/branch/branch.conf automatically, but
> -may be manually set in locations.conf or bazaar.conf
> +format.  They are usually set in ``.bzr/branch/branch.conf`` automatically, but
> +may be manually set in ``locations.conf`` or ``bazaar.conf``.
>  
>  append_revisions_only
>  ---------------------
> -If set to "True", then revisions can only be appended to the log, not removed.
> -A branch with this setting enabled can only pull from another branch if the
> -other branch's log is a longer version of its own.
> -
> -This is normally set by ``bzr init --append-revisions-only``.
> +If set to "true" then revisions can only be appended to the log, not

The value is case-sensitive.  "true" has no effect.

> === modified file doc/server.txt
> --- doc/server.txt
> +++ doc/server.txt
> @@ -28,12 +28,12 @@
>  protocol as a dumb server.  This is the first stage high performance server
>  functionality to be delivered.
>  
> -The current high performance server provides read only access by default for
> -security. To enable read-write access, run it with --allow-writes. When using
> -the SSH access method, bzr automatically runs with with the --allow-writes
> -option.
> +The current high performance server provides read-only access by
> +default for security. To enable read-write access, run it with

It probably wouldn't hurt to rewrite this sentence, e.g. "To maintain
the highest security possible, the current high-performance server
provides read-only access by default."

>  How to setup your email address 
>  ===============================

I tend to use "set up" for the verb and "setup" for the noun.  I find
"setup" jarring as a verb.

>  Bazaar will try to guess an email address based on your username and the
>  hostname if none is set.  This will probably not be what you want, so three
> -ways exist to tell Bazaar what email to use
> +ways exist to tell Bazaar what email to use:
>  
> - * You can set your email in the default ini file,
> + * You can set your email in the default configuration file,
>   * You can set emails per-branch in the branch specific ini file,

There are actually three relevant config files, so we need to do some
restructuring here.  I would suggest reducing it to two ways:

 * You can set your email in a config file.  Like other configuration
values, you can set it in "bazaar.conf" as a general setting.  If you
want to override the value for a particular branch or set of branches,
you can use "locations.conf".  ".bzr/branch/branch.conf" will also work,
but will cause all commits to that branch to use the same email address,
even if someone else does them.

>  as shown below.  Please note that the word DEFAULT is case sensitive, and
> -must be in upper-case.::
> +must be in upper-case. ::

I don't think a colon is appropriate here, so the :: should be moved to
the next line.

> @@ -68,28 +70,27 @@
>  ===================================
>  
>  The second approach is to set email on a branch by branch basis by using the
> -`$HOME/.bazaar/locations.conf` ini file, thusly::
> +``$HOME/.bazaar/locations.conf`` ini file, thusly::

Should be "config" file, I think.

> -Setting email via environment
> ------------------------------
> -The final method Bazaar will use is checking for the `$BZREMAIL` and
> -`$EMAIL` environment variables.  Generally, one would use this method to
> +Setting email via environment variable
> +--------------------------------------
> +The final method Bazaar will use is checking for the ``$BZR_EMAIL`` and
> +``$EMAIL`` environment variables.  Generally, one would use this method to
>  override the email in a script context.  If you would like to set a general
>  default, then please see the ini methods above.

There's inconsistency in this paragraph.  It uses both the formal "one"
and the informal "you".


>  Concerns for spam
>  =================

I think people are more concerned *about* spam than they are concerned
*for* it.

> @@ -82,8 +82,8 @@
>  revid
>  -----
>  
> -**revid** allows specifying a an internal revision ID, as show by **bzr
> -testament** and some other commands.
> +**revid** allows specifying a an internal revision ID, as show by ``bzr
> +testament`` and some other commands.

Should be "as shown by".  Also, I suspect "bzr log" is a much more
common command that shows ids.

>  Creating a branch
>  =================
>  
> -History is by default stored in the .bzr directory of the branch. There
> -will be a facility to store it in a separate repository, which may be
> -remote.  We create a new branch by running **bzr init** in an existing
> -directory::
> +History is by default stored in the .bzr directory of the branch. In a
> +future version of Bazaar, there will be a facility to store it in a
> +separate repository, which may be remote.  We create a new branch by
> +running **bzr init** in an existing directory::

Should probably be ``bzr init``.

> @@ -207,7 +206,7 @@
>  
>      % bzr log http://bazaar-vcs.org/bzr/bzr.dev/
>  
> -By installing bzr plugins you can also access branches over the sftp or
> +By installing bzr plugins you can also access branches using the sftp or
>  rsync protocols.

sftp no longer requires a plugin.

> @@ -499,14 +498,24 @@
>    % bzr merge URL
>  
>  
> -If there is a conflict during a merge, 3 files with the same basename are
> -created. The filename of the common base is appended with .BASE, the
> -filename of the file containing your changes is appended .THIS and the
> -filename with the changes from the other tree is appended .OTHER.
> -Using a program such as kdiff3, you can now comfortably merge them into
> -one file. To commit you have to rename it to the original basename and
> -delete the other two files. As long as there exist files with .BASE, .THIS
> -or .OTHER the commit command will complain.
> +If there is a conflict during a merge, 3 files with the same basename
> +are created. The filename of the common base is appended with ".BASE",
> +the filename of the file containing your changes is appended with
> +".THIS" and the filename with the changes from the other tree is
> +appended with ".OTHER".  Using a program such as kdiff3, you can now
> +comfortably merge them into one file.  In order to commit you have to
> +rename the merged file (".THIS") to the original file name and delete
> +the other two temporary files (".BASE" and ".OTHER"). As long as there
> +exist files with .BASE, .THIS or .OTHER the commit command will
> +complain.  To complete the conflict resolution you must use the
> +resolve command.

Deleting the files is done by the resolve command, so that step can be
omitted.

> @@ -525,7 +534,7 @@
>  
>  * bzr push sftp://servername.com/this/directory/here 
>  
> -  (The directory that must already exist)
> +  (The destination directory must already exist)

Actually, it's "directory" that must exist, not "here".  (but you can
supply "--create prefix" if "this" or "directory" doesn't exist).

>  Rules for Aliases
>  =================
>  
>   * You can override parts of the options given in an alias by overriding it.
> -   For example, if you run **lastlog -r-5..**, you will only get five
> +   For example, if you run ``lastlog -r-5..``, you will only get five
>     line-based log entries instead of 10.

Probably should add "Note that all boolean options have an implicit
inverse, so you can override the commit alias with ``commit --no-strict``."

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

iD8DBQFF5aVX0F+nu1YWqI0RAoaxAJ9WS/J4YFR/Fl8mFCf3K74ruo2SgwCggzTF
+p31lQvVKIhYGVmZwx0AeGI=
=Mm3Q
-----END PGP SIGNATURE-----