Comment 1 for bug 1540293

Turns out I found what looks like the smoking gun in bzrlib/doc_generate/autodoc_man.py:
format_command():
     """Provides long help for each public command"""
     subsection_header = '.SS "%s"\n' % (cmd._usage())
     doc = "%s\n" % (cmd.__doc__)
-> doc = bzrlib.help_topics.help_as_plain_text(cmd.help())

First we use cmd.__doc__ then we overwrite with man-escaped help text.
Later in infogen(), we call man_escape() on this same text. No wonder it doesn't turn out correctly, we escaped the escape sequences!

That's easy to fix, just eliminate the line with the arrow above.

But this brings up a different question: Most of the places with problems stem from the manpage author(s) using two single quote marks:
``bzr help hooks``
or
''added''

instead of double quote marks:
"bzr help hooks"
or
"added"

The documentation in other places does use double quotes for the same purpose. (Id est, the usage is inconsistent.)

What would be the preferrable punctuation. Can we establish or reference a decent convention?