Documentation Unification and Awesomeification

[Nicola Nye]

Hi Nic

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).
http://sphinx-doc.org/extdev/index.html#dev-extensions

That would let us override sphinx's builders/manpage.py and therefore
sphinx's writers/manpage.py.

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!

Nicola

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
> 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 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
+++ /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:
>    * Alter the docutils/writers/manpage.py code, as shown above,
          or
>    * 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
> Email had 1 attachment:


>  * nic.vcf  1k (text/x-vcard)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150609/6790d8a3/attachment-0001.html