[patch] bzr documentation clean-up

[James Westby]

On (27/02/07 17:24), 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 for this work. It's probably not that much fun, but very useful.

>  
> -For locations.conf, the variables from the section with the longest matching
> +For ``locations.conf``, the variables from the section with the longest matching

^ This is a full line. I'm not sure what bzr classes as the line break
point, especially in docs. I'm not bothered about it, but jsut wanted to
flag it up.

>  
>  never
> -    Refuse to sign newly committed revisions, even if the branch requires signatures
> +    Refuse to sign newly committed revisions, even if the branch requires signatures.

^ An actual long line.

>  
>  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 prefer the original in this case, it is explicit that it is not just
subdirectories.

>  overriding commands, adding new commands, providing additional network
> -transports, customizing log output. The sky is the limit for the
> -customization that can be done through plugins.
> +transports, or customizing log output. The sky is the limit for the
> +customizations that can be done through plugins.

^ customization reads better to me here.

> +Bzr will scan ``bzrlib/plugins`` and ``~/.bazaar/plugins`` for plugins
> +by default.  You can override this with ``BZR_PLUGIN_PATH``.  Plugins
> +may be either modules or packages.  If your plugin is a single file,
> +you can structure it as a module.  If it has multiple files, or if you
> +want to distribute it as a bzr branch, you should structure it as a
> +package, i.e. a directory with an ``__init__.py`` file.

^ Would it be worth metioning the restriction on naming here? (Not
necessarily in this patch, it's a more general question.)

>  
> -The `BZR_REMOTE_PATH` environment variable adjusts how `bzr` will be invoked on
> +The ``BZR_REMOTE_PATH`` environment variable adjusts how `bzr` will be invoked on

^ Another long line.

> +specific user, you should use ``su`` or login as that user.  This example runs ``bzr
> +serve`` on `localhost` port `1234`.

^ v and a couple more.

> -These modify your global bazaar.conf or branch branch.conf file, respectively.
> +These modify your global ``bazaar.conf`` or branch ``branch.conf`` file, respectively.

>  
> -Note::
> +Note:
>      Omitting the lower bound doesn't work on currently released versions.

^ This is not true of bzr.dev now. Perhaps it should say "on versions
before ...". The same for the whoami $NAME above as well.

(Again this doesn't have to be addresses by this patch.)

>  take the modifications in one branch of software and apply them to
> -another, related, branch -- even if those changes exist in a branch owned
> +another related branch -- even if those changes exist in a branch owned

^ I would prefer the original here.

>  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::

Is this meant as an alternative to init on the server and then a local
lightweight checkout, or is there something I am missing?

> +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.
> +
> +::
> +
> +  % kdiff3 file.BASE file.OTHER file.THIS
> +  % mv file.THIS file
> +  % rm file.BASE file.OTHER
> +  % bzr resolve file

This seems to be saying that the only way to solve the conflict is to
take THIS, when it's not. Perhaps that is what happens with kdiff3, but
it seems a little misleading.

Again this isn't your patch.


Overall, there's nothing that would stop it from being merged as is in my
opinion, so +1 from me if that counts for anything.

This seems like prime 0.15 material to me, there's it can't regress
anything, and its an overall improvement.

Thanks again,

James

-- 
  James Westby   --    GPG Key ID: B577FE13    --     http://jameswestby.net/
  seccure key - (3+)k7|M*edCX/.A:n*N!>|&7U.L#9E)Tu)T0>AM - secp256r1/nistp256