Documentation Unification and Awesomeification

[Nic Bernstein]

On 06/09/2015 04:59 AM, Sebastian Hagedorn wrote:
> --On 8. Juni 2015 17:14:21 -0500 Nic Bernstein <nic at onlight.com> wrote:
>
>> 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?
>
> How about reporting this as a bug upstream?

I fully intend to. My quandary, perhaps incompletely summarized, had to 
do with the exigencies of producing usable manpages, in a repeatable 
manner, given the time frame of releases.

I think I'll opt for Nicola's suggestion of an extension for Sphinx, if 
that will do the job. For the record, however, the problem here is with 
a component of docutils, not Sphinx, so it's unclear to me if a Sphinx 
extension can fix it. I'll look into that. I'm not a Python expert, so...

Cheers,
-nic

-- 
Nic Bernstein                             nic at onlight.com
Onlight llc.                              www.onlight.com
219 N. Milwaukee St., Ste. 2A	          v. 414.272.4477
Milwaukee, Wisconsin  53202		  f. 414.290.0335