MSVC/Win32: building the documentation

[John W. Eaton]

On 27-Oct-2006, address@hidden wrote:

| - MSYS comes with an out-dated makeinfo, which cannot handle
| @float, so you have to use another one, for instance from
| the GnuWin32 project (you have to play with the PATH as makeinfo
| is part of the core MSYS)

OK.  I don't think we can solve build-dependency problems for various
systems within Octave itself.

| - texi2dvi and texi2pdf are available either from MSYS or
| from GnuWin32; in both cases, the texi2dvi script has special
| code to handle ; or : as path separator for the TEXINPUTS
| variable. The choice is made on the existence of COMSPEC
| variable, so you have to undefine it (such that it uses : as
| pathsep). I do it with \"COMSPEC= make\" at MSYS prompt
| 
| - TeX is needed, I have MiKTeX installed; this also provides
| makeinfo and texi2dvi, but not texi2pdf (Grrr). That's not
| a big deal as texi2pdf is simply \"texi2dvi --pdf\". What about
| adding this to the configure script: if texi2pdf is not found,
| try with \"texi2dvi --pdf\"?

I think I handled this in the patch below.

| - for reasons beyond my understanding, \"texi2dvi --pdf\" (from
| MiKTeX) does not handle TEXINPUTS variable correctly, while
| \"texi2dvi\" does. The result is that \"conf.texi\" is not found
| when building octave.pdf. The easiest is just to type the
| actual path of the file when requested by TeX (../conf.texi)

I think it would be best to fix this problem in texi2dvi.  Can you
please report it to the maintainers of that script?

| - run-octave failed to recreate the figures because it couldn't
| start the gnuplot process, while pgnuplot was actually in my
| PATH. I identified the cause as the way how gnuplot is invoked
| when use_title_options is true. For some (still unidentified)
| reasons, this does not work. But I could workaround it easily
| by undefining DISPLAY, as in \"DISPLAY= make\". However, and that's
| the funny part, you cannot set COMSPEC to an empty value to
| build the images, as in the second point, otherwise octave is
| unable to start pgnuplot as sub-process. So either you run a
| suite of \"COMSPEC= make\" and \"DISPLAY= make\" up to the next error.
| Or you can use the texi2dvi from the MiKTeX package, which does
| not require COMSPEC set to empty. As a 3rd solution, you can
| simply forget about the COMSPEC setting and just type \"../conf.texi\"
| when texi2dvi/pdf fails to find it.

How about just unsetting COMSPEC when running texinfo and texi2dvi, as
in the patch below?  Does that work for you?

Thanks,

jwe


ChangeLog:

2006-10-27  John W. Eaton  <address@hidden>

        * aclocal.m4 (OCTAVE_PROG_TEXI2PDF): Require OCTAVE_PROG_TEXI2DVI.
        If texi2pdf is not found but texi2dvi is available, set TEXI2PDF
        to "$TEXI2DVI --pdf".
        (OCTAVE_PROG_GPERF, OCTAVE_PROG_GHOSTSCRIPT, OCTAVE_PROG_MAKEINFO,
        OCTAVE_PROG_TEXI2DVI, OCTAVE_PROG_TEXI2PDF, OCTAVE_PROG_PERL,
        OCTAVE_PROG_PYTHON, OCTAVE_PROG_DESKTOP_FILE_INSTALL): Simplify
        calls to AC_CHECK_PROG.
        (OCTAVE_PROG_GHOSTSCRIPT): Also check for gswin32 on Windows systems.
        * Makeconf.in (UNSETCOMSPEC): Define if COMSPEC is defined.
        From Michael Goffioul <address@hidden>.

doc/ChangeLog:

2006-10-27  John W. Eaton  <address@hidden>

        * interpreter/Makefile.in (run-octave):
        Unset DISPLAY while running Octave.
        From Michael Goffioul <address@hidden>.

        * interpreter/Makefile.in (octave.dvi, octave.pdf):
        Use $(UNSETCOMSPEC) in command.
        * faq/Makefile.in (Octave-FAQ.dvi, Octave-FAQ.pdf): Likewise.
        * liboctave/Makefile.in (liboctave.dvi, liboctave.pdf): Likewise.


Index: Makeconf.in
===================================================================
RCS file: /cvs/octave/Makeconf.in,v
retrieving revision 1.182
diff -u -u -r1.182 Makeconf.in
--- Makeconf.in 26 Oct 2006 20:50:04 -0000      1.182
+++ Makeconf.in 27 Oct 2006 16:35:36 -0000
@@ -63,6 +63,14 @@
 TEXI2DVI = @TEXI2DVI@
 TEXI2PDF = @TEXI2PDF@
 
+# Both texi2dvi and texi2pdf check COMSPEC to decide what path
+# separator to use.  We build Octave with a Unixy shell, even on
+# Windows sytems, so we need to unset COMSPEC when invoking these
+# scripts.  Used in the doc/*/Makefiles.
+ifneq ($(COMSPEC),)
+  UNSETCOMSPEC = COMSPEC=
+endif
+
 GHOSTSCRIPT = @GHOSTSCRIPT@
 
 DEFAULT_PAGER = @DEFAULT_PAGER@
Index: aclocal.m4
===================================================================
RCS file: /cvs/octave/aclocal.m4,v
retrieving revision 1.101
diff -u -u -r1.101 aclocal.m4
--- aclocal.m4  26 Oct 2006 21:41:39 -0000      1.101
+++ aclocal.m4  27 Oct 2006 16:35:36 -0000
@@ -538,7 +538,7 @@
 dnl
 dnl OCTAVE_PROG_GPERF
 AC_DEFUN(OCTAVE_PROG_GPERF, [
-  AC_CHECK_PROG(GPERF, gperf, gperf, [])
+  AC_CHECK_PROG(GPERF, gperf)
   if test -n "$GPERF"; then
     if echo "%{
 enum octave_kw_id { a_kw };
@@ -564,7 +564,15 @@
 dnl
 dnl OCTAVE_PROG_GHOSTSCRIPT
 AC_DEFUN(OCTAVE_PROG_GHOSTSCRIPT, [
-  AC_CHECK_PROG(GHOSTSCRIPT, gs, gs, [])
+  case "$canonical_host_type" in
+    *-*-cygwin* | *-*-mingw32* | *-*-msdosmsvc)
+      gs_names="gs gswin32"
+    ;;
+    *)
+      gs_names=gs
+    ;;
+  esac
+  AC_CHECK_PROGS(GHOSTSCRIPT, $gs_names)
   if test -z "$GHOSTSCRIPT"; then
     GHOSTSCRIPT='$(top_srcdir)/missing gs'
     warn_ghostscript="I didn't find ghostscript, but it's only a problem if 
you need to reconstruct figures for the manual"
@@ -577,7 +585,7 @@
 dnl
 dnl OCTAVE_PROG_MAKEINFO
 AC_DEFUN(OCTAVE_PROG_MAKEINFO, [
-  AC_CHECK_PROG(MAKEINFO, makeinfo, makeinfo, [])
+  AC_CHECK_PROG(MAKEINFO, makeinfo)
   if test -z "$MAKEINFO"; then
     MAKEINFO='$(top_srcdir)/missing makeinfo'
     warn_makeinfo="I didn't find makeinfo, but it's only a problem if you need 
to reconstruct the Info version of the manual"
@@ -590,7 +598,7 @@
 dnl
 dnl OCTAVE_PROG_TEXI2DVI
 AC_DEFUN(OCTAVE_PROG_TEXI2DVI, [
-  AC_CHECK_PROG(TEXI2DVI, texi2dvi, texi2dvi, [])
+  AC_CHECK_PROG(TEXI2DVI, texi2dvi)
   if test -z "$TEXI2DVI"; then
     TEXI2DVI='$(top_srcdir)/missing texi2dvi'
     warn_texi2dvi="I didn't find texi2dvi, but it's only a problem if you need 
to reconstruct the DVI version of the manual"
@@ -603,8 +611,18 @@
 dnl
 dnl OCTAVE_PROG_TEXI2PDF
 AC_DEFUN(OCTAVE_PROG_TEXI2PDF, [
-  AC_CHECK_PROG(TEXI2PDF, texi2pdf, texi2pdf, [])
+  AC_REQUIRE([OCTAVE_PROG_TEXI2DVI])
+  AC_CHECK_PROG(TEXI2PDF, texi2pdf)
   if test -z "$TEXI2PDF"; then
+    missing=true;
+    if test -n "$TEXI2DVI"; then
+      TEXI2PDF="$TEXI2DVI --pdf"
+      missing=false;
+    fi
+  else
+    missing=false;
+  fi
+  if $missing; then
     TEXI2PDF='$(top_srcdir)/missing texi2pdf'
     warn_texi2pdf="I didn't find texi2pdf, but it's only a problem if you need 
to reconstruct the PDF version of the manual"
     AC_MSG_WARN($warn_texi2pdf)
@@ -865,7 +883,7 @@
 dnl
 dnl OCTAVE_PROG_PERL
 AC_DEFUN(OCTAVE_PROG_PERL,
-[AC_CHECK_PROG(PERL, perl, perl, [])
+[AC_CHECK_PROG(PERL, perl)
   AC_SUBST(PERL)
 ])
 dnl
@@ -873,7 +891,7 @@
 dnl
 dnl OCTAVE_PROG_PYTHON
 AC_DEFUN(OCTAVE_PROG_PYTHON,
-[AC_CHECK_PROG(PYTHON, python, python, [])
+[AC_CHECK_PROG(PYTHON, python)
   AC_SUBST(PYTHON)
 ])
 dnl
@@ -881,7 +899,7 @@
 dnl
 dnl OCTAVE_PROG_DESKTOP_FILE_INSTALL
 AC_DEFUN(OCTAVE_PROG_DESKTOP_FILE_INSTALL,
-[AC_CHECK_PROG(DESKTOP_FILE_INSTALL, desktop-file-install, 
desktop-file-install, [])
+[AC_CHECK_PROG(DESKTOP_FILE_INSTALL, desktop-file-install)
   AC_SUBST(DESKTOP_FILE_INSTALL)
 ])
 dnl
Index: doc/faq/Makefile.in
===================================================================
RCS file: /cvs/octave/doc/faq/Makefile.in,v
retrieving revision 1.29
diff -u -u -r1.29 Makefile.in
--- doc/faq/Makefile.in 22 Mar 2006 22:25:59 -0000      1.29
+++ doc/faq/Makefile.in 27 Oct 2006 16:35:36 -0000
@@ -42,13 +42,15 @@
        -$(MAKEINFO) -I.. -I$(srcdir) -I$(srcdir)/.. $<
 
 Octave-FAQ.dvi: $(TEXINFO)
-       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" $(TEXI2DVI) $<
+       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" \
+         $(UNSETCOMSPEC) $(TEXI2DVI) $<
 
 Octave-FAQ.ps: Octave-FAQ.dvi
        -dvips -o $@ $<
 
 Octave-FAQ.pdf: $(TEXINFO)
-       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" $(TEXI2PDF) $<
+       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" \
+         $(UNSETCOMSPEC) $(TEXI2PDF) $<
 
 HTML/index.html: $(TEXINFO)
        -$(MAKEINFO) --html --ifinfo --output=HTML -I.. -I$(srcdir) 
-I$(srcdir)/.. $<
Index: doc/interpreter/Makefile.in
===================================================================
RCS file: /cvs/octave/doc/interpreter/Makefile.in,v
retrieving revision 1.125
diff -u -u -r1.125 Makefile.in
--- doc/interpreter/Makefile.in 4 Oct 2006 16:09:38 -0000       1.125
+++ doc/interpreter/Makefile.in 27 Oct 2006 16:35:36 -0000
@@ -110,13 +110,15 @@
        -$(MAKEINFO) -I.. -I$(srcdir) -I$(srcdir)/.. $(MAIN_TEXINFO)
 
 octave.dvi: $(IMAGES_EPS) $(TEXINFO)
-       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" $(TEXI2DVI) 
$(MAIN_TEXINFO)
+       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" \
+         $(UNSETCOMSPEC) $(TEXI2DVI) $(MAIN_TEXINFO)
 
 octave.ps: octave.dvi
        -dvips -o $@ $<
 
 octave.pdf: $(IMAGES_PDF) $(TEXINFO)
-       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" $(TEXI2PDF) 
$(MAIN_TEXINFO)
+       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" \
+         $(UNSETCOMSPEC) $(TEXI2PDF) $(MAIN_TEXINFO)
 
 ../../INSTALL.OCTAVE: install.texi
        rm -f INSTALL
@@ -144,8 +146,10 @@
        fi
        $(INSTALL_DATA) $(filter-out html-dir, $<) HTML
 
+## Unset DISPLAY here to avoid problems with the -title option for
+## gnuplot (it doesn't work if we are calling pgnuplot).
 define run-octave
-  $(TOPDIR)/run-octave -f -q -H -p $(srcdir) \
+  DISPLAY= $(TOPDIR)/run-octave -f -q -H -p $(srcdir) \
     --eval "$(notdir $(basename $<)) ('$(notdir $(basename $@))', '$(patsubst 
.%,%, $(suffix $@))')"
 endef
 
Index: doc/liboctave/Makefile.in
===================================================================
RCS file: /cvs/octave/doc/liboctave/Makefile.in,v
retrieving revision 1.35
diff -u -u -r1.35 Makefile.in
--- doc/liboctave/Makefile.in   22 Mar 2006 22:25:59 -0000      1.35
+++ doc/liboctave/Makefile.in   27 Oct 2006 16:35:36 -0000
@@ -50,13 +50,15 @@
        -$(MAKEINFO) -I.. -I$(srcdir) -I$(srcdir)/.. $<
 
 liboctave.dvi: $(TEXINFO)
-       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" $(TEXI2DVI) $<
+       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" \
+         $(UNSETCOMSPEC) $(TEXI2DVI) $<
 
 liboctave.ps: liboctave.dvi
        -dvips -o $@ $<
 
 liboctave.pdf: $(TEXINFO)
-       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" $(TEXI2PDF) $<
+       -TEXINPUTS="..:$(srcdir):$(srcdir)/..:$(TEXINPUTS):" \
+         $(UNSETCOMSPEC) $(TEXI2PDF) $<
 
 HTML/index.html: $(TEXINFO)
        -$(MAKEINFO) --html --ifinfo --output=HTML -I.. -I$(srcdir) 
-I$(srcdir)/.. $<