9674
|
1 The documentation and its translations reside in subdirectories.
|
|
2 When building the documentation, the toplevel Makefile goes into
|
|
3 the subdirectories listed in the SUBDIRS variable and executes make
|
|
4 in each of those directories to create the HTML documentation
|
11202
|
5 in subdirectories of the 'HTML' and 'HTML-single' directories.
|
9674
|
6
|
11202
|
7 IMPORTANT: Do NOT place sensitive files under 'HTML' or 'HTML-single'!
|
9674
|
8 It is for generated documentation only.
|
|
9 The whole directory tree is wiped out by the Makefile
|
11204
|
10 when running 'make distclean' or 'make clean'.
|
9674
|
11 Also, subdirectories are wiped out one by one before
|
|
12 creating the HTML files.
|
|
13
|
|
14 Each subdirectory must have a Makefile. Its purpose is to include
|
|
15 the toplevel Makefile.inc file (with the rules to build the docs)
|
|
16 and add dependency information to the main target, $(HTMLDIR)/index.html.
|
|
17 The main target usually depends on all the XML and XSL files in the
|
|
18 subdirectory. (Note that the toplevel *.xsl files are added automatically
|
|
19 by Makefile.inc, so you do not have to list them.)
|
|
20
|
|
21
|
|
22 Adding new translations
|
|
23 ~~~~~~~~~~~~~~~~~~~~~~~
|
|
24
|
|
25 1) Create a new subdirectory and copy the XML files there.
|
11199
|
26
|
9674
|
27 2) Make sure to create a 'Makefile' for the translation -- you can
|
|
28 use 'en/Makefile' as an example.
|
11199
|
29
|
9674
|
30 3) Set <book lang="XX"> to your language code if the DocBook XSL
|
|
31 stylesheets support it.
|
11199
|
32
|
9674
|
33 4) If you want to use a customized XSL stylesheet, create one and name it
|
11209
|
34 'html-common.xsl'. Also create two additional XSL stylesheets
|
|
35 ('html-single.xsl' and 'html-chunk.xsl'), with content such as this:
|
11188
|
36
|
11209
|
37 html-single.xsl:
|
11188
|
38
|
|
39 <?xml version="1.0" encoding="ISO-8859-1"?>
|
|
40 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
|
41 version="1.0">
|
|
42
|
11209
|
43 <xsl:import href="../html-single.xsl"/>
|
11188
|
44 <xsl:include href="html-common.xsl"/>
|
9674
|
45
|
11188
|
46 </xsl:stylesheet>
|
|
47
|
|
48 html-chunk.xsl:
|
|
49
|
|
50 <?xml version="1.0" encoding="ISO-8859-1"?>
|
|
51 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|
|
52 version="1.0">
|
|
53
|
|
54 <xsl:import href="../html-chunk.xsl"/>
|
|
55 <xsl:include href="html-common.xsl"/>
|
|
56
|
|
57 </xsl:stylesheet>
|
|
58
|
11132
|
59
|
11145
|
60 Note: You mustn't xsl:include or xsl:import chunk.xsl directly!
|
|
61 Including it can (and will) break building of documentation if chunk.xsl
|
|
62 is installed at a nonstandard location.
|
11199
|
63
|
|
64 5) If you wish to change the output encoding of generated files, create
|
|
65 html-common.xsl as suggested in step 4) and add strings such as these
|
|
66 somewhere between the <xsl:stylesheet ...> and </xsl:stylesheet> tags
|
11188
|
67 (please, pay attention to quotes):
|
9674
|
68
|
10911
|
69 <xsl:param name="chunker.output.encoding" select="'your_encoding'"/>
|
11188
|
70 <xsl:output encoding="your_encoding"/>
|
|
71
|
|
72 Use ru/html-common.xsl as example.
|
11199
|
73
|
10911
|
74 6) If you are using your own HTML stylesheet, edit your Makefile and set
|
11199
|
75 the HTML_STYLESHEET variable to its name. Please, don't call your HTML
|
|
76 stylesheet 'default.css'.
|
|
77
|
10926
|
78 7) In each translated file after the <?xml ... ?> tag you must put a note
|
|
79 like <!-- synced with 1.2 -->, where 1.2 is the revision of corresponding
|
|
80 English file (see comment at the top of file).
|
11199
|
81
|
11051
|
82 8) While your translation isn't finished, you can change USE_SYMLINKS
|
|
83 to "yes" in your Makefile. This will help you testing your translation:
|
15778
|
84 English files will be used instead of untranslated ones, when generating
|
11051
|
85 HTML docs.
|
10926
|
86
|
9674
|
87 That's all, in theory.
|