Documentation Unification and Awesomeification
nicolan at fastmail.com
Mon Jun 8 20:43:16 EDT 2015
Nice sleuthing work!
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).
That would let us override sphinx's builders/manpage.py and therefore
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!
On Tue, Jun 9, 2015, at 08:14 AM, Nic Bernstein wrote:
> 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.
>> * 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
>> .INDENT 3.5
>> .ft C
\fBarbitron \-d\fP \fI14\fP
>> .ft P
.fi .UNINDENT .UNINDENT .sp Normal short list format for the past 14
days. .INDENT 0.0
> But 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 innroff. 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
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
'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
> * Alter the docutils/writers/manpage.py code, as shown above,
> * Grep or sed out the gratuitous ".ft " commands from the
> 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." <...>
Nic Bernstein nic at onlight.com Onlight, Inc.
www.onlight.com 1442 N Farwell Ave., Suite 600 v.
414.272.4477 Milwaukee, Wisconsin 53202
> Email had 1 attachment:
> * nic.vcf 1k (text/x-vcard)
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Cyrus-devel