<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
On 06/25/2015 11:01 PM, Nicola Nye wrote:<br>
<blockquote
cite="mid:1435291275.3272716.308118625.3689C00E@webmail.messagingengine.com"
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>
Nicola,<br>
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.<br>
<br>
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:<br>
<blockquote>
<pre> 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)
</pre>
</blockquote>
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:<br>
<blockquote>
<pre> if text.startswith('.'):
</pre>
</blockquote>
So in order to get manpages to build <u>at all</u>, 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.<br>
<br>
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:<br>
<ul>
<li>python-docutils-0.11.3</li>
<li>python-sphinx-1.2.2<br>
</li>
</ul>
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.<br>
<br>
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 <u>we</u>
can build the manpages, we're golden (as they say).<br>
<br>
That's why I feel comfortable recommending that we ask that a newer
version of these tools be installed on harbormaster.<br>
<br>
Your thoughts?<br>
-nic
<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>