gletex documentation: Print version
« 
André Wobst, 2001/10/10, 04:48 PM
| http://www.wobsta.de/uni/gletex/print.shtml.en gletex documentation: Print version |
»« André Wobst, 2001/10/10, 04:48 PM |
gletex is an extension of gle (see also http://www.uark.edu/misc/vlabella/gle/gle.html). It adds two commands to the syntax of gle for writing TeX and LaTeX expressions directly within a gle file. gletex runs (La)TeX and dvips to convert the given expressions to encapsulated postscript files and replaces the gletex commands by the according gle include postscript command. After the correct replacement of all (La)TeX expressions gle is started to generate the hole figure as an encapsulated postscript file.
The temporary created encapsulated postscript files are stored in a database. The files are reused if the same (La)TeX expression appers again. When the number of stored files exceeds a variable limit (default value is 50), the for the longest time unused files are removed.
The command line of gletex is:
gletex [-verbose] [-dbsize<size>] [["-dvips <option>"] <file>[.gle]]
You have to give a modification of the database size (option "-dbsize<size>") or a gletex file for execution, otherwise a usage message is printed out. The same happens if an error in the command line is found. If a change of the database size is combined with the execution of a gletex file, first the database size is modified and then the gletex file is executed. The flag "-verbose" turns on additional messages. The -dvips <option> can be used to give some special parameters to dvips during the conversion of the (La)TeX expressions. This option is for experts only.
Basically gletex forwards the given file to gle only, but the following two additional commands are implemented:
tex "<TeX-expression>" <size> "<position>"
latex "<LaTeX-expression>" <size> "<position>"
<TeX-expression> stands for a TeX expression, while <LaTeX-expression> consequently stands for a LaTeX expression. The exclamation mark itself within such an expression must be written as two coherent excalamtion marks.
When TeX is used, <size> is a number from 0 to 5. It is replaced with \magnification=\magstep<size> in front of the TeX expression. In case of LaTeX numbers from 10 to 12 are possible and stand for the font size 10pt to 12pt of the LaTeX article style. Additionally the font size may be altered with the usual LaTeX size commands like \Large within the LaTeX expression.
Finally the position parameter <position> uses the same abbreviations like the gle command "set just", which are bl, bc, br, lc, cc, rc, tl, tc, tr and reversed letter combinations. This fix the alignment of the (La)TeX output regarding the current position.
tex "$\vec a$" 2 "cc"
A vector might be the most simple example where TeX is needed within gle. Although TeX fonts are available in gle, complex formulas can't be written.
latex "$$\sum_{n=1}^{\infty}\frac{1}{n^2}=\frac{\pi^2}{6}$$" 11 "bl"
This formula is written with LaTeX commands. This might be easier for everyone, who is more familiar with LaTeX than with plain TeX. But TeX commands executed more quickly, because LaTeX needs more time during startup due to its macros. $$ instead of a single $ for switching into (La)TeX mathematical modus might be useful for large terms, because (La)TeX shrinks the hight of mathematical terms within normal text, which is done inside single $'. But $$ switches into a full line mathematical modus (see LaTeX command "\displaystyle"), which is preferred by most users.
tex "\input colordvi.tex \textColor{c m y k} text example" 2 "cc"
This is an easy way for writing colored text with (La)TeX and gletex. c, m, y, and k describe the CMKY code of the color (c=cyan, m=magenta, y=yellow, and k=black) and can be values from zero to one. The same color in gle can be created with the undocumented command cvtrgb(r,g,b), which can be written instead of a color name. The letters r, g, and b are the RGB code of the color (r=red, g=green, and b=blue) and can be numbers from zero to one. The conversion to CMKY is c=1-r, m=1-g, b=1-y, and k=0. By the way, the color white within a (La)TeX expression might be used for an alignment. gletex uses the bounding box of the created encapsulated postscript file to align the (La)TeX expression. Therefore white text can be used to align the output. This solution is sloppy, but it might be used to prevent time consuming manual alignments.
tex "\hsize=50truecm This text is a example for a long line, which \TeX should not break into several lines." 4 "cc"
Large (La)TeX texts are splitted into several lines to fit the paragraph width. Sometimes this behavior is disturbing within gletex. For instance, if you want to print something in landscape format. A simple solution for this problem is to set the page width to a value large enough to prevent the line breaks. Additionally the following lines are useful while plotting A4 pages in landscape format:
size 21 29.7
amove 10.5 14.85
begin rotate 90
begin translate -4.35 4.35
...
end translate
end rotate
Multiple simultaneous execution of gletex can create inconsistent states of the internal database and therefore wrong outputs. Once such state is reached, the problem remains even if gletex is started again. Usually gletex recognizes the problem of multiple starts with a simple file locking mechanism. gletex stops then with a message that it is not allowed to run gletex twice at the same time. The failure of this mechanism is somehow academic.
An inconsistent database state is also created if gletex is canceled during its execution, but then you'll get the problem description message for sure next time you run gletex. The inconsistent database should be deleted by running "rm -rf ~/.gletextemp" in this case.
There are some additional restrictions. The following list has mainly infomativ character and doesn't necessarily describe all possible problems.
The directory ~/.gletextemp is used to store temporary created files used for replacement of the (La)TeX expressions. The produced encapsulated postscript files are not deleted after running gle, because they can be reused, if the same expression occurs again later. This causes a substantial faster processing of gletex files once the (La)TeX expressions are available in the database.
Additionally to the encapsulated postscript files gletex stores an index file containing the expressions available in the database. Furthermore the write access to the database is locked by a lock file. This makes is tolerably stable to ensure that two simultaneously running versions of gletex destroy the database content. The start of a second gletex is disabled if the lock file already exists.
gletex doesn't handle signals currently. Therefore the locking mechanism is still active after killing gletex by <Ctrl>C or an explizit kill command. Then gletex can't run anymore until the database is cleaned up as written in the error message of gletex. The easiest and strongly recommended solution in such a case is to remove the hole database directory by executing "rm -fr ~/.gletextemp" at your shell. Important files are never lost by erasing this directory, because all the datas temporary stored there are automatically reproduced by gletex if they are needed again. If you rerun gletex on you last processed files, only the execution of gletex is slowed down.
gletex v0.10 (alpha) from June 3 1997 was the first implementation of gletex (which was written in awk!). The idea for this project came from Prof. Ingold - many thanks to the mental father of gletex. This first version has used an existing program from Prof. Ingold named psformel for creating the encapsulated postscript files. An error corrected version - gletex v0.11 (alpha) from June 6 1997 - was successfully used for a few month. In this version all the TeX expressions have been recreated every time gletex was started. But it became obvious that the usage could be improved considerably by temporary storage of the most recent TeX expressions.
gletex v0.20 (beta) from October 21 1997 implemented such a temporary storage. Due to the higher complexity C was used instead of awk. A second substantial change in this version was an error handling for wrong TeX expressions. This version was successfully in use for about 1½ years.
gletex v0.30 (beta) from May 19 1999 was written again in another language, namely perl. (My personal goal for doing this was to learn perl. Please remember that the program was written by a beginner and my aim was to write a small useful tool in perl rather than a large well done software project.) One benefit of a perl implementation of gletex is the easy installation, because perl is a script language. Additionally some features were added which had been missed in the former version over the years, especially LaTeX support (for people how know LaTeX much better than TeX), flexible database size (previously fixed at 20 enties) and an error return code, which had been missed for calling gletex from make. Another main intention was the backwards compatibility. Some bug fixing (mostly within the gletex file parser) resulted in the versions gletex v0.31 (beta) vom August 4 1999, gletex v0.32 (beta) from February 4 2000 and gletex v0.33 (beta) from March 23 2000, which is the latest version.
First of all you need a machine running an operating system, which means there is a vi editor from scratch. Running or porting gletex on any Microsoft sham operating systems is forbidden explicitly by the author. Additionally the following programs need to be installed in actual versions:
To install gletex the following three files need to be copied in a common directory:
gletex traces sym-links. Therefore it is possible to copy the files into a directory and maka a sym-link to a binary directory.
gletex might be copied under the restrictions written above. Modifications of the program for further development or adaption to other platforms are allowed as long as the original author remains named in the source. Additionally it would be a benefit for the users of gletex to propagate those changes. I'm open for this.
Important notice: There is no warranty of any kind for the program. You use it entirely at your own risk.
| Homepage | Theoretical physics I | Physics department | Augsburg University |