On 05/19/2015 07:22 AM, Nic Bernstein wrote:
# The Sphinx man page output can be unpredictable* Man output can sometimes shift to *bold* and never come back to normal. o See cyrus-docs/source/imap/admin/commands/unexpunge.rst for an example
Nicola, et al.,I've tracked down the problem with Sphinx formatting of manpage output. When using the parsed-literal role, like so:
.. parsed-literal::**arbitron -d** *14*
Normal short list format for the past 14 days.The docutils manpage writer will produce this output (note my red highlights):
.INDENT 3.5 .sp .nf .ft C \fBarbitron \-d\fP \fI14\fP .ft P .fi .UNINDENT .UNINDENT .sp Normal short list format for the past 14 days. .INDENT 0.0But this is bogus output. It's popping fonts which have never been "installed" in the font stack, so renders unreliably:
*arbitron -d* _14_
_Normal_ _short_ _list_ _format_ _for_ _the_ _past_ _14_ _days._
It should look like this:
*arbitron -d* _14_
Normal short list format for the past_14_ days.
Also, it relies on the availability of the font "C" (being Courier)
which is a bad assumption on many systems. Furthermore, since almost
all manpage output we're concerned with is processed with nroff, not
groff, and "Fonts have limited meaning in nroff. The font used is a
constant-width font. If you specify bold, characters are overstruck in
printing. Italic is interpreted as an underline. Other fonts have no
meaning."
I've modified my local copy of (on Ubuntu Trusty) /usr/lib/python2.7/dist-packages/docutils/writers/manpage.py to remove these gratuitous ".ft C"...".ft P" couplets, and now it works perfectly, producing this:
.INDENT 3.5
.sp
.nf
\fBarbitron \-d\fP \fI14\fP
.fi
.UNINDENT
.UNINDENT
.sp
Normal short list format for the past 14 days.
.INDENT 0.0
Here's a diff fragment of my changes:
--- /usr/lib/python2.7/dist-packages/docutils/writers/manpage.py
2015-06-08 16:34:27.602186607 -0500
+++ /usr/local/lib/python2.7/dist-packages/docutils/writers/manpage.py
2015-05-26 12:14:01.000000000 -0500
@@ -213,7 +213,7 @@
'definition_list_item' : ('.TP', ''),
'field_name' : ('.TP\n.B ', '\n'),
'literal' : ('\\fB', '\\fP'),
- 'literal_block' : ('.sp\n.nf\n', '\n.fi\n'),
+ 'literal_block' : ('.sp\n.nf\n.ft C\n', '\n.ft P\n.fi\n'),
'option_list_item' : ('.TP\n', ''),
So here's my quandary:
* I've found it completely impossible to produce standards-compliant
man pages using ReStructuredText with the Sphinx/Docutils tool
suite, without running into this problem.
* There's just no way I can find to work around this other than to either:
o Alter the docutils/writers/manpage.py code, as shown above, or
o Grep or sed out the gratuitous ".ft " commands from the
resultant output.
I think the best way forward with this is to opt for the latter and
modify cyrus-docs/Makefile to strip the resulting manpages from
cyrus-docs/build/man, like so:
<...>
BUILDDIR = build
SED = /bin/sed
<snip>
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
$(SED) -i -e 's/^\.ft.*//' $(BUILDDIR)/man/*.[0-9]*
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
<...>
Thoughts?
Cheers,
-nic
--
Nic Bernstein n...@onlight.com
Onlight, Inc. www.onlight.com
1442 N Farwell Ave., Suite 600 v. 414.272.4477
Milwaukee, Wisconsin 53202
<<attachment: nic.vcf>>
