Include documentation and template for new doc buildlib system

3 files changed, 75 insertions, 3 deletions

diff --git a/README.i18n b/README.i18n
index 7b839b71..04afe2a5 100644
--- a/README.i18n
+++ b/README.i18n
@@ -3,12 +3,35 @@ aptitude: information for translators
 Aptitude uses the standard gettext mechanism for translations.  However,
 there are a few twists that you should be aware of.
 
+  * Documents using po4a -- man page, user's manual
+
+    These documents can be translated and maintained quite simply
+    using po4a.  The po template is doc/po4a/po/aptitude.pot and
+    contains messages associated with all the documents.  If you just
+    wish to translate the man page then focus on the entities from
+    manpage.xml.
+
+    The user's manual is typically supplied in both html form, for
+    offline reading, and text form (README.$LANG), for browsing from
+    the program.  We have set up a makefile system which makes it
+    simple to generate and install the translated documents, see the
+    file doc/xx/Makefile.am to get started.
+
+    All a translator needs to do is provide a po file based on the
+    doc/po4a/po/aptitude.pot template.  Additionally, if translating
+    the user's manual, please also provide screenshots based on those
+    in doc/en/images/.
+
   * External data files.
 
     There are several external data files that you can choose to
     translate: help.txt (online help), help-mine.txt (online help for
-    Minesweeper), and aptitude.xml (user's manual/online manual).
-    aptitude.xml is a large file, but help.txt and help-mine.txt are
+    Minesweeper), and README (user's manual/online manual).
+
+    README is generated using po4a or by translating aptitude.xml
+    manually.  See the previous section for using po4a.
+
+    The online help files, help.txt and help-mine.txt, are
     quite tractable and it is recommended that you translate
     them. (especially help.txt)
 
@@ -22,6 +45,9 @@ there are a few twists that you should be aware of.
 
   * Manpage.
 
+    [This section is old and only applies if you do not wish to use
+     po4a for the man page.]
+
     aptitude has a manpage, and it can be translated; if you choose to
     translate it, your translation should be named aptitude.XX.1
     (replace XX with the language code)
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 3f67de3c..ed22739f 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,6 +1,6 @@
 SUBDIRS=cs de en es fi fr it ja pl po4a
 
-EXTRA_DIST=aptitude-common.xsl aptitude-html.xsl aptitude-man.xsl aptitude-txt.xsl aptitude.css html-to-text
+EXTRA_DIST=aptitude-common.xsl aptitude-html.xsl aptitude-man.xsl aptitude-txt.xsl aptitude.css html-to-text xx/Makefile.am
 
 PO4AFLAGS = --srcdir=$(top_srcdir)/doc --destdir=$(top_builddir)/doc \
 	--package-name='$(PACKAGE)' --package-version='$(PACKAGE_VERSION)' \
diff --git a/doc/xx/Makefile.am b/doc/xx/Makefile.am
new file mode 100644
index 00000000..32d88ddc
--- /dev/null
+++ b/doc/xx/Makefile.am
@@ -0,0 +1,46 @@
+#SUBDIRS = images
+#EXTRA_DIST = 
+
+# Language code.  Example: ja
+LC = xx
+
+# Always include this file which sets up install targets.
+include $(top_srcdir)/buildlib/doc.mk
+# Also include this file if you are using the po4a system.
+include $(top_srcdir)/buildlib/po4a.mk
+
+# Name of the translated README file (user's manual in text format)
+#
+# This file will be accessible from the programs help menu if you
+# also translate "README" to "README.xx" in the program translation.
+#
+# Comment this out if you have not translated the user's manual.
+README = README.xx
+README_encoding = utf-8
+
+# List of images to include in the html output.
+#
+# Most of these are screenshots which you will have to generate
+# yourself.  Some are diagrams translated using po4a and
+# contained in the list PO4A_IMAGES (set by po4a.mk).
+IMAGES := $(wildcard $(srcdir)/images/*.png) $(PO4A_IMAGES)
+
+# Uncomment this to provide your own stylesheet for producing the html
+# output.  Such a stylesheet could, for example, change the output
+# encoding of the html document.
+#DOCBOOK_HTML_XSL = aptitude-html-xx.xsl
+
+# By default the docbook-man target will output all available
+# man pages.  Uncomment this line if you only have the main one
+# translated.
+#DOCBOOK_MANS = aptitude.8
+
+# Specify the desired output formats.
+DOCBOOK_TARGETS = docbook-html docbook-man docbook-readme
+
+# Include this file to setup targets which generate the documents from
+# the translated docbook source.
+include $(top_srcdir)/buildlib/docbook.mk
+
+# Finally, this target ensures that all desired documents get built.
+all-local: docbook-stamp