Links and automatically generated content

1.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 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 ⌘I> 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 ⌘I* 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 ⌘II 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.

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.

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, and the Netpbm tools. 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 InsertAutomaticTable 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 DocumentPage…), 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

Editing files with bibliographic entries

TeXmacs uses the BibTEX model for its bibliographies. Manuals about BibTEX can easily be found at various places on the web. BibTEX 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 BibTEX files, so several editors can easily be used in conjunction.

The built-in editor for BibTEX files is automatically used for files with the .bib extension. New items can easily be added using InsertDatabase 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 FocusInsert above and FocusInsert below.

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

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:

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 ⌘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 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 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 InsertLinkAlternateBibliography, 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:

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 InsertLinkAlternateBibliography and enter bib2 on the prompt. Next insert the bibliography as usual, via InsertAutomaticBibliography. Now do DocumentUpdateAll 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 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, until One next creates one file for the whole book, in which the files, until are included using the above mechanism. The table of contents, bibliography, etc. are usually put into

In order to see cross references to other chapters when editing a particular chapter, one may specify as a “master file” for the files to using ToolsProjectAttach 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.