tex4ebook (5jul15)

git-svn-id: svn://tug.org/texlive/trunk@37771 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 269 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/support/tex4ebook/README b/Master/texmf-dist/doc/support/tex4ebook/README
new file mode 100644
index 00000000000..73a4e3f46d9
--- /dev/null
+++ b/Master/texmf-dist/doc/support/tex4ebook/README
@@ -0,0 +1,269 @@
+# Introduction
+
+`TeX4ebook` is bundle of Lua scripts and `LaTeX` packages for conversion of
+LaTeX files to ebook formats, for example `epub`, `mobi` and `epub3`. `tex4ht`
+is used as conversion engine. 
+
+Note that while `mobi` is supported by Amazon Kindle, most widespread ebook 
+reader, it doesn't support `mathml` and this means that math must re represented
+as images. The same is true for `epub`. This is not a good thing, especially 
+for inline math, as you may experience wrong baselines. If your ebook contains
+math, the only correct solution is to produce `epub3`, as it supports `mathml`.
+The issue with `epub3` is, that majority of `e-ink` ebook readers doesn't 
+support this format, reader applications exists mainly for Android and Apple 
+devices. For books which contains mainly prose, all formats should be suitable,
+but `epub3` supports most features from web standards, such as `CSS`. 
+
+As with `tex4ht`, the emphasis is on conversion of document's logical structure
+and metadata, basic visual appearance is preserved as well, but you should use
+custom configurations if you want to make the document more visually appealing.
+You can include custom `CSS` or fonts in configuration files.
+
+## License
+
+Permission is granted to copy, distribute and/or modify this software
+under the terms of the LaTeX Project Public License, version 1.3.
+
+
+# Usage
+
+
+Run on the command line:
+
+    tex4ebook [options] filename
+
+You don't have to modify your source files unless you want to use commands
+defined by `tex4ebook` in the document, or when your document uses some
+unsupported package like `fontspec` (see details bellow how to solve this
+issue).
+
+If you want to use `tex4ebook` commands, add this line to your document
+preamble:
+
+    \usepackage{tex4ebook}
+
+but it is optional. You shouldn't need to modify your \TeX\ files
+
+## Available commands
+
+- `\coverimage{coverimage.name}` - include cover image to the document. 
+
+# Command line options
+
+-c,--config 
+
+:    specify custom config file for `tex4ht`
+
+   **example config file**: File `sample.cfg`
+  
+  
+      \Preamble{xhtml}
+      \CutAt{section}
+      \begin{document}
+      \EndPreamble
+  
+  run 
+  
+      tex4ebook -c sample filename.tex
+  
+  This config file will create `xhtml` file for every section. Note that this
+  behaviour is default.
+
+-e,--build-file (default nil)  
+
+:    Specify make4ht build file^[\url{https://github.com/michal-h21/make4ht\#build-file}].
+     Defaulf build file filename is `filename.mk4`, use this option if you use
+     different filename.
+  
+-f,--format (default epub) 
+
+:    Output format. epub, epub3 and mobi are supported.
+
+-l,--lua
+
+:    Runs htlualatex instead of htlatex.
+
+-m,--mode (default default)
+
+:    This set `mode` variable, accessible in the build file. Default supported
+     values are `default` and `draft`. In `draft` mode, document is compiled
+     only once, instead of three times.
+
+-r,--resolution 
+
+:    Resolution of generated images, for example math. It should meet resolution
+     of target devices, which is usually about 167 ppi.
+
+-s,--shell-escape
+
+:     Enable shell escape in htlatex run. This may be needed if you run external
+      commands from your source files.
+
+t,--tidy
+
+:     process output html files with `HTML tidy` command^[It needs to be installed separately].
+
+
+# Configuration
+
+`tex4ebook` uses `tex4ht`^[\url{http://www.tug.org/tex4ht/}] for conversion from LaTeX
+to html. `tex4ht` is highly configurable using config files. Basic config file
+structure is
+
+    \Preamble{xhtml, comma separated list of options}
+    ...
+    \begin{document}
+    ...
+    \EndPreamble
+
+Basic info about command configurations can be found in a work-in-progres 
+ *tex4ht tutorial*^[\url{https://github.com/michal-h21/helpers4ht/wiki/tex4ht-tutorial}]
+, *tex4ht documentation*^[\url{http://www.tug.org/applications/tex4ht/mn11.html}], 
+and in series of blogposts on CV Radhakrishnan's blog:
+*Configure part 1*^[\url{http://www.cvr.cc/?p=323}], 
+*Configure part 2*^[\url{http://www.cvr.cc/?p=362}], 
+*Low level commands*^[\url{http://www.cvr.cc/?p=482}]. 
+Available options for `\Preamble` command are listed in the article 
+*TeX4ht: options*^[\url{http://www.cvr.cc/?p=504}].
+
+Great source of tips for `tex4ht` configuring is *tex4ht tag on TeX.sx*^[\url{http://tex.stackexchange.com/questions/tagged/tex4ht}], there is also a *tag for tex4ebook*^[\url{http://tex.stackexchange.com/questions/tagged/tex4ebook}].
+
+Examples of interesting questions are 
+*including images and fonts in ebooks*^[\url{http://tex.stackexchange.com/a/213165/2891}] 
+or *setting image size in em units instead of pt*^[\url{http://tex.stackexchange.com/a/195718/2891}].
+
+## Provided configurations
+
+`tex4ebook` provides some configurations for your usage:
+
+    \Configure{UniqueIdentifier}{identifier}
+
+
+Every epub file should have unique identifier, like ISBN, DOI, URI etc. 
+Default identifier is URI, with value `http://example.com/\jobname`.
+
+    \Configure{OpfScheme}{URI}
+
+Type of unique identifier, default type is URI. It is
+used only in epub, it is deprecated for `epub3`
+
+    \Configure{CoverImage}{before cover image}{after cover image}
+
+By default, cover image is inserted in `<div class="cover-image">` element, 
+you may use this configuration option to insert different markup, 
+or even to place the cover image to standalone page.
+
+
+    \Configure{CoverMimeType}{mime type of cover image}
+
+Default value is `image/png`, change this value if you use other image 
+type than `png`.
+
+If you don't want to include the cover image in the document, use command 
+
+    \CoverMetadata{filename}
+
+in the config file.
+
+    \Configure{OpfMetadata}{item element}
+
+Add item to `<metadata>` section in the `OPF` file.
+
+    \Configure{OpfManifest}{maifest element}
+
+Add item to `<manifest>` section in the `OPF` file.
+
+    \Configure{xmlns}{prefix}{uri}
+
+Add xml name space to `xhtml` files. Useful in `EPUB 3`
+
+
+
+## Commands available in config files
+
+`\OpfRegisterFile[filename]`
+
+:    register file in the `OPF` file. Current output file is added by default.
+
+`\OpfAddProperty{property type}`
+
+:    add `EPUB3` property for the current file. See *EPUB3 spec*^[\url{http://www.idpf.org/epub/301/spec/epub-publications.html\#sec-item-property-values}]
+
+`\OpfGuide[filename]{title}{type}`
+
+:    Add file to the `<guide>` section in the `OPF` file. See *Where do you    start an ePUB and what is the `<guide>` section of the .OPF
+     file?*^[\url{http://epubsecrets.com/where-do-you-start-an-epub-and-what-is-the-guide-section-of-the-opf-file.php}]
+     for some details. Note that `<guide>` is deprecated in `EPUB 3`.
+
+## Build files
+
+`tex4ebook` uses `make4ht`^[\url{https://github.com/michal-h21/make4ht}] as a build
+system. See `make4ht` documentation for details on build files. 
+
+# Troubleshooting
+
+When compilation of the document breaks with error during `LaTeX` run, it may
+be caused by some problem in `tex4ht` configuration. Comment out line
+`\usepackage{tex4ebook}` in your source file and run command:
+
+    htlatex filename 
+
+if same error as in `tex4ebook` run arises, the problem is in some `tex4ht`
+configuration. Try to identify the source of problem and if you cannot find the
+solution, make minimal example showing the error and ask for help either on
+*tex4ht mailinglist*^[\url{http://tug.org/mailman/listinfo/tex4ht}] or on
+*TeX-sx*^[\url{http://tex.stackexchange.com/}]. 
+
+## Fontspec
+
+`tex4ht` currently doesn't support `fontspec` and open type fonts. At this
+moment, workaround for this is to modify your source file and conditionally
+include fontspec and any other conflicting packages only when document is not
+processed with `tex4ht`. 
+
+Sample:
+
+    \documentclass{article}
+    \makeatletter
+    \@ifpackageloaded{tex4ht}{%
+    % Packages for tex4ht unicode support
+    \usepackage[utf8]{inputenc}
+    \usepackage[T1]{fontenc}
+    \usepackage[english,czech]{babel}
+    }{%
+    % Packages for xelatex
+    \usepackage{fontspec}
+    \usepackage{polyglossia}
+    \setmainfont{Latin Modern Roman}
+    }
+    \makeatother
+
+Drawback is that not all characters of Unicode range are supported with
+`inputenc`. For some solutions of this limitation, see a thread on *tex4ht
+mailinglist*^[\url{http://tug.org/pipermail/tex4ht/2013q1/000719.html}]
+
+## Validation
+
+In case of successful compilation, use command line tool `epubcheck`^[you need
+to install it separately, see \url{https://github.com/IDPF/epubcheck}] to check
+whether your document doesn't contain any errors.
+
+
+Type 
+ 
+    epubcheck filename.epub
+
+### Common validation issues:
+
+-  WARNING: filename.epub: item (OEBPS/foo.boo) exists in the zip file, but is
+not declared in the OPF file
+
+  Delete the `filename-(epub|epub3|mobi)` folder and `filename.epub`. Then
+  run `tex4ebook` again.
+
+- WARNING(ACC-009): hsmmt10t.epub/OEBPS/hsmmt10tch17.xhtml(235,15): 
+MathML should either have an alt text attribute or annotation-xml child element.
+
+  This is accessibility message. Unless you use some macro with annotations for
+  each math instance, you will get lot of these messages. Try to use 
+  `epubcheck -e` to print only serious errors.