[cluttermm_tutorial] Port from gnome-doc-utils to yelp-tools
- From: Murray Cumming <murrayc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [cluttermm_tutorial] Port from gnome-doc-utils to yelp-tools
- Date: Thu, 17 Apr 2014 18:51:45 +0000 (UTC)
commit f8b607de90f502d402bf164696046f2a3fe2b5a6
Author: Murray Cumming <murrayc murrayc com>
Date: Thu Apr 17 20:51:36 2014 +0200
Port from gnome-doc-utils to yelp-tools
Makefile.am | 154 +----------------
autogen.sh | 16 ++-
configure.ac | 5 +-
docs/tutorial/{ => C}/figures/actor-box.png | Bin 17917 -> 17917 bytes
docs/tutorial/{ => C}/figures/actor_events.png | Bin 3857 -> 3857 bytes
docs/tutorial/{ => C}/figures/actor_group.png | Bin 5907 -> 5907 bytes
.../{ => C}/figures/actor_transformations.png | Bin 5531 -> 5531 bytes
docs/tutorial/{ => C}/figures/actors.png | Bin 5444 -> 5444 bytes
docs/tutorial/{ => C}/figures/alpha-func.png | Bin 30651 -> 30651 bytes
docs/tutorial/{ => C}/figures/behaviours.png | Bin 3856 -> 3856 bytes
docs/tutorial/{ => C}/figures/custom_actor.png | Bin 4159 -> 4159 bytes
docs/tutorial/{ => C}/figures/custom_container.png | Bin 3874 -> 3874 bytes
docs/tutorial/{ => C}/figures/effects.png | Bin 3857 -> 3857 bytes
docs/tutorial/{ => C}/figures/full_example.png | Bin 422283 -> 422283 bytes
docs/tutorial/{ => C}/figures/path-alpha-func.png | Bin 41123 -> 41123 bytes
docs/tutorial/{ => C}/figures/score.png | Bin 3949 -> 3949 bytes
docs/tutorial/{ => C}/figures/scrolling.png | Bin 3896 -> 3896 bytes
docs/tutorial/{ => C}/figures/stage.png | Bin 3826 -> 3826 bytes
docs/tutorial/{ => C}/figures/stage_widget.png | Bin 5174 -> 5174 bytes
docs/tutorial/{ => C}/figures/timeline.png | Bin 3910 -> 3910 bytes
.../{cluttermm-tut.xml => C/index-in.docbook} | 6 +-
docs/tutorial/Makefile.am | 182 ++++++++++++++++++++
docs/tutorial/docbook_phpwebnotes.xsl | 38 ----
docs/tutorial/insert_example_code.pl | 18 ++-
24 files changed, 218 insertions(+), 201 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index 7591898..5ebf19e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -26,6 +26,9 @@ AUTOMAKE_OPTIONS = subdir-objects
ACLOCAL_AMFLAGS = -I m4 $(ACLOCAL_FLAGS)
DISTCHECK_CONFIGURE_FLAGS = --enable-warnings=fatal
+# yelp-tools seems to need the files to be in a folder with its own Makefile.am.
+SUBDIRS = docs/tutorial
+
noinst_PROGRAMS = \
examples/actor/example \
examples/actor_group/example \
@@ -79,158 +82,7 @@ dist_pkgdata_DATA = \
examples/full_example/images/mikael_hallendal.jpg \
examples/full_example/images/ryan_lortie.jpg
-cluttermm_docdir = $(datadir)/doc/cluttermm-0.9/docs
-tutorialdir = $(cluttermm_docdir)/tutorial/html
-figuresdir = $(cluttermm_docdir)/tutorial/figures
-iconsdir = $(cluttermm_docdir)/tutorial/icons
-
-dist_figures_DATA = \
- docs/tutorial/figures/actor_events.png \
- docs/tutorial/figures/actor_group.png \
- docs/tutorial/figures/actors.png \
- docs/tutorial/figures/actor_transformations.png \
- docs/tutorial/figures/alpha-func.png \
- docs/tutorial/figures/behaviours.png \
- docs/tutorial/figures/custom_actor.png \
- docs/tutorial/figures/custom_container.png \
- docs/tutorial/figures/effects.png \
- docs/tutorial/figures/full_example.png \
- docs/tutorial/figures/path-alpha-func.png \
- docs/tutorial/figures/score.png \
- docs/tutorial/figures/scrolling.png \
- docs/tutorial/figures/stage.png \
- docs/tutorial/figures/stage_widget.png \
- docs/tutorial/figures/timeline.png
-
-dist_icons_DATA = \
- docs/tutorial/icons/caution.png \
- docs/tutorial/icons/home.png \
- docs/tutorial/icons/important.png \
- docs/tutorial/icons/next.png \
- docs/tutorial/icons/note.png \
- docs/tutorial/icons/prev.png \
- docs/tutorial/icons/tip.png \
- docs/tutorial/icons/up.png \
- docs/tutorial/icons/warning.png
-
-web_host = www.openismus.com
-web_path = /home/openismusadmin/openismus.com/documents/cluttermm_tutorial/1.0/
-web_path_docs = $(web_path)docs/
-
-clutter_tut_path = $(web_path_docs)tutorial
-
-rsync_args = -vz --rsh ssh
-
-DOCBOOK_PHPWEBNOTES_TRANSFORM = docs/tutorial/docbook_phpwebnotes.xsl
-
-dist_noinst_DATA = \
- docs/index.html \
- docs/tutorial/README \
- docs/tutorial/cluttermm-tut.xml \
- docs/tutorial/cluttermm-tut-with-examples.xml \
- $(DOCBOOK_PHPWEBNOTES_TRANSFORM) \
- docs/tutorial/insert_example_code.pl \
- docs/tutorial/style.css
-
-EXTRA_DIST = docs/tutorial/html
-
-DOCBOOK_STYLESHEET ?= http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl
-
-# Create a DocBook source file that doesn't have the examples' comments blocks:
-docs/tutorial/cluttermm-tut-with-examples.xml: docs/tutorial/cluttermm-tut.xml
docs/tutorial/insert_example_code.pl
- $(PERL_PATH) $(srcdir)/docs/tutorial/insert_example_code.pl $(srcdir)/examples $< >$@
-
-# The new XML DocBook way:
-XSLTPROC = xsltproc
-XMLLINT = xmllint
-DB2PDF = docbook2pdf
-
-docs/tutorial/html/index.html: docs/tutorial/cluttermm-tut-with-examples.xml
- -rm -rf docs/tutorial/html
- mkdir docs/tutorial/html
- $(XSLTPROC) \
- --param toc.section.depth 1 \
- --stringparam html.stylesheet style.css \
- --stringparam admon.graphics 1 \
- --stringparam admon.graphics.path ../icons/ \
- --stringparam admon.graphics.extension .png \
- --stringparam chunker.output.indent yes \
- --stringparam chunker.output.encoding UTF-8 \
- --stringparam navig.graphics yes \
- --stringparam navig.graphics.extension .png \
- --stringparam navig.graphics.path ../icons/ \
- --stringparam toc.list.type ul \
- --stringparam use.id.as.filename 1 \
- --xinclude --catalogs -o docs/tutorial/html/ \
- $(DOCBOOK_STYLESHEET) $<
-
-validate-original: docs/tutorial/cluttermm-tut.xml
- $(XMLLINT) --xinclude --valid --noout --catalogs $(DOCBOOK_STYLESHEET) $<
-
-validate: docs/tutorial/cluttermm-tut-with-examples.xml
- $(XMLLINT) --xinclude --valid --noout --catalogs $(DOCBOOK_STYLESHEET) $<
-
-post-html: docs/tutorial/html/index.html docs/tutorial/style.css
docs/tutorial/pdf/programming-with-cluttermm.pdf
- rsync $(rsync_args) $(srcdir)/docs/tutorial/figures/*.png $$USER
$(web_host):$(clutter_tut_path)/figures/
- rsync $(rsync_args) $(srcdir)/docs/tutorial/icons/*.png $$USER $(web_host):$(clutter_tut_path)/icons/
- rsync $(rsync_args) -Cr docs/tutorial/html/ $$USER $(web_host):$(clutter_tut_path)/html/
- rsync $(rsync_args) $(srcdir)/docs/tutorial/*.css $$USER $(web_host):$(clutter_tut_path)/html/
- rsync $(rsync_args) -Cr docs/tutorial/pdf/ $$USER $(web_host):$(clutter_tut_path)/pdf/
- rsync $(rsync_args) -Cr $(srcdir)/examples/ --exclude '*/example' $$USER
$(web_host):$(web_path)/examples/
-
-# PDF Generation:
-
-# we need to produce a version with full examples with all of the XIncludes done so that it
-# can processed for PDF
-docs/tutorial/programming-with-cluttermm.xml: docs/tutorial/cluttermm-tut-with-examples.xml
- rm -rf docs/tutorial/html
- mkdir docs/tutorial/html
- $(XMLLINT) --xinclude --postvalid -o $@ $<
-
-# We have to generate the pdf in a subdirectory (e.g. pdf/) because the tutorial
-# specifies the path to the figures as '../figures' so if we build it in this
-# directory, it won't find the images.
-docs/tutorial/pdf/programming-with-cluttermm.pdf: docs/tutorial/programming-with-cluttermm.xml
- $(DB2PDF) --output docs/tutorial/pdf $<
-
-pdf-local: docs/tutorial/pdf/programming-with-cluttermm.pdf
-
-html-local: docs/tutorial/html/index.html
-
-doc-clean:
- -rm -rf docs/tutorial/html docs/tutorial/html_withcomments docs/tutorial/pdf
- -rm -f docs/tutorial/cluttermm-tut-with-examples.xml
-
-clean-local: doc-clean
-
-doc-rebuild: doc-clean html pdf
-
-install-tutorial: docs/tutorial/html/index.html docs/tutorial/style.css
- @$(NORMAL_INSTALL)
- $(mkinstalldirs) $(DESTDIR)$(tutorialdir)
- @dir='$(<D)'; for p in $$dir/*.html ; do \
- f=`echo "$$p" | sed -e 's|^.*/||'`; \
- echo " $(INSTALL_DATA) $$p $(DESTDIR)$(tutorialdir)/$$f"; \
- $(INSTALL_DATA) $$p $(DESTDIR)$(tutorialdir)/$$f; \
- done
- $(INSTALL_DATA) $(srcdir)/docs/tutorial/style.css $(DESTDIR)$(tutorialdir)
-
-uninstall-tutorial: docs/tutorial/html/index.html docs/tutorial/style.css
- @$(NORMAL_UNINSTALL)
- @dir='$(<D)'; for p in $$dir/*.html ; do \
- f="`echo $$p | sed -e 's|^.*/||'`"; \
- echo " rm -f $(DESTDIR)$(tutorialdir)/$$f"; \
- rm -f $(DESTDIR)$(tutorialdir)/$$f; \
- done
- rm -f $(DESTDIR)$(tutorialdir)/style.css
- rm -rf $(DESTDIR)$(tutorialdir)/icons
-
-all-local: html
-install-data-local: install-tutorial
-uninstall-local: uninstall-tutorial
-maintainer-clean-local: doc-clean
-.PHONY: post-html doc-clean doc-rebuild install-tutorial uninstall-tutorial validate validate-original
diff --git a/autogen.sh b/autogen.sh
index bf30b9a..29a0b27 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -14,9 +14,19 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#! /bin/sh -e
test -n "$srcdir" || srcdir=`dirname "$0"`
test -n "$srcdir" || srcdir=.
-set -ex
-autoreconf --install --force "$srcdir"
-"$srcdir/configure" "$@"
+# cluttermm-tutorial depends on the mm-common module. Stop if it's not
+# installed.
+# Also copy files from mm-common to the build/ directory so that things like
+# auto-generating the ChangeLog from the git commit messages on 'make dist' is
+# possible.
+mm-common-prepare --copy --force "$srcdir"
+
+(
+ cd "$srcdir" &&
+ autoreconf --force --install --verbose
+) || exit
+test -n "$NOCONFIGURE" || "$srcdir/configure" "$@"
diff --git a/configure.ac b/configure.ac
index a5f3389..8954fda 100644
--- a/configure.ac
+++ b/configure.ac
@@ -39,5 +39,8 @@ DK_ARG_ENABLE_WARNINGS([TUTORIAL_WXXFLAGS],
[-pedantic -Wall -Wextra -w1 -Wno-non-virtual-dtor -Wno-long-long],
[GLIBMM GTKMM])
-AC_CONFIG_FILES([Makefile])
+YELP_HELP_INIT
+
+AC_CONFIG_FILES([Makefile
+ docs/tutorial/Makefile])
AC_OUTPUT()
diff --git a/docs/tutorial/cluttermm-tut.xml b/docs/tutorial/C/index-in.docbook
similarity index 99%
rename from docs/tutorial/cluttermm-tut.xml
rename to docs/tutorial/C/index-in.docbook
index fadde15..ca0465b 100644
--- a/docs/tutorial/cluttermm-tut.xml
+++ b/docs/tutorial/C/index-in.docbook
@@ -9,7 +9,8 @@
<!ENTITY gtk "<application>GTK+</application>">
<!ENTITY gtkmm "<application>gtkmm</application>">
<!ENTITY url_figures_base "../figures/">
- <!ENTITY url_examples_base "../../../examples/">
+ <!ENTITY url_examples_base "http://git.gnome.org/browse/cluttermm_tutorial/tree/examples/";>
+ <!ENTITY url_examples_branchsuffix "master">
<!ENTITY url_refdocs_base_cluttermm "http://library.gnome.org/devel/cluttermm/unstable/";>
<!ENTITY url_refdocs_base_clutter_gtkmm "http://library.gnome.org/devel/clutter-gtkmm/unstable/";>
]>
@@ -21,7 +22,8 @@ clutter with <application></application> tags which can then be styled by CSS if
boldface, monospace, etc) to make it stand out as the project name
-->
-<book>
+<!-- The XSL for developer.gnome.org requires this id. -->
+<book id="index" lang="en">
<bookinfo>
diff --git a/docs/tutorial/Makefile.am b/docs/tutorial/Makefile.am
new file mode 100644
index 0000000..18f7e3d
--- /dev/null
+++ b/docs/tutorial/Makefile.am
@@ -0,0 +1,182 @@
+## This file is part of cluttermm_tutorial.
+
+ YELP_HELP_RULES@
+
+cluttermm_docdir = $(datadir)/doc/cluttermm-1.0
+
+# Function: $(call vpath_listall,PATTERN ...)
+# Get all filenames which match a PATTERN from the list. Look for files
+# relative to either the current directory or $(srcdir). Strip $(srcdir)/
+# again before returning and remove any duplicates.
+vpath_srclist = $(patsubst $(srcdir)/%,%,$(wildcard $(addprefix $(srcdir)/,$(1))))
+vpath_listall = $(sort $(wildcard $(1)) $(if $(srcdir:.=),$(vpath_srclist)))
+
+DOCBOOK_STYLESHEET_HTML ?= http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl
+XMLLINT = xmllint
+XSLTPROC = xsltproc
+DB2PDF = docbook2pdf
+
+DOCBOOK_STYLESHEET_EPUB ?= http://docbook.sourceforge.net/release/xsl/current/epub/docbook.xsl
+
+HELP_ID = cluttermm-tutorial
+
+HELP_FILES = \
+ index.docbook
+
+HELP_MEDIA = \
+ figures/actor_events.png \
+ figures/actor_group.png \
+ figures/actors.png \
+ figures/actor_transformations.png \
+ figures/alpha-func.png \
+ figures/behaviours.png \
+ figures/custom_actor.png \
+ figures/custom_container.png \
+ figures/effects.png \
+ figures/full_example.png \
+ figures/path-alpha-func.png \
+ figures/score.png \
+ figures/scrolling.png \
+ figures/stage.png \
+ figures/stage_widget.png \
+ figures/timeline.png
+
+HELP_LINGUAS =
+
+
+MAINTAINERCLEANFILES = html/*.html $(srcdir)/html/*.html
+
+# Set the use.id.as.filename param so that we don't use the chapter / section
+# number as the filename, otherwise the url will change every time anything is
+# re-ordered or inserted in the documentation
+xslt_params = $(strip \
+ --param toc.section.depth 1 \
+ --stringparam html.stylesheet 'style.css' \
+ --stringparam admon.graphics '1' \
+ --stringparam admon.graphics.path 'icons/' \
+ --stringparam admon.graphics.extension '.png' \
+ --stringparam chunker.output.indent 'yes' \
+ --stringparam chunker.output.encoding 'UTF-8' \
+ --stringparam navig.graphics 'yes' \
+ --stringparam navig.graphics.extension '.png' \
+ --stringparam navig.graphics.path 'icons/' \
+ --stringparam toc.list.type 'ul' \
+ --stringparam use.id.as.filename '1' \
+ )
+
+tutorialdir = $(cluttermm_docdir)/tutorial
+tutorial_htmldir = $(tutorialdir)/html
+tutorial_figuresdir = $(tutorial_htmldir)/figures
+tutorial_iconsdir = $(tutorial_htmldir)/icons
+
+tutorial_html_files = $(call vpath_listall,html/*.html) style.css
+tutorial_html_inst = $(foreach\
+ file,$(tutorial_html_files),$(or $(wildcard $(file)),$(srcdir)/$(file)))
+
+tutorial_xml_files = $(addsuffix /index.docbook,C $(HELP_LINGUAS))
+tutorial_po_files = $(foreach lang,$(lang)/$(lang).po,$(HELP_LINGUAS))
+
+dist_noinst_DATA = \
+ insert_example_code.pl \
+ C/index-in.docbook \
+ $(tutorial_po_files) \
+ $(tutorial_xml_files) \
+ $(tutorial_html_files)
+
+dist_tutorial_figures_DATA = $(addprefix C/,$(HELP_MEDIA))
+
+dist_tutorial_icons_DATA = \
+ icons/caution.png \
+ icons/home.png \
+ icons/important.png \
+ icons/next.png \
+ icons/note.png \
+ icons/prev.png \
+ icons/tip.png \
+ icons/up.png \
+ icons/warning.png
+
+
+all-local: $(HELP_LINGUAS) $(addsuffix /index.docbook,C $(HELP_LINGUAS)) html/index.html
+
+install-data-local: install-tutorial
+
+uninstall-local: uninstall-tutorial
+
+install-tutorial: html/index.html
+ @$(NORMAL_INSTALL)
+ $(MKDIR_P) '$(DESTDIR)$(tutorial_htmldir)'
+ $(INSTALL_DATA) $(tutorial_html_inst) '$(DESTDIR)$(tutorial_htmldir)/'
+
+uninstall-tutorial:
+ @$(NORMAL_UNINSTALL)
+ rm -f '$(DESTDIR)$(tutorial_htmldir)'/*.html
+ rm -f '$(DESTDIR)$(tutorial_htmldir)/style.css'
+
+$(HELP_LINGUAS):
+ @$(MKDIR_P) $@
+
+# Create a html generation of the C locale's version of the DocBook,
+# using our custom stylesheet and graphics:
+html/index.html: $(srcdir)/C/index.docbook
+ $(AM_V_at)rm -fr html
+ $(AM_V_at)$(MKDIR_P) html
+ $(AM_V_GEN)$(XSLTPROC) $(xslt_params) -o html/ --xinclude --catalogs \
+ '$(DOCBOOK_STYLESHEET_HTML)' $<
+
+# TODO: I'm not sure how useful this output is, or what we can do with it. murrayc.
+epub_via_xsl: $(srcdir)/C/index.docbook
+ $(AM_V_at)rm -fr epub
+ $(AM_V_at)$(MKDIR_P) epub
+ $(AM_V_GEN)$(XSLTPROC) $(xslt_params) -o epub/ --xinclude --catalogs \
+ '$(DOCBOOK_STYLESHEET_EPUB)' $<
+
+# This epub/mobi generation is experimental. murrayc.
+epub: $(srcdir)/cluttermm-tutorial.epub
+
+# Create an epub generation of the C locale's version of the DocBook,
+# using our custom stylesheet and graphics.
+# This apparently uses the XSL stylesheets that we try to use in epub_via_xsl above.
+cluttermm-tutorial.epub: $(srcdir)/C/index.docbook
+ dbtoepub $<
+
+mobi: $(srcdir)/cluttermm-tutorial.mobi
+
+# ebook-convert is provided by the calibre UI app.
+# TODO: Use --cover kindle_cover.jpg when this ImageMagik problem is fixed:
+# Exception: no decode delegate for this image format `' @ error/blob.c/BlobToImage/348
+cluttermm-tutorial.mobi: $(srcdir)/cluttermm-tutorial.epub $(srcdir)/kindle_cover.jpg
+ ebook-convert $< cluttermm-tutorial.mobi --input-profile=kindle
+
+# Make sure that the documentation will always have been generated before
+# executing the commands of a rule that depends on files in html/.
+html/chapter-%.html html/sec-%.html: | html/index.html
+
+# Create a DocBook source file that doesn't have the examples' comments blocks:
+$(srcdir)/C/index.docbook: $(srcdir)/C/index-in.docbook $(srcdir)/insert_example_code.pl
+ $(AM_V_GEN)$(PERL) -- $(srcdir)/insert_example_code.pl $(top_srcdir)/examples $< >$@
+
+validate_original: $(srcdir)/C/index-in.docbook
+ $(XMLLINT) --xinclude --postvalid --noout $<
+
+validate: $(srcdir)/C/index.docbook
+ $(XMLLINT) --xinclude --postvalid --noout $<
+
+# we need to produce a full examples with all of the XIncludes done so that it
+# can be processed for PDF
+C/programming-with-cluttermm-onefile.xml: $(srcdir)/C/index.docbook
+ $(AM_V_at)$(MKDIR_P) C
+ $(AM_V_GEN)$(XMLLINT) --xinclude --postvalid -o $@ $<
+
+# We have to generate the pdf in a subdirectory (e.g. pdf/) because the tutorial
+# specifies the path to the figures as '../figures' so if we build it in this
+# directory, it won't find the images.
+pdf/programming-with-cluttermm-pdf.pdf: C/programming-with-cluttermm-onefile.xml
+ $(AM_V_at)$(MKDIR_P) pdf
+ $(AM_V_GEN)$(DB2PDF) --output pdf/ $<
+
+.PHONY: install-tutorial uninstall-tutorial
+
+# Instruct GNU make to delete the targets of a rule after it failed, in
+# order to avoid the complication of handling that situation manually.
+.DELETE_ON_ERROR:
diff --git a/docs/tutorial/insert_example_code.pl b/docs/tutorial/insert_example_code.pl
index 62e9086..f0f22fe 100755
--- a/docs/tutorial/insert_example_code.pl
+++ b/docs/tutorial/insert_example_code.pl
@@ -12,14 +12,17 @@
while(<FILE>)
{
- print $_;
-
#Beginning of comment:
# Look for
- # <para><ulink url="&url_examples_base;helloworld">Source code</ulink></para>
+ # <para><ulink url="&url_examples_base;helloworld">Source Code</ulink></para>
- if(/<para><ulink url=\"&url_examples_base;([\/\w]+)\">Source [Cc]ode<\/ulink><\/para>/)
+ if(/<para><ulink url=\"&url_examples_base;([\/\w]+)\">Source Code<\/ulink><\/para>/)
{
+ #Modify the line to add the branch, so people see the correct version.
+ #This is particularly important during major API changes every few years,
+ #when the API might no longer even exist in the new version.
+ print "<para><ulink url=\"&url_examples_base;${1}?h=&url_examples_branchsuffix;\">Source
Code<\/ulink><\/para>\n";
+
#List all the source files in that directory:
my $directory = $examples_base . $1;
@@ -34,8 +37,6 @@
foreach $source_file (@header_files, @source_files)
{
- print "<para>File: <filename>${source_file}</filename>\n";
- print "</para>\n";
print "<programlisting>\n";
&process_source_file("${directory}/${source_file}");
@@ -45,6 +46,11 @@
print "<!-- end inserted example code -->\n";
}
+ else
+ {
+ # Just print the line without changes:
+ print $_;
+ }
}
close(FILE);
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
