<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
Nicola,<br>
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.<br>
<br>
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.<br>
<br>
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?<br>
<br>
Cheers,<br>
-nic<br>
<br>
<div class="moz-cite-prefix">On 05/20/2015 10:34 PM, Nicola Nye
wrote:<br>
</div>
<blockquote
cite="mid:1432179271.3688345.274400681.4C63EC35@webmail.messagingengine.com"
type="cite">
<title></title>
<div>Hi Nic,<br>
</div>
<div> </div>
<div>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.<br>
</div>
<div> </div>
<div>Bron added you as a committer to the cyrus-docs repo, so
you're free to update in there.<br>
</div>
<div> </div>
<div>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.<br>
</div>
<div> </div>
<div>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.<br>
</div>
<div> </div>
<div>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. <a
moz-do-not-send="true"
href="http://sphinx-doc.org/markup/misc.html#directive-only">http://sphinx-doc.org/markup/misc.html#directive-only</a><br>
</div>
<div> </div>
<div>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!<br>
</div>
<div> </div>
<div>Cheers,<br>
</div>
<div> </div>
<div> Nicola<br>
</div>
<div> </div>
<div>On Tue, May 19, 2015, at 10:22 PM, Nic Bernstein wrote:<br>
</div>
<blockquote type="cite">
<div>Nicola, et alia,<br>
</div>
<div> [Apologies for top-posting, but it seemed appropriate
here]<br>
</div>
<div> </div>
<div> Glad to see you jumping on board, and welcome!<br>
</div>
<div> </div>
<div> 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.<br>
</div>
<div> </div>
<div> Since there <i>is</i> 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.<br>
</div>
<div> </div>
<div> <whinge><br>
</div>
<blockquote>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.<br>
<br>
Similarly, I've more recently submitted D43, D44 & D45,
which still await review, etc.</blockquote>
<div></whinge><br>
</div>
<div> </div>
<div> 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:<br>
</div>
<blockquote>[2015-05-06 15:37:44] <kanarip_> <b>fwiw, i
also plan to generate very much larger man-pages by using
the rst</b><br>
[2015-05-06 15:42:36] <kanarip_> <b>so, this for
example: <a moz-do-not-send="true"
href="https://docs.cyrus.foundation/imap/admin/commands/chk_cyrus.html">https://docs.cyrus.foundation/imap/admin/commands/chk_cyrus.html</a></b><br>
[2015-05-06 15:42:44] <kanarip_> <b>can also become
chk_cyrus.8</b><br>
[2015-05-06 15:43:04] <kanarip_> <b>but there's just
much more real-estate in the web page than there is in the
man page, right?</b><br>
[2015-05-06 15:43:14] <kanarip_> <b>and much more
markup to be used and abused</b><br>
[2015-05-06 15:43:43] <kanarip_> <b>so i would prefer
that when we aim to make the documentation more complete if
you will</b><br>
[2015-05-06 15:44:26] <kanarip_> <b>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</b><br>
[2015-05-06 15:44:34] <onlight> <i>Ok, but how shall we
harmonize the two different versions? Shall we deprecate
the old-style stuff in cyrus-imap/man in preference</i><br>
[2015-05-06 15:45:17] <onlight> <i>for the newer
RST-based stuff?...</i><br>
[2015-05-06 15:45:43] <kanarip_><b> 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</b><br>
[2015-05-06 15:45:56] <kanarip_> <b>with the exception
of man/imapd.conf.5 of course</b></blockquote>
<div>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.<br>
</div>
<div> </div>
<div> [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?]<br>
</div>
<div> </div>
<div> That said, there are problems with the reStructured Text
man pages:<br>
</div>
<ul>
<li>They are incomplete<br>
</li>
<ul>
<li>The initial list in <a moz-do-not-send="true"
href="https://docs.cyrus.foundation/imap/admin/commands.html#work-in-progress">https://docs.cyrus.foundation/imap/admin/commands.html#work-in-progress</a>
is about halfway complete. These are done:<br>
</li>
<ul>
<li>chk_cyrus<br>
</li>
<li>ctl_cyrusdb<br>
</li>
<li>cyradm<br>
</li>
<li>unexpunge<br>
</li>
<li>ctl_deliver<br>
</li>
<li>ctl_mboxlist<br>
</li>
<li>cvt_cyrusdb<br>
</li>
<li>cyr_dbtool<br>
</li>
<li>cyr_df<br>
</li>
<li>cyr_expire<br>
</li>
<li>cyr_info<br>
</li>
<li>squatter<br>
</li>
<li>ctl_conversationsdb<br>
</li>
<li>sync_client<br>
</li>
</ul>
<li>These are not done:<br>
</li>
<ul>
<li>cyrus-master<br>
</li>
<li>ipurge<br>
</li>
<li>master<br>
</li>
<li>mbexamine<br>
</li>
<li>mbpath<br>
</li>
<li>mbtool<br>
</li>
<li>mkimap<br>
</li>
<li>ptdump<br>
</li>
</ul>
<li>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:<br>
</li>
<ul>
<li>nntpd<br>
</li>
<li>notifyd<br>
</li>
<li>pop3d<br>
</li>
<li>proxyd<br>
</li>
<li>rehash<br>
</li>
<li>sievec<br>
</li>
<li>sieved<br>
</li>
<li>smmapd<br>
</li>
<li>sync_reset<br>
</li>
<li>sync_server<br>
</li>
<li>timsieved<br>
</li>
<li>translatesieve<br>
</li>
<li>undohash<br>
</li>
<li>upgradesieve<br>
</li>
</ul>
<li>[More] Examples are needed for many commands<br>
</li>
</ul>
<li>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 "<span>This
{feature|command} was introduced in version 3.0."</span><br>
</li>
<li>The Sphinx man page output can be unpredictable<br>
</li>
<ul>
<li>HTML output from these documents looks fine, by and
large.<br>
</li>
<li>Man output can sometimes shift to <b>bold</b> and never
come back to normal.<br>
</li>
<ul>
<li>See
cyrus-docs/source/imap/admin/commands/unexpunge.rst for
an example<br>
</li>
</ul>
</ul>
<li>There are stylistic differences which should/must get
sorted<br>
</li>
<ul>
<li>Traditional man pages, such as those in cyrus-imapd/man,
alternate <b>bold</b> and <i>italic</i> like so:<br>
</li>
<ul>
<li># <b>command --option</b> <i><value></i> <b>-D
-b -C</b> <i>/etc/imapd-new.conf</i> <b>-X</b> ...<br>
</li>
</ul>
<li>Man page output produced by Sphinx, however, does not
follow this convention.<br>
</li>
<li>In the existing collection of reStructured Text files,
there is a mix of ``literal`` and **bold** for the same
thing, such as command name. <br>
</li>
<ul>
<li>The convention is **bold**, but whatever is used, we
should unify this<br>
</li>
<li>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).<br>
</li>
</ul>
</ul>
</ul>
<div>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.<br>
</div>
<div> </div>
<div> Cheers,<br>
</div>
<div> -nic<br>
</div>
<div> </div>
<div> On 05/18/2015 10:57 PM, Nicola Nye wrote:<br>
</div>
<blockquote type="cite"
cite="mid:1432007833.2128563.272291401.2589AE90@webmail.messagingengine.com">
<div>Hi folks,<br>
</div>
<div> </div>
<div>I'm a tech writer with FastMail and I'm here to help.<br>
</div>
<div> </div>
<div>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!<br>
</div>
<div> </div>
<div><b>The Goal</b><br>
</div>
<div>Make the content on docs.cyrus.foundation the
authoritative source for all things Cyrus Imap/Sasl.<br>
</div>
<div>(The server/websitename will be changing at some point,
but we still need the content in one spot)<br>
</div>
<div> </div>
<div><b>The Plan</b><br>
</div>
<div>Migrate content from cyrusimap mediawiki, where
appropriate. Update as necessary.<br>
</div>
<div>Absorb relevant content lurking on git.cyrus.foundation's
wiki (specifically the developer setup/install guide)<br>
</div>
<div>Update <a moz-do-not-send="true"
href="http://cyrusimap.org/cyrussasl.org">cyrusimap.org/cyrussasl.org</a> to
just point people at docs.cyrus.foundation<br>
</div>
<div> </div>
<div><b>Doc structure</b><br>
</div>
<div>So what should the new docs.cyrus.foundation look like?
Much as it does now, just with more!<br>
</div>
<div> </div>
<div>Home<br>
</div>
<ul>
<li>
<div> What is Cyrus <br>
</div>
</li>
<li>
<div> About the Cyrus Foundation (what, who, history,
bylaws)<br>
</div>
</li>
<li>
<div> Latest news<br>
</div>
</li>
<li>
<div> Features (roadmap)<br>
</div>
</li>
</ul>
<div>Download<br>
</div>
<ul>
<li>
<div> Beta, Stable, Old<br>
</div>
</li>
<li>
<div> Pointers to Docs/Install guides<br>
</div>
</li>
</ul>
<div>Documentation<br>
</div>
<ul>
<li>
<div> Contributor (Set up your dev env, prerequisites,
obtaining source and libraries, building, verifying,
gotchas, faq)<br>
</div>
</li>
<li>
<div> Administrator (installation, verification,
customisation, operation, faq, man pages)<br>
</div>
</li>
</ul>
<div>Support<br>
</div>
<ul>
<li>
<div> Contact (irc, mailing list)<br>
</div>
</li>
<li>
<div> Bug reports<br>
</div>
</li>
</ul>
<div> </div>
<div>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.<br>
</div>
<div> </div>
<div>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. (<span
class="highlight" style="background-color: rgb(255, 255,
255)"><span class="colour" style="color:rgb(31, 31, 31)">cyrus-docs/source/imap/admin/commands
and in cyrus-imap/man both contain man pages)</span></span><br>
</div>
<div> </div>
<div><b>Questions</b><br>
</div>
<div>Is someone able to upgrade my privileges so I can commit
changes to the cyrus-docs tree? (<i>Jeroen?</i>)<br>
</div>
<div> </div>
<div>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". <br>
</div>
<div> </div>
<div>What's the process for pushing a new batch of docs onto
docs.cyrus.foundation once they're written?<br>
</div>
<div> </div>
<div>What else am I missing?<br>
</div>
<div> </div>
<div>Cheers,<br>
</div>
<div> </div>
<div> Nicoloa<br>
</div>
<div> </div>
</blockquote>
<div> </div>
<pre>--
Nic Bernstein <a moz-do-not-send="true" href="mailto:nic@onlight.com">nic@onlight.com</a>
Onlight llc. <a moz-do-not-send="true" href="http://www.onlight.com">www.onlight.com</a>
219 N. Milwaukee St., Ste. 2A v. 414.272.4477
Milwaukee, Wisconsin 53202 f. 414.290.0335
</pre>
</blockquote>
<div> </div>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Nic Bernstein <a class="moz-txt-link-abbreviated" href="mailto:nic@onlight.com">nic@onlight.com</a>
Onlight, Inc. <a class="moz-txt-link-abbreviated" href="http://www.onlight.com">www.onlight.com</a>
1442 N Farwell Ave., Suite 600 v. 414.272.4477
Milwaukee, Wisconsin 53202
</pre>
</body>
</html>