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

13 Jul 2009

* 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



    