Documentation Unification and Awesomeification

Nic Bernstein nic at onlight.com
Tue May 19 08:22:30 EDT 2015


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:
    https://docs.cyrus.foundation/imap/admin/commands/chk_cyrus.html*
    [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
        https://docs.cyrus.foundation/imap/admin/commands.html#work-in-progress
        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 docs.cyrus.foundation 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 git.cyrus.foundation's wiki 
> (specifically the developer setup/install guide)
> Update cyrusimap.org/cyrussasl.org 
> <http://cyrusimap.org/cyrussasl.org> to just point people at 
> docs.cyrus.foundation
> *Doc structure*
> So what should the new docs.cyrus.foundation 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 docs.cyrus.foundation 
> 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 docs.cyrus.foundation, 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 
> docs.cyrus.foundation once they're written?
> What else am I missing?
> Cheers,
>     Nicoloa

-- 
Nic Bernstein                             nic at onlight.com
Onlight llc.                              www.onlight.com
219 N. Milwaukee St., Ste. 2A	          v. 414.272.4477
Milwaukee, Wisconsin  53202		  f. 414.290.0335

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.andrew.cmu.edu/pipermail/cyrus-devel/attachments/20150519/39d2429a/attachment-0001.html 


More information about the Cyrus-devel mailing list