a9/47d810901e573343ef7cc3895331ef9e6a542b

   1 Return-Path: <tomi.ollila@iki.fi>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id A023A431FD6\r
   6         for <notmuch@notmuchmail.org>; Sun, 23 Feb 2014 09:42:35 -0800 (PST)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: 0\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]\r
  12         autolearn=disabled\r
  13 Received: from olra.theworths.org ([127.0.0.1])\r
  14         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  15         with ESMTP id gGLd9q-yLrb6 for <notmuch@notmuchmail.org>;\r
  16         Sun, 23 Feb 2014 09:42:28 -0800 (PST)\r
  17 Received: from guru.guru-group.fi (guru.guru-group.fi [46.183.73.34])\r
  18         by olra.theworths.org (Postfix) with ESMTP id 11EC0431FCF\r
  19         for <notmuch@notmuchmail.org>; Sun, 23 Feb 2014 09:42:28 -0800 (PST)\r
  20 Received: from guru.guru-group.fi (localhost [IPv6:::1])\r
  21         by guru.guru-group.fi (Postfix) with ESMTP id 04119100064;\r
  22         Sun, 23 Feb 2014 19:42:21 +0200 (EET)\r
  23 From: Tomi Ollila <tomi.ollila@iki.fi>\r
  24 To: David Bremner <david@tethera.net>, notmuch@notmuchmail.org\r
  25 Subject: Re: [RFC Patch v3 2/3] doc: add target rst2man to build man pages\r
  26         using rst2man\r
  27 In-Reply-To: <1393114575-8756-3-git-send-email-david@tethera.net>\r
  28 References: <87fvo7btu8.fsf@qmul.ac.uk>\r
  29         <1393114575-8756-1-git-send-email-david@tethera.net>\r
  30         <1393114575-8756-3-git-send-email-david@tethera.net>\r
  31 User-Agent: Notmuch/0.17+94~g1b90823 (http://notmuchmail.org) Emacs/24.3.1\r
  32         (x86_64-unknown-linux-gnu)\r
  33 X-Face: HhBM'cA~<r"^Xv\KRN0P{vn'Y"Kd;zg_y3S[4)KSN~s?O\"QPoL\r
  34         $[Xv_BD:i/F$WiEWax}R(MPS`^UaptOGD`*/=@\1lKoVa9tnrg0TW?"r7aRtgk[F\r
  35         !)g;OY^,BjTbr)Np:%c_o'jj,Z\r
  36 Date: Sun, 23 Feb 2014 19:42:21 +0200\r
  37 Message-ID: <m24n3pu3nm.fsf@guru.guru-group.fi>\r
  38 MIME-Version: 1.0\r
  39 Content-Type: text/plain\r
  40 X-BeenThere: notmuch@notmuchmail.org\r
  41 X-Mailman-Version: 2.1.13\r
  42 Precedence: list\r
  43 List-Id: "Use and development of the notmuch mail system."\r
  44         <notmuch.notmuchmail.org>\r
  45 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  46         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  47 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  48 List-Post: <mailto:notmuch@notmuchmail.org>\r
  49 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  50 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  51         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  52 X-List-Received-Date: Sun, 23 Feb 2014 17:42:35 -0000\r
  53 \r
  54 On Sun, Feb 23 2014, David Bremner <david@tethera.net> wrote:\r
  55 \r
  56 > Many people have docutils installed, but not sphinx. Allow these\r
  57 > people to build the man pages.\r
  58 \r
  59 +1 from me to start having manuals in reStructuredText format and\r
  60 then converting these to the target formats. Some comments on\r
  61 the patch series below:\r
  62 \r
  63 Building any docs using this is not yet activated ?\r
  64 \r
  65 Anyway, I tried to build manual pages using 'make man' and got this:\r
  66 \r
  67   $ make man\r
  68   sphinx-build -b man -d doc/_build/doctrees -q -c doc doc doc/_build/man\r
  69   Making output directory...\r
  70 \r
  71   Sphinx error:\r
  72   Builder name man not registered\r
  73 \r
  74 No fallback to use rst2man...\r
  75 \r
  76 \r
  77 Comments regarding prerst2man.py inline below:\r
  78 \r
  79 Tomi\r
  80 \r
  81 > ---\r
  82 \r
  83 // stuff deleted //\r
  84 \r
  85 > diff --git a/doc/rst2man/prerst2man.py b/doc/rst2man/prerst2man.py\r
  86 > new file mode 100644\r
  87 > index 0000000..797dd20\r
  88 > --- /dev/null\r
  89 > +++ b/doc/rst2man/prerst2man.py\r
  90 > @@ -0,0 +1,53 @@\r
  91 > +from sys import argv\r
  92 > +from datetime import date\r
  93 > +import re\r
  94 > +\r
  95 > +sourcedir=argv[1]\r
  96 > +outdir=argv[2]\r
  97 \r
  98 Style! run pep8 prerst2html.py and fix the issues it prints\r
  99 to the screen, like ' = ' above and remove trailing semicolon\r
 100 below... (and also pep8(1) doc/conf.py.\r
 101  \r
 102 > +\r
 103 > +execfile(sourcedir+"/conf.py");\r
 104 > +\r
 105 > +\r
 106 > +\r
 107 > +\r
 108 > +def header(file,startdocname, command, description, authors, section):\r
 109 > +    file.write("""\r
 110 > +{:s}\r
 111 > +{:s}\r
 112 > +{:s}\r
 113 > +\r
 114 > +:Date:   {:s}\r
 115 > +:Version: {:s}\r
 116 > +:Manual section: {:d}\r
 117 > +:Manual group: {:s}\r
 118 \r
 119 For python < 2.7 these needs to be {0:s}, {1:s}, {2:s}.. {5:d}...\r
 120 \r
 121 > +\r
 122 > +""".format(\r
 123 > +'-' * len(description),\r
 124 > +description,\r
 125 > +'-' * len(description),\r
 126 > +date.today().isoformat(),release,section,project))\r
 127 \r
 128 Replace date.today.isoformat() with date determined from other\r
 129 sources (NEWS file?)\r
 130 \r
 131 > +\r
 132 > +blankre = re.compile("^\s*$")\r
 133 > +for page in man_pages:\r
 134 > +    outfile = open(outdir+"/"+page[0]+'.rst','w')\r
 135 > +    infile = open(sourcedir+"/"+page[0]+".rst",'r')\r
 136 \r
 137 In addition to formatting above, use either ".rst" or '.rst'\r
 138 (and perhaps other quotations in these 2 lines) for consistency.\r
 139 \r
 140 > +\r
 141 > +\r
 142 > +    # this is a crude hack. We look for the first blank line, and\r
 143 > +    # insert the rst2man header there.\r
 144 > +    #\r
 145 > +    # XXX consider really parsing input\r
 146 > +\r
 147 > +    count=0\r
 148 > +    lines = infile.readlines()\r
 149 > +    for line in lines:\r
 150 > +        outfile.write(line);\r
 151 > +        if (blankre.match(line)):\r
 152 > +            break\r
 153 > +        count = count + 1\r
 154 > +\r
 155 > +    del lines[0:count+1]\r
 156 \r
 157 pep8 will in the lime above (as it is not lines[0:count + 1])\r
 158 I might not have complained but... :D\r
 159 \r
 160 > +\r
 161 > +    header(outfile,*page)\r
 162 > +\r
 163 > +    outfile.write("".join(lines))\r
 164 > -- \r
 165 > 1.8.5.3\r