TeXmacs in 60 minutes
This document will enable
you to quickly understand what you can do with TeXmacs, how you can
install it under Windows, and how to get started using it. For the
official source of information see texmacs.org.
1. Stable Features and Current Issues
To know about features and issues of a software plays a key role in
deciding whether is is sensible to start working with it: Are the bugs
small and the workarounds painless enough to justify the benefits?
Features
The following is an incomplete list of features, just to give an idea
what you can do with TeXmacs.
- Creating and editing structured text
- The usual constructs from LaTeX: Title, Author, Abstract,
Section, are available
- Same holds for environments like Tabular, Figure as well as
for mathematical environments like definition, theorem, proof
- Mathematical content can be imputted as known from LaTeX, and
by alternative ways
- Inclusion of graphics:
- Labels for pages, equations, and environments and references
thereof
- Citations and Bibliography based on BibTeX
- Automatically generated (and updated) Table of content,
Bibliography, etc.
- Importing and exporting
- HTML
- LaTeX
- Scheme
- Verbatim
- XML
- PS (export only)
- PDF (export only)
- Interface for computer algebra systems. There are two
possibilities: have the system installed under Cygwin, or call it
remotely.
- Maxima: available under Cygwin, not tested yet
- REDUCE: runs nicely remotely, about to get a local version
running
Issues (mostly Windows specific)
Although most of the core functionality works fine out of the box,
there are some known issues with current versions. Most of them are
restricted to the Windows setting.
- The XWin-32 AltGr-key issue.
Description: XWin-32 is a commercial
X-Windows server from Starnet. E.g. on a german keyboard, you have the
AltGr (Gr means Graph) key, which is needed for essential characters
like {[]]}~\. This key does not work. Workaround 1: change keybord map
according to this technote.
Workaround 2: Use XWin, the free
X-Windows server, which comes with Cygwin.
- The XWin copy and paste issue.
XWin is the free X-Windows server,
which comes with Cygwin. After a while of use, copy and past
between
native Windows applications (use Crtl-C and Crtl-V here) and Cygwin
applications (use left and middle mouse button) ceases to work.
Workaroud 1: Close all X-applications and restart XWin. Workaround 2:
Use XWin-32.
- The netpbm issue. To use
formats like .gif, .jpg, .png, .pnm, .ppm, .xpm, etc., this package is
needed, but there is no
official Cygwin package. Solution: Install the inofficial package
from Chuck Wilson by pointing setup.exe to http://www.neuro.gatech.edu/users/cwilson/cygutils/testing/.
After installation, it is necessary to type "export
PATH=$PATH:/usr/local/bin/netpbm" into the shell you start TeXmacs
from. In order not to modify the PATH
variable again and again, you should add the line
"PATH=$PATH:/usr/local/bin/netpbm"
to the file .bash_profile in your home directory.
- The insert image issue.
Description: if you include an image, you
get an error message like "File 'yx.fig' not found", if TeXmacs was not
started from the same directory as this image resides in. Workaround:
Close TeXmacs, change to the directory where the image resides, start
TeXmacs, and include the image.
- The ghostscript issue.
If the Cygwin package ghostscript is
installed, then the X-version is shadowed, and you get an error like
"Unknown device: x11alpha" (see this)
and the included .fig files are broken.
Unfortunately, the script fig2ps needs fig2dev, which is available in
the transfig package under cygwin, which in turn requires the
gostscript package, which leads to the wrong "gs" being used (Unknown
device: x11alpha). Workaround: Run Cygwin's setup.exe and
uninstall the ghostscript
package; futhermore, every time you use setup.exe again, make sure to
manually skip this package, or it will be installed automatically again.
2. Download and Installation
(Windows)
- Get Cygwin. If you don't
have Cygwin installed already, download setup.exe
from cygwin.com and make a default
installation. Otherwise and in case you manually compiled and installed
TeXmacs from source, uninstall it by saying "make uninstall" in the
same directory you once said "make install". In case you want to
start afresh, you can uninstall Cygwin by removing its directory
(usually C:\cygwin) and by running regedit, serarching for "cygnus" in
the registry, and deleting the appropriate key. (The usual warnings for
editing the registry apply!) Read Cygwin FAQ#19 as well.
- Install TeXmacs by
running setup.exe again, but add http://alice.fmi.uni-passau.de/~seidl/cygwin
to the server list and select this location for download. Select under
category "Math" or "Editors" the newest available TeXmacs
version. Optional but recommended: manually deselect the ghostscript
package (see issue above, can be done later). Finish the installation
now.
- Start and test your X by
typing into a Cygwin shell:
- export DISPLAY=127.0.0.1:0.0
- XWin -multiwindow -clipboard &
- xterm &
An additional window should appear. In order not to set the DISPLAY
variable again and again, you should set it as a user's variable
under
Start->Control_Panel->System->Advanced->Environment_variables
- Start TeXmacs by typing
into a Cygwin shell.
- Report problems to the texmacs-users
mailing list, not to the
cygwin list. Please include the following information: (a) the
TeXmacs version you have installed (type "texmacs --version" in a
shell) and/or the Cygwin package version you have installed (type
"cygcheck -s | grep TeXmacs" in a shell), (b) The Windows version you
are using and the file system (fat/ntfs) (c) Do or did you have a
non-Cygwin TeX-installation? (d) Have you installed StarNet's XWin-32?
3. Hands-on Tutorial
Part 1: Title, Author, Abstract, Section and the Style of a Document
- Start TeXmacs. Select Text -> Title -> Maketitle from the
menu
- Type "My little Paper" and hit [return]
- Type some name and hit [return]
- Type in some adress. Meanwhile your document should look like:
- Hit return and choose Insert -> Link -> Hyperlink from the
menu. Type in an url, then hit the cursor [right] key and retype
it. You should see something like:
- Hit [return] to finish the definition of the hyperlink:
- Hit the [right] key three times. Notice, how you gradually leave
the hyperlink, the address, and the title.
- Choose Text -> Title -> Abstract from the menu. Enter some
text.
- Hit the [right] key, and notice how you leave the abstract. Hit
[return], this brings you to the beginning of a new line.
- Choose Text -> Section -> Section from the menu. Type "The
First Section". Hit [return], type some text and hit [return] again.
- Choose Text -> Section -> Subection from the menu. Type
"The First Subsection of the first Section". You see now something like:
- Sections and subsections are not numbered. Select Document ->
Style -> article from the menu, and the numberings appear.
- Hit [return] to get to a new line. There is a second
(LaTeX-style) way to enter sections. Type "\section". You see:
- Hit [return]. Now you have archieved the same as just before by
selecting Text -> Section -> Section from the menu, but without
removing your hands from the keyboard! Type in "The Second Section" and
hit [return]. Type some text.
- Save your file.
This finishes the first part of the hands-on tutorial.
Part 2: Tables and Figures
- Proceed with your file from part 1 or download hot1.tm.
- Create a new line after the heading of the first section.
- Select Insert -> Table -> Big table, and then Insert ->
Table -> Plain block from the menu. (There is an icon as a shortcut
as well, it says "Insert a table" if you move the mouse over it.) You
see:
- By pressing [Alt]+[right] three times, you get three more colums.
Accordingly, by pressing [Alt]+[down] twice you get two more rows.
Navigate with the cursor keys and enter somthing in all the cells.
- Mark the for topmost cells by clicking inside the leftmost cell,
holding the mouse botten pressed, and moving to the rightmost cell
(works as well in the other direction). You see something like:
- Select Table -> Background color -> Yellow. (There is an
icon "Set background color of cell" as well.) Click after "Table 1."
and enter some caption. The result looks like:
- Create a new line after the heading of the first subsection.
- Select Insert -> Image -> Big figure, and then Insert ->
Image
-> Insert image from the menu. (There is an icon as a shortcut as
well, it says "Insert a picture" if you move the mouse over it.) You
get
a dialog, which offers you to load .pdf, .ps, .eps, and .fig images. If
you have installed netpbm, then you will also be able to include jpg,
gif, etc. Select circles-xy.fig. A picture with two circles should be
visible
in the preview window. (ghostscript issue, fig2dev BUG in 1.0.2.10).
- This is too big. To edit the size, hit the [backspace] key.
- Change the factor 5/8 (which means 62.5%) to something else, say
3/8. And hit [return]. You see image again, and it is smaller now.
- Save your file as hot2.tm
This finishes the second part of the hands-on tutorial.
Part 3: Mathematical Content
- Proceed with your file from part 2 or download hot2.tm.
- Go somewhere in the text in Section 2 of the document and type:
$\alpha_1[right],\ldots,\alpha_23.
- Type [right] to leave the index, [right] again to leave the math
mode, and hit [space] to insert a space before the word "some".
- Go to the end of the paragraph and make a new line
- Type: \theorem[enter]For a natural number $n\in[return]
- select from the menu the blackboard-bold version of N:
![](13.jpg)
- Type [right] to leave the math environment, then type: it holds:
- Now we want to insert a math display. Select Text ->
Mathematics -> Equation from the menu (or faster, hit A-$).
- Type:
\sum[return]_i=1[right]^n[right]n=\frac[return]n*(n-1)[down]2.
Notice that "*" results in a little space and not in an explicit
multiplication sign. If you press [tab] after "*", then the star is
choosen.
- Alternatively, press thrice [right] and then [return], or simply
press [down] to leave the theorem environment and get to a new line.
- Type: \proof[return]Done by Gauss in elementary school.
- Save your file as hot3.tm
Part 4: References
- Move the cursor just before the text "For a natural number", and
enter: \label[return]theorem:gauss.
- Hit [return] to commit the label. You see a little flag, where
the otherwise invisible label sits. This flag won't be printed. If you
go behind this flag and hit [backspace], then you can edit the label
again. Note: the label's name is not important, you could habe
jused "cat" or "dog", but mentioning the environement (theorem,
section, etc.) helps later when a reference is made.
- Go behind the Section 2 heading and type \label[return]sec:math
- Hit [return] to commit the label.
- Do a similar thing with the table and hit [return].
- Put a label after the equation and hit [return] [under construction: ignore this point
for the moment]
- After that much labels, we finally can refer to them! Go, e.g. at
the end of the document and write: We have seen in Section
\ref[return]sec:math[return]. The result is:
- go on by typing: in the Theorem on page
\pageref[return]theorem:gauss[return] the equation
(\ref[return]eq:gauss[return]).
- Play around, insert some bogus Theorems, sections and pagebreaks
to see how the labels change automatically!
- Save your file as hot4.tm
This finishes fourth part of the hands-on tutorial.
More Tutorial Information
- TeXmacs
with CAS by Chu-Ching Huang: In this chapter, the individual basic
introductions about TeXmacs, core of this book, and the tools about
computer algebra systems, CAS, and graph will be given.
© Andreas Seidl
2003-2004