1.Generalities for typing text

The usual English characters and punctuation symbols can easily be obtained on most keyboards. Most modern system also implement standard shortcuts in order to obtain accented characters and other special symbols. If necessary, accented characters can also be obtained using the prefix. For instance, “é” is obtained by typing accent:acute e. Similarly, we obtain “à” via accent:grave a and so on.

Long words at borders of successive lines are automatically hyphenated. In order to hyphenate foreign languages correctly, you should specify the language of the document in the menu DocumentLanguage.

At the left hand side of the footer, you see the document style, the text properties at the current cursor position. Initially, it displays “generic text roman 10”, which means that you type in text mode using a 10 point roman font and the generic document style. You can change the text properties (font, font size, color, language) in the Format menu. You can also change the text properties of the text you have already typed by selecting a region and then using the Format menu. Some text properties can also be changed for all the document with the Document menu.

At the right hand side of the footer, the character or object (like a change in the text properties) just before the cursor is displayed. We also display all environments which are active at the cursor position. This information should help you to orient yourself in the document.

2.Typing structured text

Usually, long documents have a structure: they are organized in chapters, sections and subsections, they contain different types of text, such as regular text, citations, footnotes, theorems, etc. After selecting a document style in DocumentStyle, TeXmacs takes care of specific layout issues, such as numbering of sections, pages, theorems, typesetting citations and footnotes in a nice way and so on.

Currently, several standard document styles have been implemented: generic, article, book, letter, exam, beamer, seminar, source. For instance, the article style can be used for writing articles. Besides, there are styles for common journals and special purposes, such as the TeXmacs documentation.

As soon as you have selected a document style, you can organize your text into sections (see InsertSection) and use specific environments (also called tags). Examples of environments are theorem, proposition, remark and so on (see InsertEnunciation). Other examples are lists of items (see InsertItemize) or numbered lists (see InsertEnumerate). Further examples of frequently used tags are strong (for writing “important” text), name (for writing names of persons), etc.

When you get more acquainted with TeXmacs, it is possible to add your own new environments in your own style file. Assume for instance that you often make citations and that you want those to appear in italic, with left and right margins of 1cm. Instead of manually changing the text and paragraph properties each time you make a citation, it is better to create a citation environment. Not only it will be faster to create a new citation when doing so, but it is also possible to systematically change the layout of your citations throughout the document just by changing the definition of the citation environment. The latter situation occurs for instance if you discover a posteriori that you prefer the citations to appear in a smaller font.

There are a few general editing principles which make it easy to manipulate structured documents using TeXmacs. One major concept is the current focus, which is best illustrated on an example. Assume that we are in the process of entering a classical theorem:

At the position of the cursor, the grey and cyan boxes indicate the active tags: in this case, the cursor is both inside a theorem and a formula. The innermost active tag (the formula in our example) is surrounded by a cyan box and called the current focus.

The contents of the Focus menu and focus toolbar (the lowest toolbar) are highly context dependent and determined as a function of the current focus. In our example, the focus toolbar contains a popup menu button Formula; when selecting Equation in this menu, the text will change into

Similarly, the arrow buttons on the left hand side of the focus toolbar allow you to jump to similar tags. In this case, they will allow you to quickly traverse all formulas and equations in your document. For more information on “structured editing operations” we refer to the chapter on editing tools.

A second important concept is the current editing mode. Currently, there are five major modes: text mode, mathematics mode, program mode, graphics mode and source mode. In principle, the current mode can be determined from the current focus, but the mode is likely to change less often than the focus. The mode dependent toolbar above the focus toolbar contains several buttons which are useful in the current mode. The contents of the Insert and Format menus are also mode dependent.

3.Content-based tags

The simplest examples of structure in a text are content-based tags. In Insertcontent tags you see a list of them. Content based tags indicate that a given portion of text is of a particular kind or that it serves a specific purpose. For instance, important text should be marked using the strong tag. Its default rendering uses a bold type face, like in this strong text. However, strong text might be rendered in a different way according to the document style. For instance, strong text may be rendered in a different color on transparencies for presentations. Here follows a short list of the most common content-based tags and their purpose:

Tag Example Purpose strong this is important Indicate an important region of text em the real thing Emphasize a region of text dfn A gnu is a horny beast Definition of some concept samp the ae ligature æ A sequence of literal characters name the Linux system The name of a particular thing person I am Joris The name of a person cite* Melville's Moby Dick A bibliographic citation abbr I work at the C.N.R.S. An abbreviation acronym the HTML format An acronym verbatim the program said hello Verbatim text like computer program output kbd Please type return Text which should be entered on a keyboard code* cout << 1+1; yields 2 Code of a computer program var cp src-file dest-file Variables in a computer program

Table 1. Some of the most common content-based tags.

4.Lists

Using InsertItemize you may start an unnumbered list. You may either select a particular tag like (bullets), (dashes) or (arrows) to indicate entries in the list or the default tag. Lists may be nested inside other tags, like in the following list:

• First item.

• Now comes the sublist:

  • A subitem.
  • Another one.
• A final item.

The default tag is rendered in a different way depending on the level of nesting. At the outermost level, we used the tag, at the second level , and so on. When you are inside a list, notice that pressing automatically starts a new item. If you need items which are several paragraphs long, then you may always use in order to start a new paragraph.

Enumerate environments, which are started using InsertEnumerate, behave in a similar way as itemize, except that the items are numbered. Here follows an example of an enumeration which was started using InsertEnumerateRoman:

1. A first item.
2. A second one.
3. And a last one.

The last type of lists are descriptive lists. They are started using InsertDescription and allow you to describe a list of concepts:

Gnu

A hairy but gentle beast.

Gnat

Only lives in a zoo.

5.Environments

In a similar way as content-based tags, environments are used to mark portions of text with a special meaning. However, while content-based tags usually enclose small portions of text, environments often enclose portions that are several paragraphs long. Frequently used environments in mathematics are theorem and proof, like in the example below:

Theorem 3. There exist no positive integers , , and with , such that .

You may enter environments using InsertEnvironment. Other environments with a similar rendering as theorems are proposition, lemma, corollary, axiom, definition. You may use the dueto macro (entered using \ d u e t o return) in order to specify the person(s) to which the theorem is due, like in

Theorem 4. (Pythagoras) Under nice circumstances, we have .

Other frequently used environments with a similar rendering as theorems, but which do not emphasize the enclosed text, are remark, note, example, warning, exercise and problem. The remaining environments verbatim, code, quote, quotation and verse can be used in order to enter multiparagraph text or code, quotations or poetry.

6.Layout issues

As a general rule, TeXmacs takes care of the layout of your text. Therefore, although we did not want to forbid this possibility, we do not encourage you to typeset your document visually. For instance, you should not insert spaces or blank lines as substitutes for horizontal and vertical spaces between words and lines; instead, additional space should be inserted explicitly using InsertSpace. This will make your text more robust in the sense that you will not have to reconsider the layout when performing some minor changes, which affect line or page breaking, or major changes, such as changing the document style.

Several types of explicit spacing commands have been implemented. First of all, you can insert rigid spaces of given widths and heights. Horizontal spaces do not have a height and are either stretchable or not. The length of a stretchable spaces depends on the way a paragraph is hyphenated. Furthermore, it is possible to insert tabular spaces. Vertical spaces may be inserted either at the start or the end of a paragraph: the additional vertical space between two paragraphs is the maximum of the vertical space after the first one and the vertical space before the second one (contrary to TeX, this prevents from superfluous space between two consecutive theorems).

As to the paragraph layout, the user may specify the paragraph style (justified, left ragged, centered or right ragged), the paragraph margins and the left (resp. right) indentation of the first (resp. last) line of a paragraph. The user also controls the spaces between paragraphs and successive lines in paragraphs.

You can specify the page layout in the DocumentPage menu. First of all, you can specify the way pages are displayed on the screen: when selecting “paper” as page type in DocumentPageType, you explicitly see the page breaks. By default, the page type is “papyrus”, which avoids page breaking during the preparation of your document. The “automatic” page type assumes that your paper size is exactly the size of your window. The page margins and text width are specified in DocumentPageLayout. Often, it is convenient to reduce the page margins for usage on the screen; this can be done in DocumentPageScreen layout.

7.The font selection system

In TeXmacs, fonts have five main characteristics:

• Its name (roman, pandora, concrete, etc.).
• Its family (roman, typewriter or sans serif).
• Its size (a base size (in points) and a relative size (normal, small, etc.).
• Its series (bold, medium or light).
• Its shape (right, italic, small caps, etc.).

Notice that in the font selection system of LaTeX , the font name and family are only one (namely, the family). Notice also that the base font size is specified for the entire document in DocumentFontSize.

8.Mastering the keyboard

We recall that the section on general conventions contains explanations on the way keyboard shortcuts are printed in this manual. It may also be useful to take a look at the section on keyboard configuration.

8.1.General prefix rules

Since there are many keyboard shortcuts, it is important to have some ways of classifying them in several categories, in order to make it easier to memorize them. As a general rule, keyboard shortcuts which fall in the same category are identified by a common prefix. The active prefixes heavily depend on the selected “look and feel” in EditPreferences. In the current look and feel of your TeXmacs system,the main common prefixes are as follows:

Standard shortcuts, which are similar to shortcuts used by other applications (for the selected look and feel). For instance, can be used for pasting text on your system.

TeXmacs shortcuts, which often rely on the current editing mode. For instance, text s produces strong text in text mode and a square root in math mode.

Compound TeXmacs shortcuts. Usually, these shortcuts first indicate the kind of markup to which the command will apply and then specify the specific command. For instance, the executable prefix is used for insering executable markup, which is useful for writing style files. One example is the shortcut executable + for the insertion of an addition.

This prefix is used in combination with arrow keys and certain other special keys for positioning and resizing objects

This prefix is used in combination with arrow keys and some other special keys for structured cursor movements.

This prefix is occasionally used in combination with letters and ponctuation symbols for creating some additional easy to remind shortcuts.

This prefix can be used in combination with normal letters for the insertion of special symbols. For instance, text:symbol s yields ß and math:symbol a yields . The prefix is also used for the insertion of “literal characters”. For instance, symbol \ will always produce the \ character, whereas the \ key is used for entering hybrid commands.

Unfortunately, -based shortcuts are superseded by system shortcuts on several systems. For instance, accented characters and common special symbols are entered using this prefix under Mac OS. In that case, you may use the key as an equivalent for altcmd. For more information, we refer to the section on keyboard configuration.

8.2.Keyboard shortcuts for text mode

To write a text in an european language with a keyboard which does have the appropriate special keys, you can use the following shortcuts to create accented characters. Note that they are active regardless of the current language setting.

Shortcut Example Shortcut Example accent:acute Acute ´ accent:acute e é accent:grave Grave ‘ accent:grave e è accent:hat Hat ˆ accent:hat e ê accent:umlaut Umlaut ¨ accent:umlaut e ë accent:tilde Tilde ˜ accent:tilde a ã accent:cedilla Cedilla ¸ accent:cedilla c ç accent:breve Breve ˘ accent:breve g ğ accent:check Check ˇ accent:check s š accent:abovering Above ring ˚ accent:abovering a å accent:abovedot Above dot ˙ accent:abovedot z ż accent:doubleacute Hungarian ˝ accent:doubleacute o ő

Table 2. Typing accented characters.

Special characters can also be created in any language context:

Shortcuts symbol a æ symbol A Æ symbol a e æ symbol A E Æ symbol o ø symbol O Ø symbol o e œ symbol O E Œ symbol s ß symbol S SS symbol ! ¡ symbol ? ¿ symbol p § symbol P £

Table 3. Typing special characters.

When you press the " key, an appropriate quote will be inserted. The quote character is chosen according to the current language and the surrounding text. If the chosen quoting style is not appropriate, you can change it in EditPreferencesKeyboardAutomatic quotes. You can also insert raw quotes:

Shortcuts symbol " " , , „ < var ‹ > var › < < « > > »

Table 4. Typing raw quotes.

“English” quotes are considered ligatures of two successive backticks or apostrophes. They can be created with ‘ ‘ and ' ' but these are not actual keyboard commands: the result is two characters displayed specially, not a special single character.

Some shortcuts are available in specific language contexts. You can set the text language for the whole document with DocumentLanguage or only locally with FormatLanguage (see generalities for typing text).

Hungarian Spanish Polish symbol o ő ! var ¡ symbol a ą symbol o ó symbol O Ő ? var ¿ symbol A Ą symbol O Ó symbol u ű ! ‘ ¡ symbol c ć symbol s ś symbol U Ű ? ‘ ¿ symbol C Ć symbol S Ś symbol e ę symbol x ź symbol E Ę symbol X Ź symbol l ł symbol z ż symbol L Ł symbol Z Ż symbol n ń symbol z var ź symbol N Ń symbol Z var Ź

Table 5. Language-specific text shorthands.

Language-specific shortcuts override generic shortcuts; for example, you cannot easily type “ø” in hungarian context.

8.3.Hybrid commands and LaTeX simulation

TeXmacs allows you to enter LaTeX commands directly from the keyboard as follows. You first hit the \-key in order to enter the hybrid LaTeX/TeXmacs command mode. Next you type the command you wish to execute. As soon as you finished typing your command, the left footer displays something like

    <return>: action to be undertaken

When you hit the -key at this stage, your command will be executed. For instance, in math-mode, you may create a fraction by typing \ f r a c return.

If the command you have typed is not a (recognized) LaTeX command, then we first look whether the command is an existing TeXmacs macro, function or environment (provided by the style file). If so, the corresponding macro expansion, function application or environment application is created (with the right number of arguments). Otherwise, it is assumed that your command corresponds to an environment variable and we ask for its value. The \-key is always equivalent to one of the commands inactive l, inactive e, inactive a, inactive # or inactive v.

To insert a literal \ (backslash) character, you can use the symbol \ sequence.

8.4.Dynamic objects

Certain more complex objects can have several states during the editing process. Examples of such dynamic objects are labels and references, because the appearance of the reference depends on a dynamically determined number. Many other examples of dynamic markup can be found in the documentation about writing style files.

When entering a dynamic object like a label using , the default state is inactive. This inactive state enables you to type the information which is relevant to the dynamic object, such as the name of the label in our case. Certain dynamic objects take an arbitrary number of parameters, and new ones can be inserted using var.

labelpythagoras

Figure 1. Inactive label

When you finished typing the relevant information for your dynamic object, you may type in order to activate the object. An active dynamic object may be deactivated by placing your cursor just behind the object and hitting backspace.

8.5.Various useful keyboard shortcuts

Some assorted shortcuts which are often useful are displayed in table ?. Notice that spaces inserted using , and can be resized a posteriori using the shortcuts and . This kind of resizing actually works for more general horizontal and vertical spaces inserted from the menu FormatSpace, as well as several other objects, such as images.

Shortcut Action Remove the containing object or environment. Insert a non breaking space. Insert a quad space. Insert a small space. Insert a small negative space. Insert a “tab” Go to the start of the document. Go to the end of the document. Insert a line break. Insert a “rigid” piece of text, which cannot be line-broken.

Table 6. Various useful keyboard shortcuts