README

   1 ----------------------------------------------------------------------
   2               README file for the DocBook XSL Stylesheets
   3 ----------------------------------------------------------------------
   4 $Id: README 9731 2013-03-17 05:01:54Z bobstayton $
   5
   6 These are XSL stylesheets for transforming DocBook XML document
   7 instances into various output formats.
   8
   9 This README file provides only very minimal documentation on using
  10 the stylesheets. For more complete information, see Bob Stayton's
  11 book "DocBook XSL: The Complete Guide", available online at:
  12
  13   http://www.sagehill.net/docbookxsl/
  14
  15 ----------------------------------------------------------------------
  16 Installation
  17 ----------------------------------------------------------------------
  18 See the INSTALL file for information about installing this release.
  19
  20 ----------------------------------------------------------------------
  21 How to use the stylesheets
  22 ----------------------------------------------------------------------
  23 The base canonical URI for these stylesheets is:
  24
  25   http://docbook.sourceforge.net/release/xsl/current/
  26
  27 You call any of the stylesheets in this distribution by doing one
  28 of the following:
  29
  30   - Use the base canonical URI in combination with one of the
  31     pathnames below. For example, for "chunked" HTML, output:
  32
  33     http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl
  34
  35     If your system has a working XML Catalog or SGML Catalog setup
  36     (most Linux systems do), then that URI will automatically be
  37     resolved and replaced with a local pathname on your system.
  38
  39   - Use a "real" local system base path in combination with one of
  40     the pathnames below. For example, for "chunked" HTML, output:
  41
  42     /usr/share/xml/docbook/stylesheet/nwalsh/html/chunk.xsl
  43
  44 To transform documents created with the standard DocBook
  45 schema/DTD, use one of the following stylesheets:
  46
  47   fo/docbook.xsl              - for XSL-FO
  48
  49   html/docbook.xsl            - for HTML (as a single file)
  50   html/chunk.xsl              - for HTML (chunked into multiple files)
  51   html/onechunk.xsl           - for HTML (chunked output in single file)
  52
  53   xhtml/*.xsl                 - for XHTML versions of the above
  54
  55   xhtml-1_1/*.xsl             - for XHTML 1.1 versions of the above
  56
  57   xhtml5/*.xsl                 - for XHTML5 versions of the above
  58
  59   epub/docbook.xsl            - for .epub version 2 and earlier
  60   epub3/docbook.xsl           - for .epub version 3 and later
  61
  62   htmlhelp/htmlhelp.xsl       - for HTML Help
  63   javahelp/javahelp.xsl       - for JavaHelp
  64   eclipse/eclipse.xsl         - for Eclipse Help
  65
  66   manpages/docbook.xsl        - for groff/nroff man pages
  67
  68   */profile-*                 - single-pass-profiling versions of all above
  69
  70   roundtrip/*.xsl             - for DocBook to WordML, etc., to DocBook
  71
  72   assembly/assemble.xsl       - converts an assembly into a DocBook document
  73   assembly/topic-maker-chunk.xsl
  74                               - converts a DocBook document into an assembly
  75                                 with topic files.
  76
  77   webhelp/build.xml           - Ant script to generate webhelp output.
  78   webhelp/Makefile            - Makefile to generate webhelp output.
  79
  80 To transform documents created with the DocBook Slides schema/DTD,
  81 use one of the following stylesheets:
  82
  83   slides/xhtml/*.xsl          - for XHTML slides of various kinds
  84   slides/fo/plain.xsl         - for XSL-FO slides
  85
  86 To transform documents created with the DocBook Website
  87 schema/DTD, use one of the following stylesheets:
  88
  89   website/website.xsl         - for non-tabular, non-chunked output
  90   website/tabular.xsl         - for tabular, non-chunked output
  91   website/chunk-*             - for chunked output
  92
  93 To generate a titlepage customization layer from a titlepage spec:
  94
  95   template/titlepage.xsl
  96
  97 For fo titlepage customizations, set the stylesheet parameter named 'ns'
  98 to 'http://www.w3.org/1999/XSL/Format' when using this stylesheet.
  99 For xhtml titlepage customizations, set the stylesheet parameter named 'ns'
 100 to 'http://www.w3.org/1999/xhtml' when using this stylesheet.
 101
 102 For details about creating titlepage spec files and generating and
 103 using titlepage customization layers, see "DocBook XSL: The
 104 Complete Guide" <http://www.sagehill.net/docbookxsl/>
 105
 106 ----------------------------------------------------------------------
 107 Manifest
 108 ----------------------------------------------------------------------
 109 AUTHORS       contact information
 110 BUGS          about known problems
 111 COPYING       copyright information
 112 INSTALL       installation instructions
 113 README        this file
 114 RELEASE.*     per-release cumulative summaries of user-visible changes
 115 TODO          about planned features not yet implemented
 116 VERSION       release metadata, including the current version
 117               number (note that the VERSION file is an XSL stylesheet)
 118 NEWS          changes since the last public release (for a cumulative list of
 119               changes, see the ChangeHistory.xml file)
 120
 121 assembly/     for making and processing DocBook assemblies.
 122 common/       code used among several output formats (HTML, FO, manpages,...)
 123 docsrc/       documentation sources
 124 eclipse/      for producing Eclipse Help
 125 epub/         for producing .epub version 2.
 126 epub3/        for producing .epub version 3 and beyond.
 127 extensions/   DocBook XSL Java extensions
 128 fo/           for producing XSL-FO
 129 highlighting  files used for adding source-code syntax highlighting in output
 130 html/         for producing HTML
 131 htmlhelp/     for producing HTML Help
 132 images/       images used in callouts and graphical admonitions
 133 javahelp/     for producing Java Help
 134 lib/          utility stylesheets with schema-independent functions
 135 manpages/     for producing groff/troff man pages
 136 profiling/    for profiling (omitting/including conditional text)
 137 roundtrip/    for "round trip" conversion among DocBook and
 138               various word-processor formats (WordML, etc.)
 139 slides/       for producing slides output (from Slides source)
 140 template/     templates for building stylesheet customization layers
 141 tools/        assorted supplementary tools
 142 webhelp/      templates and scripts for generating webhelp output
 143 website/      for producing website output (from Website source)
 144 xhtml/        for producing XHTML
 145 xhtml-1_1/    for producing (stricter) XHTML 1.1
 146 xhtml5/       for producing XHTML5
 147
 148 ----------------------------------------------------------------------
 149 Changes
 150 ----------------------------------------------------------------------
 151 See the NEWS file for changes made since the previous release.
 152
 153 See the RELEASE-NOTES.html or RELEASE-NOTES.txt or RELEASE-NOTES.pdf
 154 files for per-release cumulative summaries of significant
 155 user-visible changes.
 156
 157 For online access to a hyperlinked view of all changes made over
 158 the entire history of the codebase, see the following:
 159
 160   http://docbook.svn.sourceforge.net/viewvc/docbook/trunk/xsl/?view=log
 161
 162 WARNING: That above change history is a very long list and may
 163 take a long time to load/download.
 164
 165 You can also create an XML-formatted "ChangeHistory.xml" copy of
 166 the complete change history for the codebase by running the
 167 following commands:
 168
 169   svn checkout https://docbook.svn.sf.net/svnroot/docbook/trunk/xsl
 170   svn log --xml --verbose xsl > ChangeHistory.xml
 171
 172 ----------------------------------------------------------------------
 173 Copyright information
 174 ----------------------------------------------------------------------
 175 See the accompanying file named COPYING.