Documentation Unification and Awesomeification

[Nic Bernstein]

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.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 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                             nic at onlight.com
Onlight, Inc.                             www.onlight.com
1442 N Farwell Ave., Suite 600            v. 414.272.4477
Milwaukee, Wisconsin  53202

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150608/e295abae/attachment.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: nic.vcf
Type: text/x-vcard
Size: 271 bytes
Desc: not available
Url : http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150608/e295abae/attachment.vcf