1
0
mirror of https://github.com/mpv-player/mpv synced 2024-12-15 11:25:10 +00:00
mpv/DOCS/xml
boskicinek 558960583b - svn sync tag added
- massive updates, fixes etc.
- more updates soon
- hope I'm doing this right - it's my firs time with SVN:)

git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@19032 b3059339-0415-0410-9bf9-f77b7e298cf2
2006-07-12 14:06:43 +00:00
..
cs Sync to svn up to 27.6.2006 2006-07-04 09:10:28 +00:00
de r18824: URL update for Marillat Debian packages 2006-06-26 18:18:51 +00:00
en Telecine article on divx.com has gone 404, link to Wikipedia instead. 2006-07-12 12:35:09 +00:00
es Remove now obsolete .cvsignore files. 2006-06-02 11:24:33 +00:00
fr some more s/CVS/Subversion/ + update some step-by-step directions which were specific to old MPlayer CVS layout 2006-06-07 12:59:07 +00:00
hu DOCS/xml/hu synced with r18973 2006-07-09 09:27:09 +00:00
pl - svn sync tag added 2006-07-12 14:06:43 +00:00
ru Remove now obsolete .cvsignore files. 2006-06-02 11:24:33 +00:00
xsl
configure Add XML tool paths for SUSE 10.0 2006-02-24 17:38:23 +00:00
default.css
html-common.xsl
ldp.dsl
Makefile English docs should be built first. 2006-04-17 00:29:56 +00:00
Makefile.inc Simplify link removal. 2006-04-17 00:28:36 +00:00
README Correct toolchain for building XML docs on Debian Sarge. 2006-03-07 11:09:40 +00:00
README.maintainers Add a note about main.xml. 2006-05-09 13:49:15 +00: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.

It's also possible to use the Saxon XSLT Processor. The Russian translator
used it (version 6.4.4) for a while. If you have a suitable JavaVM and a
saxon.jar installed somewhere, configure will try to detect them. If
autodetection fails, try to tweak DOCS/xml/configure to get it working and
send us a patch :)

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

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


Installing the required tools from source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1) Download libxslt AND libxml2 packages from
   http://xmlsoft.org/XSLT/downloads.html

   Installing them should be straightforward, execute the usual "./configure"
   and "make" then "make install" commands.


2) Download the docbook-xml package from http://www.oasis-open.org/docbook/xml/
   Use the newest version. The URL will be something like this:

	http://www.oasis-open.org/docbook/xml/4.2/docbook-xml-4.2.zip

   Extract this package into a directory, enter it, and execute the following
   commands:

	mkdir -p /usr/share/sgml/docbook/dtd/xml/4.2/
	cp -r * /usr/share/sgml/docbook/dtd/xml/4.2/


3) Download the docbook-xsl package from
   http://prdownloads.sourceforge.net/docbook/

   Use the newest version. The URL will be something like this:

	http://prdownloads.sourceforge.net/docbook/docbook-xsl-1.62.0.tar.gz

   Extract this package into a directory, enter it, and execute the following
   commands:

	mkdir -p /usr/share/sgml/docbook/stylesheet/xsl/nwalsh
	cp -r VERSION common html lib \
		/usr/share/sgml/docbook/stylesheet/xsl/nwalsh


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.


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. ;-))