Home | | Help | Contribute | Plug-ins | About | Contact | Search
Editing tools
Manual | Top | Previous | Next

In this chapter, we discuss the general editing facilities present in TeXmacs. Besides classical features, like “cut and paste”, “search and replace”, etc., TeXmacs also supports additional functionality which exploits the document structure. Examples of such features are “structured cursor movement” and “structured variants”. It should be noticed that more traditional functions like “search and replace” also attempt to exploit the structure. For instance, when searching x in math mode, you will only find matches which are also in math mode.

1.Cut and paste

You can select text and formulas by maintaining the left mouse button. In order to delete the selected region, use EditCut. In order to copy the selected region, first click on EditCopy. Next, paste it as many times as you want to the location of your cursor, using EditPaste. Alternatively, you may copy a selected region using the middle mouse button.

It is also possible to the change text properties of a selected region. For instance, in order to transform some black text in red, you select it using the left mouse button and click on FormatColorRed. Similarly, if you select a formula and you click on InsertFraction, then the formula becomes the numerator of some fraction.

When using the copy and paste mechanism to communicate with other applications, text is copied and pasted using the TeXmacs data format. You may specify other import and export formats using EditImport resp. EditExport. By default, copying and pasting uses the primary text buffer. Using EditCopy to and EditPaste from, you may specify as many other buffers as you like.

There are two ways to make selections using the keyboard. When using the cursor keys left, right, etc. while holding down the button, you may select text while moving around the cursor. Alternatively, you may press ⌃Space once to fix a starting position. When moving around using the cursor keys, the text between the starting position and the current position keeps being selected. The selection gets cleared when pressing ⌃G.

Notice that the ⌃Space shortcut also allows you to make structured selections. You may select the current word you are in by pressing ⌃Space twice. Each additional time you press ⌃Space results in the selection of the smallest structure which englobes the current selection. Ultimately, when the entire document gets selected, pressing ⌃Space once more clears the selection.

2.Search and replace

You can start searching text by pressing C-s or EditSearch. Doing this, a new special “search toolbar” will appear below the main text, just above the footer. When typing text in the search field of the toolbar, all occurrences of this text will be highlighted in the main document. Moreover, one “principal” occurrence will be highlighted in red and you may navigate through all occurrences using pageup and pagedown (or up and down, or return). Using home and end, you may jump to the first and last occurrences respectively. As soon as you press the escape key escape, the search toolbar will be closed, searching stops and focus returns to the main document.

During a search, only text in the same mode and the same language will be found, as those which are active at the position where you started your search. In other words, when searching an x in math-mode, you will not find any x's in the ordinary text. As a current limitation, the search string can only contain ordinary text and no math-symbols or more complicated structured text.

In order to replace text, you should use EditReplace or press C-=. This will cause a special “replace toolbar” to appear below the main text, just above the footer. You are prompted for a string which is to be replaced and the string by which to replace. Again, you may use the pageup and pagedown keys in order to navigate through the occurrences of the search string. When pressing tab or return in the search field, focus will be moved to the replace field. You may still use the pageup and pagedown keys in order to navigate through the occurrences of the search string. In addition, pressing return will replace the principal occurrence of the search string by the replace string. Using S-return, you may undo the last replacement. You may replace all remaining occurrences by pressing C-return. Like in the case of searching, the query-replace command is mode and language sensitive.

The search and replace toolbars are quite rudimentary in the sense that they only allow for searching and replacing plain text. By pressing the icon on either of these toolbars, you may expand the toolbar into a full blown widget with larger search and replace fields which may contain arbitrary markup. Searching and replacing can be done using more or less the same keyboard shortcuts as in the case of the toolbars, but you may now search and replace arbitrary content.

When searching non textual content, the conditions for having a hit are somewhat released. For instance, assume that you are just starting a new search with an empty search field. Then typing F6 inserts the strong tag with no text inside yet. Instead of looking only for “strong empty strings”, TeXmacs will rather look for all strong markup in your document. If you next enter the letter “a”, then TeXmacs will look for all strong text which contains the letter “a”. In a similar way, when searching for the formula

x
, TeXmacs will highlight all fractions in which the numerator contains the variable x . Yet another example: a search for
sqrt (x)
will highlight all formulas in which the denominator contains a square root which contains the variable x . For instance, the fraction
a + b
c + sqrt (x + y)
will be highlighted, but not
sqrt (x + y)
a + sqrt (y)
.

When using the structured text and replace widgets, TeXmacs also implements a few additional special tags for enhancing structured searching. First of all, it can happen that you would like to search for certain content inside a special context. For instance, you might want to search for all occurrences of the letter “a” inside a strong tag. When searching for a, as above, TeXmacs will highlight all strong tags which contain the letter “a”. In order to highlight the letters “a” themselves, you should first enter the strong tag inside an empty search field using F6. You next enter a special select-region tag using std ?, and finally insert the letter “a” inside this tag. Other special markup which can be used inside search fields are the “wildcards” x, y and z which are entered using std 1, std 2 and std 3.

As soon as you start using the structured text and replace widgets instead of the toolbars, this will be remembered as a user preference: any subsequent searches or replacements will again use the widgets. In order to switch back to the less intrusive toolbar methods for searching and replacing, you should press the icon.

3.Spell checking

If the program ispell has been installed on your system, then you may use it to check your text for misspelled words by pressing ⌘$ or EditSpell. Notice that you might have to verify that the dictionaries corresponding to the languages in which your texts have been written have been installed on your system; this is usually the case for English.

When you launch the spell checker (either on the whole text or a selected region), you will be prompted at each misspelled word and the footer displays the available options:

a)

Accepts the misspelled word and all its future occurrences in the text.

r)

Replace the misspelled word by a correction you have to enter.

i)

Indicate that the “misspelled” word is actually correct and that it has to be inserted in your personal dictionary.

1-9)

Several suggested corrections for your misspelled word.

Notice that ispell just checks for misspelled words. No grammatical faults will be detected.

When starting the spell checker, it will use the dictionary of the language which is active at the current cursor position (or the start of a selection). Only text in that language will be checked for. If your document contains text in several languages, then you will have to launch the spell checker once for each language being used.

4.Undo and redo

It is possible to gradually undo the changes you made in a document from the moment that you launched TeXmacs. This can be done via EditUndo or using the keystrokes ⌘[ or ⌘[. Undone changes can be “redone” using EditRedo or ⌘].

In order to save memory, the number of successive actions which can be undone is limited to 100 (by default). It is possible to increase this number by adding a command like

    (set-maximal-undo-depth 1000)

in our personal initialization file (see HelpScheme). When specifying a negative number as your maximal undo depth, any number of actions can be undone.

5.Structured editing

As a general rule, the behaviour of most structured editing operations is conditioned by the current focus. By default, the innermost tag which contains the cursor. Whenever some selection is active, the current focus is the innermost tag which contains the selection. During structured operations, such as navigating among similar tags, the current focus may temporarily be set to something else. The current focus is visually indicated by the innermost cyan box around the cursor.

For instance, the structured insertion commands ⌥←, ⌥→, ⌥↑ and ⌥↓ have a particular meaning both inside tables and trees. Inside tables, they allow you to insert new rows and columns (see figure ?). Inside trees, they correspond to the insertion of new nodes (see figure ?). Whenever you inside a tree inside a table, then the innermost tag is a tree, and node insertions will take precedence over the insertion of new rows and columns.

In many cases, a “default particular behaviour” has been defined for all tags minus some exceptional ones. In our example of structured insertion, the default behaviour of ⌥← and ⌥→ is to insert a new argument to the tag at the left or at the right (when allowed).

(
a b c
d e f
) (
a b c
d e f
) (
a b c
d e f
) (
a b c
d e f
) (
a b c
d e f
)

Figure 1. Assume that the cursor is at the position of inside the left-most matrix. Then the four other matrices respectively correspond to the insertion of a new column at the left (⌥←) or right (⌥→), resp. a new row above (⌥↑) or below (⌥↓).

Figure 2. Assume that the cursor is at the position of inside the left-most tree. Then the four other trees respectively correspond to the insertion of a new node at the left (⌥←), at the right (⌥→), above (⌥↑) or below (⌥↓).

Similarly, in the case of matrices, the keys ⌥↖, ⌥↘, ⌥⇞ and ⌥⇟ can be used for inserting a new first or last column, resp. a new first or last row. The keys ⌥⌫ and ⌥⌦ are mapped to the commands for backward resp. forward structured deletion. In the case of matrices, this will result in the removal of the column before or after the cursor (see figure ?). In order to remove the enclosing environment you may use ⌃⌫ or ⌃⌫.

(
a b c
d e f
) (
b c
e f
) (
a c
d f
) b

Figure 3. Assume that the cursor is at the position of inside the left-most matrix. Then pressing the keys ⌥⌫ and ⌥⌦ respectively result in the next two matrices. Pressing either ⌃⌫ or ⌃⌫ replaces the matrix by the content of the cell in which you are, leaving you with the b at the right-hand side.

6.Structured cursor movement

TeXmacs implements the three main mechanisms for structured cursor movement:

  1. Traversal of the entire structure of the document.

  2. Traversal of tags which are similar to the innermost tag.

  3. Movements inside the innermost tag.

Most keyboard shortcuts for structured cursor movements can be used in combination with the -key so as to similtaneously select text while moving around.

To do: customizing the behaviour

Structured traversal of the document

The ⌃←, ⌃→, ⌃↑ and ⌃↓ keys are used for the structured traversal of the entire document. Inside plain text, ⌃← and ⌃→ allow you to move in a word-by-word manner, while ⌃↑ and ⌃↓ correspond to paragraph-by-paragraph motion.

In the presence of other markup, the ⌃← and ⌃→ keys allow you to visit all accessible cursor positions of the document, except that we keep moving in a word-by-word manner inside plain text. The behaviour of the ⌃↑ and ⌃↓ keys is more context-dependent. Inside matrices, they typically allow you to move one row up or down.

Traversal of tags which are similar to the innermost tag

This type of cursor movement allows you to quickly visit all other tags in the document which are similar to the innermost tag. The ⌃⇞ and ⌃⇟ keys allow you move to the previous or next similar tags, whereas ⌃↖ and ⌃↘ directly jump to the first or last similar tags.

For instance, when you are inside a section title, you may move to the previous sectional title (which could also be the title of a subsection or a chapter, for instance) using ⌃⇞. Notice that you may use C-§ to jump to the previous section title.

Movements inside the innermost tag

It is also possible to quickly move inside the innermost tag without quitting it. The shortcuts ⌘⌥←, ⌘⌥→, ⌘⌥↖ and ⌘⌥↘ provide a way to move to the previous, next, first or last argument of the innermost tag. Furthermore, the shortcuts ⌘⌥⌫ and ⌘⌥⌦ may be used to exit the innermost tag on the left or on the right.

This default behaviour may be overridden in special contexts. For instance, inside tables or trees, they rather correspond to cell-by-cell or node-by-node cursor movement. In addition, these cases associate vertical cursor movements to ⌘⌥↑, ⌘⌥↓, ⌘⌥⇞ and ⌘⌥⇟.

7.Structured variants

When creating an environment like a theorem, an equation or a list, it frequently happens that one would like to change the environment a posteriori. This can be done using the keyboard shortcuts ⌃⇥ and ⌃⇧⇥ for cycling through the list of structured variants of the innermost tag in a direct or inverse manner.

For instance, assuming that you are inside a theorem, pressing ⌃⇥ several times will change the theorem into a proposition, a lemma, a corollary, a conjecture and back into a theorem. The ⌃⇧⇥ key allows you to cycle in the inverse direction: theorem conjectur corollary lemma proposition theorem.

In the case of mathematical formulas, the ⌃⇥ shortcuts allows you to change an inline formula like a2 + b2 = c2 into a displayed formula like

a2 + b2 = c2

while taking care of potential “trailing spaces and punctuation signs”.

TeXmacs also provides the ⌃# shortcut for turning numbered environments into unnumbered environments and vice versa. This works for most common environments like theorems, remarks, tables, equations, etc. Notice that ⌃# also turns an unnumbered itemize environment into an enumeration and vice versa, whereas ⌃⇥ allows you to cycle between the available kinds of list items (bullets, dashes, arrows, etc.).

8.Positioning and resizing objects

The prefix may be used for positioning and resizing objects. For instance, inside a cell of a table, you may use structured:geometry right to align the cell more to the right. Behind a space introduced via FormatSpace, the same key allows you to increase the width of space. More generally, the following shortcuts are implemented:

⌘←

Decrease the horizontal size of an object, or align more to the left.

⌘→

Increase the horizontal size of an object, or align more to the right.

⌘↓

Decrease/increase the vertical size of an object, or align more to the bottom.

⌘↑

Increase/decrease the vertical size of an object, or align more to the top.

⌘↖

Decrease the horizontal offset of an object, or left align.

⌘↘

Increase the horizontal offset of an object, or right align.

⌘⇟

Decrease the vertical offset of an object, or align at the bottom.

⌘⇞

Increase the vertical offset of an object, or align at the top.

⌘⌫

Revert the geometry (size, position, alignment) to the defaults.

⌘⌃⇥, ⌘⌃⇧⇥

Circulate among available length units for specifying the geometry.

⌘⌃[, ⌘⌃]

Decrease or increase the step size when positioning or resizing.

Particular tags to which the shortcuts apply are the following

Spaces

Both horizontal and vertical spaces from the FormatSpace menu. You should put the cursor just after the space tag for the shortcuts to apply.

Box modifiers

The tags move, shift, resize, extend, clipped, smashed, swell from the FormatAdjust menu.

Animations

The durations of animations can be modified using ⌘← and ⌘→.

Images

The size and alignment of images can be changed.

9.Versioning tools

When writing documents in collaboration with other authors, it frequently arises that one wants to go through changes made by the other authors, and either accept, discard or further correct them. After enabling the versioning tool through EditPreferencesUtilitiesVersioning tool, a special menu Version appears in the main menu bar, which makes this process automatic. Below, we will describe in more detail how this tool works.

In addition, there exist many stand-alone programs for maintaining several versions of a same file, such as Subversion, Git, Darcs, GNU Arch, just to mention a few of them. TeXmacs currently provides a rudimentary support for Subversion, but interfaces for the other systems could easily be added.

Comparing two versions

Assume that we have two versions old.tm and new.tm of the same document. In order to see the changes, first load the newer version new.tm, then click on VersionCompareWith older version and select the older version old.tm. The buffer will still be named new.tm, and the changes between both versions will be indicated by special markup. If there are any changes, then the cursor will be positioned at the first difference. In a similar way, you may compare the current buffer to a newer version on disk using VersionCompareWith newer version.

It is possible to go through all the differences between the old and new versions either from the items in the submenu VersionMove, or using the keyboard shortcuts ⌃↑ and ⌃↓. One may also use the more general structured navigation shortcuts ⌃↖, ⌃↘, ⌃⇞ and ⌃⇟.

Visualization of the differences

Differences between the two versions can be displayed in three ways: by showing only the old version, only the new version, or both versions simultaneously. In all cases, the old version is displayed in dark red and the new version in dark green.

The visualization style can be specified individually for each individual change, via VersionShow or the keyboard shortcuts ⌃← (old version), ⌃→ (new version) and ⌃| (both versions). One may also cycle through the different style using the structured variant key ⌃⇥. If you selected some text, then the above actions will apply to the whole selection. In particular, by selecting the entire file, you can visualize the older or the newer version, or both versions.

Retaining a specific version

It often occurs that we want to go through the changes between two versions and progressively retain either one or the other version for each individual difference. Assuming that the cursor is inside a given difference, this can be done from entries in the submenu VersionRetain. Alternatively, one may use the shortcuts ⌃1, ⌃2 and ? to retain the old, new and currently displayed version, respectively. If both versions are displayed, then ? retains the new version. After retaining one of the versions, we automatically jump to the next difference, which can then be processed.

If you selected some text, then any of the above action will retain the appropriate version for each of the differences in the selection. This applies in particular to the case when you select the entire document. A convenient alternative way to process all differences is to use ⌃↑ and ⌃↓ to go through the differences, use ⌃← and ⌃→ to select the preferred version. As soon as all differences have been processed, you select the entire document and click on VersionRetainCurrent version.

Grain control and reactualizing the differences

The entries in the submenu VersionGrain allow you to control the grain with which differences between versions are computed. By default, we use the finest grain Detailed. It is also possible to compute differences on a paragraph-based level, using Block. In that case, the entire paragraphs in which a change occurs will be highlighted. The roughest grain Rough will highlight the entire text, if a change occurs somewhere inside.

The grain is used when comparing two documents using VersionFileCompare, but it is also possible to change the grain for a selected portion of text: simply select the text and choose the new grain in the submenu VersionGrain. This can in particular be applied on the entire buffer. Similarly, if you change the grain inside a difference, then the difference will be recomputed using the new grain.

Notice that you may also “change” the grain to the current grain. This has the effect of reactualizing the differences of a selected portion or of the current difference at the cursor position. This may be useful, if you made some changes to one of the versions. For instance, assume that the old version contained a theorem and that we changed it into a lemma in the new version and also modified part of its inside text. When visualizing the changes, the whole theorem will be highlighted, since there is no appropriate markup to indicate that we just changed from a theorem to a lemma. Nevertheless, if we want to compare the inside texts, we may turn the old theorem into a lemma and then reactualize.

Using external programs for version control such as Subversion

If the file you are editing belongs to a directory which is under version control (only Subversion is currently supported, although other systems might follow), then the first part of the Version menu will contain some clickable entries.

First of all, if the current buffer is under version control, then you may take a look at its history using VersionHistory. The history contains a list of hyperlinks to older revisions, together with short information about who changed what and when. Older revisions cannot be saved, but you may compare them to the current user version (on disk or being edited) using VersionCompareWith current user version.

After making some changes to a file under version control, the version inside the editor or on disk no longer corresponds to the version in the repository. Using VersionCommit, the current user's version can be committed to the repository. When doing so, you will be prompted for a small explanatory message about the changes that you have made. A file which is not yet under version control can be added to the version control system using VersionRegister. Registering a file does not commit it to the repository; you still have to use VersionCommit in order to do so.

If, while you were editing, changes to the file were made in the repository, then you may merge the result with your current version using VersionUpdate. At the moment, no conflict resolution has been implemented yet, although this is planned for the future.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".