Re: Add support for generating HTML docs a` la PDF, etc., revision2

[Richard Dawe]

Hello.

Ralf Corsepius wrote:
> 
> Am Son, 2003-03-02 um 14.00 schrieb Alexandre Duret-Lutz:
> > >>> "Ralf" == Ralf Corsepius <address@hidden> writes:
> >
> >  Ralf> Am Fre, 2003-02-28 um 12.30 schrieb Richard Dawe:
> >  >> Hello.
> >  >>
> >  >> Below is a revised version of the patch to add support for an 'html'
> >  >> target for generating HTML using makeinfo. Changes:
> >
> >  Ralf> Hmm, this just caught my eye:
> >
> >  >> -.PHONY: info info-am dvi dvi-am pdf pdf-am
> >  >> +.PHONY: info info-am dvi dvi-am pdf pdf-am html html-am
> >  Ralf> Is it really a good idea to make "info", "dvi", "pdf" and "html"
> >  Ralf> make-targets PHONY?
> >
> >  Ralf> I think, there non-negligible possibility for them to conflict with
> >  Ralf> sub-directories, eg. if docs are generated dynamically (eg. doxygen
> >  Ralf> generating its docs into html/) or with subdirectories containing
> >  Ralf> include-files for documents (e.g. texi-docs conditionally including
> >  Ralf> files by @ifhtml/@ifinfo etc.).
> >
> >  Ralf> Esp. html seem critical to me, because unlike dvi, pdf
> >  Ralf> and ps, html docs often are split into several
> >  Ralf> sub-documents.
> >
> > I'm a bit confused by this.  Could you provide an scenario for
> > such a situation (i.e., where `.PHONY: html' is harmful)?
> I am not sure if using "PHONY html/info/pdf etc." is harmful, that's why
> I am asking.
> 
> Let me try to rephrase my question:
> 
> What will happen in case a directory containing *.texi files contains a
> subdirectory called html and descends into $builddir/html to generate
> some files to be included by the makeinfo --html generated texinfo
> document?

It works fine. I've included a hacked-up version of txinfo21.test from my
patch at the end of this mail. I've also included a log file of a test run:

    make TESTS=txinfo21-ralf.test check VERBOSE=x >txinfo21-ralf.log 2>&1

> > AFAICT, we need `.PHONY: html' precisely to work around cases
> > where `html/' exists.  Without PHONY, `make html' would stop its
> > recursion as soon as it encounters a `html' file or directory.
> >
> > Maybe you are talking about a user-supplied `html:' rule that
> > build a `html/' directory?
> Yes, that is one part of the question.
> 
> Eg. I have one Makefile.am using this:
> 
> if DOXY_HTML
> html:
>         mkdir html
> 
> html/index.html: html doxyfile
>         doxygen doxyfile
> 
> noinst_DATA = html/index.html
> endif
> 
> [doxyfile is configure/autoconf-generated and supposed to generate
> doxygen documents into $(builddir)/html/; DOXY_HTML is an automake
> conditional, set by autoconf-magic]

Do you really need the separate html rule? Why can't you create html in the
rule for html/index.html? E.g.:

    html/index.html
        mkdir -p html
        doxygen doxyfile

> >   Still I don't really see how `.PHONY: html' would harm.
> That's what I wanted to know.

If you have ".PHONY: html" and DOXY_HTML set and run "make html" with your
above example, then make will always run the "html" rules. These will work the
first time. But they will fail afterwards, because the html directory will
exist.

You'd need to use "mkdir -p" instead, if html were PHONY.

    html:
        mkdir -p html

Hmmm, I guess "mkdir -p" may not be portable. How about "test -d html || mkdir
html" instead.

> >  Are there cases where you type `make
> > html' and don't want the documentation to be rebuilt?
> 
> Yes, because html can be a directory (cf. the example above).

It's unclear to me which "html" rule will be run, when there are two rules. I
can't remember how make decides in this case. I'm guessing we can't rely on
the order.

If the HTML-generation patch is merged, you could use the html-local target to
make doxygen docs instead. E.g.:

    if DOXY_HTML
    html-local: html/index.html

    html/index.html: doxyfile
        doxygen doxyfile

    noinst_DATA = html/index.html
    endif

> >   (E.g.,
> > with Doxygen I'd assume that short of accurate dependencies you
> > always want to rebuild the doc.)

If my HTML-generation patch makes it in, it seems like people will have to
more careful, with their "home-made" HTML-generation rules.

Bye, Rich =]

-- 
Richard Dawe [ http://www.phekda.freeserve.co.uk/richdawe/ ]

---Start txinfo21-ralf.test---
#! /bin/sh
# Copyright (C) 2003  Free Software Foundation, Inc.
#
# This file is part of GNU Automake.
#
# GNU Automake is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
#
# GNU Automake is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Automake; see the file COPYING.  If not, write to
# the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
# Boston, MA 02111-1307, USA.

# Test support for building HTML documentation.

required='makeinfo tex'
. ./defs || exit 1

set -e

cat > configure.in << 'END'
AC_INIT([txinfo21-ralf], [1.0])
AM_INIT_AUTOMAKE
AC_CONFIG_FILES([Makefile html/Makefile])
AC_OUTPUT
END

cat > Makefile.am << 'END'
SUBDIRS = html

info_TEXINFOS = main.texi
END

mkdir html
cat > html/Makefile.am <<'END'
all-local:
        echo "wibble" > wibble.texi
END

cat > main.texi << 'END'
\input texinfo
@setfilename main.info
@settitle main
@node Top
Hello walls.

@include html/wibble.texi
@bye

END

$ACLOCAL
$AUTOMAKE --add-missing
$AUTOCONF

./configure

$MAKE
$MAKE html

exit 0

# Test production of split-per-node HTML.
$MAKE html
test -d main.html
rm -rf main.html

# Test production of a single HTML file.
$MAKE MAKEINFOFLAGS=--no-split html
test -f main.html
rm -f main.html

# Check that HTML is cleaned up properly.
$MAKE distcheck
---End txinfo21-ralf.test---

---Start txinfo21-ralf.log---
c:/djgpp/bin/make.exe  defs
make.exe[1]: Entering directory `c:/develop/automake/tests'
make.exe[1]: `defs' is up to date.
make.exe[1]: Leaving directory `c:/develop/automake/tests'
c:/djgpp/bin/make.exe  check-TESTS
make.exe[1]: Entering directory `c:/develop/automake/tests'
txinfo21-ralf: running makeinfo --version
makeinfo (GNU texinfo) 4.2

Copyright (C) 2002 Free Software Foundation, Inc.
There is NO warranty.  You may redistribute this software
under the terms of the GNU General Public License.
For more information about these matters, see the files named COPYING.
=== Running test ./txinfo21-ralf.test
++ pwd
c:/develop/automake/tests/testSubDir
+ set -e
+ cat
+ cat
+ mkdir html
+ cat
+ cat
+ /dev/env/DJDIR/bin/perl.exe
c:/develop/automake/tests/testSubDir/../../aclocal -I
c:/develop/automake/tests/testSubDir/../../m4
--acdir=c:/develop/automake/tests/../m4
+ /dev/env/DJDIR/bin/perl.exe
c:/develop/automake/tests/testSubDir/../../automake
--libdir=c:/develop/automake/tests/../lib --foreign -Werror -Wall
--add-missing
Makefile.am:3: installing `./texinfo.tex'
+ /dev/env/DJDIR/bin/bash.exe c:/develop/automake/lib/missing --run autoconf
+ ./configure
configure: loading site script c:/djgpp/share/config.site
checking for a BSD-compatible install... /dev/env/DJDIR/bin/ginstall.exe -c
checking whether build environment is sane... yes
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
configure: creating ./config.status
config.status: creating Makefile
config.status: creating html/Makefile
+ make
Making all in html
make.exe[1]: Entering directory `c:/develop/automake/tests/testSubDir/html'
echo "wibble" > wibble.texi
make.exe[1]: Leaving directory `c:/develop/automake/tests/testSubDir/html'
make.exe[1]: Entering directory `c:/develop/automake/tests/testSubDir'
restore=: && \
backupdir=".am$$" && \
rm -rf $backupdir && mkdir $backupdir && \
for f in main.info main.info-[0-9] main.info-[0-9][0-9] main.i[0-9]
main.i[0-9][0-9]; do \
  if test -f $f; then \
    mv $f $backupdir; \
    restore=mv; \
  fi; \
done; \
if /dev/env/DJDIR/bin/bash.exe c:/develop/automake/tests/testSubDir/missing
--run makeinfo   -I . \
 -o main.info `test -f 'main.texi' || echo './'`main.texi; \
then rc=0; else \
  rc=$?; \
  $restore $backupdir/* `echo "./main.info" | sed 's|[^/]*$||'`; \
fi; \
rm -rf $backupdir; \
exit $rc
make.exe[1]: Leaving directory `c:/develop/automake/tests/testSubDir'
+ make html
Making html in html
make.exe[1]: Entering directory `c:/develop/automake/tests/testSubDir/html'
make.exe[1]: Nothing to be done for `html'.
make.exe[1]: Leaving directory `c:/develop/automake/tests/testSubDir/html'
make.exe[1]: Entering directory `c:/develop/automake/tests/testSubDir'
/dev/env/DJDIR/bin/bash.exe c:/develop/automake/tests/testSubDir/missing --run
makeinfo   --html -I . \
 -o main.html `test -f 'main.texi' || echo './'`main.texi
make.exe[1]: Leaving directory `c:/develop/automake/tests/testSubDir'
+ exit 0
PASS: txinfo21-ralf.test
==================
All 1 tests passed
==================
make.exe[1]: Leaving directory `c:/develop/automake/tests'
---End txinfo21-ralf.log---