manpage escape strings showing

Bug #1540293 reported by Richard Wilbur
6
This bug affects 1 person
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 help bugs'
 bzr ignore 'bzr help patterns'
 bzr log 'Output control:' 'long', 'short', 'line',
                              'bzr help log-formats', 'added',
                              'modified'
            'Revision filtering'
                              'bzr help revisionspec'
            'Path filtering'->'In this case'
                              'bzr log guide.txt',
                              'bzr log tutorial.txt',
                              'bzr log -r2 -p tutorial.txt',
                              'bzr log -r2 -p guide.txt',
            'Tips & tricks' 'bazaar.conf', 'bzr tip',
                              'bzr top', 'bzr show -rX',
                              'bzr log -n0 -rX', 'bzr log -v'
 bzr send 'bzr send',
                              'bzr help configuration',
                              'bzr info'
 bzr serve 'Options' 'bzr server'
 bzr tag 'bzr tag new-name -r tag:old-name',
                              'bzr tag --delete oldname',
                              'bzr help hooks'
 bzr view 'off'

Related branches

Revision history for this message
Richard Wilbur (richard-wilbur) wrote :

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?

Changed in bzr:
status: New → Triaged
status: Triaged → In Progress
Revision history for this message
Richard Wilbur (richard-wilbur) wrote :

So I searched on the internet and found that `man man-pages` or `info man-pages` talks about conventions for writing Linux man pages. Sounds like I have some reading to do!

Vincent Ladeuil (vila)
Changed in bzr:
milestone: 2.7.0 → 2.8b1
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.