[PATCH 0/7] doc: Python 3 compat, rst2man.py support, etc.

[PATCH 0/7] doc: Python 3 compat, rst2man.py support, etc.

[W. Trevor King]

I just bumped into this today while testing v2 of my
content-description series:

  $ ./configure
  …
  $ make
  …
  python ./doc/mkdocdeps.py ./doc doc/_build doc/docdeps.mk
  Traceback (most recent call last):
    File "./doc/mkdocdeps.py", line 6, in <module>
      execfile(srcdir + '/conf.py')
  NameError: name 'execfile' is not defined
  …

The first patch in this series fixes that issue, and the rest of the
series fixes some other issues I bumped into while working on that.
Sorry I missed these in the initial series.

Note that while mkdocdeps.py and prerst2man.py are now Python 3
compatible (with this series), the build will fail for Python's 3.0
through 3.2 because of the explicit unicode literals in conf.py [1].
It's likely that conf.py could use [2]

  from __future__ import unicode_literals

drop the u'' prefixes, and be compatible with all Python's ≥2.6
(including all 3s).  I haven't checked the logic though, and I'm not
running 3.2 locally anymore, so it's not a big priority for me.

Cheers,
Trevor

[1]: https://docs.python.org/3/whatsnew/3.3.html#pep-414-explicit-unicode-literals
[2]: from __future__ import unicode_literals

W. Trevor King (7):
  doc/mkdocdeps.py: Convert execfile to import
  doc/mkdocdeps.py: Use "with" statement for the output file
  doc/prerst2man.py: Use Python-3-compatible octal notation
  doc/prerst2man.py: Fix 'os.system' -> 'system' typo
  doc: Allow rst2man.py as an alternative to rst2man
  doc/prerst2man.py: Convert execfile to import
  doc/INSTALL: Remove rst2man reference and other updates

 configure          | 12 +++++++-----
 doc/INSTALL        | 34 ++++++++++++++++++++--------------
 doc/Makefile.local |  6 +++---
 doc/mkdocdeps.py   | 19 ++++++++++---------
 doc/prerst2man.py  | 25 ++++++++++++++-----------
 5 files changed, 54 insertions(+), 42 deletions(-)

-- 
1.9.1.353.gc66d89d

[PATCH 1/7] doc/mkdocdeps.py: Convert execfile to import

[W. Trevor King]

excefile is gone in Python 3 [1].  Instead of exec-ing the
configuration, it's easier to insert the source directory in Python's
path [2], and just import the configuration.  With this change,
mkdocdeps.py is compatible with both Python 2 and 3.

[1]: https://docs.python.org/3.0/whatsnew/3.0.html#builtins
[2]: https://docs.python.org/3/library/sys.html#sys.path
---
 doc/mkdocdeps.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/doc/mkdocdeps.py b/doc/mkdocdeps.py
index 71bd135..de1cbb8 100644
--- a/doc/mkdocdeps.py
+++ b/doc/mkdocdeps.py
@@ -1,15 +1,16 @@
-from sys import argv
-srcdir = argv[1]
-builddir = argv[2]
-outfile = argv[3]
+import sys
 
-execfile(srcdir + '/conf.py')
+srcdir = sys.argv[1]
+builddir = sys.argv[2]
+outfile = sys.argv[3]
 
+sys.path.insert(0, srcdir)
+import conf
 
 roff_files = []
 rst_files = []
 out=open(outfile,'w')
-for page in man_pages:
+for page in conf.man_pages:
     rst_files = rst_files + ["{0:s}/{1:s}.rst".format(srcdir,page[0])]
     roff_files = roff_files + ["{0:s}/man/{1:s}.{2:d}".format(builddir,page[0],page[4])]
 
-- 
1.9.1.353.gc66d89d

[PATCH 2/7] doc/mkdocdeps.py: Use "with" statement for the output file

[W. Trevor King]

Before this patch, the open was unnecessarily early and relied on the
process cleanup to close.  Neither one of these was a real problem,
but PEP 343's context managers (which landed in Python 2.5) make
proper cleanup very easy.

[1]: http://legacy.python.org/dev/peps/pep-0343/
---
 doc/mkdocdeps.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/mkdocdeps.py b/doc/mkdocdeps.py
index de1cbb8..b87fe3e 100644
--- a/doc/mkdocdeps.py
+++ b/doc/mkdocdeps.py
@@ -9,10 +9,10 @@ import conf
 
 roff_files = []
 rst_files = []
-out=open(outfile,'w')
 for page in conf.man_pages:
     rst_files = rst_files + ["{0:s}/{1:s}.rst".format(srcdir,page[0])]
     roff_files = roff_files + ["{0:s}/man/{1:s}.{2:d}".format(builddir,page[0],page[4])]
 
-out.write ('MAN_ROFF_FILES := ' + ' \\\n\t'.join(roff_files)+'\n')
-out.write ('MAN_RST_FILES := ' + ' \\\n\t'.join(rst_files)+'\n')
+with open(outfile, 'w') as out:
+    out.write('MAN_ROFF_FILES := ' + ' \\\n\t'.join(roff_files) + '\n')
+    out.write('MAN_RST_FILES := ' + ' \\\n\t'.join(rst_files) + '\n')
-- 
1.9.1.353.gc66d89d

[PATCH 3/7] doc/prerst2man.py: Use Python-3-compatible octal notation

[W. Trevor King]

Python 3 only supports the 0oXXX notation for octal literals [1,2],
which have also been supported in 2.x since 2.6 [2].

[1]: https://docs.python.org/3.0/whatsnew/3.0.html#integers
[2]: http://legacy.python.org/dev/peps/pep-3127/
---
 doc/prerst2man.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 4591264..108f4a3 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -8,7 +8,7 @@ sourcedir = argv[1]
 outdir = argv[2]
 
 if not isdir(outdir):
-    makedirs(outdir, 0755)
+    makedirs(outdir, 0o755)
 
 execfile(sourcedir + "/conf.py")
 
@@ -34,7 +34,7 @@ blankre = re.compile("^\s*$")
 for page in man_pages:
     outdirname = outdir + '/' + dirname(page[0])
     if not isdir(outdirname):
-        makedirs(outdirname, 0755)
+        makedirs(outdirname, 0o755)
     filename = outdir + '/' + page[0] + '.rst'
     outfile = open(filename, 'w')
     infile = open(sourcedir + '/' + page[0] + '.rst', 'r')
-- 
1.9.1.353.gc66d89d

[PATCH 4/7] doc/prerst2man.py: Fix 'os.system' -> 'system' typo

[W. Trevor King]

Avoid:

  $ make HAVE_SPHINX=0 HAVE_RST2MAN=1 build-man
  python ./doc/prerst2man.py ./doc doc/_build/man
  Traceback (most recent call last):
    File "./doc/prerst2man.py", line 65, in <module>
      os.system('set -x; rst2man {0} {1}/{2}.{3}'
  NameError: name 'os' is not defined
  make: *** [doc/_build/man/man1/notmuch.1] Error 1

by using system directly.  We don't need the 'os.' namespacing,
because the function was imported with:

  from os import makedirs, system
---
 doc/prerst2man.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 108f4a3..437dea9 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -59,5 +59,5 @@ for page in man_pages:
     outfile.write("".join(lines))
     outfile.close()
 
-    os.system('set -x; rst2man {0} {1}/{2}.{3}'
-              .format(filename, outdir, page[0],page[4]))
+    system('set -x; rst2man {0} {1}/{2}.{3}'
+           .format(filename, outdir, page[0], page[4]))
-- 
1.9.1.353.gc66d89d

[PATCH 5/7] doc: Allow rst2man.py as an alternative to rst2man

[W. Trevor King]

Gentoo's dev-python/docutils-0.10 installs Docutils scripts with a
*.py extension, so I have /usr/bin/rst2man.py and no rst2man script.
This patch supports users with both types of systems by checking for
rst2man, falling back on rst2man.py, and giving up only if neither is
found.  Users can also set the new RST2MAN path variable explicitly
when they call Make:

  make RST2MAN=/my/custom/rst_to_man_converter build-man

I use POSIX's 'command -v' [1] to find the path to rst2man or
rst2man.py, and save that as RST2MAN in Makefile.config.  We can use a
non-empty RST2MAN to check for the availability of an rst2man program,
so there's no need for a separate HAVE_RST2MAN.  Then pass the
configured RST2MAN path through to prerst2man.py to use in its system
call.

[1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
---
 configure          | 12 +++++++-----
 doc/Makefile.local |  6 +++---
 doc/prerst2man.py  |  9 +++++----
 3 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/configure b/configure
index 1d430b9..81c286b 100755
--- a/configure
+++ b/configure
@@ -400,7 +400,6 @@ printf "Checking if sphinx is available and supports nroff output... "
 if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev/null 2>&1 ; then
     printf "Yes.\n"
     have_sphinx=1
-    have_rst2man=0
 else
     printf "No (falling back to rst2man).\n"
     have_sphinx=0
@@ -408,10 +407,12 @@ else
     printf "Checking if rst2man is available... "
     if rst2man -V > /dev/null 2>&1; then
        printf "Yes.\n"
-       have_rst2man=1
+       RST2MAN=$(command -v rst2man)
+    elif rst2man.py -V > /dev/null 2>&1; then
+       printf "Yes.\n"
+       RST2MAN=$(command -v rst2man.py)
     else
        printf "No (so will not install man pages).\n"
-       have_rst2man=0
     fi
 fi
 
@@ -788,8 +789,9 @@ HAVE_EMACS = ${have_emacs}
 # Whether there's a sphinx-build binary available for building documentation
 HAVE_SPHINX=${have_sphinx}
 
-# Whether there's a rst2man binary available for building documentation
-HAVE_RST2MAN=${have_rst2man}
+# The path to the rst2man program for building documentation.  Set to
+# an empty string if no such program is available.
+RST2MAN=${RST2MAN}
 
 # The directory to which desktop files should be installed
 desktop_dir = \$(prefix)/share/applications
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 0980c71..e08fc99 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -42,8 +42,8 @@ ifeq ($(HAVE_SPHINX),1)
 	    mkdir -p $(DOCBUILDDIR)/man/man$${section}; \
 	    mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
 	done
-else ifeq ($(HAVE_RST2MAN),1)
-	$(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
+else ifdef RST2MAN
+	$(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
 else
 	@echo "Fatal: build dependency fail."
 	@false
@@ -51,7 +51,7 @@ endif
 
 # Do not try to build or install man pages if a man page converter is
 # not available.
-ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
+ifeq ($(HAVE_SPHINX)$(RST2MAN),0)
 build-man:
 install-man:
 	@echo "No sphinx or rst2man, will not install man pages."
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 437dea9..81ce817 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -4,8 +4,9 @@ from os.path import dirname, isdir
 from os import makedirs, system
 import re
 
-sourcedir = argv[1]
-outdir = argv[2]
+rst2man = argv[1]
+sourcedir = argv[2]
+outdir = argv[3]
 
 if not isdir(outdir):
     makedirs(outdir, 0o755)
@@ -59,5 +60,5 @@ for page in man_pages:
     outfile.write("".join(lines))
     outfile.close()
 
-    system('set -x; rst2man {0} {1}/{2}.{3}'
-           .format(filename, outdir, page[0], page[4]))
+    system('set -x; {0} {1} {2}/{3}.{4}'
+           .format(rst2man, filename, outdir, page[0], page[4]))
-- 
1.9.1.353.gc66d89d

[PATCH 6/7] doc/prerst2man.py: Convert execfile to import

[W. Trevor King]

excefile is gone in Python 3 [1].  Instead of exec-ing the
configuration, it's easier to insert the source directory in Python's
path [2], and just import the configuration.  With this change,
prerst2man.py is compatible with both Python 2 and 3.

[1]: https://docs.python.org/3.0/whatsnew/3.0.html#builtins
[2]: https://docs.python.org/3/library/sys.html#sys.path
---
 doc/prerst2man.py | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 81ce817..7d78e9b 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -1,18 +1,20 @@
-from sys import argv
+import sys
 from datetime import date
 from os.path import dirname, isdir
 from os import makedirs, system
 import re
 
-rst2man = argv[1]
-sourcedir = argv[2]
-outdir = argv[3]
+rst2man = sys.argv[1]
+sourcedir = sys.argv[2]
+outdir = sys.argv[3]
+
+sys.path.insert(0, sourcedir)
+import conf
+
 
 if not isdir(outdir):
     makedirs(outdir, 0o755)
 
-execfile(sourcedir + "/conf.py")
-
 
 def header(file, startdocname, command, description, authors, section):
     file.write("""
@@ -29,10 +31,10 @@ def header(file, startdocname, command, description, authors, section):
 '-' * len(description),
 description,
 '-' * len(description),
-date.today().isoformat(), release, section, project))
+date.today().isoformat(), conf.release, section, conf.project))
 
 blankre = re.compile("^\s*$")
-for page in man_pages:
+for page in conf.man_pages:
     outdirname = outdir + '/' + dirname(page[0])
     if not isdir(outdirname):
         makedirs(outdirname, 0o755)
-- 
1.9.1.353.gc66d89d

[PATCH 7/7] doc/INSTALL: Remove rst2man reference and other updates

[W. Trevor King]

The rst2man target was removed in 9d9a700 (doc: build man pages at
build time; introduce HAVE_SPHINX, HAVE_RST2MAN, 2014-03-13), but a
reference in the install docs slipped through.  While I was removing
that reference, I also:

* Converted doc/INSTALL to reStructuredText, so I can link to Sphinx
  and Docutils directly.  Not everyone has access to Debian's
  python-docutils, so it's better to be genric here.
* Converted from an unordered list to paragraphs, because I think it
  flows better.
* Dropped the rst2man no-automatic-install caveat.  I don't think this
  applies to the current code, although I haven't tried to track down
  a commit that adds the automatic-install support.  Anyhow,

    $ make HAVE_SPHINX=0 RST2MAN=/usr/bin/rst2man.py DESTDIR=/tmp/ install-man

  works for me.
---
 doc/INSTALL | 34 ++++++++++++++++++++--------------
 1 file changed, 20 insertions(+), 14 deletions(-)

diff --git a/doc/INSTALL b/doc/INSTALL
index e37c2b9..91222f9 100644
--- a/doc/INSTALL
+++ b/doc/INSTALL
@@ -1,24 +1,30 @@
 This file contains some more detailed information about building and
 installing the documentation.
 
-Building with sphinx.
----------------------
+Building with Sphinx
+--------------------
 
-- You need sphinx at least version 1.0.
+With Sphinx_ version 1.0 or greater, you can build man, info, html,
+and pdf versions of the docs (currently only the man pages) with::
 
-- You can build build and install man pages with 'make install-man'
+  make build-{man|info|html|pdf}
 
-- You can build man, info, html, and pdf versions of the docs
-  (currently only the man pages) with
+You can build build and install the docs (currently only the man
+pages) with::
 
-     'make install-{man|info|html|pdf}'
+  make install-{man|info|html|pdf}
 
-Building the man pages
-----------------------
+Building the man Docutils
+-------------------------
 
-- You can build the man pages with rst2man (from python-docutils) with
-  'make rst2man'.
+If you don't have Sphinx installed, you can still build the man-page
+version of the docs using rst2man (from Docutils_)::
 
-- Currently there is no support to automagically install the resulting
-  nroff files, but it should work to modify the target install-man
-  in doc/Makefile.local.
+  make build-man
+
+and install with::
+
+  make install-man
+
+.. _Sphinx: http://sphinx-doc.org/
+.. _Docutils: http://docutils.sourceforge.net/
-- 
1.9.1.353.gc66d89d

Re: [PATCH 5/7] doc: Allow rst2man.py as an alternative to rst2man

[Tomi Ollila]

On Sat, Apr 05 2014, "W. Trevor King" <wking@tremily.us> wrote:

> Gentoo's dev-python/docutils-0.10 installs Docutils scripts with a
> *.py extension, so I have /usr/bin/rst2man.py and no rst2man script.
> This patch supports users with both types of systems by checking for
> rst2man, falling back on rst2man.py, and giving up only if neither is
> found.  Users can also set the new RST2MAN path variable explicitly
> when they call Make:
>
>   make RST2MAN=/my/custom/rst_to_man_converter build-man
>
> I use POSIX's 'command -v' [1] to find the path to rst2man or
> rst2man.py, and save that as RST2MAN in Makefile.config.  We can use a
> non-empty RST2MAN to check for the availability of an rst2man program,
> so there's no need for a separate HAVE_RST2MAN.  Then pass the
> configured RST2MAN path through to prerst2man.py to use in its system
> call.
>
> [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html

This series looks good to me. 

Except the reference to _POSIX_ page. One knows how consistent these
specifications are; alternative:

http://pubs.opengroup.org/onlinepubs/009695399/utilities/command.html

mentions additionally that -v flag
"(On systems supporting the User Portability Utilities option.)" 

Also, we don't give such a treatment to other command either; I'd rather
see RST2MAN=rst2man, RST2MAN=rst2man.py *and* RST2MAN= lines used
instead -- the last to set RST2MAN to empty string instead of being unset.

Tomi


> ---
>  configure          | 12 +++++++-----
>  doc/Makefile.local |  6 +++---
>  doc/prerst2man.py  |  9 +++++----
>  3 files changed, 15 insertions(+), 12 deletions(-)
>
> diff --git a/configure b/configure
> index 1d430b9..81c286b 100755
> --- a/configure
> +++ b/configure
> @@ -400,7 +400,6 @@ printf "Checking if sphinx is available and supports nroff output... "
>  if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev/null 2>&1 ; then
>      printf "Yes.\n"
>      have_sphinx=1
> -    have_rst2man=0
>  else
>      printf "No (falling back to rst2man).\n"
>      have_sphinx=0
> @@ -408,10 +407,12 @@ else
>      printf "Checking if rst2man is available... "
>      if rst2man -V > /dev/null 2>&1; then
>         printf "Yes.\n"
> -       have_rst2man=1
> +       RST2MAN=$(command -v rst2man)
> +    elif rst2man.py -V > /dev/null 2>&1; then
> +       printf "Yes.\n"
> +       RST2MAN=$(command -v rst2man.py)
>      else
>         printf "No (so will not install man pages).\n"
> -       have_rst2man=0
>      fi
>  fi
>  
> @@ -788,8 +789,9 @@ HAVE_EMACS = ${have_emacs}
>  # Whether there's a sphinx-build binary available for building documentation
>  HAVE_SPHINX=${have_sphinx}
>  
> -# Whether there's a rst2man binary available for building documentation
> -HAVE_RST2MAN=${have_rst2man}
> +# The path to the rst2man program for building documentation.  Set to
> +# an empty string if no such program is available.
> +RST2MAN=${RST2MAN}
>  
>  # The directory to which desktop files should be installed
>  desktop_dir = \$(prefix)/share/applications
> diff --git a/doc/Makefile.local b/doc/Makefile.local
> index 0980c71..e08fc99 100644
> --- a/doc/Makefile.local
> +++ b/doc/Makefile.local
> @@ -42,8 +42,8 @@ ifeq ($(HAVE_SPHINX),1)
>  	    mkdir -p $(DOCBUILDDIR)/man/man$${section}; \
>  	    mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
>  	done
> -else ifeq ($(HAVE_RST2MAN),1)
> -	$(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
> +else ifdef RST2MAN
> +	$(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
>  else
>  	@echo "Fatal: build dependency fail."
>  	@false
> @@ -51,7 +51,7 @@ endif
>  
>  # Do not try to build or install man pages if a man page converter is
>  # not available.
> -ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
> +ifeq ($(HAVE_SPHINX)$(RST2MAN),0)
>  build-man:
>  install-man:
>  	@echo "No sphinx or rst2man, will not install man pages."
> diff --git a/doc/prerst2man.py b/doc/prerst2man.py
> index 437dea9..81ce817 100644
> --- a/doc/prerst2man.py
> +++ b/doc/prerst2man.py
> @@ -4,8 +4,9 @@ from os.path import dirname, isdir
>  from os import makedirs, system
>  import re
>  
> -sourcedir = argv[1]
> -outdir = argv[2]
> +rst2man = argv[1]
> +sourcedir = argv[2]
> +outdir = argv[3]
>  
>  if not isdir(outdir):
>      makedirs(outdir, 0o755)
> @@ -59,5 +60,5 @@ for page in man_pages:
>      outfile.write("".join(lines))
>      outfile.close()
>  
> -    system('set -x; rst2man {0} {1}/{2}.{3}'
> -           .format(filename, outdir, page[0], page[4]))
> +    system('set -x; {0} {1} {2}/{3}.{4}'
> +           .format(rst2man, filename, outdir, page[0], page[4]))
> -- 
> 1.9.1.353.gc66d89d
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH 5/7] doc: Allow rst2man.py as an alternative to rst2man

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 1902 bytes --]

On Sat, Apr 05, 2014 at 10:05:31PM +0300, Tomi Ollila wrote:
> On Sat, Apr 05 2014, W. Trevor King wrote:
> > I use POSIX's 'command -v' [1] to find the path to rst2man…
> >
> > [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
> 
> …
> Except the reference to _POSIX_ page. One knows how consistent these
> specifications are; alternative:
> 
> http://pubs.opengroup.org/onlinepubs/009695399/utilities/command.html
> 
> mentions additionally that -v flag
> "(On systems supporting the User Portability Utilities option.)" 

It's been a decade since POSIX 2004 ;).  I'm not sure when the “User
Portability Utilities” caveat was removed, but I imagine most
POSIX-aspiring shells have -v support.  Short of citing POSIX 2013, I
think I'd have to survey likely shells, and that seems even less
reliable.  Maybe I'm missunderstanding your suggested change?

> Also, we don't give such a treatment to other command either; I'd rather
> see RST2MAN=rst2man, RST2MAN=rst2man.py *and* RST2MAN= lines used
> instead -- the last to set RST2MAN to empty string instead of being unset.

I'm fine with that.  Alternatively, we could add an:

  if -n "${RST2MAN}"

clause to the front of the detection code to allow users with oddball
scripts (maybe a null set) to override RST2MAN at configure time:

  $ RST2MAN=/my/custom/rst_to_man_converter ./configure
  $ make

instead of at make-invocation time:

  $ ./configure
  $ make RST2MAN=/my/custom/rst_to_man_converter

That would consolidate configuration around the 'config' call, and
make explicitly emptying the RST2MAN variable more clearly superfluous
(although I'm still fine with an explicit empty).

Thoughts?

Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 7/7] doc/INSTALL: Remove rst2man reference and other updates

[David Bremner]

"W. Trevor King" <wking@tremily.us> writes:

> The rst2man target was removed in 9d9a700 (doc: build man pages at
> build time; introduce HAVE_SPHINX, HAVE_RST2MAN, 2014-03-13), but a
> reference in the install docs slipped through.  While I was removing
> that reference, I also:
>
> * Converted doc/INSTALL to reStructuredText, so I can link to Sphinx
>   and Docutils directly.  Not everyone has access to Debian's
>   python-docutils, so it's better to be genric here.
> * Converted from an unordered list to paragraphs, because I think it
>   flows better.
> * Dropped the rst2man no-automatic-install caveat.  I don't think this
>   applies to the current code, although I haven't tried to track down
>   a commit that adds the automatic-install support.  Anyhow,
>
>     $ make HAVE_SPHINX=0 RST2MAN=/usr/bin/rst2man.py DESTDIR=/tmp/ install-man
>
>   works for me.
> ---
>  doc/INSTALL | 34 ++++++++++++++++++++--------------
>  1 file changed, 20 insertions(+), 14 deletions(-)
>
> diff --git a/doc/INSTALL b/doc/INSTALL
> index e37c2b9..91222f9 100644
> --- a/doc/INSTALL
> +++ b/doc/INSTALL
> @@ -1,24 +1,30 @@
>  This file contains some more detailed information about building and
>  installing the documentation.
>  
> -Building with sphinx.
> ----------------------
> +Building with Sphinx
> +--------------------
>  
> -- You need sphinx at least version 1.0.
> +With Sphinx_ version 1.0 or greater, you can build man, info, html,
> +and pdf versions of the docs (currently only the man pages) with::
>  
> -- You can build build and install man pages with 'make install-man'
> +  make build-{man|info|html|pdf}

most of those those targets now start with sphinx-
>  
> -- You can build man, info, html, and pdf versions of the docs
> -  (currently only the man pages) with
> +You can build build and install the docs (currently only the man
> +pages) with::

build build
>  
> -     'make install-{man|info|html|pdf}'
> +  make install-{man|info|html|pdf}
>  

this is not your bug per se, but while we're fixing docs, most of those
targets don't exist.

> -Building the man pages
> -----------------------
> +Building the man Docutils
> +-------------------------
>  

+ with

> -- You can build the man pages with rst2man (from python-docutils) with
> -  'make rst2man'.
> +If you don't have Sphinx installed, you can still build the man-page
> +version of the docs using rst2man (from Docutils_)::
>  
> -- Currently there is no support to automagically install the resulting
> -  nroff files, but it should work to modify the target install-man
> -  in doc/Makefile.local.

This should mention the relevant variables, since the targets are the
same in both cases

Finally, I don't really object to rewriting doc/INSTALL in rst, but I
wonder if we should rename it to INSTALL.rst

d

Re: [PATCH 7/7] doc/INSTALL: Remove rst2man reference and other updates

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 2308 bytes --]

On Sat, Apr 05, 2014 at 05:35:49PM -0300, David Bremner wrote:
> W. Trevor King writes:
> 
> > -- You can build build and install man pages with 'make install-man'
> > +  make build-{man|info|html|pdf}
> 
> most of those those targets now start with sphinx-

Ah, looks like that happended in with the original Sphinx code in
d736260 (doc: convert sphinx based docs, 2014-01-28).  It looks like
the current usage is (from the .PHONY entries):

  {build|install}-man, which is backend (Sphinx/Docutils) agnostic
  sphinx-{html|texinfo|info}, which doesn't have an install target

Is that distinction intentional?  Personally I prefer the consistency
of:

  {build|install}-{man|html|texinfo|info}

if the configured backend (Sphinx/Docutils) doesn't support the
requested target, we should error out.  If no backend is detected,
build-man and install-man should be pulled from the default dependency
tree (but they would still error out if you called them directly).  If
that sounds reasonable, I can work up a patch.

> > -- You can build man, info, html, and pdf versions of the docs
> > -  (currently only the man pages) with
> > +You can build build and install the docs (currently only the man
> > +pages) with::
> 
> build build

Oops, thanks.

> > -Building the man pages
> > -----------------------
> > +Building the man Docutils
> > +-------------------------
> >  
> 
> + with

Thanks again :p.

> > -- You can build the man pages with rst2man (from python-docutils) with
> > -  'make rst2man'.
> > +If you don't have Sphinx installed, you can still build the man-page
> > +version of the docs using rst2man (from Docutils_)::
> >  
> > -- Currently there is no support to automagically install the resulting
> > -  nroff files, but it should work to modify the target install-man
> > -  in doc/Makefile.local.
> 
> This should mention the relevant variables, since the targets are
> the same in both cases

Ok.

> Finally, I don't really object to rewriting doc/INSTALL in rst, but
> I wonder if we should rename it to INSTALL.rst

Sure (I don't really mind).

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 836 bytes --]

Re: [PATCH 7/7] doc/INSTALL: Remove rst2man reference and other updates

[David Bremner]

"W. Trevor King" <wking@tremily.us> writes:

>   {build|install}-man, which is backend (Sphinx/Docutils) agnostic
>   sphinx-{html|texinfo|info}, which doesn't have an install target
>
> Is that distinction intentional?  Personally I prefer the consistency
> of:
>
>   {build|install}-{man|html|texinfo|info}
>

I think the sphinx- prefix is a historical accident, from when we tried
to control backend with targets, so I don't really mind those switching
(back?) to build-

install-man is backend agnostic. Similar targets could be written for
html and info, but no-one did yet. I guess we'd need variables to
specify destinations. Installing info is a bit tricky because of the
need to use install-info(1) to update directory files

Re: [PATCH 7/7] doc/INSTALL: Remove rst2man reference and other updates

[Tomi Ollila]

On Sat, Apr 05 2014, David Bremner <david@tethera.net> wrote:

> "W. Trevor King" <wking@tremily.us> writes:
>
>>
>> * Converted doc/INSTALL to reStructuredText, so I can link to Sphinx
>>   and Docutils directly.  Not everyone has access to Debian's
>>   python-docutils, so it's better to be genric here.
>
> Finally, I don't really object to rewriting doc/INSTALL in rst, but I
> wonder if we should rename it to INSTALL.rst

Or make the file start with '.. -*- rst -*-' ?

>
> d

Tomi

Re: [PATCH 5/7] doc: Allow rst2man.py as an alternative to rst2man

[Tomi Ollila]

On Sat, Apr 05 2014, "W. Trevor King" <wking@tremily.us> wrote:

> On Sat, Apr 05, 2014 at 10:05:31PM +0300, Tomi Ollila wrote:
>> On Sat, Apr 05 2014, W. Trevor King wrote:
>> > I use POSIX's 'command -v' [1] to find the path to rst2man…
>> >
>> > [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
>> 
>> …
>> Except the reference to _POSIX_ page. One knows how consistent these
>> specifications are; alternative:
>> 
>> http://pubs.opengroup.org/onlinepubs/009695399/utilities/command.html
>> 
>> mentions additionally that -v flag
>> "(On systems supporting the User Portability Utilities option.)" 
>
> It's been a decade since POSIX 2004 ;).  I'm not sure when the “User
> Portability Utilities” caveat was removed, but I imagine most
> POSIX-aspiring shells have -v support.  Short of citing POSIX 2013, I
> think I'd have to survey likely shells, and that seems even less
> reliable.  Maybe I'm missunderstanding your suggested change?
>
>> Also, we don't give such a treatment to other command either; I'd rather
>> see RST2MAN=rst2man, RST2MAN=rst2man.py *and* RST2MAN= lines used
>> instead -- the last to set RST2MAN to empty string instead of being unset.
>
> I'm fine with that.  Alternatively, we could add an:
>
>   if -n "${RST2MAN}"
>
> clause to the front of the detection code to allow users with oddball
> scripts (maybe a null set) to override RST2MAN at configure time:
>
>   $ RST2MAN=/my/custom/rst_to_man_converter ./configure
>   $ make
>
> instead of at make-invocation time:
>
>   $ ./configure
>   $ make RST2MAN=/my/custom/rst_to_man_converter
>
> That would consolidate configuration around the 'config' call, and
> make explicitly emptying the RST2MAN variable more clearly superfluous
> (although I'm still fine with an explicit empty).
>
> Thoughts?

If we did that, what about other commands, starting with sphinx-build
(that is harder as python -m `sphinx.writers.manpage` fails even 
sphinx-build is set to something else; in case of sphinx, 
make SPHINXBUILD=sphinx-1.0-build works, for example in RHEL 6.2 
machines...

...doing --with-rst2man=my.custom.rst_to_man_converter and make things
look consistent would required considerable amount of development
(and review!) time...

ATM I'd just settle with plain command names and empty RST2MAN in case not
found. 

>
> Trevor
>
> -- 

More Thoughts?


Tomi

Re: [PATCH 0/7] doc: Python 3 compat, rst2man.py support, etc.

[Tomi Ollila]

On Sat, Apr 05 2014, "W. Trevor King" <wking@tremily.us> wrote:

> I just bumped into this today while testing v2 of my
> content-description series:
>
>   $ ./configure
>   …
>   $ make
>   …
>   python ./doc/mkdocdeps.py ./doc doc/_build doc/docdeps.mk
>   Traceback (most recent call last):
>     File "./doc/mkdocdeps.py", line 6, in <module>
>       execfile(srcdir + '/conf.py')
>   NameError: name 'execfile' is not defined
>   …
>
> The first patch in this series fixes that issue, and the rest of the
> series fixes some other issues I bumped into while working on that.
> Sorry I missed these in the initial series.
>
> Note that while mkdocdeps.py and prerst2man.py are now Python 3
> compatible (with this series), the build will fail for Python's 3.0
> through 3.2 because of the explicit unicode literals in conf.py [1].
> It's likely that conf.py could use [2]
>
>   from __future__ import unicode_literals
>
> drop the u'' prefixes, and be compatible with all Python's ≥2.6
> (including all 3s).  I haven't checked the logic though, and I'm not
> running 3.2 locally anymore, so it's not a big priority for me.
>
> Cheers,
> Trevor
>
> [1]: https://docs.python.org/3/whatsnew/3.3.html#pep-414-explicit-unicode-literals
> [2]: from __future__ import unicode_literals
>
> W. Trevor King (7):
>   doc/mkdocdeps.py: Convert execfile to import
>   doc/mkdocdeps.py: Use "with" statement for the output file
>   doc/prerst2man.py: Use Python-3-compatible octal notation
>   doc/prerst2man.py: Fix 'os.system' -> 'system' typo
>   doc: Allow rst2man.py as an alternative to rst2man
>   doc/prerst2man.py: Convert execfile to import
>   doc/INSTALL: Remove rst2man reference and other updates

In this series IMO the patches 1-4:

id:8d518408f2da8bc96ae3123f05791142da26b9bc.1396718720.git.wking@tremily.us
id:543aee63407956e60f85dc11a2d25855e98c10c3.1396718720.git.wking@tremily.us
id:5e4509ab08699afe2681110fb35075e1d0bbdc7e.1396718720.git.wking@tremily.us
id:c5ec510ac25c867ad600c475a0070a003440a4b8.1396718720.git.wking@tremily.us

could go in as those are. 5:

id:adce76bb9a0ca728d856da4ecaf6b282e22e7440.1396718720.git.wking@tremily.us

if, for consistency reason (we don't use absolute paths with other commands
either), rst2man/rst2man.py is used as is (and commit message adjusted
accordingly).

patch 6:

id:7c43c614cb09665400544fc0928ac14bb67ceeb5.1396718720.git.wking@tremily.us

would be good as is, but it doesn't apply without 5

In 7:

id:edf9a674bc1f41917caead8d38b5f09295a9d1bd.1396718720.git.wking@tremily.us

In addition to David's comments, s/genric/generic/ ;D. I don't have opinion
whether INSTALL should be changed to README.rst. Maybe this is good idea;
that also distingush between ./INSTALL & doc/INSTALL. In this case 
`git grep INSTALL` shows that the line 83 in ./INSTALL needs to be changed,
too.

Tomi

PS: this id:<hash>.<timestamp>.git.<user@host> is PITA format to work with ;p

>
>  configure          | 12 +++++++-----
>  doc/INSTALL        | 34 ++++++++++++++++++++--------------
>  doc/Makefile.local |  6 +++---
>  doc/mkdocdeps.py   | 19 ++++++++++---------
>  doc/prerst2man.py  | 25 ++++++++++++++-----------
>  5 files changed, 54 insertions(+), 42 deletions(-)
>
> -- 
> 1.9.1.353.gc66d89d

Re: [PATCH 0/7] doc: Python 3 compat, rst2man.py support, etc.

[David Bremner]

Tomi Ollila <tomi.ollila@iki.fi> writes:

> In this series IMO the patches 1-4:
>
> id:8d518408f2da8bc96ae3123f05791142da26b9bc.1396718720.git.wking@tremily.us
> id:543aee63407956e60f85dc11a2d25855e98c10c3.1396718720.git.wking@tremily.us
> id:5e4509ab08699afe2681110fb35075e1d0bbdc7e.1396718720.git.wking@tremily.us
> id:c5ec510ac25c867ad600c475a0070a003440a4b8.1396718720.git.wking@tremily.us
>
> could go in as those are. 5:
>
> id:adce76bb9a0ca728d856da4ecaf6b282e22e7440.1396718720.git.wking@tremily.us
>
> if, for consistency reason (we don't use absolute paths with other commands
> either), rst2man/rst2man.py is used as is (and commit message adjusted
> accordingly).

I've queued 1-4 for merging. Any patches that might break the build
(e.g. 5 and 6 in this series) have to go in pretty quick if they are to
be in 0.18; patch 7 we can sort out during the freeze.

I'm not sure I completely understand the state of the discussion around
patch 5. Personally I don't like either undefined or empty RST2MAN as a
boolean a priori. I'd rather keep HAVE_RST2MAN for consistency.

d

Re: [PATCH 0/7] doc: Python 3 compat, rst2man.py support, etc.

[David Bremner]

"W. Trevor King" <wking@tremily.us> writes:

> I just bumped into this today while testing v2 of my
> content-description series:
>

pushed patches 1-4

d