Documentation notes from conference call 6/29/2015

Nic Bernstein nic at
Mon Jun 29 15:49:15 EDT 2015

Here's my notes from today's discussion about documentation.

The man pages have all been converted (ported, what have you) from their 
original troff format to the new ReStructuredText (rst) format.

This work was done in the new cyrus-docs (rD) repo, which is separate 
from the cyrus-imapd (rI) repo.  The singular exception to this is 
imapd.conf.5, which is generated by software from 

I produced a now tool, cyrus-imapd/tools/config2rst, cribbed from 
config2man, which achieves this goal (with small complaints from 
Sphinx).  Following the conference call Bron landed my commits for this, 
and it passed harbormaster review (after dancing clamav jig).

The need to include suitably troff formatted manpages in 
cyrus-imapd/man, but the presence of most of them in 
cyrus-docs/source/imap/admin/{configs|commands} or 
cyrus-docs/source/imap/developer/libraries (and ultimately in troff 
format in cyrus-docs/build/man), seems awkward.  Especially when the 
case of imapd.conf.5 is added to the mix.

We decided that there is probably no really compelling reason to have 
the manpages be in a separate repo from the sources.  For now, however, 
the only nod to such a change was to have cyrus-imapd/Makefile put 
imapd.conf.rst into a newly created cyrus-imapd/doc/rst directory.

Ultimately, either all of the docs should be moved back into the 
cyrus-imapd repo, or at least the manpages should.  This was left as a 
matter for further discussion, as, quite likely, the ultimate 
disposition of cyrus-imapd/doc will be.


Nic Bernstein                             nic at
Onlight, Inc.                   
1442 N Farwell Ave., Suite 600            v. 414.272.4477
Milwaukee, Wisconsin  53202

-------------- next part --------------
A non-text attachment was scrubbed...
Name: nic.vcf
Type: text/x-vcard
Size: 271 bytes
Desc: not available
Url : 

More information about the Cyrus-devel mailing list