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.


Step 1: Stable features and current issues	Step 2: Download and install	Step 3: Hands-on tutorial

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
- texmacs &
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.
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.
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:
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.