Links and automatically generated content

1.Creating labels, links and references

You may create a new inactive label using M-! or Insert→Link→Label and a reference to this label using M-? or Insert→Link→Reference. After typing the name of the label or reference, remember to hit return in order to activate it. You may also type the first characters of the name of a reference and use the tab key in order to automatically complete it.

You should be careful to put the label at a point where its number will be correct. When labeling sections, the recommended place is just after the sectional tag. When labeling single equations (created using Insert→Mathematics→Equation), the recommended place is at the start inside the equation. When labeling multiple equations (created using Insert→Mathematics→Equations), you must put the labels just behind the equation numbers. Recall that you may use A-* in order to transform an unnumbered environment or equation into a numbered one, and vice versa.

It is possible to create hyperlinks to other documents using M-i > or Insert→Link→Hyperlink. The first field of the hyperlink is the associated text, which is displayed in blue when activated. The second field contains the name of a document, which may be on the web. As is usual for hyperlinks, a link of the form #label points to a label in the same document and a link of the form url#label points to a label in the document located at url.

In a similar fashion, an action may be associated to a piece of text or graphics using M-i * or Insert→Link→Action. The second field now contains a Guile/Scheme script command, which is executed whenever you double click on the text, after its activation. For security reasons, such scripts are not always accepted. By default, you are prompted for acceptation; this default behaviour may be changed in Options→Security. Notice that the Guile/Scheme command

    (system "shell-command")

evaluates shell-command as a shell command.

Finally, you may directly include other documents inside a given document using M-i i or Insert→Link→Include. This allows you for instance to include the listing of a program in your text in such a way that your modifications in your program are automatically reflected in your text.

2.Inserting images

You can include images in the text using the menu Insert→Image. Currently, TeXmacs recognizes the ps, eps, tif, pdf, pdm, gif, ppm, xpm and fig file formats. Here, gs (i.e. ghostscript) is used to render postscript images. If ghostscript has not yet been installed on your system, you can download this package from

    www.cs.wisc.edu/~ghost/index.html

Currently, the other file formats are converted into postscript files using the scripts tiff2ps, pdf2ps, pnmtops, giftopnm, ppmtogif, xpmtoppm. If these scripts are not available on your system, please contact your system administrator.

By default, images are displayed at their design size. The following operations are supported on images:

• Clipping the images following a rectangle. The lower left corner of the default image is taken as the origin for specifying a rectangle for clipping.
• Resizing an image. When specifying a new width, but no height at the prompt (or vice versa), the image is resized so as to preserve the aspect ration.
• Magnifying the image. An alternative way to resize an image, by multiplying the width and the height by a constant.

We also included a script to convert pictures, with optional LaTeX formulas in it, into encapsulated postscript. In order to include a LaTeX formula in an xfig picture, we recall you should enter the formula as text, while selecting a LaTeX font and setting the special flag in the text flags.

3.Generating a table of contents

It is very easy to generate a table of contents for your document. Just put your cursor at the place where you want your table of contents and click on Text→Automatic→Table of contents.

In order to generate the table of contents, you should be in a mode where page breaks are visible (select paper in Document→Page→Type), so that the appropriate references to page numbers can be computed. Next, use Document→Update→Table of contents or Document→Update→All to generate the table of contents. You may have to do this several times, until the document does not change anymore. Indeed, the page numbers may change as a result of modifications in the table of contents!

4.Compiling a bibliography

At the moment, TeXmacs uses bibtex to compile bibliographies. The mechanism to automatically compile a bibliography is the following:

• Write a .bib file with all your bibliographic references. This file should have the format of a standard bibliography file for LaTeX.
• Use Insert→Link→Citation and Insert→Link→Invisible citation to insert citations, which correspond to entries in your .bib file.
• At the place where your bibliography should be compiled, click on Text→Automatic→Bibliography. At the prompt, you should enter a bibtex style (such as plain, alpha, abbrv, etc.) and your .bib file.
• Use Document→Update→Bibliography in order to compile your bibliography.

Notice that additional BiBTeX styles should be put in the directory ~/.TeXmacs/system/bib.

5.Generating an index

For the generation of an index, you first have to put index entries in your document using Insert→Link→Index entry. At a second stage, you must put your cursor at the place where you want your index to be generated and click on Text→Automatic→Index. The index is than generated in a similar way as the table of contents.

In the Insert→Link→Index entry menu, you find several types of index entries. The simplest are “main”, “sub”, “subsub”, which are macros with one, two and three arguments respectively. Entries of the form “sub” and “subsub” may be used to subordinate index entries with respect to other ones.

A complex index entry takes four arguments. The first one is a key how the entry has to be sorted and it must be a “tuple” (created using M-i <) whose first component is the main category, the second a subcategory, etc. The second argument of a complex index entry is either blank or “strong”, in which case the page number of your entry will appear in a bold typeface. The third argument is usually blank, but if you create two index entries with the same non-blank third argument, then this will create a “range” of page numbers. The fourth argument, which is again a tuple, is the entry itself.

It is also possible to create an index line without a page number using “interject” in Insert→Link→Index entry. The first argument of this macro is a key for how to sort the index line. The second argument contains the actual text. This construct may be useful for creating different sections “A”, “B”, etc. in your index.

6.Compiling a glossary

Glossaries are compiled in a similar way as indexes, but the entries are not sorted. A “regular” glossary entry just contains some text and a page number will be generated for it. An “explained” glossary entry contains a second argument, which explains the notation. A “duplicate” entry may be used to create a page number for the second occurence of an entry. A glossary line creates an entry without a page number.

7.Books and multifile documents

When a document gets really large, you may want to subdivide it into smaller pieces. This both makes the individual pieces more easily reusable in other works and it improves the editor's responsiveness. An entire file can be inserted into another one using Insert→Link→Include. In order to speed up the treatment of included documents, they are being buffered. In order to update all included documents, you should use Tools→Update→Inclusions.

When writing a book, one usually puts the individual chapters in files c1.tm, c2.tm until cn.tm. One next creates one file book.tm for the whole book, in which the files c1.tm, c2.tm until cn.tm are included using the above mechanism. The table of contents, bibliography, etc. are usually put into book.tm.

In order to see cross references to other chapters when editing a particular chapter ci.tm, one may specify book.tm as a “master file” for the files c1.tm to cn.tm using Document→Master→Attach. Currently, the chapter numbers themselves are not dealt with by this mechanism, so you may want to manually assign the environment variable chapter-nr at the start of each chapter file in order to get the numbering right when editing.