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

Note: Building pdf and ps versions of the manual for Japanese and Greek is
      not supported at the moment.
      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

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)

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.


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