<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
Nicola,<br>
No rush. I put on my big-boy pants and got this sorted. In effect
I took every change between docutils v0.8.1 & v0.11.3, and
between sphinx v1.1.2 & v1.2.3 and incorporated them verbatim in
the bottom of our <a
href="https://git.cyrus.foundation/diffusion/D/browse/master/source/exts/sphinxlocal/writers/manpage.py">cyrus-docs/source/exts/sphinxlocal/writes/manpage.py</a>.<br>
<br>
This is a total, absolute and unrepentant hack, but it does work, it
builds on Wheezy, and even harbormaster is happy (see <a
href="https://git.cyrus.foundation/B2110">B2110</a>).
<a class="moz-txt-link-freetext" href="https://docs.cyrus.foundation/">https://docs.cyrus.foundation/</a> is now up to date and has all of your
changes as well as mine.<br>
<br>
I commented the start of the ugly hack quite clearly, so we can lop
it off if and when we ever do get modern versions of the toolset
installed.<br>
<br>
Cheers,<br>
-nic<br>
<br>
<div class="moz-cite-prefix">On 06/26/2015 04:40 PM, Nicola Nye
wrote:<br>
</div>
<blockquote
cite="mid:1435354815.3617542.308862793.7ACE8791@webmail.messagingengine.com"
type="cite">
<pre wrap="">Hi Nic,
Yes! Spot on. I remember looking into the Sphinx versions when I first
started and then promptly forgot about it.
I totally agree about your proposed versions. I'll chase down Jeroen who
I think has the keys to that box and see if we can't get it brought up
to date. Or at least out of the dark ages.
Cheers,
Nicola
On Sat, Jun 27, 2015, at 05:28 AM, Nic Bernstein wrote:
</pre>
<blockquote type="cite">
<pre wrap="">On 06/25/2015 11:01 PM, Nicola Nye wrote:
</pre>
<blockquote type="cite">
<pre wrap="">Hi Nic,
After some false starts using arc, I finally got a bunch of my changes
committed through onto the cyrus docs tree. And then I noticed the
website wasn't updating.
After some help from ellie, it turns out our doc build broke a while ago
and we hadn't noticed!
I think it has to do with the new man page builder you wrote.
Developer's lament: it works for me (and for you!) but for some reason
it looks like it's falling over on the server.
<a class="moz-txt-link-freetext" href="https://git.cyrus.foundation/harbormaster/build/964/">https://git.cyrus.foundation/harbormaster/build/964/</a>
School holidays are here for the next couple of weeks so I'm on reduced
hours but I'll be checking in to see if I can also work out what's going
on.
Cheers,
Nicola
</pre>
</blockquote>
<pre wrap="">Nicola,
Note sure what to do about this. I've spent the day bringing up a
Wheezy VM to play with this stuff, and made a version of
writer/manpage.py which works, but there's lots of other problems with
the old python-docutils which I could spend the next month trying to
work around.
Wheezy uses Sphinx v1.1.3 (2012-03-10) and docutils v0.8.1, which dates
from 2011-08-31. There's been a lot of changes since then, some of
which had to do with basic functionality. For example, in
docutils-0.8.1, in writer/manpage.py, is this definition:
def visit_Text(self, node):
text = node.astext()
text = text.replace('\\','\\e')
replace_pairs = [
(u'-', ur'\-'),
(u'\'', ur'\(aq'),
(u'´', ur'\''),
(u'`', ur'\(ga'),
]
for (in_char, out_markup) in replace_pairs:
text = text.replace(in_char, out_markup)
# unicode
text = self.deunicode(text)
if self._in_literal:
# prevent interpretation of "." at line start
if text[0] == '.':
# << BUG
text = '\\&' + text
text = text.replace('\n.', '\n\\&.')
self.body.append(text)
The line "if text[0] == '.':" is a flat out bug, since if 'text' is ever
empty, it fails. This bug was fixed in release 0.11 (2013-07-22), with
this line:
if text.startswith('.'):
So in order to get manpages to build _at all_, I need to redefine
visit_Text in our custom writer/manpage.py. I've done so, but that's
just the start of the problems.
I would like to propose that we get a newer version of python-docutils
and python-sphinx installed on harbormaster and declare that certain
minimum versions of both packages are required to build documentation
from source. For the record, I further propose that these be:
* python-docutils-0.11.3
* python-sphinx-1.2.2
By the way, those are the versions which are supported by Ubuntu Trusty
(14.04.2) and Utopic (14.10); Debian Jessie and Sid; Fedora 20 & 21;
etc. This is not bleeding edge stuff, but at least it doesn't suffer
from long-ago fixed bugs.
Building Cyrus documentation from source is a different proposition from
building the server from source. It's my understanding that the
manpages, in particular, are to be built and included, pre-built, in the
cyrus-imapd distribution package. So as long as _we_ can build the
manpages, we're golden (as they say).
That's why I feel comfortable recommending that we ask that a newer
version of these tools be installed on harbormaster.
Your thoughts?
-nic
--
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
Email had 1 attachment:
+ nic.vcf
1k (text/x-vcard)
</pre>
</blockquote>
</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>