summaryrefslogtreecommitdiff
path: root/support/latex2nemeth/README
diff options
context:
space:
mode:
Diffstat (limited to 'support/latex2nemeth/README')
-rw-r--r--support/latex2nemeth/README129
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).
+
+