manual/doc/building.txt

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 
1	fjpop-guest	24112	This document describes how the scripts in this directory can be used for
2			building the Debian Installer Manual.
3
4			The scripts support building the manual for different architectures, in
5			different languages and in different document types.
6			The currently supported document types are:
7			- html
8			- pdf
9			- ps
10	fjpop-guest	24223	- txt
11	fjpop-guest	24112
12	fjp	40073	Note: Building pdf and ps versions of the manual is not supported for some
13			languages. Reason is that we have not yet figured out how to use the
14			required fonts in the build process.
15	fjpop-guest	24112
16
17	mck-guest	8213	1. Requirements:
18			================
19
20	fjpop-guest	24112	The build dependencies depend on which document types you wish to generate:
21			all : docbook, docbook-xml, docbook-xsl, xsltproc
22			html : (no additional packages required)
23			pdf, ps : openjade, jadetex, docbook-dsssl
24			pdf : gs-common
25	fjpop-guest	24223	txt : w3m
26	mck-guest	8213
27	fjp	40073	For some languages additional packages are needed to build pdf:
28			ko : latex-hangul-ucs-hlatex
29	fjp	46483	ru : cm-super (type1 fonts)
30	fjp	40073
31	fjpop-guest	24112	Note: It's not possible to build the documentation on Woody as packages are
32			required that are not available for Woody.
33			Note: jadetex depends on tetex-bin which unfortunately depends on some X libs,
34			so installing jadetex will pull in a basic X installation.
35			There are several open bugs about this (the oldest over 3 years old, but
36			it seems nobody cares enough to fix it (see #223728).
37	mck-guest	8213
38			2. Included Files:
39			==================
40
41	fjpop-guest	24112	SCRIPTS
42			-------
43			buildone.sh: For given architecture and language builds one set of
44			documentation in .html, .fo (and sometimes .pdf).
45	mck-guest	8213
46	fjpop-guest	24112	build.sh: For each language and architecture calls buildone.sh, moves
47			rendered documentation somewhere and cleans after that.
48
49			clear.sh: Does the actual cleaning.
50
51			In ./templates
52	fjpop-guest	24223	--------------
53	fjpop-guest	24112	install.xml.template: Main xml file used to aggregate various parts into
54			one big whole. This is a bit customized compared to the original
55			(changed SYSTEM entities, hardcode local path to docbook dtd -- broken
56			system xml catalogs?)
57
58			docstruct.ent: Describes physical structure of documentation. Not
59			included directly (because of hardcoded en/ path), but in a form
60			of dynamic.ent (after some path replacing by sed).
61
62			In ./entities
63			-------------
64	mck-guest	8213	common.ent: Contains various entities like &num-of-distrib-packages;
65	fjpop-guest	24112	&debian; &arch-title; ...
66	mck-guest	8213
67			urls.ent: Contains various urls used through the manual.
68
69			dynamic.ent: Generated on-the-fly from the shell script buildone.sh.
70	fjpop-guest	24112	Contains lang and arch specific entities which can't be profiled
71			the usual xml way.
72	mck-guest	8213
73			any other .ent: Location of installation files (kernels, boot disks,
74	fjpop-guest	24112	base tarballs) for various architectures.
75	mck-guest	8213
76	fjpop-guest	24112	In ./stylesheets
77	fjpop-guest	24223	----------------
78	mck-guest	8213	style-common.xsl: Common parameters for xsl transformation.
79
80			style-html.xsl: HTML-specific parameters for xsl transformation.
81
82	fjpop-guest	24112	style-print.dsl: Parameters for dvi transformation.
83
84	mck-guest	8213	style-fo.xsl: FO-specific parameters for xsl transformation.
85	fjpop-guest	24112	(currently unused)
86	mck-guest	8213
87	fjpop-guest	24223	In ./arch-options
88			-----------------
89			A file for each architecture where architecture specific parameters
90			are set.
91
92	mck-guest	8213	3. Building:
93			============
94
95			After you customize build.sh and style-.xsl to suit your needs
96			(esp. various paths), you can run
97
98	fjpop-guest	24112	./buildone.sh <architecture> <language> <format(s)>
99	mck-guest	8213
100	fjpop-guest	24112	to build documentation for one specific architecture and language, and
101			one or more output formats.
102			If you call buildone.sh without any parameters, it will build the html
103			version of the English manual for i386 (equivalent to 'i386 en html').
104			If you specify multiple output formats, you should put quotes around them.
105			Example: ./buildone.sh sparc es "html pdf"
106	mck-guest	8213
107	fjpop-guest	24112	For mass building you can use ./build.sh script.
108	mck-guest	8213
109	fjpop-guest	24112
110	mck-guest	8213	--
111	fjpop-guest	24223	05. December 2004 Frans Pop
112	fjpop-guest	24112	27. January 2004 Miroslav Kure