Documentation Unification and Awesomeification
Nic Bernstein
nic at onlight.com
Thu May 21 17:36:18 EDT 2015
Nicola,
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?
Cheers,
-nic
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.
> http://sphinx-doc.org/markup/misc.html#directive-only
> 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:
>> 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 Bernsteinnic at onlight.com <mailto:nic at onlight.com>
>> Onlight llc.www.onlight.com <http://www.onlight.com>
>> 219 N. Milwaukee St., Ste. 2A v. 414.272.4477
>> Milwaukee, Wisconsin 53202 f. 414.290.0335
--
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/20150521/055eb958/attachment-0001.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/20150521/055eb958/attachment-0001.vcf
More information about the Cyrus-devel
mailing list