text wrapping in doc_generate causes broken links and ReST syntax errors (was: make docs fails creating manpage due to "-0.92" at lines 2344, 2424)

[cfr]

Issuing make docs in the source directory for bzr 1.5 fails with the following error:

python tools/rst2html.py --link-stylesheet --footnote-references=superscript --halt=warning --stylesheet=../../default.css doc/en/user-reference/bzr_man.txt doc/en/user-reference/bzr_man.html
doc/en/user-reference/bzr_man.txt:2344: (WARNING/2) Option list ends without a blank line; unexpected unindent.
Exiting due to level-2 (WARNING) system message.
make: *** [doc/en/user-reference/bzr_man.html] Error 1

I discovered that substituting "--pack" for "--pack-0.92" allows the generation to continue but the same error occurs at line 2424 (which seems to be a repeat of 2344). I did not tinker further since removing "-0.92" obviously is not a fix - I just wanted to figure out which part of the line caused the error. Unfortunately, I'm not familiar with the mark-up for RST and my efforts to correct doc/en/user-reference/bzr_man.txt have been unsuccessful. I'm hoping that for somebody familiar with the syntax the error will be obvious and a quick fix equally so.

I checked MacPorts in case they had a patch but couldn't find anything relevant.

I'm not sure if this is a bzr bug, a docutils bug or something else but this seemed the best place to report it initially.

Darwin Kernel Version 8.11.0: Wed Oct 10 18:26:00 PDT 2007; root:xnu-792.24.17~1/RELEASE_PPC
bzr 1.5
python 2.5.2
docutils snapshot (downloaded 2008/07/14)

[cfr (margali)]

Bumping the version of docutils from 0.4.1 to 0.6.0 in tools/rst2html.py at line 23 allows the documentation to build successfully but I gather from the comments there that this is not an optimal solution.

[Martin Pool (mbp)]

I think the problem here is that the txt file generation is doing wordwrapping on hyphens. There are compound words like "doc.bazaar-vcs.org" or "pack-0.92" that if broken across lines will cause either broken links or ReST errors.

[Martin Pool (mbp)]

I've put up a change that fixes some of these. Unfortunately some of the unwanted wrapping is happening inside optparse where we can't easily control it.

[Martin Pool (mbp)]

The other cases would probably be fixed by fixing bug 330494.

[Martin Pool (mbp)]

bb http://bundlebuggy.aaronbentley.com/project/bzr/request/%3Ce01316480903232138n34d2e189w71e7e8ee1f7e255a%40mail.gmail.com%3E

[Martin Pool (mbp)]

I was going to use break_on_hyphens=False, but that doesn't work in python2.5 which is still supported by bzr. With that removed, this patch passes on 2.5 and 2.4 so I'm going to send it in.

The state now is that there are no syntax errors, and the output in the user reference looks OK, except for some arguments to check. I'll see if they can be tweaked.

[Martin Pool (mbp)]

New attempt at this patch http://bundlebuggy.aaronbentley.com/project/bzr/request/%3Ce01316480906152143n3e9cdddw4a91756290ccf931%40mail.gmail.com%3E

[Martin Pool (mbp)]

Sent to pqm

[Martin Pool (mbp)]

More could be done to make both the docs and help cleaner, but the branch for this bug is landed.