1 files changed, 112 insertions, 0 deletions
diff --git a/doc/building.txt b/doc/building.txt
new file mode 100644
index 000000000..b3f533572
--- /dev/null
+++ b/doc/building.txt
@@ -0,0 +1,112 @@
+This document describes how the scripts in this directory can be used for
+building the Debian Installer Manual.
+
+The scripts support building the manual for different architectures, in
+different languages and in different document types.
+The currently supported document types are:
+- html
+- pdf
+- ps
+- txt
+
+Note: Building pdf and ps versions of the manual is not supported for some
+      languages. Reason is that we have not yet figured out how to use the
+      required fonts in the build process.
+
+
+1. Requirements:
+================
+
+The build dependencies depend on which document types you wish to generate:
+all     : docbook, docbook-xml, docbook-xsl, xsltproc
+html    : (no additional packages required)
+pdf, ps : openjade, jadetex, docbook-dsssl
+pdf     : gs-common
+txt     : w3m
+
+For some languages additional packages are needed to build pdf:
+ko      : latex-hangul-ucs-hlatex
+ru      : cm-super (type1 fonts)
+
+Note: It's not possible to build the documentation on Woody as packages are
+      required that are not available for Woody.
+Note: jadetex depends on tetex-bin which unfortunately depends on some X libs,
+      so installing jadetex will pull in a basic X installation.
+      There are several open bugs about this (the oldest over 3 years old, but
+      it seems nobody cares enough to fix it (see #223728).
+
+2. Included Files:
+==================
+
+SCRIPTS
+-------
+buildone.sh: For given architecture and language builds one set of
+    documentation in .html, .fo (and sometimes .pdf).
+
+build.sh: For each language and architecture calls buildone.sh, moves
+    rendered documentation somewhere and cleans after that.
+
+clear.sh: Does the actual cleaning.
+
+In ./templates
+--------------
+install.xml.template: Main xml file used to aggregate various parts into
+    one big whole. This is a bit customized compared to the original
+    (changed SYSTEM entities, hardcode local path to docbook dtd -- broken
+    system xml catalogs?)
+
+docstruct.ent: Describes physical structure of documentation. Not
+    included directly (because of hardcoded en/ path), but in a form
+    of dynamic.ent (after some path replacing by sed).
+
+In ./entities
+-------------
+common.ent: Contains various entities like &num-of-distrib-packages;
+    &debian; &arch-title; ...
+
+urls.ent: Contains various urls used through the manual.
+
+dynamic.ent: Generated on-the-fly from the shell script buildone.sh.
+    Contains lang and arch specific entities which can't be profiled
+    the usual xml way.
+
+any other .ent: Location of installation files (kernels, boot disks,
+    base tarballs) for various architectures.
+
+In ./stylesheets
+----------------
+style-common.xsl: Common parameters for xsl transformation.
+
+style-html.xsl: HTML-specific parameters for xsl transformation.
+
+style-print.dsl: Parameters for dvi transformation.
+
+style-fo.xsl: FO-specific parameters for xsl transformation.
+    (currently unused)
+
+In ./arch-options
+-----------------
+A file for each architecture where architecture specific parameters
+are set.
+
+3. Building:
+============
+
+After you customize build*.sh and style-*.xsl to suit your needs
+(esp. various paths), you can run
+
+ ./buildone.sh <architecture> <language> <format(s)>
+
+to build documentation for one specific architecture and language, and
+one or more output formats.
+If you call buildone.sh without any parameters, it will build the html
+version of the English manual for i386 (equivalent to 'i386 en html').
+If you specify multiple output formats, you should put quotes around them.
+Example: ./buildone.sh sparc es "html pdf"
+
+For mass building you can use ./build.sh script.
+
+
+-- 
+05. December 2004 Frans Pop
+27. January 2004  Miroslav Kure