diff options
Diffstat (limited to 'Master/texmf-dist/doc/support/tex4ebook/README.md')
-rw-r--r-- | Master/texmf-dist/doc/support/tex4ebook/README.md | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/support/tex4ebook/README.md b/Master/texmf-dist/doc/support/tex4ebook/README.md new file mode 100644 index 00000000000..86f7c8ee09a --- /dev/null +++ b/Master/texmf-dist/doc/support/tex4ebook/README.md @@ -0,0 +1,264 @@ +# 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](https://github.com/michal-h21/make4ht#build-file). + Defaulf build file filename is `filename.mk4`, use this option when it has + 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 + +: Run tidy on output html files. + + +# Configuration + +`tex4ebook` uses [tex4ht](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](https://github.com/michal-h21/helpers4ht/wiki/tex4ht-tutorial) +, [tex4ht documentation](http://www.tug.org/applications/tex4ht/mn11.html), +and in series of blogposts on CV Radhakrishnan's blog: +[Configure part 1](http://www.cvr.cc/?p=323), +[Configure part 2](http://www.cvr.cc/?p=362), +[Low level commands](http://www.cvr.cc/?p=482). +Available options for `\Preamble` command are listed in the article +[TeX4ht: options](http://www.cvr.cc/?p=504). + +Great source of tips for `tex4ht` configuring is [tex4ht tag on TeX.sx](http://tex.stackexchange.com/questions/tagged/tex4ht), there is also a [tag for tex4ebook](http://tex.stackexchange.com/questions/tagged/tex4ebook). + +Examples of interesting questions are +[including images and fonts in ebooks](including images and fonts in ebooks) +or [setting image size in em units instead of pt](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](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?](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](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](http://tug.org/mailman/listinfo/tex4ht) or on +[TeX-sx](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 conditionaly +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](http://tug.org/pipermail/tex4ht/2013q1/000719.html) + +## Validation + +In case of successful compilation, use command line tool `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. |