From: Tomi Ollila <tomi.ollila@iki.fi>
To: David Bremner <david@tethera.net>, notmuch@notmuchmail.org
Subject: Re: [RFC Patch v3 2/3] doc: add target rst2man to build man pages
	using rst2man
In-Reply-To: <1393114575-8756-3-git-send-email-david@tethera.net>
References: <87fvo7btu8.fsf@qmul.ac.uk>
	<1393114575-8756-1-git-send-email-david@tethera.net>
	<1393114575-8756-3-git-send-email-david@tethera.net>
User-Agent: Notmuch/0.17+94~g1b90823 (http://notmuchmail.org) Emacs/24.3.1
	(x86_64-unknown-linux-gnu)
Date: Sun, 23 Feb 2014 19:42:21 +0200
Message-ID: <m24n3pu3nm.fsf@guru.guru-group.fi>
MIME-Version: 1.0
Content-Type: text/plain
Precedence: list

On Sun, Feb 23 2014, David Bremner <david@tethera.net> wrote:

> Many people have docutils installed, but not sphinx. Allow these
> people to build the man pages.

+1 from me to start having manuals in reStructuredText format and
then converting these to the target formats. Some comments on
the patch series below:

Building any docs using this is not yet activated ?

Anyway, I tried to build manual pages using 'make man' and got this:

  $ make man
  sphinx-build -b man -d doc/_build/doctrees -q -c doc doc doc/_build/man
  Making output directory...

  Sphinx error:
  Builder name man not registered

No fallback to use rst2man...


Comments regarding prerst2man.py inline below:

Tomi

> ---

// stuff deleted //

> diff --git a/doc/rst2man/prerst2man.py b/doc/rst2man/prerst2man.py
> new file mode 100644
> index 0000000..797dd20
> --- /dev/null
> +++ b/doc/rst2man/prerst2man.py
> @@ -0,0 +1,53 @@
> +from sys import argv
> +from datetime import date
> +import re
> +
> +sourcedir=argv[1]
> +outdir=argv[2]

Style! run pep8 prerst2html.py and fix the issues it prints
to the screen, like ' = ' above and remove trailing semicolon
below... (and also pep8(1) doc/conf.py.
 
> +
> +execfile(sourcedir+"/conf.py");
> +
> +
> +
> +
> +def header(file,startdocname, command, description, authors, section):
> +    file.write("""
> +{:s}
> +{:s}
> +{:s}
> +
> +:Date:   {:s}
> +:Version: {:s}
> +:Manual section: {:d}
> +:Manual group: {:s}

For python < 2.7 these needs to be {0:s}, {1:s}, {2:s}.. {5:d}...

> +
> +""".format(
> +'-' * len(description),
> +description,
> +'-' * len(description),
> +date.today().isoformat(),release,section,project))

Replace date.today.isoformat() with date determined from other
sources (NEWS file?)

> +
> +blankre = re.compile("^\s*$")
> +for page in man_pages:
> +    outfile = open(outdir+"/"+page[0]+'.rst','w')
> +    infile = open(sourcedir+"/"+page[0]+".rst",'r')

In addition to formatting above, use either ".rst" or '.rst'
(and perhaps other quotations in these 2 lines) for consistency.

> +
> +
> +    # this is a crude hack. We look for the first blank line, and
> +    # insert the rst2man header there.
> +    #
> +    # XXX consider really parsing input
> +
> +    count=0
> +    lines = infile.readlines()
> +    for line in lines:
> +        outfile.write(line);
> +        if (blankre.match(line)):
> +            break
> +        count = count + 1
> +
> +    del lines[0:count+1]

pep8 will in the lime above (as it is not lines[0:count + 1])
I might not have complained but... :D

> +
> +    header(outfile,*page)
> +
> +    outfile.write("".join(lines))
> -- 
> 1.8.5.3