diff options
Diffstat (limited to 'support/latex2nemeth/README')
-rw-r--r-- | support/latex2nemeth/README | 129 |
1 files changed, 129 insertions, 0 deletions
diff --git a/support/latex2nemeth/README b/support/latex2nemeth/README new file mode 100644 index 0000000000..a6f6011dd9 --- /dev/null +++ b/support/latex2nemeth/README @@ -0,0 +1,129 @@ +Latex2Nemeth +============ +Version 1.0.1 + +This is the source tree for Latex2Nemeth, a tool for translating TeX files to Braille. + + +* [Licence](#licence) +* [Dependencies](#dependencies) +* [Installing](#installing) +* [Usage](#usage) + +Licence +------- + +Copyright 2016-2017 by Andreas Papasalοuros, Antonis Tsolomitis. + +This program is distributed under the GPL, version 3 or later. Please see the COPYING file for details. + +Dependencies +------------ + +In order to use the tool, you need the following programs: + +1. **Java** + + The tool has been tested with `Java 7` and `Java 8`. + +2. **Apache Maven** + + Apache Maven is a software project management and comprehension tool. + - For Windows, download the [latest version](https://maven.apache.org/download.cgi). + - For Linux, install it from the repositories: + + sudo apt-get install maven + + +Installing +---------- + +* Download Latex2Nemeth's sources. E.g. for anonymous access on SourceForge: + + git clone git://git.code.sf.net/p/latex2nemeth/code latex2nemeth-code + +* Compile Latex2Nemeth. + + cd /path/to/latex2nemeth + mvn package -Dmaven.test.skip=true + +* **[Optional]** You can compile and also run the tests with `mvn package` + +Usage +----- + +After compiling the tool the executable `jar` will be located in the `target/` directory, +e.g. `target/latex2nemeth-v1.0.1.jar`. + +A simple to way to run the tool is + + java -jar <latex2nemeth.jar> <tex-file> <aux-file> + +**Options** + +|Option|Description| +|------|-----------| +|-e,--encoding <arg> | The encoding table for Braille Mathematical symbols in the form of a JSON file. If not specified, default Nemeth table is used. | +| -m,--mode <arg> | The mode of the parser which controls the type of the output Braille files. It can be either 'nemeth' or 'pef'. The default mode is nemeth.| +| -o <arg> | The output prefix of the Braille files. It can also be prefixed with a path to a specific directory. The default value is the name of the TeX file. The program generates an output file for each chapter in the input TeX file.| + +**Examples** + A simple example: + java -jar target/latex2nemeth-v1.0.1.jar src/test/resources/com/latex2nemeth/bootstrap/mathtest.tex src/test/resources/com/latex2nemeth/bootstrap/mathtest.aux + + A more complicated example: + java -jar target/latex2nemeth-v1.0.1.jar src/test/resources/com/latex2nemeth/bootstrap/mathtest.tex src/test/resources/com/latex2nemeth/bootstrap/mathtest.aux -o ch -m nemeth -e src/test/resources/com/latex2nemeth/bootstrap/nemeth.json + + An example with pictures: + java -jar target/latex2nemeth-v1.0.1.jar src/test/resources/com/latex2nemeth/bootstrap/mathpics.tex src/test/resources/com/latex2nemeth/bootstrap/mathpics.aux + +**Notes** +------------- +1. Input tex files must be in utf-8. If using another encoding (such as iso-8859-7) + run first LaTeX to produce the aux file and then convert the source.tex to utf-8 + with a command such as + + iconv -f iso8859-7 -t utf-8 source.tex > source-utf8.tex + + or using your editor. Now run "java -jar latex2nemeth-v1.0.1.jar" as above with + source-utf8.tex as the tex file and source.aux as the aux file. If errors are + produced you need to modify the source-utf8.tex at the line indicated. + Usually the errors have to do either with non supported shortcuts for macros + (in which case replace the shortcut with the true code) or with macros that + are irrelevant to the blind (in which case remove them). + +2. Braille/Nemeth output files are encoded in UTF-16. + Convert them to utf-8 with a command such as + + iconv -f utf-16 -t utf-8 source.nemeth > source-utf8.nemeth + + (This step will be eliminated in future releases and the output will be directly + in utf-8.) + +3. To emboss the output open the produced source-utf8.nemeth in LibreOffice + with the odt2braille plugin installed, open it as "Unicode UTF-8 encoded text" + and emboss as usually. + +4. Pictures are exported separately in text files. Currently only `pstricks` pictures are supported. +Currently their preable is hardcoded in `com.latex2nemeth.utils.Preamble`. + +5. In order to save space when braille pages are embossed a paragraph change corresponds +to three spaces. Thus commands such as \\ (double backslash) are transcribed as three spaces. +However, there are cases, such as in poems, that a change of line must occur from line to line. +To support these cases, a new latex-type command, named \latextonemethnewline +is understood by the program, which produces a new line. So the double backslash +at the end of each line of a poem must be substituted by \latextonemethnewline. For LaTeX to run +smoothly a \newcommand can be introduced in the preamble, such as +\newcommand{\latextonemethnewline}{\newline} + +6. It is possible to translate TeX files using different Braille alphabets. A different Braille alphabet +is encoded in a JSON file. For example, in order to translate a texfile into polytonic Greek, the command is as follows: + + java -jar latex2nemeth-v1.0.1.jar texfile.tex auxfile.aux -e /path/to/polytonic.json + +Please report issues related to erratic output to a n d p a p a s [AT] a e g e a n . g r +and issues related to the tex file handling/modifying to a n t o n i s . t s o l o m i t i s [AT] g m a i l . c o m + +The project was supported by the Research Unit of the University of the Aegean (project 2625). + + |