Links and automatically generated content

1.Creating labels, links and references

You may create a new inactive label using or InsertLinkLabel and a reference to this label using or InsertLinkReference. After typing the name of the label or reference, remember to hit 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 InsertMathematicsEquation), the recommended place is at the start inside the equation. When labeling multiple equations (created using InsertMathematicsEquations), you must put the labels just behind the equation numbers. Recall that you may use 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 inactive > or InsertLinkHyperlink. 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 inactive * or InsertLinkAction. 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 OptionsSecurity. 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 inactive i or InsertLinkInclude. 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 InsertImage. 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 sizes and aligned at their bottom lines. Alternative widths, heights and alignment offsets may be specified in the image chooser dialogue window.

• 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. For instance, entering a width of 1par will make the image span over the entire paragraph width and adjust the height proportionally.

  You may use w and h as special lengths for the default width and height of the image. For instance, specifying 2w and 2h for the width and the height, the image will be displayed at twice its default size.

• When specifying an alternative alignment, you may use the w and h lengths for the displayed width and height (i.e. w and h no longer stand for the default width and height). For instance, using -0.5h for the -offset will vertically align the image at its center.

We also included a script to convert Xfig 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 InsertAutomaticTable of contents.

In order to generate the table of contents, you should be in a mode where page breaks are visible (select paper in DocumentPageType), so that the appropriate references to page numbers can be computed. Next, use DocumentUpdateTable of contents or DocumentUpdateAll 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 InsertLinkCitation and InsertLinkInvisible citation to insert citations, which correspond to entries in your .bib file.
• At the place where your bibliography should be compiled, click on InsertAutomaticBibliography. At the prompt, you should enter a bibtex style (such as plain, alpha, abbrv, etc.) and your .bib file.
• Use DocumentUpdateBibliography 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 InsertLinkIndex entry. At a second stage, you must put your cursor at the place where you want your index to be generated and click on InsertAutomaticIndex. The index is than generated in a similar way as the table of contents.

In the InsertLinkIndex 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 inactive <) 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 InsertLinkIndex 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 InsertLinkInclude. In order to speed up the treatment of included documents, they are being buffered. In order to update all included documents, you should use ToolsUpdateInclusions.

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 DocumentMasterAttach. 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.