Documentation Unification and Awesomeification

Nicola Nye nicolan at
Wed May 20 23:34:31 EDT 2015

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!



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.
>> 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
      [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
>    * 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
>    * These are not done:
>      * cyrus-master
>      * ipurge
>      * master
>      * mbexamine
>      * mbpath
>      * mbtool
>      * mkimap
>      * ptdump
>    * 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
>    * [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....) 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
>    * HTML output from these documents looks fine, by and large.
>    * 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
>    * 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* ...
>    * Man page output produced by Sphinx, however, does not follow
          this convention.
>    * 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.
    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,
>>  * 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 Bernstein nic at Onlight llc. 219 N.
Milwaukee St., Ste. 2A v. 414.272.4477 Milwaukee, Wisconsin 53202 f.

-------------- next part --------------
An HTML attachment was scrubbed...

More information about the Cyrus-devel mailing list