1
0
mirror of https://github.com/mpv-player/mpv synced 2024-12-12 18:06:18 +00:00
mpv/DOCS/xml
Uoti Urpala 685bbb5734 DOCS/xml/en: remove various outdated documentation
The XML documentation was badly outdated, with various obsolete,
useless and and sometimes actively harmful advice. Delete a lot of the
obsolete stuff, without spending much effort to replace it for now.

In the FAQ section I removed some questions completely; in other cases
I only removed the answer if I thought the entry might be worth
keeping but the answer would need to be updated.
2011-02-15 12:08:16 +02:00
..
cs DOCS/xml: don't use old "--with-extralibdir" configure option 2011-01-31 16:03:09 +02:00
de DOCS/xml: don't use old "--with-extralibdir" configure option 2011-01-31 16:03:09 +02:00
en DOCS/xml/en: remove various outdated documentation 2011-02-15 12:08:16 +02:00
es libfaad2:/ Remove forked internal libfaad2 copy 2011-01-31 16:00:58 +02:00
fr DOCS/xml: don't use old "--with-extralibdir" configure option 2011-01-31 16:03:09 +02:00
hu DOCS/xml: don't use old "--with-extralibdir" configure option 2011-01-31 16:03:09 +02:00
it libfaad2:/ Remove forked internal libfaad2 copy 2011-01-31 16:00:58 +02:00
pl DOCS/xml: don't use old "--with-extralibdir" configure option 2011-01-31 16:03:09 +02:00
ru DOCS/xml: don't use old "--with-extralibdir" configure option 2011-01-31 16:03:09 +02:00
xsl the great MPlayer tab removal: part I 2010-04-12 10:56:17 +00:00
zh_CN DOCS/xml: edit TV/radio chapters 2010-11-02 04:15:49 +02:00
configure DOCS/xml/configure: misc changes 2010-11-02 04:14:46 +02:00
default.css the great MPlayer tab removal: part I 2010-04-12 10:56:17 +00:00
html-common.xsl Remove trailing whitespace from most files 2009-07-07 02:34:35 +03:00
ldp.dsl the great MPlayer tab removal: part I 2010-04-12 10:56:17 +00:00
Makefile DOCS/xml/Makefile: Remove help target that prints available targets 2010-11-02 04:11:43 +02:00
README DOCS/xml/README: improve 2010-11-02 04:14:46 +02:00

Tools required for building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* GNU make 3.80 or later
* DocBook 4.1.2 or later
* The DocBook XML DTD (also known as DocBk XML)
* DocBook XSL stylesheets -- version 1.50.0 or later is recommended.

I am not quite sure which tools work, but I used the following
ones successfully, so they are required:

* xmllint (part of libxml2) is used for validation.
* xsltproc (part of libxslt1) is used for transforming XML files into HTML
  files. Version 1.0.18 or later is recommended.

On Red Hat systems you need the following packages:
libxml2, libxslt, docbook-dtds, docbook-style-xsl

On Debian you will need these packages:
docbook-xml, docbook-xsl, xsltproc, libxml2-utils


Building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~

Before trying to build the documentation, run

  make help

to see all available build targets and make your choice. If something goes
wrong, check the Configuration section of the toplevel Makefile and adjust
the variables.

The documentation and its translations reside in subdirectories.
When building the documentation, the generated HTML files are
placed in subdirectories of the 'HTML' directory.

IMPORTANT: Do NOT place sensitive files under 'HTML'!
           It is for generated documentation only.
           The whole directory tree is wiped out by the Makefile
           when running 'make distclean' or 'make clean'.


Adding new translations
~~~~~~~~~~~~~~~~~~~~~~~

1) Create a new subdirectory and copy the XML files there. main.xml must not be
   copied, it is autogenerated.

2) In each translated file after the <?xml ... ?> tag you must put a note
   like <!-- synced with r2 -->, where 2 is the revision of corresponding
   English file (see comment at the top of file).

That's all, in theory.


A few words about SGML catalog files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As far as I know, the document type declaration in XML files requires
both a public and a system identifier. For example:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd">

where

  "-//OASIS//DTD DocBook XML V4.1.2//EN"

is the public, and

  "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd"

is the system identifier.

The problem is that the system identifier is most probably system-dependent.
To avoid the need to manually fix the system identifiers before building the
documentation, I've decided to use SGML catalogs. If you have your catalogs
set up correctly, xmllint and xsltproc will use them to find the DTDs
based on the public identifiers.

Note that this works only if public identifiers override system identifiers
(i.e. the catalog file must contain 'OVERRIDE YES'). (I had no problem with
these on my system, since the Debian people took care of everything. ;-))