<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
On 05/19/2015 07:22 AM, Nic Bernstein wrote:<br>
<blockquote cite="mid:555B2B06.20708@onlight.com" type="cite">
<li>The Sphinx man page output can be unpredictable<br>
</li>
<ul>
<li>Man output can sometimes shift to <b>bold</b> and never
come back to normal.</li>
<ul>
<li>See cyrus-docs/source/imap/admin/commands/unexpunge.rst
for an example</li>
</ul>
</ul>
</blockquote>
<br>
Nicola, et al.,<br>
I've tracked down the problem with Sphinx formatting of manpage
output. When using the parsed-literal role, like so:<br>
<blockquote>
<pre>.. parsed-literal::
**arbitron -d** *14*
Normal short list format for the past 14 days.
</pre>
</blockquote>
The docutils manpage writer will produce this output (note my <font
color="#990000">red</font> highlights):<br>
<blockquote>
<pre>.INDENT 3.5
.sp
.nf
<font color="#990000">.ft C</font>
\fBarbitron \-d\fP \fI14\fP
<font color="#990000">.ft P</font>
.fi
.UNINDENT
.UNINDENT
.sp
Normal short list format for the past 14 days.
.INDENT 0.0
</pre>
</blockquote>
But this is bogus output. It's popping fonts which have never been
"installed" in the font stack, so renders unreliably:<br>
<pre> <b>arbitron -d</b> <u>14</u>
<u>Normal</u> <u>short</u> <u>list</u> <u>format</u> <u>for</u> <u>the</u> <u>past</u> <u>14</u> <u>days.</u>
</pre>
It should look like this:<br>
<pre> <b>arbitron -d</b> <u>14</u>
Normal short list format for the past <u>14</u> days.
</pre>
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 <tt>nroff</tt>.
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."<br>
<br>
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:<br>
<blockquote>
<pre>.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
</pre>
</blockquote>
Here's a diff fragment of my changes:<br>
<blockquote>
<pre>--- /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', ''),
</pre>
</blockquote>
So here's my quandary:<br>
<ul>
<li>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.</li>
<li>There's just no way I can find to work around this other than
to either:</li>
<ul>
<li>Alter the docutils/writers/manpage.py code, as shown above,
or</li>
<li>Grep or sed out the gratuitous ".ft " commands from the
resultant output.<br>
</li>
</ul>
</ul>
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:<br>
<blockquote>
<pre><...>
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."
<...>
</pre>
</blockquote>
Thoughts?<br>
<br>
Cheers,<br>
-nic<br>
<pre class="moz-signature" cols="72">--
Nic Bernstein <a class="moz-txt-link-abbreviated" href="mailto:nic@onlight.com">nic@onlight.com</a>
Onlight, Inc. <a class="moz-txt-link-abbreviated" href="http://www.onlight.com">www.onlight.com</a>
1442 N Farwell Ave., Suite 600 v. 414.272.4477
Milwaukee, Wisconsin 53202
</pre>
</body>
</html>