annotate DOCS/xml/README.maintainers @ 26114:cc7bc19e3166

replace all occurences of "M$" by "Microsoft" because it's what we really meant, and "M$" nickname is quite childish
author gpoirier
date Mon, 03 Mar 2008 12:38:33 +0000
parents 5fe4721562ed
children 5513e1981e0e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
9674
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
1 The documentation and its translations reside in subdirectories.
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
2 When building the documentation, the toplevel Makefile goes into
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
3 the subdirectories listed in the SUBDIRS variable and executes make
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
4 in each of those directories to create the HTML documentation
11202
1470e4dd1a4a Include HTML-single in README's.
wight
parents: 11199
diff changeset
5 in subdirectories of the 'HTML' and 'HTML-single' directories.
9674
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
6
11202
1470e4dd1a4a Include HTML-single in README's.
wight
parents: 11199
diff changeset
7 IMPORTANT: Do NOT place sensitive files under 'HTML' or 'HTML-single'!
9674
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
8 It is for generated documentation only.
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
9 The whole directory tree is wiped out by the Makefile
11204
5c232a30d497 grammar + renamed target
diego
parents: 11202
diff changeset
10 when running 'make distclean' or 'make clean'.
9674
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
11 Also, subdirectories are wiped out one by one before
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
12 creating the HTML files.
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
13
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
14 Each subdirectory must have a Makefile. Its purpose is to include
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
15 the toplevel Makefile.inc file (with the rules to build the docs)
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
16 and add dependency information to the main target, $(HTMLDIR)/index.html.
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
17 The main target usually depends on all the XML and XSL files in the
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
18 subdirectory. (Note that the toplevel *.xsl files are added automatically
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
19 by Makefile.inc, so you do not have to list them.)
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
20
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
21
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
22 Adding new translations
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
23 ~~~~~~~~~~~~~~~~~~~~~~~
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
24
18409
0b8825d823dd Add a note about main.xml.
diego
parents: 15778
diff changeset
25 1) Create a new subdirectory and copy the XML files there. main.xml must not be
0b8825d823dd Add a note about main.xml.
diego
parents: 15778
diff changeset
26 copied, it is autogenerated.
11199
b61680a0b29a Add some whitespace for readability + some wording improvements.
diego
parents: 11188
diff changeset
27
9674
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
28 2) Make sure to create a 'Makefile' for the translation -- you can
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
29 use 'en/Makefile' as an example.
11199
b61680a0b29a Add some whitespace for readability + some wording improvements.
diego
parents: 11188
diff changeset
30
21626
e9736e48523f - there's no <book lang=""> for ages, it's automated
torinthiel
parents: 18409
diff changeset
31 3) If you want to use a customized XSL stylesheet, create one and name it
11209
904f8b9c617c html.xsl -> html-single.xsl
lumag
parents: 11204
diff changeset
32 'html-common.xsl'. Also create two additional XSL stylesheets
904f8b9c617c html.xsl -> html-single.xsl
lumag
parents: 11204
diff changeset
33 ('html-single.xsl' and 'html-chunk.xsl'), with content such as this:
11188
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
34
11209
904f8b9c617c html.xsl -> html-single.xsl
lumag
parents: 11204
diff changeset
35 html-single.xsl:
11188
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
36
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
37 <?xml version="1.0" encoding="ISO-8859-1"?>
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
38 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
39 version="1.0">
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
40
11209
904f8b9c617c html.xsl -> html-single.xsl
lumag
parents: 11204
diff changeset
41 <xsl:import href="../html-single.xsl"/>
11188
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
42 <xsl:include href="html-common.xsl"/>
9674
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
43
11188
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
44 </xsl:stylesheet>
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
45
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
46 html-chunk.xsl:
18409
0b8825d823dd Add a note about main.xml.
diego
parents: 15778
diff changeset
47
11188
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
48 <?xml version="1.0" encoding="ISO-8859-1"?>
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
49 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
50 version="1.0">
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
51
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
52 <xsl:import href="../html-chunk.xsl"/>
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
53 <xsl:include href="html-common.xsl"/>
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
54
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
55 </xsl:stylesheet>
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
56
11132
550c25c57f34 Document, that chunk.xsl mustn't be included directly.
lumag
parents: 11051
diff changeset
57
11145
753395e422d0 wording
diego
parents: 11132
diff changeset
58 Note: You mustn't xsl:include or xsl:import chunk.xsl directly!
753395e422d0 wording
diego
parents: 11132
diff changeset
59 Including it can (and will) break building of documentation if chunk.xsl
753395e422d0 wording
diego
parents: 11132
diff changeset
60 is installed at a nonstandard location.
11199
b61680a0b29a Add some whitespace for readability + some wording improvements.
diego
parents: 11188
diff changeset
61
21626
e9736e48523f - there's no <book lang=""> for ages, it's automated
torinthiel
parents: 18409
diff changeset
62 4) If you wish to change the output encoding of generated files, create
11199
b61680a0b29a Add some whitespace for readability + some wording improvements.
diego
parents: 11188
diff changeset
63 html-common.xsl as suggested in step 4) and add strings such as these
b61680a0b29a Add some whitespace for readability + some wording improvements.
diego
parents: 11188
diff changeset
64 somewhere between the <xsl:stylesheet ...> and </xsl:stylesheet> tags
11188
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
65 (please, pay attention to quotes):
9674
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
66
10911
a2b9b13af73f Update readme's. Remove incorrect bug :)
lumag
parents: 9953
diff changeset
67 <xsl:param name="chunker.output.encoding" select="'your_encoding'"/>
11188
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
68 <xsl:output encoding="your_encoding"/>
6dfed0b2a300 Add support for building all-in-one HTML docs. (Files go to DOCS/HTML-single)
lumag
parents: 11145
diff changeset
69
21626
e9736e48523f - there's no <book lang=""> for ages, it's automated
torinthiel
parents: 18409
diff changeset
70 5) If you are using your own HTML stylesheet, edit your Makefile and set
11199
b61680a0b29a Add some whitespace for readability + some wording improvements.
diego
parents: 11188
diff changeset
71 the HTML_STYLESHEET variable to its name. Please, don't call your HTML
b61680a0b29a Add some whitespace for readability + some wording improvements.
diego
parents: 11188
diff changeset
72 stylesheet 'default.css'.
b61680a0b29a Add some whitespace for readability + some wording improvements.
diego
parents: 11188
diff changeset
73
21626
e9736e48523f - there's no <book lang=""> for ages, it's automated
torinthiel
parents: 18409
diff changeset
74 6) In each translated file after the <?xml ... ?> tag you must put a note
21627
5fe4721562ed CVS -> SVN
torinthiel
parents: 21626
diff changeset
75 like <!-- synced with r2 -->, where 2 is the revision of corresponding
10926
f9e8401ec049 Added a note about "synced with ..." comment.
lumag
parents: 10911
diff changeset
76 English file (see comment at the top of file).
11199
b61680a0b29a Add some whitespace for readability + some wording improvements.
diego
parents: 11188
diff changeset
77
21626
e9736e48523f - there's no <book lang=""> for ages, it's automated
torinthiel
parents: 18409
diff changeset
78 7) While your translation isn't finished, you can change USE_SYMLINKS
11051
5418c410a3da Document USE_SYMLINKS
lumag
parents: 10926
diff changeset
79 to "yes" in your Makefile. This will help you testing your translation:
15778
diego
parents: 11209
diff changeset
80 English files will be used instead of untranslated ones, when generating
11051
5418c410a3da Document USE_SYMLINKS
lumag
parents: 10926
diff changeset
81 HTML docs.
10926
f9e8401ec049 Added a note about "synced with ..." comment.
lumag
parents: 10911
diff changeset
82
9674
461f71ba8af4 XML version of MPlayer's doc
nicolas
parents:
diff changeset
83 That's all, in theory.