[Mplayer-cvslog] CVS: main/DOCS/xml BUGS,NONE,1.1 default.css,NONE,1.1 gen-html.xsl.sh,NONE,1.1 html-common.xsl,NONE,1.1 ldp.dsl,NONE,1.1 Makefile,NONE,1.1 Makefile.inc,NONE,1.1 README,NONE,1.1 README.maintainers,NONE,1.1

Nico nicolas at mplayerhq.hu
Mon Mar 24 00:26:58 CET 2003


Update of /cvsroot/mplayer/main/DOCS/xml
In directory mail:/var/tmp.root/cvs-serv32506/main/DOCS/xml

Added Files:
	BUGS default.css gen-html.xsl.sh html-common.xsl ldp.dsl 
	Makefile Makefile.inc README README.maintainers 
Log Message:
XML version of MPlayer's doc


--- NEW FILE ---
* Can't change output encoding...it's always ISO-8859-1. :-(
  Should figure out a way to change it...
  
  <xsl:output encoding="..."/> does not seem to work with xsltproc.
  
  <xsl:param name="chunker.output.encoding" select="'...'"/> seems not to
  work either.
  
  Is it a limitation of xsltproc?

--- NEW FILE ---
body {
	color: black;
	background: white;

	font-family: Arial, Helvetica, sans-serif;
/*
 * It's a Bad Idea(tm) to use fixed font sizes.
 * Uncomment it if you _really_ want
 */
	font-size: 14px;
}

div.table table, div.informaltable table {
	background: #333366;
	border-collapse: separate;
	border: solid 1px #333366;
	border-spacing: 1px;
}

div.table th, div.informaltable th {
	color: white;
	background: #4488cc;
	border: 0px;
	padding: 2px;
}

div.table td, div.informaltable td {
	background: #fffff8;
	border: 0px;
	padding: 2px;
}


pre.screen {
	padding: 4px;
	background: #e0e0e0;
}

pre.programlisting {
	padding: 4px;
	background: #e0e8f0;
}

/*
span.application {
}
*/

span.keycap {
	background: #ddd;
	border: solid 1px #aaa;
	white-space: nowrap;
	font-family: Arial, Helvetica, sans-serif;
}

span.guimenu, span.guisubmenu, span.guimenuitem {
	background: #dddddd;
}

tt.filename {
	color: maroon;
	white-space: nowrap;
}

tt.option {
	color: #066;
	white-space: nowrap;
}

div.example {
	padding-left: 0.5em;
	border-left: solid 2px black;
}

div.important .title, div.caution .title, div.warning .title {
	color: #c00;
}
/*
div.important, div.warning, div.caution {
	padding-left: 0.5em;
	border-left: solid 2px maroon;
}
*/

--- NEW FILE ---
#
# Helper script to generate html.xsl.
#

if test $# -ne 1; then
	echo "Usage: $0 <path to chunk.xsl>"
	exit 1
fi

if test -f "$1"; then :; else
	echo "$0: file not found: \"$1\""
	exit 1
fi

cat << EOF
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- ***************************************************
     This file is generated automatically.  DO NOT EDIT.
     *************************************************** -->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">

  <xsl:import href="$1"/>
  <xsl:include href="html-common.xsl"/>

</xsl:stylesheet>
EOF

--- NEW FILE ---
<?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">

<xsl:output method="html" indent="no"/>
 
<!-- **************
     Set parameters
     ************** -->

  <xsl:param name="toc.section.depth" select="'3'"/>

  <xsl:param name="html.stylesheet" select="'default.css'"/>
  <xsl:param name="html.stylesheet.type" select="'text/css'"/>

  <xsl:param name="html.cleanup" select="'1'"/>
  <xsl:param name="make.valid.html" select="'1'"/>
  <xsl:param name="make.single.year.ranges" select="'1'"/>
  <xsl:param name="make.year.ranges" select="'1'"/>

  <!-- Use ID value for generated filenames -->
  <xsl:param name="use.id.as.filename" select="'1'"/>

  <!-- Depth to which sections are chunked -->
  <xsl:param name="chunk.section.depth" select="'1'"/>

  <!-- Create a chunk for the 1st top-level section too  -->
  <xsl:param name="chunk.first.sections" select="'1'"/>

  <xsl:param name="admon.graphics" select="'0'"/>
  <xsl:param name="navig.graphics" select="'0'"/>
  <xsl:param name="navig.showtitles" select="'1'"/>
 
  <!-- Label sections too (eg. 2.1, 2.1.1) -->
  <xsl:param name="section.autolabel" select="'1'"/>
  <xsl:param name="section.label.includes.component.label" select="'1'"/>

  <!-- Use informal procedures; no need to number them -->
  <xsl:param name="formal.procedures" select="'0'"/>

  <xsl:param name="generate.toc">
    appendix  toc
    article   toc
    book      toc
    chapter   toc
    part      toc
    preface   toc
    qandadiv  toc
    qandaset  toc
    reference toc
    section   toc
    set       toc
  </xsl:param>

<!-- *********
     Templates
     ********* -->

  <xsl:template match="application">
    <span class="application"><xsl:apply-templates/></span>
  </xsl:template>

  <xsl:template match="option">
    <tt class="option"><xsl:apply-templates/></tt>
  </xsl:template>

  <xsl:template match="filename">
    <tt class="filename"><xsl:apply-templates/></tt>
  </xsl:template>

  <xsl:template match="keycap">
    <span class="keycap"><b><xsl:apply-templates/></b></span>
  </xsl:template>

  <xsl:template match="guimenu">
    <span class="guimenu"><xsl:apply-templates/></span>
  </xsl:template>

  <xsl:template match="guisubmenu">
    <span class="guisubmenu"><xsl:apply-templates/></span>
  </xsl:template>

  <xsl:template match="guimenuitem">
    <span class="guimenuitem"><xsl:apply-templates/></span>
  </xsl:template>

</xsl:stylesheet>

--- NEW FILE ---
<!DOCTYPE style-sheet PUBLIC
          "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY % html "IGNORE">
<![%html;[
<!ENTITY % print "IGNORE">
<!ENTITY docbook.dsl PUBLIC
         "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN"
         CDATA dsssl>
]]>
<!ENTITY % print "INCLUDE">
<![%print;[
<!ENTITY docbook.dsl PUBLIC
         "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN"
         CDATA dsssl>
]]>
]>

<style-sheet>

;; ------------------------------------------------------------------------
;; ldp.dsl - LDP Customized DSSSL Stylesheet
;; v1.11, 2003-02-03
;; Copyright (C) 2000-2003
;;
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2 of the License, or
;; (at your option) any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this program; if not, write to the Free Software
;; Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
;; ------------------------------------------------------------------------

<style-specification id="print" use="docbook">
<style-specification-body> 

;; customize the print stylesheet

(declare-characteristic preserve-sdata?
  ;; this is necessary because right now jadetex does not understand
  ;; symbolic entities, whereas things work well with numeric entities.
  "UNREGISTERED::James Clark//Characteristic::preserve-sdata?"
  #f)

(define %generate-article-toc%
  ;; Should a Table of Contents be produced for Articles?
  #t)

(define (toc-depth nd)
  4)

(define %generate-article-titlepage-on-separate-page%
  ;; Should the article title page be on a separate page?
  #t)

(define %section-autolabel%
  ;; Are sections enumerated?
  #t)

(define %footnote-ulinks%
  ;; Generate footnotes for ULinks?
  #f)

(define %bop-footnotes%
  ;; Make "bottom-of-page" footnotes?
  #f)

(define %body-start-indent%
  ;; Default indent of body text
  0pi)

(define %para-indent-firstpara%
  ;; First line start-indent for the first paragraph
  0pt)

(define %para-indent%
  ;; First line start-indent for paragraphs (other than the first)
  0pt)

(define %block-start-indent%
  ;; Extra start-indent for block-elements
  0pt)

(define formal-object-float
  ;; Do formal objects float?
  #t)

(define %hyphenation%
  ;; Allow automatic hyphenation?
  #t)

(define %admon-graphics%
  ;; Use graphics in admonitions?
  #f)

(define %default-quadding%
  ;; Full justification.
  'justify)

(define (book-titlepage-verso-elements)
  ;;added publisher, releaseinfo to the default list
  (list (normalize "title")
        (normalize "subtitle")
        (normalize "corpauthor")
        (normalize "authorgroup")
        (normalize "author")
        (normalize "publisher")
        (normalize "releaseinfo")
        (normalize "editor")
        (normalize "edition")
        (normalize "pubdate")
        (normalize "copyright")
        (normalize "abstract")
        (normalize "legalnotice")
        (normalize "revhistory")))

</style-specification-body>
</style-specification>


<!--
;; customize the html stylesheet; parts borrowed from 
;; Cygnus at http://sourceware.cygnus.com/ (cygnus-both.dsl)
-->

<style-specification id="html" use="docbook">
<style-specification-body> 

(declare-characteristic preserve-sdata?
  ;; this is necessary because right now jadetex does not understand
  ;; symbolic entities, whereas things work well with numeric entities.
  "UNREGISTERED::James Clark//Characteristic::preserve-sdata?"
  #f)

(declare-flow-object-class element
  ;; for redhat
  "UNREGISTERED::James Clark//Flow Object Class::element")

(define %generate-legalnotice-link%
  ;; put the legal notice in a separate file
  #t)

(define %admon-graphics-path%
  ;; use graphics in admonitions, set their
  "../images/")

(define %admon-graphics%
  #t)

(define %funcsynopsis-decoration%
  ;; make funcsynopsis look pretty
  #t)

(define %html-ext%
  ;; when producing HTML files, use this extension
  ".html")

(define %generate-book-toc%
  ;; Should a Table of Contents be produced for books?
  #t)

(define %generate-article-toc% 
  ;; Should a Table of Contents be produced for articles?
  #t)

(define %generate-part-toc%
  ;; Should a Table of Contents be produced for parts?
  #t)

(define %generate-book-titlepage%
  ;; produce a title page for books
  #t)

(define %generate-article-titlepage%
  ;; produce a title page for articles
  #t)

(define (chunk-skip-first-element-list)
  ;; forces the Table of Contents on separate page
  '())

(define (list-element-list)
  ;; fixes bug in Table of Contents generation
  '())

(define %root-filename%
  ;; The filename of the root HTML document (e.g, "index").
  "index")

(define %shade-verbatim%
  ;; verbatim sections will be shaded if t(rue)
  #t)

(define %use-id-as-filename%
  ;; Use ID attributes as name for component HTML files?
  #t)

(define %graphic-extensions%
  ;; graphic extensions allowed
  '("gif" "png" "jpg" "jpeg" "tif" "tiff" "eps" "epsf" ))

(define %graphic-default-extension% 
  "gif")

(define %section-autolabel%
  ;; For enumerated sections (1.1, 1.1.1, 1.2, etc.)
  #t)

(define (toc-depth nd)
  ;; more depth (2 levels) to toc; instead of flat hierarchy
  2)

(element emphasis
  ;; make role=strong equate to bold for emphasis tag
  (if (equal? (attribute-string "role") "strong")
     (make element gi: "STRONG" (process-children))
     (make element gi: "EM" (process-children))))

(define (book-titlepage-recto-elements)
  ;; elements on a book's titlepage
  (list (normalize "title")
        (normalize "subtitle")
        (normalize "graphic")
        (normalize "mediaobject")
        (normalize "corpauthor")
        (normalize "authorgroup")
        (normalize "author")
        (normalize "othercredit")
        (normalize "edition")
        (normalize "releaseinfo")
        (normalize "publisher")
        (normalize "editor")
        (normalize "copyright")
        (normalize "pubdate")
        (normalize "revhistory")
        (normalize "abstract")
        (normalize "legalnotice")))

(define (article-titlepage-recto-elements)
  ;; elements on an article's titlepage
  (list (normalize "title")
        (normalize "subtitle")
        (normalize "authorgroup")
        (normalize "author")
        (normalize "othercredit")
        (normalize "releaseinfo")
        (normalize "copyright")
        (normalize "pubdate")
        (normalize "revhistory")
        (normalize "abstract")
        (normalize "legalnotice")))

(define (process-contrib #!optional (sosofo (process-children)))
  ;; print out with othercredit information; for translators, etc.
  (make sequence
    (make element gi: "SPAN"
          attributes: (list (list "CLASS" (gi)))
          (process-children))))

(define (process-othercredit #!optional (sosofo (process-children)))
  ;; print out othercredit information; for translators, etc.
  (let ((author-name  (author-string))
        (author-contrib (select-elements (children (current-node))
                                          (normalize "contrib"))))
    (make element gi: "P"
         attributes: (list (list "CLASS" (gi)))
         (make element gi: "B"
              (literal author-name)
              (literal " - "))
         (process-node-list author-contrib))))

(mode article-titlepage-recto-mode
  (element contrib (process-contrib))
  (element othercredit (process-othercredit))
)

(mode book-titlepage-recto-mode
  (element contrib (process-contrib))
  (element othercredit (process-othercredit))
)

(define (article-title nd)
  (let* ((artchild  (children nd))
         (artheader (select-elements artchild (normalize "artheader")))
         (artinfo   (select-elements artchild (normalize "articleinfo")))
         (ahdr (if (node-list-empty? artheader)
                   artinfo
                   artheader))
         (ahtitles  (select-elements (children ahdr)
                                     (normalize "title")))
         (artitles  (select-elements artchild (normalize "title")))
         (titles    (if (node-list-empty? artitles)
                        ahtitles
                        artitles)))
    (if (node-list-empty? titles)
        ""
        (node-list-first titles))))

(mode subtitle-mode
  ;; do not print subtitle on subsequent pages
  (element subtitle (empty-sosofo)))

;; Redefinition of $verbatim-display$
;; Origin: dbverb.dsl
;; Different foreground and background colors for verbatim elements
;; Author: Philippe Martin (feloy at free.fr) 2001-04-07

(define ($verbatim-display$ indent line-numbers?)
  (let ((verbatim-element (gi))
        (content (make element gi: "PRE"
                       attributes: (list
                                    (list "CLASS" (gi)))
                       (if (or indent line-numbers?)
                           ($verbatim-line-by-line$ indent line-numbers?)
                           (process-children)))))
    (if %shade-verbatim%
        (make element gi: "TABLE"
              attributes: (shade-verbatim-attr-element verbatim-element)
              (make element gi: "TR"
                    (make element gi: "TD"
                          (make element gi: "FONT" 
                                attributes: (list
                                             (list "COLOR" (car (shade-verbatim-element-colors
                                                                 verbatim-element))))
                                content))))
        content)))

;;
;; Customize this function
;; to change the foreground and background colors
;; of the different verbatim elements
;; Return (list "foreground color" "background color")
;;
(define (shade-verbatim-element-colors element)
  (case element
    (("SYNOPSIS") (list "#000000" "#6495ED"))
    ;; ...
    ;; Add your verbatim elements here
    ;; ...
    (else (list "#000000" "#E0E0E0"))))

(define (shade-verbatim-attr-element element)
  (list
   (list "BORDER" 
	(cond
		((equal? element (normalize "SCREEN")) "1")
		(else "0")))
   (list "BGCOLOR" (car (cdr (shade-verbatim-element-colors element))))
   (list "WIDTH" ($table-width$))))

;; End of $verbatim-display$ redefinition

</style-specification-body>
</style-specification>

<external-specification id="docbook" document="docbook.dsl">

</style-sheet>


--- NEW FILE ---
# Makefile for generating the HTML documentation

#####[ Configuration ]##################################################

# The xsltproc program.
XSLTPROC = xsltproc

# The xmllint program.
XMLLINT = xmllint

# A colon separated list of catalog entry files.
# Without this properly set up, xmllint and xsltproc might be unable
# to find the DTDs for the system identifiers specified in the XML files.
# If the SGML_CATALOG_FILES environment variable is not set, list one
# or more catalogs here.
#
# on debian (potato?) systems, maybe others
#SGML_CATALOG_FILES ?= /etc/sgml/catalog
#
# on Mandrake (9.0?) systems, maybe others
SGML_CATALOG_FILES ?= /usr/share/sgml/docbook/xml-dtd-4.1.2/xmlcatalog
#SGML_CATALOG_FILES ?= /usr/share/apps/ksgmltools2/customization/en/catalog

# Full path of the "chunker" DocBook XSL stylesheet used to generate
# the HTML files.
#
# on debian (potato?)
#CHUNK_XSL = /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl
#
# on Mandrake (9.0?) systems, maybe others
CHUNK_XSL = /usr/share/sgml/docbook/yelp/docbook/html/chunk.xsl

# List of subdirectories to be processed.
SUBDIRS = en

#####[ End of configuration ]###########################################

export CHUNK_XSL SGML_CATALOG_FILES XMLLINT XSLTPROC

.PHONY: no-target
no-target:
	@echo "What to make?"
	@echo
	@echo "Targets"
	@echo "*******"
	@echo "all       : Build everything (same as build-html for now)."
	@echo "build-html: Build HTML documentation."
	@echo "clean-html: Purge the 'HTML' directory."
	@echo "distclean : Remove ALL generated files."

.PHONY: all
all: build-html

.PHONY: build-html
build-html:
	test -d HTML || mkdir HTML
	for d in $(SUBDIRS); do\
		test -f $$d/Makefile &&\
		(test -d HTML/$$d || mkdir HTML/$$d) &&\
		if $(MAKE) HTMLDIR=../../HTML/$$d -C $$d; then :; else exit 1; fi;\
	done

.PHONY: test
test:
	@if command -v $(XSLTPROC) >/dev/null; then :; else exit 1; fi
	@if command -v $(XMLLINT) >/dev/null; then :; else exit 1; fi
	@test -f $(CHUNK_XSL) || (echo "file not found: $(CHUNK_XSL)"; exit 1)
	@echo "All tests passed."

.PHONY: clean-html
clean-html:
	-rm -rf ../HTML

.PHONY: distclean
distclean: clean-html
	-rm -f html.xsl

--- NEW FILE ---
#
# Makefile.inc for Makefiles in sub-directories.
#

export SGML_CATALOG_FILES

# Use customized html.xsl file if exists...
ifeq (html.xsl,$(wildcard html.xsl))
HTML_XSL := html.xsl
XSL_DEPS := $(HTML_XSL) ../html.xsl ../html-common.xsl
else
HTML_XSL := ../html.xsl
XSL_DEPS := $(HTML_XSL) ../html-common.xsl
endif

# Fall back to the default HTML stylesheet if not specified.
HTML_STYLESHEET ?= ../default.css

# This is the main target...
$(HTMLDIR)/index.html: documentation.xml $(XSL_DEPS)
	-rm -f $(HTMLDIR)/*
	$(XMLLINT) --noout --noent --postvalid --catalogs $<
	$(XSLTPROC) --catalogs -o $(HTMLDIR)/ $(HTML_XSL) $<
	cp $(HTML_STYLESHEET) $(HTMLDIR)/

../html.xsl:
	sh ../gen-html.xsl.sh $(CHUNK_XSL) > $@

--- NEW FILE ---
Tools required for building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* 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.


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

1) Before trying to build the documentation, run

	make test

   to see if everything is set up properly.  If something goes wrong,
   check the Configuration section of the toplevel Makefile and adjust
   the variables.


2) Now simply run

	make all

   to build the documentation.


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


--
Andras Mohari

--- NEW FILE ---
The documentation and its translations reside in subdirectories.
When building the documentation, the toplevel Makefile goes into
the subdirectories listed in the SUBDIRS variable and executes make
in each of those directories to create the HTML documentation
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-html'.
	   Also, subdirectories are wiped out one by one before
	   creating the HTML files.

Each subdirectory must have a Makefile.  Its purpose is to include
the toplevel Makefile.inc file (with the rules to build the docs)
and add dependency information to the main target, $(HTMLDIR)/index.html.
The main target usually depends on all the XML and XSL files in the
subdirectory.  (Note that the toplevel *.xsl files are added automatically
by Makefile.inc, so you do not have to list them.)


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

1) Create a new subdirectory and copy the XML files there.
2) Make sure to create a 'Makefile' for the translation -- you can
   use 'en/Makefile' as an example.
3) Set <book lang="XX"> to your language code if the DocBook XSL
   stylesheets support it.
4) If you want to use a customized XSL stylesheet, create one and name it
   'html.xsl'.  And do not forget to import the toplevel XSL file:

	<xsl:import href="../html.xsl"/>

5) If you are using you own HTML stylesheet, edit your Makefile and set
   the HTML_STYLESHEET variable to its name.
   
That's all, in theory.



More information about the MPlayer-cvslog mailing list