Merge lp:~vila/bzr/cleanup-docs into lp:bzr

[Vincent Ladeuil]

Cleanup some bogus rest constructs in the doc.

This cleans some rest constructs causing problems with texinfo or which were just wrong
but encountered while working on it.

Bad indentation:
=== modified file 'bzrlib/help_topics/en/conflict-types.txt'
--- bzrlib/help_topics/en/conflict-types.txt 2010-02-04 13:29:34 +0000
+++ bzrlib/help_topics/en/conflict-types.txt 2010-07-05 12:40:19 +0000
@@ -28,11 +28,11 @@

 Whatever the conflict is, resolving it is roughly done in two steps::

-- modify the working tree content so that the conflicted item is now in the
- state you want to keep,
+ - modify the working tree content so that the conflicted item is now in the
+ state you want to keep,

and some others like the above.
=== modified file 'doc/en/mini-tutorial/index.txt'
--- doc/en/mini-tutorial/index.txt 2009-12-03 00:44:16 +0000
+++ doc/en/mini-tutorial/index.txt 2010-07-05 12:44:35 +0000
@@ -64,7 +64,7 @@
  $ mkdir subdirectory
  $ touch test1.txt test2.txt test3.txt subdirectory/test4.txt

-**Note for Windows users:** use Windows Explorer to create your
+**Note for Windows users**: use Windows Explorer to create your
 directories, then right-click in those directories and select

':' inside the '**' is problematic for texinfo, given the few occurrences, I'd prefer to fix
them than trying to address them for now.

Finally:
=== modified file 'doc/en/user-guide/index-plain.txt'
--- doc/en/user-guide/index-plain.txt 2009-12-02 20:34:07 +0000
+++ doc/en/user-guide/index-plain.txt 2010-07-05 12:44:35 +0000
@@ -115,5 +115,3 @@
 .. include:: http_smart_server.txt
 .. include:: writing_a_plugin.txt

-.. |--| unicode:: U+2014
-

I deleted the above as I couldn't find where it was used. If we really need it for html output, I'd prefer some conditional or a solution based on same html style stuff.

I also updated the copyright line that appear on all sphinx pages:

=== modified file 'bzrlib/doc_generate/sphinx_conf.py'
--- bzrlib/doc_generate/sphinx_conf.py 2009-09-08 16:37:05 +0000
+++ bzrlib/doc_generate/sphinx_conf.py 2010-07-05 12:45:12 +0000
@@ -34,7 +34,7 @@

 # General information about the project.
 project = u'Bazaar'
-copyright = u'2009, Canonical Ltd'
+copyright = u'2009, 2010, Canonical Ltd'

[John A Meinel (jameinel)]

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

..

 === modified file 'doc/en/user-guide/index-plain.txt'
> --- doc/en/user-guide/index-plain.txt 2009-12-02 20:34:07 +0000
> +++ doc/en/user-guide/index-plain.txt 2010-07-05 12:44:35 +0000
> @@ -115,5 +115,3 @@
> .. include:: http_smart_server.txt
> .. include:: writing_a_plugin.txt
>
> -.. |--| unicode:: U+2014
> -
>
> I deleted the above as I couldn't find where it was used. If we really need it for html output, I'd prefer some conditional or a solution based on same html style stuff.
>

I don't really know when we *need* an em-dash versus hyphen vs dash,
etc. I'm not a typographer :). However, if you grep the source code, it
is *all over* the place.

grep -rnI "|--|" doc/

Returns 109 hits. Some of those are definitions, but I also see:

doc/developers/implementation-notes.txt:13:* `BTree Index Prefetch
<btree_index_prefetch.html>`_ |--| How bzr decides

doc/developers/index-plain.txt:11:* `Architectural Overview
<overview.html>`_ |--| describes some of the
doc/developers/index-plain.txt:16: |--| automatically generated API
reference information

> I also updated the copyright line that appear on all sphinx pages:
>
> === modified file 'bzrlib/doc_generate/sphinx_conf.py'
> --- bzrlib/doc_generate/sphinx_conf.py 2009-09-08 16:37:05 +0000
> +++ bzrlib/doc_generate/sphinx_conf.py 2010-07-05 12:45:12 +0000
> @@ -34,7 +34,7 @@
>
> # General information about the project.
> project = u'Bazaar'
> -copyright = u'2009, Canonical Ltd'
> +copyright = u'2009, 2010, Canonical Ltd'
                           ^
Everywhere in the source code we use:
  Copyright (C) 2009, 2010 Canonical Ltd

The extra comma looks wrong to me.

(comment for now, running out of time to review the actual content)

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkwzL1IACgkQJdeBCYSNAAP2qwCfY/DDUQKtgukjFLq7Jj1hwhdh
TbAAn1NQ8zyH82/dTmWYJNg+BVdbmcI3
=A9qa
-----END PGP SIGNATURE-----

[Vincent Ladeuil (vila)]

>>>>> John A Meinel <email address hidden> writes:

    > ..

    > === modified file 'doc/en/user-guide/index-plain.txt'
    >> --- doc/en/user-guide/index-plain.txt 2009-12-02 20:34:07 +0000
    >> +++ doc/en/user-guide/index-plain.txt 2010-07-05 12:44:35 +0000
    >> @@ -115,5 +115,3 @@
    >> .. include:: http_smart_server.txt
    >> .. include:: writing_a_plugin.txt
    >>
    >> -.. |--| unicode:: U+2014
    >> -
    >>
    >> I deleted the above as I couldn't find where it was used. If we really need it for html output, I'd prefer some conditional or a solution based on same html style stuff.
    >>

    > I don't really know when we *need* an em-dash versus hyphen vs dash,
    > etc. I'm not a typographer :). However, if you grep the source code, it
    > is *all over* the place.

In doc/developers yes, I don't know exactly why but it seems I searched
only doc/en and missed that.

I need to revisit that.

<snip/>

    >> # General information about the project.
    >> project = u'Bazaar'
    >> -copyright = u'2009, Canonical Ltd'
    >> +copyright = u'2009, 2010, Canonical Ltd'
    > ^
    > Everywhere in the source code we use:
    > Copyright (C) 2009, 2010 Canonical Ltd

    > The extra comma looks wrong to me.

Bah, typo.

[Vincent Ladeuil (vila)]

> === modified file 'doc/en/user-guide/index-plain.txt'
> > --- doc/en/user-guide/index-plain.txt 2009-12-02 20:34:07 +0000
> > +++ doc/en/user-guide/index-plain.txt 2010-07-05 12:44:35 +0000
> > @@ -115,5 +115,3 @@
> > .. include:: http_smart_server.txt
> > .. include:: writing_a_plugin.txt
> >
> > -.. |--| unicode:: U+2014
> > -
> >
> > I deleted the above as I couldn't find where it was used. If we really need
> it for html output, I'd prefer some conditional or a solution based on same
> html style stuff.
> >
>
> I don't really know when we *need* an em-dash versus hyphen vs dash,
> etc. I'm not a typographer :). However, if you grep the source code, it
> is *all over* the place.
>
> grep -rnI "|--|" doc/
>
> Returns 109 hits. Some of those are definitions, but I also see:

But none under doc/user-guide !

[lp:~vila/bzr/cleanup-docs]

5336. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-06

(lifeless) Document the basedir on WorkingTree. (Robert Collins)

[Martin Pool (mbp)]

On 6 July 2010 23:30, John A Meinel <email address hidden> wrote:

>
> I don't really know when we *need* an em-dash versus hyphen vs dash,
> etc. I'm not a typographer :). However, if you grep the source code, it
> is *all over* the place.
>
> grep -rnI "|--|" doc/
>
> Returns 109 hits. Some of those are definitions, but I also see:

I suspect this is Mr Curly Quotes (spiv). I do like using emdashes --
but I'm happy with the ascii form. Really turning '--' into '—' u2014
should be a job of the formatter, not something we have to tell it
every time. I don't care much either way but I don't want edit wars
taking them in or out.

>
> doc/developers/implementation-notes.txt:13:* `BTree Index Prefetch
> <btree_index_prefetch.html>`_ |--| How bzr decides
>
> doc/developers/index-plain.txt:11:* `Architectural Overview
> <overview.html>`_ |--| describes some of the
> doc/developers/index-plain.txt:16:  |--| automatically generated API
> reference information
>
>
>> I also updated the copyright line that appear on all sphinx pages:
>>
>> === modified file 'bzrlib/doc_generate/sphinx_conf.py'
>> --- bzrlib/doc_generate/sphinx_conf.py        2009-09-08 16:37:05 +0000
>> +++ bzrlib/doc_generate/sphinx_conf.py        2010-07-05 12:45:12 +0000
>> @@ -34,7 +34,7 @@
>>
>>  # General information about the project.
>>  project = u'Bazaar'
>> -copyright = u'2009, Canonical Ltd'
>> +copyright = u'2009, 2010, Canonical Ltd'
>                           ^
> Everywhere in the source code we use:
>  Copyright (C) 2009, 2010 Canonical Ltd
>
> The extra comma looks wrong to me.

It is wrong.

--
Martin

[lp:~vila/bzr/cleanup-docs]

5337. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-07

(mbp) developer docs about testing (Martin Pool)

[Vincent Ladeuil (vila)]

> > I don't really know when we *need* an em-dash versus hyphen vs dash,
> > etc. I'm not a typographer :). However, if you grep the source code, it
> > is *all over* the place.
> >
> > grep -rnI "|--|" doc/
> >
> > Returns 109 hits. Some of those are definitions, but I also see:

grep -rnI -e '\( \||\)--\( \||\)' doc/ | wc -l
132

So we already missed some which means either people are not aware it should be used (including me)
or it wasn't deployed completely.

>
> I suspect this is Mr Curly Quotes (spiv). I do like using emdashes --
> but I'm happy with the ascii form.

Same here, I love beautiful TeX output.

> Really turning '--' into '—' u2014
> should be a job of the formatter, not something we have to tell it
> every time.

Indeed. I note that rest *allows* using the 2014 unicode char in its input.

But rest unicode support doesn't seem complete either:
/home/vila/src/bzr/bugs/219334-texinfo/doc/ja/user-guide/stacked.txt:25: (WARNING/2) Title underline too short.

スタックブランチを作成する
-------------------------

Yes, the message says too short, I'm typing this under firefox and the underline seems too long, under emacs, it looks ok...

> I don't care much either way but I don't want edit wars
> taking them in or out.

Anyway, I can't reproduce the problem that triggered that change anymore. But since I migrated from
karmic to lucid in the mean time, that may be enough to explain why.

I still feel a bit distasteful to have to use such an explicit markup in rest (which is otherwise
so unintrusive) but I don't feel the need to fix it either with a solution that doesn't require using
a specific markup or at least define it in a single centralised place (there are other things
to do in this area which are out of scope for my current work).

So I reverted this piece.

> > The extra comma looks wrong to me.
>
> It is wrong.

It is fixed now :)

[John A Meinel (jameinel)]

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

Vincent Ladeuil wrote:
>>> I don't really know when we *need* an em-dash versus hyphen vs dash,
>>> etc. I'm not a typographer :). However, if you grep the source code, it
>>> is *all over* the place.
>>>
>>> grep -rnI "|--|" doc/
>>>
>>> Returns 109 hits. Some of those are definitions, but I also see:
>
> grep -rnI -e '\( \||\)--\( \||\)' doc/ | wc -l
> 132
>
> So we already missed some which means either people are not aware it should be used (including me)
> or it wasn't deployed completely.
>
>> I suspect this is Mr Curly Quotes (spiv). I do like using emdashes --
>> but I'm happy with the ascii form.
>
> Same here, I love beautiful TeX output.
>
>> Really turning '--' into '—' u2014
>> should be a job of the formatter, not something we have to tell it
>> every time.
>
> Indeed. I note that rest *allows* using the 2014 unicode char in its input.
>
> But rest unicode support doesn't seem complete either:
> /home/vila/src/bzr/bugs/219334-texinfo/doc/ja/user-guide/stacked.txt:25: (WARNING/2) Title underline too short.
>
> スタックブランチを作成する
> -------------------------
>
> Yes, the message says too short, I'm typing this under firefox and the underline seems too long, under emacs, it looks ok...

In Thunderbird it looks too long. In ViM it looks correct except these
are 'wide' characters that take up 2 spaces, so I have a []_ (box
followed by space) and the proposed underline doesn't cover up the final -.

(I originally thought that it might be a UTF-8 length thing, but now I'm
not so sure.)

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkw0tn0ACgkQJdeBCYSNAAMhJwCfcGTN0WMqq5OEAhLAYkCE6taV
5RYAn3d6VU9HZ9hOZptRWoA3R/VMQB/F
=OVx7
-----END PGP SIGNATURE-----

[lp:~vila/bzr/cleanup-docs]

5338. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-07

(jameinel) Use a better list of PyQt includes and excludes. (Gary van der
 Merwe)

5339. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-08

(parthm) Better regex compile errors (Parth Malwankar)

5340. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-09

(jameinel) Rename errors.InvalidPattern argument message=>msg to work with
 multiple Python versions. (Parth Malwankar)

5341. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-12

(jam) Merge 2.2b4 to dev, bump the version numbers.

5342. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-13

(jam) Bump trunk to 2.3-dev1

5343. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-13

(mbp) change some test tearDowns to addCleanup or overrideAttr (Martin Pool)

5344. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-13

(mbp) more documentation about maintaing the ppa (Martin Pool)

5345. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-13

(vila) Merge 2.2 into bzr.dev including fixes for bug #525571 and bug
 #494221

5346. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-15

(mbp) document some tricks about testing bzr (tmpfs, tc qdisc,
 parallel) (Martin Pool)

5347. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-16

(vila) Delete deprecated code. (Vincent Ladeuil)

5348. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-16

(mbp) developer docs about transports and symlinks (Martin Pool)

[Vincent Ladeuil (vila)]

sent to pqm by email

[lp:~vila/bzr/cleanup-docs]

5349. By Canonical.com Patch Queue Manager <email address hidden> on 2010-07-16

(vila) Cleanup some bogus rest constructs in the doc. (Vincent Ladeuil)

=== modified file 'bzrlib/doc_generate/sphinx_conf.py'
--- bzrlib/doc_generate/sphinx_conf.py	2009-09-08 16:37:05 +0000
+++ bzrlib/doc_generate/sphinx_conf.py	2010-07-07 11:31:00 +0000
@@ -34,7 +34,7 @@
 
 # General information about the project.
 project = u'Bazaar'
-copyright = u'2009, Canonical Ltd'
+copyright = u'2009, 2010 Canonical Ltd'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

=== modified file 'bzrlib/help_topics/en/conflict-types.txt'
--- bzrlib/help_topics/en/conflict-types.txt	2010-02-04 13:29:34 +0000
+++ bzrlib/help_topics/en/conflict-types.txt	2010-07-07 11:31:00 +0000
@@ -28,11 +28,11 @@
 
 Whatever the conflict is, resolving it is roughly done in two steps::
 
-- modify the working tree content so that the conflicted item is now in the
-  state you want to keep,
+ - modify the working tree content so that the conflicted item is now in the
+   state you want to keep,
 
-- inform Bazaar that the conflict is now solved and ask to cleanup any
-  remaining generated information (``bzr resolve <item>``).
+ - inform Bazaar that the conflict is now solved and ask to cleanup any
+   remaining generated information (``bzr resolve <item>``).
 
 For most conflict types, there are some obvious ways to modify the working
 tree and put it into the desired state. For some types of conflicts, Bazaar
@@ -126,9 +126,9 @@
 
 ``bzr resolve`` recognizes the following actions:
 
-- ``--action=take-this`` will issue ``bzr mv FILE.THIS FILE``,
-- ``--action=take-other`` will issue ``bzr mv FILE.OTHER FILE``,
-- ``--action=done`` will just mark the conflict as resolved.
+ - ``--action=take-this`` will issue ``bzr mv FILE.THIS FILE``,
+ - ``--action=take-other`` will issue ``bzr mv FILE.OTHER FILE``,
+ - ``--action=done`` will just mark the conflict as resolved.
 
 Any action will also delete the previously generated ``.BASE``, ``.THIS`` and
 ``.OTHER`` files if they are still present in the working tree.
@@ -174,9 +174,9 @@
 
 ``bzr resolve`` recognizes the following actions::
 
-- ``--action=take-this`` will issue ``bzr rm FILE ; bzr mv FILE.moved FILE``,
-- ``--action=take-other`` will issue ``bzr rm FILE.moved``,
-- ``--action=done`` will just mark the conflict as resolved.
+ - ``--action=take-this`` will issue ``bzr rm FILE ; bzr mv FILE.moved FILE``,
+ - ``--action=take-other`` will issue ``bzr rm FILE.moved``,
+ - ``--action=done`` will just mark the conflict as resolved.
 
 Note that you must get rid of FILE.moved before using ``--action=done``.
 
@@ -215,10 +215,11 @@
 
 ``bzr resolve`` recognizes the following actions::
 
-- ``--action=take-this`` will issue ``bzr rm directory`` including the children,
-- ``--action=take-other`` will acknowledge Bazaar choice to keep the children
-  and restoring the directory,
-- ``--action=done`` will just mark the conflict as resolved.
+ - ``--action=take-this`` will issue ``bzr rm directory`` including the
+   children,
+ - ``--action=take-other`` will acknowledge Bazaar choice to keep the children
+   and restoring the directory,
+ - ``--action=done`` will just mark the conflict as resolved.
 
 Bazaar cannot auto-detect when conflicts of this kind have been resolved.
 
@@ -238,10 +239,10 @@
 
 ``bzr resolve`` recognizes the following actions::
 
-- ``--action=take-this`` will acknowledge Bazaar choice to keep the directory,
-- ``--action=take-other`` will issue ``bzr rm directory`` including the 
-  children,
-- ``--action=done`` will just mark the conflict as resolved.
+ - ``--action=take-this`` will acknowledge Bazaar choice to keep the directory,
+ - ``--action=take-other`` will issue ``bzr rm directory`` including the 
+   children,
+ - ``--action=done`` will just mark the conflict as resolved.
 
 Bazaar cannot auto-detect when conflicts of this kind have been resolved.
 
@@ -260,10 +261,10 @@
 
 ``bzr resolve`` recognizes the following actions::
 
-- ``--action=take-this`` will revert Bazaar choice and keep ``PATH1`` by
-  issuing ``bzr mv PATH2 PATH1``,
-- ``--action=take-other`` will acknowledge Bazaar choice of keeping ``PATH2``,
-- ``--action=done`` will just mark the conflict as resolved.
+ - ``--action=take-this`` will revert Bazaar choice and keep ``PATH1`` by
+   issuing ``bzr mv PATH2 PATH1``,
+ - ``--action=take-other`` will acknowledge Bazaar choice of keeping ``PATH2``,
+ - ``--action=done`` will just mark the conflict as resolved.
 
 Bazaar cannot auto-detect when conflicts of this kind have been resolved.
 
@@ -295,11 +296,11 @@
 
 ``bzr resolve`` recognizes the following actions::
 
-- ``--action=take-this`` will acknowledge Bazaar choice of leaving ``white`` 
-  in ``black``,
-- ``--action=take-other`` will revert Bazaar choice and move ``black`` in
-  ``white`` by issuing ``bzr mv black/white white ; bzr mv black white``,
-- ``--action=done`` will just mark the conflict as resolved.
+ - ``--action=take-this`` will acknowledge Bazaar choice of leaving ``white`` 
+   in ``black``,
+ - ``--action=take-other`` will revert Bazaar choice and move ``black`` in
+   ``white`` by issuing ``bzr mv black/white white ; bzr mv black white``,
+ - ``--action=done`` will just mark the conflict as resolved.
 
 Bazaar cannot auto-detect when conflicts of this kind have been resolved.
 
@@ -330,11 +331,11 @@
 
 ``bzr resolve`` recognizes the following actions::
 
-- ``--action=take-this`` will issue ``bzr rm --force foo.new`` and 
-  ``bzr add foo``,
-- ``--action=take-other`` will issue ``bzr rm --force foo`` and 
-  ``bzr mv foo.new foo``,
-- ``--action=done`` will just mark the conflict as resolved.
+ - ``--action=take-this`` will issue ``bzr rm --force foo.new`` and 
+   ``bzr add foo``,
+ - ``--action=take-other`` will issue ``bzr rm --force foo`` and 
+   ``bzr mv foo.new foo``,
+ - ``--action=done`` will just mark the conflict as resolved.
 
 Bazaar cannot auto-detect when conflicts of this kind have been resolved.
 

=== modified file 'doc/en/mini-tutorial/index.txt'
--- doc/en/mini-tutorial/index.txt	2009-12-03 00:44:16 +0000
+++ doc/en/mini-tutorial/index.txt	2010-07-07 11:31:00 +0000
@@ -64,7 +64,7 @@
  $ mkdir subdirectory
  $ touch test1.txt test2.txt test3.txt subdirectory/test4.txt
 
-**Note for Windows users:** use Windows Explorer to create your
+**Note for Windows users**: use Windows Explorer to create your
 directories, then right-click in those directories and select
 ``New file`` to create your files.
 
@@ -164,7 +164,7 @@
 
  $ bzr branch http://www.example.com/myproject
 
-**Note:** to use sftp, you may need to install ``paramiko`` and
+**Note**: to use sftp, you may need to install ``paramiko`` and
 ``pyCrypto``. See http://bazaar-vcs.org/InstallationFaq for details.
 
 
@@ -186,7 +186,7 @@
 
 .. [#] Use of the ``lp:`` URL scheme requires bzr 0.92 or later.
 
-**Note:** ``+junk`` means that this branch isn't associated with any particular
+**Note**: ``+junk`` means that this branch isn't associated with any particular
 project in Launchpad.
 
 Now, anyone can create their own copy of your branch by typing::