[Olena-patches] [PATCH 02/10] Build the reference documentation in the source dir.

* doc/Makefile.am (USER_REFMAN_PDF): Set to user-refman.pdf. (USER_REFMAN_HTML): Set to user-refman-html. (DEVEL_REFMAN_PDF): Set to devel/latex/refman.pdf. (DEVEL_REFMAN_HTML): Set to devel/html. (ref-doc-pdf, $(srcdir)/$(USER_REFMAN_PDF)) (ref-doc-html, $(srcdir)/$(USER_REFMAN_HTML)) (ref-doc-devel-pdf, $(srcdir)/$(DEVEL_REFMAN_PDF)) (ref-doc-devel-html, $(srcdir)/$(DEVEL_REFMAN_HTML)) (fake-doc): Adjust. * doc/ref_guide/Makefile.am (REF_GUIDE_HH): Set to $(srcdir)/ref_guide.hh. (REF_GUIDE_PDF): Set to $(srcdir)/ref_guide.pdf ($(REF_GUIDE_HH), $(REF_GUIDE_PDF)): Adjust. * doc/tutorial/Makefile.am (TUTORIAL_HH): Set to $(srcdir)/tutorial.hh. (TUTORIAL_PDF): Set to $(srcdir)/tutorial.pdf. ($(TUTORIAL_HH), $(TUTORIAL_PDF)): Adjust. * doc/white_paper/Makefile.am (WHITE_PAPER_HTML): Set to $(srcdir)/white_paper_html/index.html. (WHITE_PAPER_PDF): Set to $(srcdir)/white_paper.pdf. ($(WHITE_PAPER_HTML), $(WHITE_PAPER_PDF), fake-doc): Adjust rules. --- milena/ChangeLog | 26 +++++++++++++++++++++ milena/doc/Makefile.am | 44 +++++++++++++++++++++-------------- milena/doc/ref_guide/Makefile.am | 33 +++++++++++++++++++++++--- milena/doc/tutorial/Makefile.am | 34 ++++++++++++++++++++++++--- milena/doc/white_paper/Makefile.am | 34 +++++++++++++++++++++++++-- 5 files changed, 142 insertions(+), 29 deletions(-) diff --git a/milena/ChangeLog b/milena/ChangeLog index faac29e..223d1d8 100644 --- a/milena/ChangeLog +++ b/milena/ChangeLog @@ -1,5 +1,31 @@ 2009-07-13 Roland Levillain &lt;roland(a)lrde.epita.fr&gt; + Build the reference documentation in the source dir. + + * doc/Makefile.am (USER_REFMAN_PDF): Set to user-refman.pdf. + (USER_REFMAN_HTML): Set to user-refman-html. + (DEVEL_REFMAN_PDF): Set to devel/latex/refman.pdf. + (DEVEL_REFMAN_HTML): Set to devel/html. + (ref-doc-pdf, $(srcdir)/$(USER_REFMAN_PDF)) + (ref-doc-html, $(srcdir)/$(USER_REFMAN_HTML)) + (ref-doc-devel-pdf, $(srcdir)/$(DEVEL_REFMAN_PDF)) + (ref-doc-devel-html, $(srcdir)/$(DEVEL_REFMAN_HTML)) + (fake-doc): Adjust. + * doc/ref_guide/Makefile.am (REF_GUIDE_HH): Set to + $(srcdir)/ref_guide.hh. + (REF_GUIDE_PDF): Set to $(srcdir)/ref_guide.pdf + ($(REF_GUIDE_HH), $(REF_GUIDE_PDF)): Adjust. + * doc/tutorial/Makefile.am (TUTORIAL_HH): Set to + $(srcdir)/tutorial.hh. + (TUTORIAL_PDF): Set to $(srcdir)/tutorial.pdf. + ($(TUTORIAL_HH), $(TUTORIAL_PDF)): Adjust. + * doc/white_paper/Makefile.am (WHITE_PAPER_HTML): Set to + $(srcdir)/white_paper_html/index.html. + (WHITE_PAPER_PDF): Set to $(srcdir)/white_paper.pdf. + ($(WHITE_PAPER_HTML), $(WHITE_PAPER_PDF), fake-doc): Adjust rules. + +2009-07-13 Roland Levillain &lt;roland(a)lrde.epita.fr&gt; + Polish clean rules. * apps/statues/Makefile.am (CLEANFILES): Add diff --git a/milena/doc/Makefile.am b/milena/doc/Makefile.am index 57c3810..a7d4647 100644 --- a/milena/doc/Makefile.am +++ b/milena/doc/Makefile.am @@ -79,35 +79,43 @@ $(srcdir)/ref_guide/ref_guide.hh: fig-convert ## Vaucanson's doc build system. (Do not forget to adjust Doxyfiles.) # Doxygen PDF documentation outputs. -USER_REFMAN_PDF = $(srcdir)/user/latex/refman.pdf -ref-doc-pdf: $(USER_REFMAN_PDF) +USER_REFMAN_PDF = user-refman.pdf +ref-doc-pdf: $(srcdir)/$(USER_REFMAN_PDF) # FIXME: Split in two rules: one generating the LaTeX file from the # Doxyfile, and another one generating the PDF from the LaTeX source. # Moreover, the LaTeX to PDF rule could be factored using a suffix # rule (as in LRDE's share/). -$(USER_REFMAN_PDF): $(srcdir)/Doxyfile_user_pdf $(srcdir)/figures.stamp $(EXTRA_DEPS) - $(DOXYGEN) $< - cd $(srcdir)/user/latex && $(MAKE) pdf - -USER_REFMAN_HTML = $(srcdir)/user/html -ref-doc-html: $(USER_REFMAN_HTML) -$(USER_REFMAN_HTML): $(srcdir)/Doxyfile_user $(srcdir)/figures.stamp $(EXTRA_DEPS) - $(DOXYGEN) $< +$(srcdir)/$(USER_REFMAN_PDF): $(srcdir)/Doxyfile_user_pdf $(srcdir)/figures.stamp $(EXTRA_DEPS) + $(DOXYGEN) $< \ + && cd $(srcdir)/user/latex \ + && $(MAKE) pdf \ + && cp -f refman.pdf ../../$(USER_REFMAN_PDF) + +# FIXME: Careful, `user-refman-pdf' is a directory, and this make rule +# depends on its timestamp, which is wrong. +USER_REFMAN_HTML = user-refman-html +ref-doc-html: $(srcdir)/$(USER_REFMAN_HTML) +$(srcdir)/$(USER_REFMAN_HTML): $(srcdir)/Doxyfile_user $(srcdir)/figures.stamp $(EXTRA_DEPS) + $(DOXYGEN) $< \ + && rm -fr $(srcdir)/$(USER_REFMAN_HTML) \ + && mv $(srcdir)/user/html $(srcdir)/$(USER_REFMAN_HTML) # Doxygen HTML documentation output directories. -DEVEL_REFMAN_PDF = $(srcdir)/devel/latex/refman.pdf -ref-doc-devel-pdf: $(DEVEL_REFMAN_PDF) +DEVEL_REFMAN_PDF = devel/latex/refman.pdf +ref-doc-devel-pdf: $(srcdir)/$(DEVEL_REFMAN_PDF) # FIXME: Split in two rules: one generating the LaTeX file from the # Doxyfile, and another one generating the PDF from the LaTeX source. # Moreover, the LaTeX to PDF rule could be factored using a suffix # rule (as in LRDE's share/). -$(DEVEL_REFMAN_PDF): $(srcdir)/Doxyfile_devel_pdf $(srcdir)/figures.stamp $(EXTRA_DEPS) +$(srcdir)/$(DEVEL_REFMAN_PDF): $(srcdir)/Doxyfile_devel_pdf $(srcdir)/figures.stamp $(EXTRA_DEPS) $(DOXYGEN) $< cd $(srcdir)/devel/latex && $(MAKE) $(AM_MAKEFLAGS) -DEVEL_REFMAN_HTML = $(srcdir)/devel/html -ref-doc-devel-html: $(DEVEL_REFMAN_HTML) -$(DEVEL_REFMAN_HTML): $(srcdir)/Doxyfile_devel $(srcdir)/figures.stamp $(EXTRA_DEPS) +# FIXME: Careful, `devel/html' is a directory, and this make rule +# depends on its timestamp, which is wrong. +DEVEL_REFMAN_HTML = devel/html +ref-doc-devel-html: $(srcdir)/$(DEVEL_REFMAN_HTML) +$(srcdir)/$(DEVEL_REFMAN_HTML): $(srcdir)/Doxyfile_devel $(srcdir)/figures.stamp $(EXTRA_DEPS) $(DOXYGEN) $< ## ---------- ## @@ -303,10 +311,10 @@ fake-doc: touch $(srcdir)/Doxyfile_user touch $(srcdir)/Doxyfile_user_pdf cd $(srcdir) && test -d user || mkdir user - for d in $(USER_REFMAN_HTML) $(srcdir)/user/latex; do \ + for d in $(srcdir)/$(USER_REFMAN_HTML) $(srcdir)/user/latex; do \ if test -d $$d; then touch $$d; else mkdir $$d; fi; \ done - touch $(USER_REFMAN_PDF) + touch $(srcdir)/$(USER_REFMAN_PDF) # The converse of the previous rule, voiding the timestamps. .PHONY: void-doc diff --git a/milena/doc/ref_guide/Makefile.am b/milena/doc/ref_guide/Makefile.am index d1af059..f13074f 100644 --- a/milena/doc/ref_guide/Makefile.am +++ b/milena/doc/ref_guide/Makefile.am @@ -25,6 +25,29 @@ $(SPLIT_OUTPUTS_SRCDIR):$(IMG_SRCDIR):$(SPLIT_EXAMPLES_SRCDIR):" ref-guide: ref-guide-html ref-guide-pdf +# FIXME: As in milena/doc/Makefile.am, we should probably strip +# $(srcdir) prefixes from target variables, e.g. instead of: +# +# FOO = $(srcdir)/foo.pdf +# $(FOO): foo.tex bar.tex +# dist_doc_DATA = $(FOO) +# +# we should use: +# +# FOO = foo.pdf +# $(srcdir)/$(FOO): foo.tex bar.tex +# dist_doc_DATA = $(FOO) +# +# since it minimizes installation issues (see milena/doc/Makefile.am +# and Vaucanson's doc/Makefile.am). + +# FIXME: Distributed products should be generated in the source dir. +# That's actually the case, *but* the current solution is not clean +# and might break sometimes. The clean approach is to create a +# temporary directory, try to generate the documentation there, and +# move its contents to the source dir in case of success. If the +# product is a directory, also refresh a timestamp (in the source +# dir). # Intermediate product for the various doc targets of the parent # directory. @@ -32,20 +55,22 @@ ref-guide: ref-guide-html ref-guide-pdf # This is not a bug: REF_GUIDE_HH is meant to have a `.hh' # extension, since it is later parsed by Doxygen, which complains # about `.html' files. -REF_GUIDE_HH = ref_guide.hh +REF_GUIDE_HH = $(srcdir)/ref_guide.hh ref-guide-html: $(REF_GUIDE_HH) $(REF_GUIDE_HH): ref_guide.tex $(srcdir)/../figures.stamp $(DOC_SRCDIR)/tools/todoxygen.sh \ - $< $(DOC_SRCDIR)/ref_guide $(DOC_SRCDIR) + $< $(DOC_SRCDIR)/ref_guide $(DOC_SRCDIR) \ + && mv -f ref_guide.hh $(srcdir) # Final product. -REF_GUIDE_PDF = ref_guide.pdf +REF_GUIDE_PDF = $(srcdir)/ref_guide.pdf ref-guide-pdf: $(REF_GUIDE_PDF) $(REF_GUIDE_PDF): ref_guide.tex $(srcdir)/../figures.stamp TEXINPUTS=$(TEXINPUTS) pdflatex $< TEXINPUTS=$(TEXINPUTS) pdflatex $< - TEXINPUTS=$(TEXINPUTS) pdflatex $< + TEXINPUTS=$(TEXINPUTS) pdflatex $< \ + && mv -f ref_guide.pdf $(srcdir) # FIXME: Regenerating figures.stamp requires make to go back to the # parent directory. We already do the opposite (descending from diff --git a/milena/doc/tutorial/Makefile.am b/milena/doc/tutorial/Makefile.am index ea4a84a..5cd7464 100644 --- a/milena/doc/tutorial/Makefile.am +++ b/milena/doc/tutorial/Makefile.am @@ -24,25 +24,51 @@ TEXINPUTS = $(DOC_SRCDIR):$(OUTPUTS_SRCDIR):$(IMG_SRCDIR): tutorial: tutorial-html tutorial-pdf +# FIXME: As in milena/doc/Makefile.am, we should probably strip +# $(srcdir) prefixes from target variables, e.g. instead of: +# +# FOO = $(srcdir)/foo.pdf +# $(FOO): foo.tex bar.tex +# dist_doc_DATA = $(FOO) +# +# we should use: +# +# FOO = foo.pdf +# $(srcdir)/$(FOO): foo.tex bar.tex +# dist_doc_DATA = $(FOO) +# +# since it minimizes installation issues (see milena/doc/Makefile.am +# and Vaucanson's doc/Makefile.am). + +# FIXME: Distributed products should be generated in the source dir. +# That's actually the case, *but* the current solution is not clean +# and might break sometimes. The clean approach is to create a +# temporary directory, try to generate the documentation there, and +# move its contents to the source dir in case of success. If the +# product is a directory, also refresh a timestamp (in the source +# dir). + # Intermediate product for the various doc targets of the parent # directory. # # This is not a bug: TUTORIAL_HH is meant to have a `.hh' extension, # since it is later parsed by Doxygen, which complains about `.html' # files. -TUTORIAL_HH = tutorial.hh +TUTORIAL_HH = $(srcdir)/tutorial.hh tutorial-html: $(TUTORIAL_HH) $(TUTORIAL_HH): tutorial.tex $(srcdir)/../figures.stamp $(DOC_SRCDIR)/tools/todoxygen.sh \ - $< $(DOC_SRCDIR)/tutorial $(DOC_SRCDIR) + $< $(DOC_SRCDIR)/tutorial $(DOC_SRCDIR) \ + && mv tutorial.hh $(srcdir) # Final product. -TUTORIAL_PDF = tutorial.pdf +TUTORIAL_PDF = $(srcdir)/tutorial.pdf tutorial-pdf: $(TUTORIAL_PDF) $(TUTORIAL_PDF): tutorial.tex $(srcdir)/../figures.stamp TEXINPUTS=$(TEXINPUTS) pdflatex $< TEXINPUTS=$(TEXINPUTS) pdflatex $< - TEXINPUTS=$(TEXINPUTS) pdflatex $< + TEXINPUTS=$(TEXINPUTS) pdflatex $< \ + && tutorial.pdf $(srcdir) # FIXME: Regenerating figures.stamp requires make to go back to the # parent directory. We already do the opposite (descending from diff --git a/milena/doc/white_paper/Makefile.am b/milena/doc/white_paper/Makefile.am index 6449bbb..df0a51b 100644 --- a/milena/doc/white_paper/Makefile.am +++ b/milena/doc/white_paper/Makefile.am @@ -38,20 +38,46 @@ EPSS = $(PNGS:png=eps) white-paper: white-paper-pdf white-paper-html -WHITE_PAPER_HTML = white_paper_html/index.html +# FIXME: As in milena/doc/Makefile.am, we should probably strip +# $(srcdir) prefixes from target variables, e.g. instead of: +# +# FOO = $(srcdir)/foo.pdf +# $(FOO): foo.tex bar.tex +# dist_doc_DATA = $(FOO) +# +# we should use: +# +# FOO = foo.pdf +# $(srcdir)/$(FOO): foo.tex bar.tex +# dist_doc_DATA = $(FOO) +# +# since it minimizes installation issues (see milena/doc/Makefile.am +# and Vaucanson's doc/Makefile.am). + +# FIXME: Distributed products should be generated in the source dir. +# That's actually the case, *but* the current solution is not clean +# and might break sometimes. The clean approach is to create a +# temporary directory, try to generate the documentation there, and +# move its contents to the source dir in case of success. If the +# product is a directory, also refresh a timestamp (in the source +# dir). + +WHITE_PAPER_HTML = $(srcdir)/white_paper_html/index.html white-paper-html: $(WHITE_PAPER_HTML) $(WHITE_PAPER_HTML): white_paper.tex $(EPSS) test -d white_paper_html || mkdir white_paper_html TEXINPUTS=$(TEXINPUTS) hevea -O -fix $< -o $@ $(top_srcdir)/milena/doc/tools/clearbanner.sh $@ + mv -f white_paper_html $(srcdir) -WHITE_PAPER_PDF = white_paper.pdf +WHITE_PAPER_PDF = $(srcdir)/white_paper.pdf white-paper-pdf: $(WHITE_PAPER_PDF) $(WHITE_PAPER_PDF): white_paper.tex $(PNGS) TEXINPUTS=$(TEXINPUTS) pdflatex $< TEXINPUTS=$(TEXINPUTS) pdflatex $< - TEXINPUTS=$(TEXINPUTS) pdflatex $< + TEXINPUTS=$(TEXINPUTS) pdflatex $< \ + && mv white_paper.pdf $(srcdir) dist_doc_DATA = \ @@ -76,7 +102,9 @@ clean-local: # Pretend the documentation is up-to-date. .PHONY: fake-doc fake-doc: + test -d figures || mkdir figures touch $(EPSS) + test -d $(srcdir)/white_paper_html || mkdir $(srcdir)/white_paper_html touch $(WHITE_PAPER_HTML) touch $(WHITE_PAPER_PDF) -- 1.6.1.2