From 5b1bd414021a75c10bcff405266df99f729a91da Mon Sep 17 00:00:00 2001 From: nicolas Date: Sun, 23 Mar 2003 23:26:55 +0000 Subject: [PATCH] XML version of MPlayer's doc git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@9675 b3059339-0415-0410-9bf9-f77b7e298cf2 --- DOCS/xml/BUGS | 9 + DOCS/xml/Makefile | 76 ++++++++ DOCS/xml/Makefile.inc | 27 +++ DOCS/xml/README | 66 +++++++ DOCS/xml/README.maintainers | 38 ++++ DOCS/xml/default.css | 83 ++++++++ DOCS/xml/gen-html.xsl.sh | 27 +++ DOCS/xml/html-common.xsl | 87 +++++++++ DOCS/xml/ldp.dsl | 365 ++++++++++++++++++++++++++++++++++++ 9 files changed, 778 insertions(+) create mode 100644 DOCS/xml/BUGS create mode 100644 DOCS/xml/Makefile create mode 100644 DOCS/xml/Makefile.inc create mode 100644 DOCS/xml/README create mode 100644 DOCS/xml/README.maintainers create mode 100644 DOCS/xml/default.css create mode 100644 DOCS/xml/gen-html.xsl.sh create mode 100644 DOCS/xml/html-common.xsl create mode 100644 DOCS/xml/ldp.dsl diff --git a/DOCS/xml/BUGS b/DOCS/xml/BUGS new file mode 100644 index 0000000000..7c53ea6492 --- /dev/null +++ b/DOCS/xml/BUGS @@ -0,0 +1,9 @@ +* Can't change output encoding...it's always ISO-8859-1. :-( + Should figure out a way to change it... + + does not seem to work with xsltproc. + + seems not to + work either. + + Is it a limitation of xsltproc? diff --git a/DOCS/xml/Makefile b/DOCS/xml/Makefile new file mode 100644 index 0000000000..b6b8492552 --- /dev/null +++ b/DOCS/xml/Makefile @@ -0,0 +1,76 @@ +# 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 diff --git a/DOCS/xml/Makefile.inc b/DOCS/xml/Makefile.inc new file mode 100644 index 0000000000..fa25262348 --- /dev/null +++ b/DOCS/xml/Makefile.inc @@ -0,0 +1,27 @@ +# +# 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) > $@ diff --git a/DOCS/xml/README b/DOCS/xml/README new file mode 100644 index 0000000000..13b53501dc --- /dev/null +++ b/DOCS/xml/README @@ -0,0 +1,66 @@ +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: + + + +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 diff --git a/DOCS/xml/README.maintainers b/DOCS/xml/README.maintainers new file mode 100644 index 0000000000..56ec979fa2 --- /dev/null +++ b/DOCS/xml/README.maintainers @@ -0,0 +1,38 @@ +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 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: + + + +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. diff --git a/DOCS/xml/default.css b/DOCS/xml/default.css new file mode 100644 index 0000000000..cc30679712 --- /dev/null +++ b/DOCS/xml/default.css @@ -0,0 +1,83 @@ +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; +} +*/ diff --git a/DOCS/xml/gen-html.xsl.sh b/DOCS/xml/gen-html.xsl.sh new file mode 100644 index 0000000000..8e2704959c --- /dev/null +++ b/DOCS/xml/gen-html.xsl.sh @@ -0,0 +1,27 @@ +# +# Helper script to generate html.xsl. +# + +if test $# -ne 1; then + echo "Usage: $0 " + exit 1 +fi + +if test -f "$1"; then :; else + echo "$0: file not found: \"$1\"" + exit 1 +fi + +cat << EOF + + + + + + + + +EOF diff --git a/DOCS/xml/html-common.xsl b/DOCS/xml/html-common.xsl new file mode 100644 index 0000000000..296416bdaa --- /dev/null +++ b/DOCS/xml/html-common.xsl @@ -0,0 +1,87 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + appendix toc + article toc + book toc + chapter toc + part toc + preface toc + qandadiv toc + qandaset toc + reference toc + section toc + set toc + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/DOCS/xml/ldp.dsl b/DOCS/xml/ldp.dsl new file mode 100644 index 0000000000..d3f5927c4c --- /dev/null +++ b/DOCS/xml/ldp.dsl @@ -0,0 +1,365 @@ + + + +]]> + + +]]> +]> + + + +;; ------------------------------------------------------------------------ +;; 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 +;; ------------------------------------------------------------------------ + + + + +;; 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"))) + + + + + + + + + + +(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@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 + + + + + + + +