Documentation Unification and Awesomeification

Nic Bernstein nic at
Tue Jun 9 07:48:30 EDT 2015

On 06/09/2015 04:59 AM, Sebastian Hagedorn wrote:
> --On 8. Juni 2015 17:14:21 -0500 Nic Bernstein <nic at> 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/ 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:
>> $(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...


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

More information about the Cyrus-devel mailing list