Documentation notes from conference call 6/29/2015

[Nic Bernstein]

Friends,
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 
cyrus-imapd/lib/imapoptions.

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.

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: nic.vcf
Type: text/x-vcard
Size: 271 bytes
Desc: not available
Url : http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150629/a3e672e8/attachment.vcf