Documentation Unification and Awesomeification

Nic Bernstein nic at
Thu May 21 17:36:18 EDT 2015

Thanks for the follow up.  I've not had any time for documentation 
lately, but have found some issues which need repair on the work I have 
done.  I'll get that committed once it's clean.

Given what you've said, below, I will stop changing the man pages in the 
cyrus-imapd repo.  So far I've already been replicating all changes made 
there into cyrus-docs anyway.

Once I've got the commands pages doing what I want, I'll get a 
documentation best practices or style guide put together.  Something 
where I can note how the manpages are being done, and you can add 
whatever else.  Okay?


On 05/20/2015 10:34 PM, Nicola Nye wrote:
> Hi Nic,
> I am not (yet!) aware of much of the internals of imapd or sasl, so I 
> think we have a good breakdown between us of input to add to the Cyrus 
> docs. If you're able to unify and get the commands/config docs up to 
> date, that is awesome.
> Bron added you as a committer to the cyrus-docs repo, so you're free 
> to update in there.
> My plan is to ignore cyrus-imapd repository. Just concentrate on 
> getting cyrus-docs current so we can declare the old cyrus-imapd docs 
> area obsolete. Trying to update both is just resulting in double the 
> work for little gain.
> To that end, I suggest you continue declaring your conventions on 
> handling things in cyrus-docs (such as handling the revision data, 
> along with the stylistic conventions) and throw up a note in the 
> Phabricator wiki about how it's now all done, much as you did with the 
> Documentation Desktop Tools.
> For providing fancier web based documentation vs man page 
> documentation, a quick rummage around the Sphinx docs shows that you 
> can specify to only include content which contains certain tags. 
> Perhaps we can set up some tags for html only output. 
> I also wonder if this might be used to give us simple versioning, if 
> we want to generate a separate doctree for each imap release. (Instead 
> of having a single doctree with inline notes). Probably a bridge to 
> cross later!
> Cheers,
>    Nicola
> On Tue, May 19, 2015, at 10:22 PM, Nic Bernstein wrote:
>> Nicola, et alia,
>> [Apologies for top-posting, but it seemed appropriate here]
>> Glad to see you jumping on board, and welcome!
>> This all sounds good, and much needed.  Something brought home to me 
>> by my recent push to harmonize man pages (between the two branches 
>> you've mentioned) is that the current bifurcation between cyrus-imapd 
>> and cyrus-docs repositories presents some problems.
>> Since there /is/ still documentation, in the form of man pages, at 
>> least, in the cyrus-imapd repository, any proper document review and 
>> update ends up touching both repos, and thus requires separate 
>> commits (or diffs, in arcanist lingo) and separate review and 
>> "landing" tasks.
>> <whinge>
>>     I submitted D31 over a month ago and it sat unattended until
>>     about a week ago, when it was reviewed and cleared for landing. 
>>     But, as I have insufficient rights, I cannot land it.  That's in
>>     the cyrus-imapd repo so thus requires someone with rights in that
>>     branch to land them.
>>     Similarly, I've more recently submitted D43, D44 & D45, which
>>     still await review, etc.
>> </whinge>
>> I'm not asking for such rights, but I am hoping that someone can make 
>> some proper sense out of this split repo.  In an IRC exchange, Jeroen 
>> wrote:
>>     [2015-05-06 15:37:44] <kanarip_> *fwiw, i also plan to generate
>>     very much larger man-pages by using the rst*
>>     [2015-05-06 15:42:36] <kanarip_> *so, this for example:
>>     [2015-05-06 15:42:44] <kanarip_> *can also become chk_cyrus.8*
>>     [2015-05-06 15:43:04] <kanarip_> *but there's just much more
>>     real-estate in the web page than there is in the man page, right?*
>>     [2015-05-06 15:43:14] <kanarip_> *and much more markup to be used
>>     and abused*
>>     [2015-05-06 15:43:43] <kanarip_> *so i would prefer that when we
>>     aim to make the documentation more complete if you will*
>>     [2015-05-06 15:44:26] <kanarip_> *barring that the actual man
>>     page when used as a man page does not become completely
>>     illegible, it only needs to state the text even if in a slightly
>>     less legible format IMHO*
>>     [2015-05-06 15:44:34] <onlight> /Ok, but how shall we harmonize
>>     the two different versions?  Shall we deprecate the old-style
>>     stuff in cyrus-imap/man in preference/
>>     [2015-05-06 15:45:17] <onlight> /for the newer RST-based stuff?.../
>>     [2015-05-06 15:45:43] <kanarip_>*i would like to, and then be
>>     able to create a git submodule for the docs repo, and then
>>     generate the docs, and then pull those docs back in as man-pages*
>>     [2015-05-06 15:45:56] <kanarip_> *with the exception of
>>     man/imapd.conf.5 of course*
>> I am by no means a git expert, so have no idea what's involved with 
>> realizing this goal, but I do think it would help tremendously to be 
>> able to abandon the old stuff in cyrus-imapd/man for converted pages 
>> from cyrus-docs/source/imap/admin/commands/*.rst.
>> [BTW: I see that rst2man has a feature 
>> (--strip-elements-with-class=<class>) which can filter certain stuff 
>> out of the RST pages while producing the man pages.  Does the Sphinx 
>> feature set support this?  If so, how does one effect this?]
>> That said, there are problems with the reStructured Text man pages:
>>   * They are incomplete
>>       o The initial list in
>>         is about halfway complete.  These are done:
>>           + chk_cyrus
>>           + ctl_cyrusdb
>>           + cyradm
>>           + unexpunge
>>           + ctl_deliver
>>           + ctl_mboxlist
>>           + cvt_cyrusdb
>>           + cyr_dbtool
>>           + cyr_df
>>           + cyr_expire
>>           + cyr_info
>>           + squatter
>>           + ctl_conversationsdb
>>           + sync_client
>>       o These are not done:
>>           + cyrus-master
>>           + ipurge
>>           + master
>>           + mbexamine
>>           + mbpath
>>           + mbtool
>>           + mkimap
>>           + ptdump
>>       o This initial list is itself incomplete (see hidden section in
>>         cyrus-docs/source/imap/admin/commands.rst). The following (of
>>         which some are daemons) are missing:
>>           + nntpd
>>           + notifyd
>>           + pop3d
>>           + proxyd
>>           + rehash
>>           + sievec
>>           + sieved
>>           + smmapd
>>           + sync_reset
>>           + sync_server
>>           + timsieved
>>           + translatesieve
>>           + undohash
>>           + upgradesieve
>>       o [More] Examples are needed for many commands
>>   * Unlike the cyrus-imapd repo, there are no branches or tags in
>>     cyrus-docs to differentiate between versions (2.4.X, 2.5.X,
>>     3.0...) of Cyrus, so I've compromised by adding "History"
>>     sections to those man pages which need them, and adding standard
>>     language, such as "This {feature|command} was introduced in
>>     version 3.0."
>>   * The Sphinx man page output can be unpredictable
>>       o HTML output from these documents looks fine, by and large.
>>       o Man output can sometimes shift to *bold* and never come back
>>         to normal.
>>           + See cyrus-docs/source/imap/admin/commands/unexpunge.rst
>>             for an example
>>   * There are stylistic differences which should/must get sorted
>>       o Traditional man pages, such as those in cyrus-imapd/man,
>>         alternate *bold* and /italic/ like so:
>>           + # *command --option* /<value>/ *-D -b -C*
>>             //etc/imapd-new.conf/ *-X* ...
>>       o Man page output produced by Sphinx, however, does not follow
>>         this convention.
>>       o In the existing collection of reStructured Text files, there
>>         is a mix of ``literal`` and **bold** for the same thing, such
>>         as command name.
>>           + The convention is **bold**, but whatever is used, we
>>             should unify this
>>           + For the record, this does not appear to make a
>>             significant difference in HTML output, but does affect
>>             man page rendering (at least in my experience).
>> Okay, I'll get off of my soapbox for now.  I just wanted to take this 
>> opportunity to get some of these issues out there.
>> Cheers,
>>     -nic
>> On 05/18/2015 10:57 PM, Nicola Nye wrote:
>>> Hi folks,
>>> I'm a tech writer with FastMail and I'm here to help.
>>> Here's my plan to organise the (many and flavourful) varieties of 
>>> documentation surrounding the Cyrus imap universe. Please speak up 
>>> if you have thoughts/ideas/objections!
>>> *The Goal*
>>> Make the content on the authoritative source 
>>> for all things Cyrus Imap/Sasl.
>>> (The server/websitename will be changing at some point, but we still 
>>> need the content in one spot)
>>> *The Plan*
>>> Migrate content from cyrusimap mediawiki, where appropriate. Update 
>>> as necessary.
>>> Absorb relevant content lurking on's wiki 
>>> (specifically the developer setup/install guide)
>>> Update 
>>> <> to just point people at 
>>> *Doc structure*
>>> So what should the new look like? Much as it 
>>> does now, just with more!
>>> Home
>>>  *
>>>        What is Cyrus
>>>  *
>>>        About the Cyrus Foundation (what, who, history, bylaws)
>>>  *
>>>        Latest news
>>>  *
>>>        Features (roadmap)
>>> Download
>>>  *
>>>        Beta, Stable, Old
>>>  *
>>>        Pointers to Docs/Install guides
>>> Documentation
>>>  *
>>>        Contributor (Set up your dev env, prerequisites, obtaining
>>>     source and libraries, building, verifying, gotchas, faq)
>>>  *
>>>        Administrator (installation, verification, customisation,
>>>     operation, faq, man pages)
>>> Support
>>>  *
>>>       Contact (irc, mailing list)
>>>  *
>>>       Bug reports
>>> And generally making it more pretty - cyrusimap has an icon and 
>>> colour scheme which presumably could be brought over to 
>>> which currently looks stylistically sparse.
>>> Nic (onlight) seems to have a good handle on bringing the man pages 
>>> up to date and ensuring they're current at, 
>>> which is great. (cyrus-docs/source/imap/admin/commands and in 
>>> cyrus-imap/man both contain man pages)
>>> *Questions*
>>> Is someone able to upgrade my privileges so I can commit changes to 
>>> the cyrus-docs tree? (/Jeroen?/)
>>> Does the new site need copyright content across it (a la cyrusimap 
>>> which refers to CMU). If so, what do we need? Currently it just says 
>>> copyright "The Cyrus Team".
>>> What's the process for pushing a new batch of docs onto 
>>> once they're written?
>>> What else am I missing?
>>> Cheers,
>>>     Nicoloa
>> -- 
>> Nic Bernsteinnic at  <mailto:nic at>
>> Onlight  <>
>> 219 N. Milwaukee St., Ste. 2A	          v. 414.272.4477
>> Milwaukee, Wisconsin  53202		  f. 414.290.0335

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

-------------- next part --------------
An HTML attachment was scrubbed...
-------------- 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