1.Using GNU TeXmacs as an interface

An important feature of TeXmacs is it's ability to communicate with extern systems. For computer algebra systems or other scientific computation systems, this is typically done in shell-like sessions, in which it is possible to evaluate commands and display the results in a nice, graphical way. Some systems can also be used more in the background as scripting languages.

See Help→Plug-ins for a list of existing plug-ins and more documentation on these systems.

1.Creating sessions

A session can be started from the Insert→Session menu. Since TeXmacs is based on the Scheme language, it is always possible to start a Scheme session using Insert→Session→Scheme. On Unix systems, it is usually also possible to start Bash shell sessions using Insert→Session→Shell. The remainder of the items in the Insert→Session menu depend on the plug-ins which are installed on your system.

A session consists of a sequence of input and output fields and possible text between them. When pressing ↩ inside an input field of a session, the text inside the environment is evaluated and the result is displayed in an output field.

When entering a command in a session, the application attempts to execute it. Several commands may be launched concurrently in the same document, but the output will only be active in the session where the cursor is and at the place of the cursor. Therefore, we recommend to use different buffers for parallel executions.

For each type of extern application, one may choose between sharing a single process by different sessions, or launching a separate process for each different session. More precisely, when inserting a session using Insert→Session→Other, you may specify both a “session type” (Shell, Pari, Maxima, etc.) and a “session name” (the default name is “default”). Sessions with different names correspond to different processes and sessions with the same name share a common process.

In order to finish the process which underlies a given session, you may use Session→Close session. When pressing ↩ in the input of a non-connected system, the system will be restarted automatically. You may also use Session→Interrupt execution in order to interrupt the execution of a command. However, several applications do not support this feature.

In order to evaluate all fields of e.g. a previously created session, you may use Session→Evaluate→Evaluate all. Similarly, Session→Evaluate→Evaluate above and Session→Evaluate→Evaluate below allow you to evaluate all field above or below the current field.

2.Editing sessions

Inside input fields of sessions, the cursor keys have a special meaning: when moving upwards or downwards, you will move to previous or subsequent input fields. When moving to the left or to the right, you will never leave the input field; you should rather use the mouse for this.

Some facilities for editing input, output and text fields are available in the Session→Field menu. Keyboard shortcuts for inserting fields are ⌥↑ (insert above) and ⌥↓. Keyboard shortcuts for removing matching text/input/output fields are ⌥⌫ (remove backwards) and ⌥⌦ (remove current fields).

It is possible to create “subsessions” using Session→Session→Create subsession or ⌥→. In that case, the current input-output field becomes the body of an unfolded subsession. Such a subsession consists of an explanatory text together with the subsession body. Subsessions can be folded and unfolded using ⇧F10 resp. ⇧F11. Subsessions have a nice rendering on the screen when using the framed-session package in Document→Use package→Program.

Notice that input/output fields and subsessions are foldable: when clicking on the prompt with the mouse, you may fold or unfold the entry to hide or show the output. For laptop presentations, this folding and unfolding process is done automatically when traversing your presentation. It is also possible to fold or unfold all fields in a session using Session→Session→Fold all fields and Session→Session→Unfold all fields.

Other useful editing operations are Session→Session→Clear all fields, which is useful for creating a demo session which will be executed later on, and Session→Split session, which can be used for splitting a session into parts for inclusion into a paper.

Example 1. A typical Maxima session is given below. If Maxima is present on your system, then you may put your cursor in one of the inputs, perform some edits, and try to reexecute it.

3.Selecting the input method

By default, TeXmacs will attempt to evaluate the input field when pressing ↩. Multiline input can be created using ⇧↩. Alternatively, when selecting the multiline input mode using Session→Input mode→Multiline input, the ↩ key will behave as usual and ⇧↩ may be used in order to evaluate the input field. Notice finally that certain systems admit built-in heuristics for testing whether the input has been completed; if not, then the ↩ may behave as usual.

Certain applications allow you to type the mathematical input in a graphical, two dimensional form. This feature can be used by selecting Session→Input mode→Mathematical input. If this feature is available, then it is usually also possible to copy and paste output back into the input. However, it depends on the particular application how well this works. Keep in mind that some key combinations may be used by the Mathematical input mode: for instance the key $ is usually redefined inside math mode, so if you want to input it you'll have to type ⇧F5$. You can read more about the prefix key ⇧F5 in “Keyboard shortcuts for text mode”.

Example 2. Below, you will find the previous example session, but now using mathematical input:

4.Plug-ins as scripting languages

TeXmacs provides a few other kinds of additional interfaces to external systems in addition to shell-like interfaces. First of all, it is possible to insert a so called “executable switch” anywhere in the document using Insert→Fold→Executable.

For instance, if Maxima is installed on your system, then Insert→Fold→Executable→Maxima should yield something like

Maxima

. You may enter a Maxima expression in the yellow part of this markup, say

Maxima

diff(x^x,x)

. Using ↩, you may now switch back and forth between the unevaluated input and the evaluated output . Using ⇧↩, you enable multi-line input. This kind of executable switches are very useful for plug-ins such as DraTeX, Eukleides, Feynmf, etc., which are mainly used for the efficient computation and insertion of special graphics inside TeXmacs documents.

Some plug-ins such as Maxima can even be selected as a scripting language using Document→Scripts→Maxima. When doing so, a special Maxima menu will appear, which allows for many useful operations directly on formulas. For instance, when putting the cursor inside the formula and pressing ? or Evaluate, the formula gets evaluated automatically to yield .

If a plug-in can be used as a scripting language, then it is possible to create executable switches with links between them. More precisely, assuming that you selected a scripting language from Document→Scripts, you may insert a new executable input field using \! or Insert→Link→Executable input field. As before, when pressing ↩, the current input is evaluated and you will see the corresponding output; you may switch back to the input by pressing ↩ once more.

Contrary to executable switches, you may attach an identifier to the executable input field by deactivating the field or by editing the Ref field in the focus bar. Inside other executable input fields, you may then refer to the value of the field by inserting a field reference using \? or Insert→Link→Field reference. As a variant to executable input fields, you may sometimes prefer to insert plain input fields using \\ or Insert→Link→Input field. These fields can only be used as inputs and pressing ↩ inside such a field will only recompute those other fields which depend on it.

Example 3. The executable input fields may for instance be nice in pedagogic documents in which parts of the document may be modified and recomputed by the reader. For instance, evaluation of the input fragment

yields

Of course, if the reader changes the input function into something else and presses ↩, then the first and second derivatives will be updated automatically.

5.Spreadsheets

TeXmacs provides rudimentary spreadsheet-like facilities with the advantage that the computations can be carried out using any of the plug-ins that can be used as a scripting language. In order to use the spreadsheet facilities, you should therefore start with the selection of a scripting language in the menu Document→Scripts.

As soon as you have selecting a scripting language, such as Maxima, then you may enter a new spreadsheet using Insert→Table→Textual spreadsheet or Insert→Table→Numeric spreadsheet. You may edit the spreadsheet as an ordinary table, except that the ↩ key will attempt to reevaluate the cells of the table.

In addition, when preceding the contents of a cell by =, then cell will be considered as an input-output switch. More precisely, the input is a formula which will be evaluated using the current scripting language. After the evaluation, only the result of the evaluation is shown in the cell. After pressing ↩ a second time in the cell, it will be possible switch back and edit the input. In the formulas, one may refer to the others using names such as c5 for the third row and the fifth column.

Example 4. On the left-hand side of the figure below, we have displayed a simple table with formulas for evaluating the sums of the first two items of each row. On the right-hand side, we have shown the result after evaluation.

Example 5. The cells may contain mathematical formulas and the spreadsheet may take advantage of any of the capacities of the scripting language. For instance, the figure below demonstrates another possible use of Maxima.

TeXmacs supports a few special notations for applying operations on all cells in a subtable. For instance, as in Excel, one may use the notation c3:d5 for indicating all cells c3, c4, c5, d3, d4, d5 in the block from c3 to d5. An alternative notation for : can be entered by typing ,,. In a similar way, one may enter the special notation by typing ++. For instance, c3d5 stands for the sum of all cells between c3 and d5.

Example 6. The figure below shows an example on how to use taking sums of cells. Notice that empty cells count for zero.

Notice that copying and pasting of subtables works in the same way as for ordinary tables, with the additional features that the names of the cells and references to cells in the formulas are renumbered automatically. Similarly, automatic renumbering is used when inserting new columns or rows, or when removing existing columns or rows.

We also notice that field references can be used inside spreadsheet cells in order to refer to some computational markup outside the table. Inversely, each spreadsheet also carries an invisible Ref field which can be edited by deactivating the spreadsheet or from the focus bar (when selecting the entire spreadsheet). The Ref field of the spreadsheet is used as a prefix for referring to the contents of cells outside the table or from within other spreadsheets. For instance, if Ref equals sheet, then sheet-c4 will refer to the field c4 inside the spreadsheet.

6.Remote plug-ins

It sometimes happens that certain plug-ins are only installed on a remote computer. In many cases, it will still be possible to use such a plug-in inside TeXmacs over an SSH connection.

In order to make this work, you first have to make sure that SSH is installed on both computers and that connecting by SSH to the remote machine can be done automatically, without having to type a password. This can be done by copying your public identity on the local server to the remote server into the file ~/.ssh/authorized_keys; see the documentation on SSH for more information.

As the next step, you have to make sure that TeXmacs has been installed on both computers. The remote TeXmacs installation will mainly be used in order to detect which plug-ins can be used on the remote computer.

When everything has been set up correctly in this way, select Insert→Session→Remote in order to open the remote plug-in selector. Add the name of the remote server by typing its name or IP address and clicking on Add. After a small pause, the remote server should appear in the list together with the remote plug-ins which are supported. You may now simply select the plug-in you want to use from the list. Notice that remote plug-ins may take a few seconds in order to boot. Please be patient while booting is in progress.

Servers which have been added to the list of remote plug-in servers will be remembered at the next time when you start TeXmacs. You may use the buttons Remove and Update in order to remove a server from the list and to redetermine the list of supported remote plug-ins.