Documentation notes from conference call 6/29/2015
nic at onlight.com
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/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.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...
Size: 271 bytes
Desc: not available
Url : http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150629/a3e672e8/attachment.vcf
More information about the Cyrus-devel