Mercurial > mplayer.hg
annotate DOCS/xml/README @ 31775:44a63a5a3175
The package list for Debian systems is not specific to the Sarge release.
author | diego |
---|---|
date | Wed, 28 Jul 2010 08:04:42 +0000 |
parents | 7c10f547ce96 |
children | 6a701db99f5b |
rev | line source |
---|---|
9674 | 1 Tools required for building the documentation |
2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
3 | |
11945 | 4 * GNU make 3.80 or later |
9674 | 5 * DocBook 4.1.2 or later |
6 * The DocBook XML DTD (also known as DocBk XML) | |
7 * DocBook XSL stylesheets -- version 1.50.0 or later is recommended. | |
8 | |
9 I am not quite sure which tools work, but I used the following | |
10 ones successfully, so they are required: | |
11 | |
12 * xmllint (part of libxml2) is used for validation. | |
13 * xsltproc (part of libxslt1) is used for transforming XML files into HTML | |
11269 | 14 files. Version 1.0.18 or later is recommended. |
9674 | 15 |
11269 | 16 On Red Hat systems you need the following packages: |
17 libxml2, libxslt, docbook-dtds, docbook-style-xsl | |
10911 | 18 |
31775
44a63a5a3175
The package list for Debian systems is not specific to the Sarge release.
diego
parents:
31470
diff
changeset
|
19 On Debian you will need these packages: |
17759
61e033e4daee
Correct toolchain for building XML docs on Debian Sarge.
diego
parents:
12604
diff
changeset
|
20 docbook-xml, docbook-xsl, xsltproc, libxml2-utils |
10025 | 21 |
9674 | 22 |
10868
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
23 Installing the required tools from source |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
24 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
25 |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
26 1) Download libxslt AND libxml2 packages from |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
27 http://xmlsoft.org/XSLT/downloads.html |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
28 |
11269 | 29 Installing them should be straightforward, execute the usual "./configure" |
10868
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
30 and "make" then "make install" commands. |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
31 |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
32 |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
33 2) Download the docbook-xml package from http://www.oasis-open.org/docbook/xml/ |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
34 Use the newest version. The URL will be something like this: |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
35 |
30990 | 36 http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip |
10868
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
37 |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
38 Extract this package into a directory, enter it, and execute the following |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
39 commands: |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
40 |
30990 | 41 mkdir -p /usr/share/sgml/docbook/dtd/xml/4.2/ |
42 cp -r * /usr/share/sgml/docbook/dtd/xml/4.2/ | |
10868
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
43 |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
44 |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
45 3) Download the docbook-xsl package from |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
46 http://prdownloads.sourceforge.net/docbook/ |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
47 |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
48 Use the newest version. The URL will be something like this: |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
49 |
30990 | 50 http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.62.0.tar.gz |
10868
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
51 |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
52 Extract this package into a directory, enter it, and execute the following |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
53 commands: |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
54 |
30990 | 55 mkdir -p /usr/share/sgml/docbook/stylesheet/xsl/nwalsh |
56 cp -r VERSION common html lib /usr/share/sgml/docbook/stylesheet/xsl/nwalsh | |
10868
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
57 |
74fde9d0cab6
XML tools download and installation instructions
gabucino
parents:
10025
diff
changeset
|
58 |
9674 | 59 Building the documentation |
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
61 | |
11269 | 62 Before trying to build the documentation, run |
9674 | 63 |
30990 | 64 make help |
9674 | 65 |
11269 | 66 to see all available build targets and make your choice. If something goes |
67 wrong, check the Configuration section of the toplevel Makefile and adjust | |
68 the variables. | |
9674 | 69 |
31108
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
70 The documentation and its translations reside in subdirectories. |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
71 When building the documentation, the generated HTML files are |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
72 placed in subdirectories of the 'HTML' directory. |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
73 |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
74 IMPORTANT: Do NOT place sensitive files under 'HTML'! |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
75 It is for generated documentation only. |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
76 The whole directory tree is wiped out by the Makefile |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
77 when running 'make distclean' or 'make clean'. |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
78 |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
79 |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
80 Adding new translations |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
81 ~~~~~~~~~~~~~~~~~~~~~~~ |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
82 |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
83 1) Create a new subdirectory and copy the XML files there. main.xml must not be |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
84 copied, it is autogenerated. |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
85 |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
86 2) In each translated file after the <?xml ... ?> tag you must put a note |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
87 like <!-- synced with r2 -->, where 2 is the revision of corresponding |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
88 English file (see comment at the top of file). |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
89 |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
90 That's all, in theory. |
20cee5a646b3
Merge both XML documentation README files into one.
diego
parents:
30990
diff
changeset
|
91 |
9674 | 92 |
93 A few words about SGML catalog files | |
94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
95 | |
96 As far as I know, the document type declaration in XML files requires | |
11269 | 97 both a public and a system identifier. For example: |
9674 | 98 |
99 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
30990 | 100 "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd"> |
9674 | 101 |
102 where | |
103 | |
30990 | 104 "-//OASIS//DTD DocBook XML V4.1.2//EN" |
9674 | 105 |
106 is the public, and | |
107 | |
30990 | 108 "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd" |
9674 | 109 |
110 is the system identifier. | |
111 | |
112 The problem is that the system identifier is most probably system-dependent. | |
113 To avoid the need to manually fix the system identifiers before building the | |
11269 | 114 documentation, I've decided to use SGML catalogs. If you have your catalogs |
9953 | 115 set up correctly, xmllint and xsltproc will use them to find the DTDs |
9674 | 116 based on the public identifiers. |
117 | |
118 Note that this works only if public identifiers override system identifiers | |
11269 | 119 (i.e. the catalog file must contain 'OVERRIDE YES'). (I had no problem with |
9674 | 120 these on my system, since the Debian people took care of everything. ;-)) |