DocBook documentation stub added

[stg.git] / doc / help / xslt / epub / README

diff --git a/doc/help/xslt/epub/README b/doc/help/xslt/epub/README
new file mode 100644 (file)
index 0000000..5e2587a
--- /dev/null
+++ b/doc/help/xslt/epub/README
@@ -0,0 +1,88 @@
+----------------------------------------------------------------------
+              README file for the DocBook XSL Stylesheets
+----------------------------------------------------------------------
+
+These are XSL stylesheets for transforming DocBook XML document
+instances into .epub format.
+
+.epub is an open standard of the The International Digital Publishing Forum (IDPF), 
+a the trade and standards association for the digital publishing industry. 
+
+An alpha-quality reference implementation (dbtoepub) for a DocBook to .epub 
+converter (written in Ruby) is available under bin/. 
+
+From http://idpf.org
+  What is EPUB, .epub, OPS/OCF & OEB?
+
+  ".epub" is the file extension of an XML format for reflowable digital 
+  books and publications.  ".epub" is composed of three open standards, 
+  the Open Publication Structure (OPS), Open Packaging Format (OPF) and 
+  Open Container Format (OCF), produced by the IDPF. "EPUB" allows 
+  publishers to produce and send a single digital publication file 
+  through distribution and offers consumers interoperability between 
+  software/hardware for unencrypted reflowable digital books and other 
+  publications. The Open eBook Publication Structure or "OEB", 
+  originally produced in 1999, is the precursor to OPS. 
+
+----------------------------------------------------------------------
+.epub Constraints 
+----------------------------------------------------------------------
+
+.epub does not support all of the image formats that DocBook supports.
+When an image is available in an accepted format, it will be used. The
+accepted @formats are: 'GIF','GIF87a','GIF89a','JPEG','JPG','PNG','SVG'
+A mime-type for the image will be guessed from the file extension, 
+which may not work if your file extensions are non-standard.
+
+Non-supported elements:
+  * <mediaobjectco> 
+  * <inlinegraphic>, <graphic>, <textdata>, <imagedata> with text/XML 
+    @filerefs
+  * <olink>
+  * <cmdsynopsis> in lists (generic XHTML rendering inability)
+  * <footnote><para><programlisting> (just make your programlistings 
+    siblings, rather than descendents of paras)
+
+----------------------------------------------------------------------
+dbtoepub Reference Implementation
+----------------------------------------------------------------------
+
+An alpha-quality DocBook to .epub conversion program, dbtoepub, is provided
+in bin/dbtoepub. 
+
+This tool requires:
+ - 'xsltproc' in your PATH
+ - 'zip' in your PATH
+ - Ruby 1.8.4+
+
+Windows compatibility has not been extensively tested; bug reports encouraged.
+[See http://www.zlatkovic.com/libxml.en.html and http://unxutils.sourceforge.net/]
+
+$ dbtoepub --help
+  Usage: dbtoepub [OPTIONS] [DocBook Files]
+
+  dbtoepub converts DocBook <book> and <article>s into to .epub files.
+
+  .epub is defined by the IDPF at www.idpf.org and is made up of 3 standards:
+  - Open Publication Structure (OPS)
+  - Open Packaging Format (OPF) 
+  - Open Container Format (OCF)
+
+  Specific options:
+      -d, --debug                      Show debugging output.
+      -h, --help                       Display usage info
+      -v, --verbose                    Make output verbose
+
+
+----------------------------------------------------------------------
+Validation
+----------------------------------------------------------------------
+
+The epubcheck project provides limited validation for .epub documents. 
+See http://code.google.com/p/epubcheck/ for details.
+
+----------------------------------------------------------------------
+Copyright information
+----------------------------------------------------------------------
+See the accompanying file named COPYING.
+