summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/tex4ebook/README
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-07-05 22:09:45 +0000
committerKarl Berry <karl@freefriends.org>2015-07-05 22:09:45 +0000
commitb0f3c5dbdee94cfa9a26b96c6d2f41370392df64 (patch)
treed0cf93aa29ceac864cd09bb63a2eb6b0da68aa83 /Master/texmf-dist/doc/support/tex4ebook/README
parent71f3d121e83be4220bb0b2c160b0f7f33670650c (diff)
tex4ebook (5jul15)
git-svn-id: svn://tug.org/texlive/trunk@37771 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/support/tex4ebook/README')
-rw-r--r--Master/texmf-dist/doc/support/tex4ebook/README269
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.