Merge lp:~vila/bzr/782289-chm-sphinx into lp:bzr

[Vincent Ladeuil]

Fix some ReST typos in the configuration help and restore the workaround for dotted format names breaking sphinx.

Fix some rest errors in the configuration help.

Restore the workaround to avoid sphinx errors with dotted format names (--1.14).

Rename readme.txt into README to avoid accidental deletion (I deleted all the '.txt' files there while trying to find which code where generating the files...)

[Alexander Belchenko (bialix)]

14.05.2011 16:22, Vincent Ladeuil пишет:
> Vincent Ladeuil has proposed merging lp:~vila/bzr/782289-chm-sphinx into lp:bzr.
>
> Requested reviews:
> bzr-core (bzr-core)
>
> For more details, see:
> https://code.launchpad.net/~vila/bzr/782289-chm-sphinx/+merge/60993
>
> Fix some rest errors in the configuration help.

Thanks!

> Restore the workaround to avoid sphinx errors with dotted format names (--1.14).

I'd like to have this fix backported to 2.3.

> Rename readme.txt into README to avoid accidental deletion (I deleted all the '.txt' files there while trying to find which code where generating the files...)

I'm not quite understand this change.

There are some ReST problems with japanese texts, it should be easy to
fix too.

--
All the dude wanted was his rug back

[Alexander Belchenko (bialix)]

14.05.2011 17:19, Alexander Belchenko пишет:
> There are some ReST problems with japanese texts, it should be easy to
> fix too.

Partially addressed
https://code.launchpad.net/~bialix/bzr/2.3-ja-doc-rstx/+merge/60996

[Vincent Ladeuil (vila)]

>>>>> Alexander Belchenko writes:

<snip/>

    >> Restore the workaround to avoid sphinx errors with dotted format names (--1.14).

    > I'd like to have this fix backported to 2.3.

Should be pretty straight-forward, but is it necessary ? Did we already
remove --1.9 in 2.3 ?

    >> Rename readme.txt into README to avoid accidental deletion (I
    >> deleted all the '.txt' files there while trying to find which
    >> code where generating the files...)

    > I'm not quite understand this change.

The file was named readme.txt, all generated files there are named
'.txt'. Trying to trigger a minimal rebuild I deleted some and then all
files there without realizing that this 'readme.txt' wasn't a generated
one.

Renaming it README (all caps *and* no suffix) should avoid such a
mistake in the future.

    > There are some ReST problems with japanese texts, it should be
    > easy to fix too.

File a bug please, I don't speak Japanese and last time I looked into
this one I wasn't sure my font was correctly displaying the glyphs so I
didn't want to mess with it.

I heard a rumor that we have some Japanese hacker around working on
i18n, this may be obvious for him ;)

[Alexander Belchenko (bialix)]

14.05.2011 17:48, Vincent Ladeuil пишет:
>>>>>> Alexander Belchenko writes:
> >> Restore the workaround to avoid sphinx errors with dotted format names (--1.14).
> > I'd like to have this fix backported to 2.3.
>
> Should be pretty straight-forward, but is it necessary ? Did we already
> remove --1.9 in 2.3 ?

Yes.

> >> Rename readme.txt into README to avoid accidental deletion (I
> >> deleted all the '.txt' files there while trying to find which
> >> code where generating the files...)
>
> > I'm not quite understand this change.
>
> The file was named readme.txt, all generated files there are named
> '.txt'. Trying to trigger a minimal rebuild I deleted some and then all
> files there without realizing that this 'readme.txt' wasn't a generated
> one.
>
> Renaming it README (all caps *and* no suffix) should avoid such a
> mistake in the future.

Oh, right. It's actually not source for html generation, so I'm all +1.

[John A Meinel (jameinel)]

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

On 05/14/2011 03:21 PM, Vincent Ladeuil wrote:
> Vincent Ladeuil has proposed merging lp:~vila/bzr/782289-chm-sphinx into lp:bzr.
>
> Requested reviews:
> bzr-core (bzr-core)
>
> For more details, see:
> https://code.launchpad.net/~vila/bzr/782289-chm-sphinx/+merge/60993
>
> Fix some rest errors in the configuration help.
>
> Restore the workaround to avoid sphinx errors with dotted format names (--1.14).
>
> Rename readme.txt into README to avoid accidental deletion (I deleted all the '.txt' files there while trying to find which code where generating the files...)
>
>

I really prefer it called at least README.txt. On Windows, files without
extensions won't be opened in an obvious editor. Leaving it at .txt
makes it easy to still open it with a simple double click.

 review: needsfixing

John
=:->

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

iEYEARECAAYFAk3PluUACgkQJdeBCYSNAAM5ZACfXH5Aq+nfhLoopOQOqsitS0fJ
cmIAoNlDQLytV5eL9JvEp6YwPh8UO7V9
=wfNX
-----END PGP SIGNATURE-----

review: Needs Fixing

[John A Meinel (jameinel)]

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

...
> > I'm not quite understand this change.
>
> The file was named readme.txt, all generated files there are named
> '.txt'. Trying to trigger a minimal rebuild I deleted some and then all
> files there without realizing that this 'readme.txt' wasn't a generated
> one.
>
> Renaming it README (all caps *and* no suffix) should avoid such a
> mistake in the future.

The fact that "bzr status" tells you seems sufficient to me.

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

iEYEARECAAYFAk3PlxgACgkQJdeBCYSNAAPrCQCgn8CMA0kjz5VjdiwKY0PMSc1+
ydcAnReRHFwGyDHQEytGGatxuTq+73hl
=DLY0
-----END PGP SIGNATURE-----

[Vincent Ladeuil (vila)]

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

    > ...
    >> > I'm not quite understand this change.
    >>
    >> The file was named readme.txt, all generated files there are named
    >> '.txt'. Trying to trigger a minimal rebuild I deleted some and then all
    >> files there without realizing that this 'readme.txt' wasn't a generated
    >> one.
    >>
    >> Renaming it README (all caps *and* no suffix) should avoid such a
    >> mistake in the future.

    > The fact that "bzr status" tells you seems sufficient to me.

You miss the point.

I realized my mistake *only* when doing 'bzr diff' and seeing the
content of the readme.txt.

Only then did I realized my mistake.

If it has been called README to start with, I would have notice it
earlier and be put on track faster.

You can still open a README file on windows with a
double-click... you're proposed with applications that can open it.

[Alexander Belchenko (bialix)]

review: Approve

[John A Meinel (jameinel)]

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

...
> You can still open a README file on windows with a
> double-click... you're proposed with applications that can open it.

Except that list isn't anything like the list for .txt files (much less
directly opening in your editor.)

I really don't see how README makes it that much better. Why not call it
README.txt?

It isn't that this is a big deal, and I'm going to try to stop
bikeshedding on it. I find it very odd that in our source dir we have
COPYING.txt but README. And I think its a misfeature that we have
.bzr/README instead of .bzr/README.txt

However, the prior art is there...

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

iEYEARECAAYFAk3Q2ZwACgkQJdeBCYSNAAOWngCgkyIRfe6uTPNrkhJxmwQoaXgE
TUUAoLE3yOrzbivkLJ+PTCOKZ2U+AcEN
=7ElW
-----END PGP SIGNATURE-----

[John Szakmeister (jszakmeister)]

On Mon, May 16, 2011 at 4:01 AM, John A Meinel <email address hidden> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>
> ...
>> You can still open a README file on windows with a
>> double-click... you're proposed with applications that can open it.
>
> Except that list isn't anything like the list for .txt files (much less
> directly opening in your editor.)
>
> I really don't see how README makes it that much better. Why not call it
> README.txt?

FWIW, I agree with John. I tend to name things README.txt so that
they pop open with the right editor in Windows. It is really helpful
for Windows folks.

-John

[Vincent Ladeuil (vila)]

>>>>> John Szakmeister <email address hidden> writes:

    > On Mon, May 16, 2011 at 4:01 AM, John A Meinel <email address hidden> wrote:
    >> -----BEGIN PGP SIGNED MESSAGE-----
    >> Hash: SHA1
    >>
    >>
    >> ...
    >>> You can still open a README file on windows with a
    >>> double-click... you're proposed with applications that can open it.
    >>
    >> Except that list isn't anything like the list for .txt files (much less
    >> directly opening in your editor.)
    >>
    >> I really don't see how README makes it that much better. Why not call it
    >> README.txt?

    > FWIW, I agree with John. I tend to name things README.txt so that
    > they pop open with the right editor in Windows. It is really helpful
    > for Windows folks.

I agree with that and know the reasons for the *general* case.

This particular case is a directory where we version *only* readme.txt.

Then the directory is populated with files suffixed with '.txt' and
'readme.txt' is lost in the noise.

Moreover, I think the information in this file would be better in a
guide on how to build the docs not left there as a hint (since I
experienced a workflow where this hint *failed*).

The bottom line is that you can't click a file that has been *deleted*.

Anyway, *I* won't fall in this trap again so I'd just remove this
change.

[Vincent Ladeuil (vila)]

Lol, missed jam comment, everybody stop bikeshedding today ? What's next ? Oracle will become a good free sotware citizen ?

[Vincent Ladeuil (vila)]

sent to pqm by email

=== modified file 'bzrlib/commands.py'
--- bzrlib/commands.py	2011-04-19 04:37:48 +0000
+++ bzrlib/commands.py	2011-05-16 09:18:29 +0000
@@ -520,12 +520,13 @@
         # so we get <https://bugs.launchpad.net/bzr/+bug/249908>.  -- mbp
         # 20090319
         options = option.get_optparser(self.options()).format_option_help()
-        # XXX: According to the spec, ReST option lists actually don't support 
-        # options like --1.9 so that causes syntax errors (in Sphinx at least).
-        # As that pattern always appears in the commands that break, we trap
-        # on that and then format that block of 'format' options as a literal
-        # block.
-        if not plain and options.find('  --1.9  ') != -1:
+        # FIXME: According to the spec, ReST option lists actually don't
+        # support options like --1.14 so that causes syntax errors (in Sphinx
+        # at least).  As that pattern always appears in the commands that
+        # break, we trap on that and then format that block of 'format' options
+        # as a literal block. We use the most recent format still listed so we
+        # don't have to do that too often -- vila 20110514
+        if not plain and options.find('  --1.14  ') != -1:
             options = options.replace(' format:\n', ' format::\n\n', 1)
         if options.startswith('Options:'):
             result += ':' + options

=== modified file 'bzrlib/help_topics/en/configuration.txt'
--- bzrlib/help_topics/en/configuration.txt	2011-02-25 12:12:39 +0000
+++ bzrlib/help_topics/en/configuration.txt	2011-05-16 09:18:29 +0000
@@ -603,25 +603,25 @@
 executable may omit its path if it can be found on the PATH.
 
 The following markers can be used in the command-line to substitute filenames
-involved in the merge conflict:
-
-{base}      file.BASE
-{this}      file.THIS
-{other}     file.OTHER
-{result}    output file
-{this_temp} temp copy of file.THIS, used to overwrite output file if merge
-            succeeds.
-
-For example:
+involved in the merge conflict::
+
+  {base}      file.BASE
+  {this}      file.THIS
+  {other}     file.OTHER
+  {result}    output file
+  {this_temp} temp copy of file.THIS, used to overwrite output file if merge
+              succeeds.
+
+For example::
 
   bzr.mergetool.kdiff3 = kdiff3 {base} {this} {other} -o {result}
 
 bzr.default_mergetool
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
 
 Specifies which external merge tool (as defined above) should be selected by
 default in tools such as ``bzr qconflicts``.
 
-For example:
+For example::
 
   bzr.default_mergetool = kdiff3

=== modified file 'doc/en/release-notes/bzr-2.4.txt'
--- doc/en/release-notes/bzr-2.4.txt	2011-05-14 21:16:04 +0000
+++ doc/en/release-notes/bzr-2.4.txt	2011-05-16 09:18:29 +0000
@@ -74,6 +74,10 @@
 
 .. Improved or updated documentation.
 
+* Restore the workaround for option names including dots (--1.14) which was
+  disabled when we stopped listing --1.9 as a format.
+  (Vincent Ladeuil, #782289)
+
 API Changes
 ***********