<!DOCTYPE html>
<html>
<head>
<title></title>
</head>
<body><div>Hi Nic<br></div>
<div> </div>
<div>Nice sleuthing work!<br></div>
<div> </div>
<div>The only alternative I have to offer is that much as Sphinx allows you to write custom themes to change the look and feel of the html, you can also write your own builder (or extend an existing one).</div>
<div><a href="http://sphinx-doc.org/extdev/index.html#dev-extensions">http://sphinx-doc.org/extdev/index.html#dev-extensions</a><br></div>
<div> </div>
<div>That would let us override sphinx's builders/manpage.py and therefore sphinx's writers/manpage.py.<br></div>
<div> </div>
<div>If we had more than one manpage issue, this is probably a better way forwards, but for just tweaking this bold issue, I'm totally on board with updating the Makefile. Go ye forth and fix!<br></div>
<div> </div>
<div> Nicola</div>
<div> </div>
<div>On Tue, Jun 9, 2015, at 08:14 AM, Nic Bernstein wrote:<br></div>
<blockquote type="cite"><div>On 05/19/2015 07:22 AM, Nic Bernstein wrote:<br></div>
<blockquote type="cite" cite="mid:555B2B06.20708@onlight.com"><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.<br></li><ul><li>See cyrus-docs/source/imap/admin/commands/unexpunge.rst
for an example<br></li></ul></ul></blockquote><div> </div>
<div>
Nicola, et al.,<br></div>
<div>
I've tracked down the problem with Sphinx formatting of manpage
output. When using the parsed-literal role, like so:<br></div>
<blockquote><pre>.. parsed-literal::
**arbitron -d** *14*
Normal short list format for the past 14 days.<br></pre></blockquote><div>The docutils manpage writer will produce this output (note my <span class="colour" style="color:rgb(153, 0, 0)">red</span> highlights):<br></div>
<blockquote><pre>.INDENT 3.5
.sp
.nf
<span class="colour" style="color:rgb(153, 0, 0)">.ft C</span>
\fBarbitron \-d\fP \fI14\fP
<span class="colour" style="color:rgb(153, 0, 0)">.ft P</span>
.fi
.UNINDENT
.UNINDENT
.sp
Normal short list format for the past 14 days.
.INDENT 0.0<br></pre></blockquote><div>But this is bogus output. It's popping fonts which have never been
"installed" in the font stack, so renders unreliably:<br></div>
<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><br></pre><div>It should look like this:<br></div>
<pre><b>arbitron -d</b> <u>14</u>
Normal short list format for the past <u>14</u> days.<br></pre><div>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<span class="font" style="font-family:menlo,consolas,"courier new",monospace">nroff</span>.
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></div>
<div> </div>
<div>
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></div>
<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<br></pre></blockquote><div>Here's a diff fragment of my changes:<br></div>
<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', ''),<br></pre></blockquote><div>So here's my quandary:<br></div>
<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.<br></li><li>There's just no way I can find to work around this other than
to either:<br></li><ul><li>Alter the docutils/writers/manpage.py code, as shown above,
or<br></li><li>Grep or sed out the gratuitous ".ft " commands from the
resultant output.<br></li></ul></ul><div>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></div>
<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."
<...><br></pre></blockquote><div>Thoughts?<br></div>
<div> </div>
<div>
Cheers,<br></div>
<div>
-nic<br></div>
<pre>--
Nic Bernstein <a href="mailto:nic@onlight.com">nic@onlight.com</a>
Onlight, Inc. <a href="http://www.onlight.com">www.onlight.com</a>
1442 N Farwell Ave., Suite 600 v. 414.272.4477
Milwaukee, Wisconsin 53202<br></pre><p>Email had 1 attachment:<br></p><ul><li><code>nic.vcf</code><br> 1k (text/x-vcard)</li></ul></blockquote><div> </div>
</body>
</html>