Cyrus Documentation tools

[Nic Bernstein]

On 05/13/2015 04:33 AM, Bron Gondwana wrote:
> Doxygen would be fine.
> On Wed, May 13, 2015, at 09:24 AM, Chris Davies wrote:
>> Adding the Cyrus mailing list as I can't remember who the other 
>> documentation person is.
>> Do you think something like Doxygen 
>> <http://www.stack.nl/%7Edimitri/doxygen/index.html> would be of use 
>> for the Cyrus project? it can generate HTML docs and man pages.
>> I haven't downloaded it yet but it claims to do what we need.

Chris,
The current documentation, in the cyrus-docs branch, is in reStructured 
Text <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>.

There's a page up on the wiki which describes what I have used to get up 
and working with this existing collection of files:
     https://git.cyrus.foundation/w/documentation_desktop_tools/

>> On Wed, 13 May 2015, at 05:08 PM, Chris Davies wrote:
>>> Just trying to figure out how Cyrus works and exploring the admin tools:
>>>
>>>     https://docs.cyrus.foundation/imap/admin.html
>>>     "The ctl_deliver program outputs a list of files and/or
>>>     directories that it expects to exist, but that in fact do not."
>>>     "The ctl_mboxlist program outputs a list of files and/or
>>>     directories that it expects to exist, but that in fact do not."
>>>     "The cvt_cyrusdb program outputs a list of files and/or
>>>     directories that it expects to exist, but that in fact do not."
>>>     "The cyr_dbtool program outputs a list of files and/or
>>>     directories that it expects to exist, but that in fact do not."
>>>
> Yeah, maybe not.

To be fair, these are all in the "Work-in-progress" section of the page, 
which includes this disclaimer:

    *For the following parts of the documentation, while they are a
    work-in- progress, you may already have better documentation on your
    system, in the form of actual man-pages.*

We are in the process of fixing all of this.  For example, a recent 
commit, D31 <https://git.cyrus.foundation/D31>, is ready to land, and 
contains updates to the ctl_cyrusdb(8), chk_cyrus(8) and unexpunge(8) 
man pages (these being in cyrus-imap branch, in the /man/ directory).

Another issue with which we're contending, and which was discussed 
recently on IRC, is that there's two versions (at least) of some of this 
stuff, in cyrus-docs/source/imap/admin/commands and in cyrus-imap/man.  
I'm currently working to harmonize these two versions so we can dump one 
or the other.

One of the reasons to get access control working again on the old site, 
www.cyrusimap.org, is to at least allow that to serve as an intermediary 
resource until the new site gets up to snuff.  All of the commands you 
list, above, are fully documented here:
     http://www.cyrusimap.org/docs/cyrus-imapd/2.4.17/man.php

But, we know that the branches for newer releases (2.5*) there are 
broken, so for now stick with the 2.4.17 until we can get the rest fixed.

Cheers,
     -nic (on IRC as 'onlight')

>>> Bron, Who was the other person working on documentation?
> Simon Amor.  Who is on this list I'm pretty sure.  He's ^Simon^ in IRC.
>
> Bron.
> --
> Bron Gondwana
> brong at fastmail.fm

-- 
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 --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150513/8785d165/attachment.html 
-------------- 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/20150513/8785d165/attachment.vcf