[nautilus-actions] Distribute HTML version of user's manuals
- From: Pierre Wieser <pwieser src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [nautilus-actions] Distribute HTML version of user's manuals
- Date: Wed, 15 Feb 2017 23:00:18 +0000 (UTC)
commit dcf551028f131ffbd57fbfd86a3594931dce7ee7
Author: Pierre Wieser <pwieser trychlos org>
Date: Fri Sep 18 13:59:54 2015 +0200
Distribute HTML version of user's manuals
docs/manual/Makefile.am | 437 +++++++++++++++++++++++++++++++++++++++++++++-
m4/fma-enable-manuals.m4 | 15 --
2 files changed, 430 insertions(+), 22 deletions(-)
---
diff --git a/docs/manual/Makefile.am b/docs/manual/Makefile.am
index 736baf1..be5413f 100644
--- a/docs/manual/Makefile.am
+++ b/docs/manual/Makefile.am
@@ -51,9 +51,7 @@
# to correctly generate POT files (cf. mail of Claude Paroz 2010-08-29
# http://mail.gnome.org/archives/gnome-i18n/2010-August/msg00229.html).
-#include $(srcdir)/gnome-doc-utils-na.make
include $(top_srcdir)/gnome-doc-utils.make
-dist-hook: omf-dist-hook doc-dist-hook
DOC_MODULE = fma-config-tool
@@ -139,10 +137,435 @@ DOC_FIGURES = \
#DOC_LINGUAS = $(patsubst $(srcdir)/%,%,$(shell find $(srcdir) -mindepth 1 -maxdepth 1 -type d | $(GREP) -v
$(srcdir)/C))
DOC_LINGUAS = de el es fr sl
-# Rationale: standard gnome-doc-utils.make only distributes .omf.in
-# we add here all generated .omf
+# doc-dist-hook is the dist hook provided by gnome-doc-utils.make
+# it distributes both C (original) and generated (translated) .xml files,
+# but not generated .omf files
+dist-hook: omf-dist-hook doc-dist-hook manuals-dist-hook
+
+# Distributing .omf files is required if we want the user be able to
+# get rid of gnome-doc-utils
omf-dist-hook:
- manualbuilddir=`cd $(builddir); pwd`; \
- for omf in `ls -1 $$manualbuilddir/*.omf`; do \
- $(INSTALL_DATA) -v $$omf $(distdir)/; \
+ @for lc in C $(DOC_LINGUAS); do \
+ omf="$(DOC_MODULE)-$$lc.omf"; \
+ if test -f $(builddir)/$$omf; then d=$(builddir); \
+ elif test -f $(srcdir)/$$lc/$$omf; then d=$(srcdir)/$$lc; fi; \
+ if test -f "$$d/$$omf"; then \
+ if test "$(opt_verbose)" = ""; then echo " Distributing $$omf"; fi; \
+ $(MKDIR_P) $(distdir)/$$lc; \
+ cmd="cp $$d/$$omf $(distdir)/$$lc/"; eval $$cmd; \
+ if test "$(opt_verbose)" != ""; then echo $$cmd; fi; \
+ fi; \
+ done
+
+# gnome-doc-utils doesn't provide by itself html nor pdf targets
+# generate these formats here
+
+# set to '-v' to be verbose (much verbose!)
+#opt_verbose =
+opt_verbose = -v
+
+pkgdocdir = $(datarootdir)/doc/@PACKAGE@-@VERSION@
+
+all-local: all-manuals
+
+#all-manuals: install-C-xml all-html-manuals all-pdf-manuals
+all-manuals: install-C-xml all-html-manuals
+
+# this install-data-local target below is executed after the
+# gnome-doc-utils.make install-data-local target (and this is an
+# unexpected, though welcome, behavior)
+install-data-local: install-manuals
+
+#install-manuals: install-html-manuals install-pdf-manuals
+install-manuals: install-html-manuals
+
+#uninstall-local: uninstall-manuals
+uninstall-doc-html: uninstall-manuals
+
+uninstall-manuals: uninstall-html-manuals uninstall-pdf-manuals
+
+#manuals-dist-hook: html-manuals-dist-hook pdf-manuals-dist-hook
+manuals-dist-hook: html-manuals-dist-hook
+
+# when building the manuals, C source files are in srcdir, while all
+# other xml files are in builddir - installing C xml sources in builddir
+# so that all rules apply
+install-C-xml:
+ @if ! test -f C/$(DOC_MODULE).xml; then \
+ echo "Installing C xml source files in $(abs_builddir)"; \
+ $(MKDIR_P) C; cp -v $(srcdir)/C/*.xml C/; \
+ fi
+
+remove-C-xml:
+ @echo "Removing C xml source files from $(abs_builddir)"
+ @if test "$(abs_srcdir)" != "$(abs_builddir)"; then \
+ rm -vf C/*.xml; \
+ fi
+
+# _DOC_LC_DOCS is the list of the translated (not C) DOC_MODULE.xml files
+# we so are sure that they exist and are up to date
+# (path is .po ->[msgfmt]-> .mo ->[xml2po]-> .xml)
+MANUALS_XML = C/$(DOC_MODULE).xml $(_DOC_LC_DOCS)
+MAINTAINERCLEANFILES =
+
+# Build HTML manuals as $(builddir)/<lang>/<module>.html
+#
+# We have two alternative for generating HTML manual:
+# - gnome-doc-tool (from gnome-doc-utils package)
+# - db2html (from docbook-utils package)
+# The actual tool to be used may be specified as an argument of
+# --enable-html-manuals configure option. It defaults to gnome-doc-tool.
+#
+# gnome-doc-tool <format> -o <dir> -d0 nautilus-actions-config-tool.xml
+# - format: output format (html)
+# - dir: output directory
+# -d0: nochunks
+#
+# The produced output is very close of what Yelp gives, with in particular
+# a summary in each chapter while db2html does not produce it.
+#
+# As of v 0.20.1:
+# - does not produce the legal and abstract sections in top of the document
+# - does not honor external links: they are converted to simple links
+# which target the same frame window.
+# - embeds references to 'admon-xxx' images (which are the equivalent
+# of db2html's 'stylesheet-images' ones), but does not provide them
+# (see https://bugzilla.gnome.org/show_bug.cgi?id=636175)
+# and so we 'manually' copy them as a "admon/" subdirectory
+# the same way db2html does
+# - does not honor the base directory of the source document, only
+# searching for extern entities in the current working directory
+# (see https://bugzilla.gnome.org/show_bug.cgi?id=664784)
+#
+# gnome-doc-tool is so our preferred tool for its proximity with Yelp
+# and the summary in top of the chapters.
+#
+# db2html --nochunks nautilus-actions-config-tool.xml
+# Generate the html document(s).
+#
+# As of 0.6.14.29:
+# - does produce the legal and abstract sections in top of the document
+# - creates a stylesheet-images/ subdirectory
+# - does not honor external links: they are converted to simple links
+# which target the same frame window
+# - may create docbook2html-dir(.junk) subdirectories when it is run
+# without argument
+# (see https://bugzilla.redhat.com/show_bug.cgi?id=756930)
+# - begins by emptying the target directory, even if it also contains
+# the source file
+#
+# When building HTML and PDF formats from XML sources, note that the
+# .xml documents default to be read from <srcdir> for the C version,
+# and from <builddir> for translated ones.
+
+MANUALS_HTML = $(MANUALS_XML:%.xml=%.html)
+MAINTAINERCLEANFILES += $(MANUALS_HTML)
+
+all-html-manuals: $(MANUALS_HTML)
+
+# The rule here is: only rebuild html/ files if corresponding xml has changed
+# .xml themselves are distributed, so are not modified when building from a
+# distributed package.
+
+$(MANUALS_HTML): %.html: %.xml
+ @ftarget=$@; \
+ if test "$(opt_verbose)" = ""; then echo " HTML $$ftarget building..."; fi; \
+ lc=$${ftarget%/*}; \
+ if test "x$(WITH_DB2HTML)" = "xyes"; then $(call exec_db2html,$$lc); fi; \
+ if test "x$(WITH_GDT)" = "xyes"; then $(call exec_g_d_t,$$lc); fi; \
+ if test "$(opt_verbose)" = ""; then echo " HTML $$ftarget done"; fi
+
+# execute gnome-doc-tool
+# install admon/ images now to keep consistent with db2html which
+# installs its stylesheet-images/ at build time
+# as a result, admon/stylesheet images will be copied once for each
+# language, instead of begin symlinked (a small inconvenience)
+# 1. locale
+exec_g_d_t = \
+ fxml=$(DOC_MODULE).xml; \
+ (cd $(1); \
+ cmd="gnome-doc-tool html -o . -d0 $$fxml"; \
+ if test "$(opt_verbose)" != ""; then echo "$$cmd"; fi; \
+ eval $$cmd >/dev/null; \
+ fhtml=$(DOC_MODULE).html; \
+ if test -f $$fhtml; then \
+ sed -i -e 's?url("admon?url("admon/admon?' $$fhtml; \
+ admon_dir=/usr/share/gnome-doc-utils/icons/hicolor/48x48/status; \
+ if test -d $$admon_dir; then \
+ $(MKDIR_P) -m 0775 admon; \
+ cmd="cp $(opt_verbose) $$admon_dir/*.png admon/"; eval $$cmd; \
+ fi; \
+ fi; \
+ )
+
+# execute db2html
+# 1. locale
+exec_db2html = \
+ cddir="$(1)"; \
+ output="."; \
+ fxml=$(DOC_MODULE).xml; \
+ cmd="(cd $$cddir && db2html --output $$output --nochunks $$fxml)"; \
+ if test "$(opt_verbose)" != ""; then echo "$$cmd"; fi; \
+ eval $$cmd >/dev/null; \
+ find . -type d -name '*.junk' | xargs rm -fr
+
+# Install HTML manuals in <htmldir>/<lang>/fmact/ subdirectory;
+# where <htmldir> defaults to <pkgdocdir>/html
+# Note: we do honor here --htmldir autotools configuration option.
+# Manuals may be installed from builddir, if they just have been built,
+# or from srcdir, if they were not built but come from distribution.
+
+install-html-manuals:
+ @if test "x$(htmldir)" = "x$(docdir)"; then \
+ _instd="$(DESTDIR)$(pkgdocdir)/html"; \
+ else \
+ _instd="$(DESTDIR)$(htmldir)"; \
+ fi; \
+ echo " Installing in $$_instd ..."; \
+ for lc in C $(DOC_LINGUAS); do \
+ _instdir="$$_instd/$$lc/fmact"; \
+ if test -f "$(builddir)/$$lc/$(DOC_MODULE).html"; then \
+ d="$(builddir)"; \
+ elif test -f "$(srcdir)/$$lc/$(DOC_MODULE).html"; then \
+ d="$(srcdir)"; \
+ fi; \
+ if test -f "$$d/$$lc/$(DOC_MODULE).html"; then \
+ $(call install_html_doc,$$d,$$lc,$$_instdir); \
+ $(call install_html_images,$$d,$$lc,$$_instdir,"stylesheet-images"); \
+ $(call install_html_images,$$d,$$lc,$$_instdir,"admon"); \
+ $(call install_html_figs,$$d,$$lc,$$_instdir); \
+ fi; \
+ done
+
+# installing html document
+# 1: source dir
+# 2: locale
+# 3: target dir
+install_html_doc = \
+ if test "$(opt_verbose)" = ""; then echo " $(2)/fmact/$(DOC_MODULE).html"; fi; \
+ $(MKDIR_P) $(3); \
+ cp -p $(opt_verbose) "$(1)/$(2)/$(DOC_MODULE).html" $(3)/
+
+# installing html images
+# 1: source dir
+# 2: locale
+# 3: target dir
+# 4: stylesheet-images or admon
+install_html_images = \
+ if grep -lq $(4) "$(1)/$(2)/$(DOC_MODULE).html"; then \
+ if test -d "$(1)/$(2)/$(4)"; then \
+ if test "$(opt_verbose)" = ""; then echo " $(2)/fmact/$(4)"; fi; \
+ cmd="cp -rp $(opt_verbose) \"$(1)/$(2)/$(4)\" $(3)/"; eval $$cmd; \
+ chmod -R u+w $(3); \
+ if test "$(opt_verbose)" != ""; then echo $$cmd; fi; \
+ fi; \
+ fi
+
+# installing user's manual figures
+# rebuilding list of figures here because I'm unable to pass it as a parameter
+# (it comes here as a single string in which I cannot walk through)
+# 1: source dir
+# 2: locale
+# 3: target dir
+install_html_figs = \
+ if test "$(opt_verbose)" = ""; then echo " $(2)/fmact/figures"; fi; \
+ figdir="$(3)/figures"; \
+ if ! test -d "$$figdir"; then $(MKDIR_P) "$$figdir"; fi; \
+ for fig in $(DOC_FIGURES); do \
+ figsrc=$(srcdir)/$(2)/$$fig; \
+ if test -f $${figsrc} -a ! -h $${figsrc}; then \
+ cmd="$(INSTALL_DATA) $${figsrc} $${figdir}/"; \
+ else \
+ cmd="(cd $${figdir} && $(LN_S) -f ../../../C/fmact/$$fig)"; \
+ fi; \
+ if test "$(opt_verbose)" != ""; then echo $$cmd; fi; \
+ eval $$cmd; \
+ done
+
+uninstall-html-manuals:
+ @if test "x$(htmldir)" = "x$(docdir)"; then \
+ _instdir="$(DESTDIR)$(pkgdocdir)/html"; \
+ else \
+ _instdir="$(DESTDIR)$(htmldir)"; \
+ fi; \
+ if test -d $$_instdir; then \
+ chmod -R u+w $$_instdir; \
+ find $$_instdir -type d -name 'admon' | xargs rm -fr $(opt_verbose); \
+ find $$_instdir -type d -name 'figures' | xargs rm -fr $(opt_verbose); \
+ find $$_instdir -type d -name 'stylesheet-images' | xargs rm -fr $(opt_verbose); \
+ find $$_instdir -type f -name '*.html' | xargs rm -f $(opt_verbose); \
+ find $$_instdir -type d | sort -r | xargs rmdir $(opt_verbose); \
+ fi
+
+# locale figures (_DOC_LC_FIGURES) are distributed by gnome-doc-utils
+# when they exist
+# - distribute admon/ or stylesheet-images/ icons
+# - distribute *.html manuals
+
+html-manuals-dist-hook:
+ @for lc in C $(DOC_LINGUAS); do \
+ if test -f "$(builddir)/$$lc/$(DOC_MODULE).html"; then d=$(builddir); \
+ elif test -f "$(srcdir)/$$lc/$(DOC_MODULE).html"; then d=$(srcdir); fi; \
+ if test -f "$$d/$$lc/$(DOC_MODULE).html"; then \
+ if test "$(opt_verbose)" = ""; then echo " Distributing $$lc/$(DOC_MODULE).html";
fi; \
+ cmd="cp $(opt_verbose) $$d/$$lc/$(DOC_MODULE).html $(distdir)/$$lc/"; eval $$cmd; \
+ $(call dist_html_images,$$d,$$lc,"stylesheet-images"); \
+ $(call dist_html_images,$$d,$$lc,"admon"); \
+ fi; \
+ done
+
+# distribute html images
+# 1. source dir
+# 2. locale
+# 3. image type (stylesheet-images or admon)
+dist_html_images = \
+ if grep -lq $(3) "$(1)/$(2)/$(DOC_MODULE).html"; then \
+ if test -d "$(1)/$(2)/$(3)"; then \
+ if test "$(opt_verbose)" = ""; then echo " Distributing $(2)/$(3)"; fi; \
+ cmd="cp -rp $(opt_verbose) \"$(1)/$(2)/$(3)\" $(distdir)/$(2)/"; eval $$cmd; \
+ fi; \
+ fi
+
+# Build pdf manuals as $(srcdir)/<lang>/<module>.pdf
+#
+# The rule here is: only rebuild .pdf files if corresponding xml has changed
+# .xml themselves are distributed, so are not modified when compiling from a
+# distribution
+#
+# We only use dblatex for now
+
+MANUALS_PDF = $(MANUALS_XML:%.xml=%.pdf)
+
+MAINTAINERCLEANFILES += $(MANUALS_PDF)
+
+all-pdf-manuals: $(MANUALS_PDF)
+
+# workaround against l10n bug #664768
+# pdflatex cannot generate some localized pdf
+#
+# As of dblatex 0.3.3:
+# - always create the output pdf in the same directory that the
+# source xml
+# (but we need to cd $$lc to mkdir figures)
+
+$(MANUALS_PDF): %.pdf: %.xml
+ @ftarget=$@; \
+ if test "$(opt_verbose)" = ""; then echo " PDF $$ftarget building..."; fi; \
+ lc=$${ftarget%/*}; \
+ list='$(DOC_FIGURES)'; \
+ (cd $$lc; \
+ $(MKDIR_P) figures; \
+ for fig in $$list; do \
+ if test -f "$(srcdir)/$$lc/$$fig"; then d=$$lc; else d="C"; fi; \
+ cmd="(cd figures && $(LN_S) -f $(srcdir)/$$d/$$fig)"; eval $$cmd; \
+ done; \
+ cmd="dblatex $(DOC_MODULE).xml"; eval $$cmd >/dev/null; \
+ if ! test -f $(DOC_MODULE).pdf; then \
+ echo " PDF $$ftarget recovering from dblatex error..."; \
+ tmpdir=`dblatex -d $(DOC_MODULE).xml 2>&1 | grep 'not removed' | awk '{ print $$1 }'`; \
+ cp $$tmpdir/$(DOC_MODULE).pdf . || :; \
+ rm -fr $$tmpdir; \
+ fi; \
+ for fig in $$list; do \
+ if test -h figures/$$fig; then rm -f figures/$$fig; fi; \
+ done; \
+ ); \
+ if test "$(opt_verbose)" = ""; then \
+ if test -f $$lc/$(DOC_MODULE).pdf; then \
+ echo " PDF $$ftarget done"; \
+ else \
+ echo " PDF unable to build $$ftarget"; \
+ fi; \
+ fi
+
+# if --pdfdir has not been specified, then we default to PKGDOCDIR/pdf
+# in all case, we append the locale as a subdirectory level
+#
+# as pdf are monobloc documents, we do not create a per-document subdir
+
+install-pdf-manuals:
+ @if test "$(pdfdir)" = "$(docdir)"; then \
+ _instdir=$(DESTDIR)$(pkgdocdir)/pdf; \
+ else \
+ _instdir=$(DESTDIR)$(pdfdir); \
+ fi; \
+ echo " Installing in $$_instdir ... "; \
+ for lc in C $(DOC_LINGUAS); do \
+ if test -f $(srcdir)/$$lc/$(DOC_MODULE).pdf; then d=$(srcdir); fi; \
+ if test -f $(builddir)/$$lc/$(DOC_MODULE).pdf; then d=$(builddir); fi; \
+ if test -f $$d/$$lc/$(DOC_MODULE).pdf; then \
+ if test "$(opt_verbose)" = ""; then echo " $$lc/$(DOC_MODULE).pdf"; fi; \
+ if ! test -d $$_instdir/$$lc; then cmd="$(MKDIR_P) $$_instdir/$$lc"; eval $$cmd; fi; \
+ cmd="$(INSTALL_DATA) \"$$d/$$lc/$(DOC_MODULE).pdf\" \"$$_instdir/$$lc/\""; eval
$$cmd; \
+ if test "$(opt_verbose)" != ""; then echo $$cmd; fi; \
+ fi; \
+ done
+
+uninstall-pdf-manuals:
+ @if test "$(pdfdir)" = "$(docdir)"; then \
+ _instdir=$(DESTDIR)$(pkgdocdir)/pdf; \
+ else \
+ _instdir=$(DESTDIR)$(pdfdir); \
+ fi; \
+ if test -d $$_instdir; then \
+ chmod -R u+w $$_instdir; \
+ find $$_instdir -name '*.pdf' | xargs rm -f $(opt_verbose); \
+ find $$_instdir -type d | sort -r | xargs rmdir $(opt_verbose); \
+ fi
+
+pdf-manuals-dist-hook:
+ @for lc in C $(DOC_LINGUAS); do \
+ if test -f $(builddir)/$$lc/$(DOC_MODULE).pdf; then d=$(builddir); \
+ elif test -f $(srcdir)/$$lc/$(DOC_MODULE).pdf; then d=$(srcdir); fi; \
+ if test -f "$$d/$$lc/$(DOC_MODULE).pdf"; then \
+ if test "$(opt_verbose)" = ""; then echo " Distributing $$lc/$(DOC_MODULE).pdf"; fi;
\
+ cmd="cp $$d/$$lc/$(DOC_MODULE).pdf $(distdir)/$$lc/"; eval $$cmd; \
+ if test "$(opt_verbose)" != ""; then echo $$cmd; fi; \
+ fi; \
+ done
+
+# According to GNU Make manual (ยง 13 What Gets Cleaned):
+#
+# - mostlyclean deletes files we typically want to rebuild
+# - clean deletes other files built with make
+# - distclean deletes files built by configure (none here)
+##
+## None of these target should delete any distributed file
+##
+# - maintainer-clean should delete other files
+clean-local: remove-C-xml
+ rm -f *~
+ rm -f *.stamp
+ for lc in C $(DOC_LINGUAS); do \
+ (cd $$lc; \
+ find figures -type l | xargs rm -f; \
+ rmdir figures 2>/dev/null || :; \
+ ); \
done
+
+distclean-local: distclean-html distclean-pdf
+
+distclean-html:
+
+distclean-pdf:
+
+maintainer-clean-local: maintainer-clean-html maintainer-clean-pdf
+
+maintainer-clean-html:
+ find $(srcdir) -type d -name 'admon' | xargs rm -fr
+ find $(builddir) -type l -name 'admon' | xargs rm -f
+ find $(srcdir) -type d -name 'stylesheet-images' | xargs rm -fr
+ find $(builddir) -type d -name 'stylesheet-images' | xargs rm -fr
+
+maintainer-clean-pdf:
+
+# we have to override gnome-doc-utils.make:clean-doc-dir recipe
+# as it tries to remove directories which are not empty as we have
+# not yet deleted the files we putted on
+clean-doc-dir:
+ @:
+
+.PHONY: \
+ all-manuals install-manuals uninstall-manuals dist-manuals-hook \
+ all-html-manuals install-html-manuals uninstall-html-manuals dist-html-manuals-hook \
+ all-pdf-manuals install-pdf-manuals uninstall-pdf-manuals dist-pdf-manuals-hook
diff --git a/m4/fma-enable-manuals.m4 b/m4/fma-enable-manuals.m4
index ca270ae..30fc7bc 100644
--- a/m4/fma-enable-manuals.m4
+++ b/m4/fma-enable-manuals.m4
@@ -50,9 +50,6 @@ AC_DEFUN([FMA_ENABLE_MANUALS],[
_CHECK_FOR_HTML_MANUALS
_CHECK_FOR_PDF_MANUALS
-
- AM_CONDITIONAL([ENABLE_MANUALS],
- [test "x${enable_html_manuals}" != "xno" || test "x${enable_pdf_manuals}" != "xno"])
])
AC_DEFUN([_AC_ARG_FMA_ENABLE_HTML_MANUALS],[
@@ -99,8 +96,6 @@ AC_DEFUN([_CHECK_FOR_HTML_MANUALS],[
AC_SUBST([WITH_DB2HTML],[${with_db2html}])
AC_SUBST([WITH_GDT],[${with_gdt}])
-
- AM_CONDITIONAL([ENABLE_HTML_MANUALS], [test "x${enable_html_manuals}" != "xno"])
])
AC_DEFUN([_AC_ARG_FMA_ENABLE_PDF_MANUALS],[
@@ -111,14 +106,6 @@ AC_DEFUN([_AC_ARG_FMA_ENABLE_PDF_MANUALS],[
[build PDF user's manuals @<:@dblatex@:>@]),
[enable_pdf_manuals=$enableval],
[enable_pdf_manuals="no"])
- dnl
- dnl Check for dblatex/fop (for pdf output)
- dnl from https://github.com/GNOME/gtk-doc/blob/master/configure.ac
- dnl
- AC_PATH_PROG([DBLATEX], [dblatex])
- if test -z "$DBLATEX"; then
- AC_MSG_WARN([dblatex not found, so no pdf output from xml])
- fi
])
AC_DEFUN([_CHECK_FOR_PDF_MANUALS],[
@@ -141,6 +128,4 @@ AC_DEFUN([_CHECK_FOR_PDF_MANUALS],[
AC_MSG_ERROR([dblatex has not been found, unable to generate PDF manuals])
fi
fi
-
- AM_CONDITIONAL([ENABLE_PDF_MANUALS], [test "x${enable_pdf_manuals}" != "xno"])
])
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
