From: Bob Stayton Date: Mon, 6 Feb 2012 07:28:38 +0000 (+0000) Subject: Provide README file for xhtml5 and epub3 distribution. X-Git-Tag: release/1.79.1~6^2~541 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=e88dd3c6b446b99a3dd9ae7ba8ecaa863a002eed;p=docbook-dsssl Provide README file for xhtml5 and epub3 distribution. --- diff --git a/xsl/epub3/README b/xsl/epub3/README new file mode 100644 index 000000000..8b3f30417 --- /dev/null +++ b/xsl/epub3/README @@ -0,0 +1,137 @@ +DocBook stylesheets for EPUB 3 output +============================================= + +This directory contains XSL stylesheets +for generating EPUB3 output from DocBook content. +For more information on EPUB3, see: + +http://idpf.org/epub/30 + +These EPUB3 stylesheets are a customization layer on +top of the xhtml5/ stylesheets in this distribution, which +are in turn a customization layer on top of the +xhtml/ stylesheets in this distribution. +Using a customization layer enables the EPUB3 +stylesheets to inherit all the features of the +XHTML stylesheets while making the minimum changes +for them to produce valid EPUB3. + +Usage +----------- +The general process for creating an EPUB3 ebook is: + +1. Generate chunked XHTML5 content that validates against +the EPUB3 schemas, and generate the EPUB3 package +files. + +2. Copy any image files into the output directory. + +3. Run a zip command to create an .epub file. + +4. Validate the .epub file. + + +Following are the steps in more detail. + +1. Create the XHTML5 files. +----------------------------- + +The first step is handled by these stylesheets. +To generate EPUB3-compatible XHTML5 files, +use one of the following stylesheets as you would any +other DocBook XSL stylesheet: + +epub3/chunk.xsl - Chunked output. +epub3/profile-chunk.xsl - Profiled chunk output. + +Although the stylesheet directory contains a docbook.xsl +stylesheet for single file output, that is not useful for +generated EPUB3. + +You should set the $base.dir stylesheet param to the +subdirectory that will contain the .xhtml files and +the epub package files. Here is an example using xsltproc: + +xsltproc \ + --stringparam base.dir ebook1/OEBPS/ \ + epub3/chunk.xsl \ + mybook.xml + +After processing a document with this setting, you should find +the following output: + +ebook1/mimetype - required mimetype file. +ebook1/META-INF/container.xml - required container file +ebook1/OEBPS/package.opf - required package file +ebook1/OEBPS/toc.ncx - optional NCX file for backwards compatibility +ebook1/OEBPS/docbook-epub.css - CSS file +ebook1/OEBPS/*.xhtml - The chunked content files. + + +2. Copy image files +--------------------------- + +Manually copy any image files used in the document +into the corresponding locations in the $base.dir +directory. For example, if your document contains: + + + +In this example base.dir, you would copy the file to: + + ebook1/OEBPS/images/caution.png + +You can get a list of image files from the manifest file +named ebook1/OEBPS/package.opf that is created by the +stylesheet. It includes references to image files for +callouts and admonitions if they are used in the output. +Note that the header and footer images are turned off for +EPUB3 output. + + +3. Create the epub3 file. +----------------------------- +Change to the directory containing the base.dir (ebook1 +in this example), and run the following zip command to +create the epub file: + +zip -r -X mybook.epub mimetype META-INF OEBPS + +The -r option means recursively include all directories. +The -X option excludes extra file attributes (required by epub3). +The "mybook.epub" in this example is the output file. +The other three arguments must appear in this order. + + +4. Validating with epubcheck 3 +----------------------------------- + +There is a java program that can be used to check an +epub3 file for conformance. It is currently available +from this website: + + http://code.google.com/p/epubcheck/wiki/EPUBCheck30 + +That website provides a download link, and information on +how to run the command. + + +Testing with EPUB readers +---------------------------- +The EPUB3 standard is not yet widely supported. The output of +these stylesheets has been tested in the following readers: + +Apple iBooks on an iPod and iPad. + - Handles videodata and audiodata. + - Does not format MathML yet. + - Handles SVG. + +Firefox browser with the EPUBReader version 1.4.10 add-on. + - Formats MathML nicely. + - Does not handle videodata or audiodata yet. + - Handles SVG. + +Ibis EPUB3 preview version + - Does not format MathML yet. + - Does not handle videodata or audiodata yet. + - Handles SVG with external viewer. diff --git a/xsl/xhtml5/README b/xsl/xhtml5/README new file mode 100644 index 000000000..c0db6b7e5 --- /dev/null +++ b/xsl/xhtml5/README @@ -0,0 +1,61 @@ +DocBook stylesheets for HTML5 output +============================================= + +This directory contains XSL stylesheets +for generating HTML5 output from DocBook content. +For information on HTML5, see: + +http://dev.w3.org/html5/spec/Overview.html + +Note that there is no schema available for HTML5, by design. + +The output of these stylesheets is the XML serialization of +HTML5. There is no provision for generating the HTML +serialization of HTML5 with these stylesheets. + +These HTML5 stylesheets are also used by the EPUB3 +stylesheets included in this distribution. + +These stylesheets are customizations of the +existing stylesheets in the "xhtml/" directory. +Using a customization layer enables the HTML5 +stylesheets to inherit all the features of the +XHTML stylesheets while making the minimum changes +for them to produce valid HTML5. + +If you are processing DocBook 5 document, you should use +the namespaced version of the stylesheets, with "-ns-" +in the directory name. + + +Usage +----------- +You should be able to apply any of these stylesheet files +to a DocBook document as with any other DocBook stylesheet: + +xhtml5/docbook.xsl - Single file output. +xhtml5/chunk.xsl - Chunked output. +xhtml5/profile-docbook.xsl - Profiled single file output. +xhtml5/profile-chunk.xsl - Profiled chunk output. +xhtml5/chunkfast.xsl - Chunked output with precomputed chunks. + +Do not attempt to directly use the following two stylesheet files: + +xhtml-docbook.xsl +xhtml-profile-docbook.xsl + +Those are copies of the corresponding files in the +xhtml/ directory, modified to remove the doctype +declarations in the xsl:output elements. They were also +modified to import from the original xhtml/ directory. +They will produce xhtml output, not HTML5 output. +They are imported by the xhtml5 stylesheet files. + +Testing +-------------- + +The HTML5 output of these stylesheets should pass the +W3C online validator, available here: + +http://validator.w3.org/ +