manpage escape strings showing
Affects | Status | Importance | Assigned to | Milestone | |
---|---|---|---|---|---|
Bazaar |
In Progress
|
High
|
Richard Wilbur |
Bug Description
Issues with the escape sequences observed in `man bzr`
(also visible in `info bzr`)
command, section, with:
bzr commit 'Checks:' 'bzr help hooks'
'Things to note:' 'bzr help uncommit',
bzr ignore 'bzr help patterns'
bzr log 'Output control:' 'long', 'short', 'line',
'Path filtering'->'In this case'
'Tips & tricks' 'bazaar.conf', 'bzr tip',
bzr send 'bzr send',
bzr serve 'Options' 'bzr server'
bzr tag 'bzr tag new-name -r tag:old-name',
bzr view 'off'
Related branches
- Vincent Ladeuil: Pending requested
-
Diff: 11 lines (+0/-1)1 file modifiedbzrlib/doc_generate/autodoc_man.py (+0/-1)
Changed in bzr: | |
milestone: | 2.7.0 → 2.8b1 |
Turns out I found what looks like the smoking gun in bzrlib/ doc_generate/ autodoc_ man.py: _header = '.SS "%s"\n' % (cmd._usage()) help_topics. help_as_ plain_text( cmd.help( ))
format_command():
"""Provides long help for each public command"""
subsection
doc = "%s\n" % (cmd.__doc__)
-> doc = bzrlib.
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?