<html>
  <head>
    <meta content="text/html; charset=ISO-8859-1"
      http-equiv="Content-Type">
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    Nicola,<br>
    No rush.&nbsp; I put on my big-boy pants and got this sorted.&nbsp; In effect
    I took every change between docutils v0.8.1 &amp; v0.11.3, and
    between sphinx v1.1.2 &amp; 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>).&nbsp;
    <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>
    &nbsp;&nbsp;&nbsp; -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'&acute;', 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] == '.':                                      
                        # &lt;&lt; BUG
                     text = '\\&amp;' + text
                 text = text.replace('\n.', '\n\\&amp;.')
             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 &amp; 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>