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 n...@onlight.com
Onlight, Inc. www.onlight.com
1442 N Farwell Ave., Suite 600 v. 414.272.4477
Milwaukee, Wisconsin 53202
<<attachment: nic.vcf>>
