[MERGE] some improvements for html docs

[Ian Clatworthy]

Alexander Belchenko wrote:

bb: resubmit

> ------------------------------------------------------------------------
> 
> # Bazaar merge directive format 2 (Bazaar 0.90)
> # revision_id: bialix at ukr.net-20070904141740-bvbsnbvknrbil2h6
> # target_branch: file:///E:/Bazaar/mydev/bzr.dev/
> # testament_sha1: c04b8e70804374bb66a1d608265cfd9fd49dfdd5
> # timestamp: 2007-09-04 17:19:28 +0300
> # base_revision_id: pqm at pqm.ubuntu.com-20070904035759-iv4xl6d7ez69txba
> # 
> # Begin patch
> === modified file 'Makefile'
> --- Makefile	2007-08-28 01:49:28 +0000
> +++ Makefile	2007-09-04 14:17:40 +0000
> @@ -78,8 +78,8 @@
>  	doc/en/user-reference/bzr_man.txt \
>  	doc/en/developer-guide/HACKING.txt \
>  	doc/en/release-notes/NEWS.txt
> -doc_dir := doc/en/user-guide
> -txt_files := $(wildcard $(addsuffix /*.txt, $(doc_dir))) $(derived_txt_files) \
> +doc_dirs := doc/en/user-guide doc/en/user-reference
> +txt_files := $(wildcard $(addsuffix /*.txt, $(doc_dirs))) $(derived_txt_files) \
>  	doc/en/mini-tutorial/index.txt \
>  	doc/index.txt
>  non_txt_files := \

There should be no special files in en/user-reference. We need to fix
that issue rather than change the Makefile I think.

> === modified file 'bzrlib/builtins.py'
> --- bzrlib/builtins.py	2007-09-04 01:20:26 +0000
> +++ bzrlib/builtins.py	2007-09-04 14:17:40 +0000
> @@ -3847,8 +3847,9 @@
>      for that mirror.
>  
>      Mail is sent using your preferred mail program.  This should be transparent
> -    on Windows (it uses MAPI).  On *nix, it requires the xdg-email utility.  If
> -    the preferred client can't be found (or used), your editor will be used.
> +    on Windows (it uses MAPI).  On Unix/Linux, it requires the xdg-email
> +    utility.  If the preferred client can't be found (or used),
> +    your editor will be used.

Thanks. This was on my list for today to correct. (The lone * is
breaking ReST formatting.)

> === modified file 'doc/en/user-reference/index.txt'
> --- doc/en/user-reference/index.txt	2007-08-30 03:36:01 +0000
> +++ doc/en/user-reference/index.txt	2007-09-04 14:17:40 +0000
> @@ -2,6 +2,9 @@
>  Bazaar User Reference
>  #####################
>  
> +* `User Manual <bzr_man.html>`_ |--| auto-generated from internal
> +  bzr help
> +
>  * `Hooks Reference <hooks.html>`_ |--| The various operations that Bazaar
>    lets you hook into

I don't want anything called the User "Manual". I want:

* a User Guide that presents HOW to use Bazaar (task-based)
* a User Reference that covers WHAT the detailed features are.

For a comparison, see the Python documentation (http://www.python.org/doc/):

* the Python Tutorial presents HOW
* the Language and Library References present the WHAT.

Ian C.