README.en

uTeXer
======

About uTeXer
------------

uTeXer is an helper script written in Python to translate unicode math signs and
Latin ligatures into plain text to make them readible for blind computer users.
It can be used for:

- translating formulas from web sites or from PDF's into LaTeX signs
- renice the output of the text versions of PDF's (generated e.g. by pdftotext
  from popplerutils); those are often Latin ligatures or other signs which make
  the texts harder to read.

So this allows blind users the first time to download papers  or other
scientific stuff and read it without a sighted person correcting the formulas.

Download/Installation
---------------------

You can optain a copy by using git:

    git clone https://github.com/humenda/utexer.git

or here [a zip file.](https://codeload.github.com/humenda/utexer/zip/master).

For running uTeXer, you need a working python3 installation. You can use

./install

which installs the program to /usr/local/*, or set PREFIX="/" to install it to
/bin and /share directly (and /opt or /usr respectively).

You can run it also directly from the source(s).

Using uTeXer
------------

uTeXer is a simple program, the help screen should explain most:

    Usage: utexer [options] INPUTFILE
    
    If no output file is specified with the -o option, the input file will be
    overwritten. If no input file is specified, stdin/stdout will be used (but you
    can redirect stdout with -o too).
    
    Options:
      -h, --help            show this help message and exit
      -e ENC, --encoding=ENC
                            Set encoding for stdin (default UTF-8)
      -l, --ligature        replace ligatures through normal letters (at least in
                            Latin languages where they are only for better
                            readibility)
      -o FILE, --output=FILE
                            set output file (if unset, overwrite input file)
      -p, --pdftotext       Replace some signs generated just by PDFtotext
      -s, --strip-pagebreak Strip the newpage character
      -u FILE, --userdict=FILE
                            set path to user-defined replacements/additions for
                            unicode mappings (format described in README)

Where Do The LaTeX-commands Come From / How Do I Customize Them?
----------------------------------------------------------------

The initial unicode table was downloaded from:

http://www.w3.org/Math/characters/unicode.xml

With the -u switch you can supply an additional unicode table to override (or
even add) unicode points. The format is simple:

    <decimal_number><tab><replacement>

Example:

    123	\{

This allows you to customize LaTeX-commands. E.g. I don't like \\varnothing,
\\emptyset seems more intuitive for me.


Known Issues
------------

As said before, uTeXer can not fully translate formulas. Especially formulas who
are bigger than a line, e.g. a fraction, indices and powers are (often) not
recognized, just because they are not marked in unicode, but by changing their
relative height. This only matters for PDF output, ob web pages, people often
use tags to indicate subscripts and so on.

Overline and underlines are also lost!

There are signs in the unicode table which should not be translated or are
translated to not commonly used LaTeX-commands:

- \\varnothing instead of the more common \\emptyset
- { } instead of \\lbrace and \\rbrace, since source code is also replaced