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

[Ralf Corsepius]

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?

> 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]

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

>  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).

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

Ralf