1.Links and automatically generated content

1.Creating labels, links and references

You may create a new inactive label using ⌘! or Insert→Link→Label and a reference to this label using ⌘?⇥ or Insert→Link→Reference. 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 ⇥ 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 ⌃# 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 ⌘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 ⌘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 ⌘II 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 or using drag-and-drop. Currently, TeXmacs recognizes the ps, eps, tif, pdf, svg, png, pdm, gif, ppm, xpm and fig file formats.

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, using TeXmacs notation for lengths.

• When specifying a new width, but no height at the prompt (or vice versa), the image is resized so as to preserve the aspect ratio. 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.

Remark 1. For the support of certain formats, TeXmacs may rely on external converters to more standard formats such as Ghostscript, ImageMagick, Inkscape, or rsvg-convert. If necessary, then you may consider installing these tools or ask your system administrator.

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 Insert→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 for the Screen rendering option of the Format tab in Document→Page…), 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

Editing files with bibliographic entries

TeXmacs uses the BibT_EX model for its bibliographies. Manuals about BibT_EX can easily be found at various places on the web. BibT_EX files can either be entered and edited using TeXmacs itself or using an external tool. Some external tools offer possibilities to search and retrieve bibliographic entries on the web, which can be a reason to prefer such tools from time to time. TeXmacs implements good converters for BibT_EX files, so several editors can easily be used in conjunction.

The built-in editor for BibT_EX files is automatically used for files with the .bib extension. New items can easily be added using Insert→Database entry. When creating a new entry, required fields appear in dark blue, alternative fields in dark green and optional fields in light blue. The special field inside the header of your entry is the name of your entry, which will be used later for references to this entry. When editing a field, you may use ↩ to confirm it and jump to the next one (blank optional fields will automatically be removed when doing this). When the cursor is inside a bibliographic entry, additional fields may also be added using Focus→Insert above and Focus→Insert below.

BibT_EX contains a few unnatural conventions for entering names of authors and managing capitalization inside titles. When editing BibT_EX files using TeXmacs, these conventions are replaced by the following more user friendly conventions:

• When entering authors (inside “Author” or “Editor” fields), use the name tag for specifying last names (using Insert→Last name or ⇧F6) For instance, “Albert Einstein” should be entered as “Albert Einstein” or as “A. Einstein”. Special particles such as “von” can be entered using Insert→Particle. Title suffices such as “Jr.” can be entered similarly using Insert→Title suffix.

• When entering titles, do not capitalize, except for the first character and names or concepts that always must be. For instance, use “Riemannian geometry” instead of “Riemannian Geometry” and “Differential Galois theory” instead of “Differential Galois Theory”.

Inserting citations and compiling bibliographies

Assuming that you have created a .bib file with your bibliographic references, the mechanism to automatically compile a bibliography is the following:

• 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 Insert→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 Insert→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 ⌘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 occurrence of an entry. A glossary line creates an entry without a page number.

7.Multiple extractions

TeXmacs allows users to create multiple bibliographies, tables of contents, indexes, etc. inside the same document. Let us explain how to do this for bibliographies; the procedure is similar for other types of automatically generated content.

First of all, every separate bibliography is identified by a “name”. The default name of the bibliography is bib. Using Insert→Link→Alternate→Bibliography, it is possible to specify a different bibliography (than the default one) for a certain region of text.

For instance, to specify that a given citation should appear in a second bibliography with name bib2, you should proceed as follows:

• Click on Insert→Link→Alternate→Bibliography and enter bib2 on the prompt. This will insert an empty with-bib tag into your document, with the cursor inside.

• Inside this with-bib tag, enter your citation, using Insert→Link→Citation.

If needed, the with-bib tag can be made to span over a large portion of text. All citations inside this span will be be put into the bibliography with name bib2.

The bibliography bib2 itself should be created in a similar way: first click on Insert→Link→Alternate→Bibliography and enter bib2 on the prompt. Next insert the bibliography as usual, via Insert→Automatic→Bibliography. Now do Document→Update→All as many times as need in order to generate the bibliography and get all links right.

8.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 Tools→Project→Attach master. 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.