Documentation Unification and Awesomeification
nic at onlight.com
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 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
>> • Alter the docutils/writers/manpage.py code, as shown above, or
>> • Grep or sed out the gratuitous ".ft " commands from the resultant
>> 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
>> $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
>> $(SED) -i -e 's/^\.ft.*//' $(BUILDDIR)/man/*.[0-9]*
>> @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
> 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.com
Onlight llc. www.onlight.com
219 N. Milwaukee St., Ste. 2A v. 414.272.4477
Milwaukee, Wisconsin 53202 f. 414.290.0335
More information about the Cyrus-devel