<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
Nicola, et alia.,<br>
Firstly, I apologize that I haven't made a hang-out in ages -- for
reasons too long, boring and personal to get into -- but I'll stick
my head above the ramparts long enough to cause some trouble...<br>
<br>
On 09/16/2015 08:50 PM, Nicola Nye wrote:<br>
<blockquote
cite="mid:1442454640.448210.385858161.52671089@webmail.messagingengine.com"
type="cite">
<title></title>
<div><snip><br>
</div>
<div> </div>
Equally, there are some documentation issues that are affected by
our current straddling of two worlds. Read on for a discussion of
the issues and down to the options and recommendation.<br>
<div> </div>
<div>I'd love to have your input (particularly Nic Bernstein on
the docs angle!) if you agree or disagree so we can make for a
more unified Cyrus presence.<br>
</div>
<div> </div>
<div><span class="size" style="font-size:16px"><b>Issues</b></span><br>
</div>
<div> </div>
<div>1) Branding<br>
</div>
<div> <snip></div>
<div> </div>
<div>2) Docs logistics<br>
</div>
<div> </div>
<div>The docs repo is separate to source which is causing friction
keeping man pages updated. <br>
</div>
</blockquote>
<br>
Yes! We need to get cyrus-docs into cyrus-imapd, and eliminate the
problems caused by the split repos. Bron and I discussed this some
time back, when I had tackled config2rst, and needed to find a
target home for the resultant doc/rst/imapd.conf.rst<br>
<br>
<blockquote
cite="mid:1442454640.448210.385858161.52671089@webmail.messagingengine.com"
type="cite">
<div>We want man pages in two formats: *nix for actual man pages
to ship and install with cyrus, and html for web presentation.<br>
</div>
<div> </div>
<div>Nice to have: ship a snapshot of all current docs (not just
man pages) along with source distribution.<br>
</div>
<div> </div>
<div>3) Sphinx vs wiki<br>
</div>
<div> </div>
<div>We have been working towards making the content on
cyrus.foundation to be the most up to date. This is using
Sphinx, which allows us to generate, from the same source, man
pages as well as web pages. (And even pdf or single page html).
So we get nicer output format options. Clearer history in the
git log than you get from wiki.<br>
</div>
<div> </div>
<div>Cyrusimap docs are held in mediawiki. Not so great for man
pages. But it's much easier for third party contributor to pitch
in and help out: they don't need to learn rst, they don't need a
phabricator account, they don't need to navigate git.<br>
</div>
</blockquote>
<br>
I like the git/sphinx combo for the audit trail it provides (blame)
and the easy ability to back out errant changes. I am not a
MediaWiki expert, barely a novice, so if it offers the same
capabilities...<br>
<br>
But perhaps more importantly, the existing docs on cyrus.foundation
make use of the nifty macros and such in Sphinx, in order that they
can include references to, or portions of, man pages. The
aforementioned config2rst, for example, was purposefully written
such that it adds useful delimiters into the resultant
imapd.config.rst to facilitate this, thus eliminating duplication of
information.<br>
<br>
For an example of this, check out the page on automatic creation of
mailboxes, which makes heavy use of this to present the actual
imapd.conf settings to the user, in context:<br>
<a class="moz-txt-link-freetext" href="https://docs.cyrus.foundation/imap/features/automatic-creation-of-mailboxes.html">https://docs.cyrus.foundation/imap/features/automatic-creation-of-mailboxes.html</a><br>
<br>
Which is produced by the simple code here:<br>
<a class="moz-txt-link-freetext" href="https://docs.cyrus.foundation/_sources/imap/features/automatic-creation-of-mailboxes.txt">https://docs.cyrus.foundation/_sources/imap/features/automatic-creation-of-mailboxes.txt</a><br>
<br>
This ensures that the docs for the website (or package inclusion,
why not?) will always accurately reflect the actual settings in
lib/imapoptions, tracking changes as they're made.<br>
<br>
Is there any parallel in MediaWiki?<br>
<br>
For all of these reasons, I vote for solution 1, below.<br>
<br>
Cheers,<br>
-nic (ducking back below the wall...)<br>
<br>
<blockquote
cite="mid:1442454640.448210.385858161.52671089@webmail.messagingengine.com"
type="cite">
<div> </div>
<div> </div>
<div><b><span class="size" style="font-size:16px">Possible
solutions</span></b><br>
</div>
<snip>
<div>Option 1: Single domain, unify git repos, use sphinx
everywhere<br>
</div>
<div>--------------------------------------------------------------------------------<br>
</div>
<div> </div>
<div>Moving the git repo to cyrusimap (or anywhere) isn't hard. (a
job for Bron)<br>
</div>
<div> </div>
<div>Get rid of separate cyrus-docs repo. Put cyrus-docs stuff
back inside cyrus-imapd/docs for easier man page generation and
tagging of docs versions with source, and shipping of current
docs with source.<br>
</div>
<div> </div>
<div>Put sphinx on cyrusimap to replace the wiki. This requires
either:<br>
</div>
<ol>
<li>
<div>working out how to set up the existing generated docs for
use with sphinx, <br>
</div>
</li>
<li>
<div>or make all the stuff in cyrus-imapd/doc into rst so it
works with sphinx. We can still ship the built html.<br>
</div>
</li>
</ol>
</blockquote>
<blockquote
cite="mid:1442454640.448210.385858161.52671089@webmail.messagingengine.com"
type="cite">
<div>Option 2: Single domain, unify git repos, use wiki for docs<br>
</div>
<div>-----------------------------------------------------------------------------<br>
</div>
<div> </div>
<div>Put sphinx on cyrusimap.org just for generating man page
html. Leave the existing wiki where it is for documentation.
(Requires porting the page updates I made from cyrus.foundation
onto the wiki). <br>
</div>
<div> </div>
<div>This means the only thing left in the cyrus-docs git repo
would be the man pages, at which point it makes more sense to
put them back into the cyrus-source repo.<br>
</div>
<div> </div>
<div>We can still ship docs with the release if we tie in a wiki
export into the release-building process. (A job for Ellie and
I)</div>
</blockquote>
<blockquote
cite="mid:1442454640.448210.385858161.52671089@webmail.messagingengine.com"
type="cite">
<div>Option 3: Single domain, separate git repos, use sphinx for
docs<br>
</div>
<div>----------------------------------------------------------------------------------<br>
</div>
<div> </div>
<div>Move all services to cyrusimap.org, but still leaves us with
all the docs logistics and sphinx and wiki chafe points. Not
recommended.<br>
</div>
<div> </div>
<div><b><span class="size" style="font-size:16px">Recommendation</span></b><br>
</div>
<div> </div>
<div>I am leaning towards suggesting option 2. Anything that makes
documentation support easier is a good! But we'd still like to
retain the usefulness of sphinx for generating two output
formats from single source man pages.<br>
</div>
<div> </div>
<div><b><span class="size" style="font-size: 16px">What Now?</span><span
class="size" style="font-size: 16px"><br>
</span></b></div>
<div> </div>
<div>Discuss! I imagine those folks who come to the Hangout in the
next few meetings will kick it around and we'll come to a
decision next week.<br>
</div>
<div> </div>
<div> Nicola<br>
</div>
<div> </div>
<div> </div>
<div> </div>
<div> </div>
<div> </div>
<div> </div>
<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>
6525 W Bluemound Rd., Ste 24 v. 414.272.4477
Milwaukee, Wisconsin 53213-4073 f. 414.290.0335
</pre>
</body>
</html>