Contents

Part A User guide 7

1 Welcome to GNU TeXmacs 9 1.1 Where to find help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.2 About GNU TeXmacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2 Introduction to GNU TeXmacs 11 2.1 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.2 Typing text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.2.1 Generalities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.2.2 Layout issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.3 Typing structured text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.4 Typing mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.4.1 Mathematical symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.5 Editing facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.5.1 Cut and paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.5.2 Search and replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.5.3 Spell checker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.5.4 Undo and redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.6 Miscellaneous issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.6.1 The font selection system . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.6.2 Including images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.6.3 Hyperlinks and actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.7 Conversion of TeXmacs documents . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.7.1 Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.7.2 Compatibility with L^{A}TEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.7.3 Compatibility with HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3 The keyboard 19

3.1 General keyboard actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.1.1 Standard keyboard actions . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.1.2 Manipulation of dynamic objects . . . . . . . . . . . . . . . . . . . . . . . . 20 3.1.3 Latex commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.2 The keyboard in text mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 3.2.1 West-European languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3.2.2 Typing Russian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 3.3 The keyboard in math mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3.3.1 Mathematical objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 3.3.2 Accents in math-mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.3.3 Large symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 3.3.4 Large delimiters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.3.5 Other mathematical symbols . . . . . . . . . . . . . . . . . . . . . . . . . . 25

3.4 The keyboard in prog mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4 Document styles 27 4.1 Main architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.2 Standard document styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.3 User style files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.3.1 Look at an example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.3.2 Some important paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.3.3 Writing your own style file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.3.4 Other useful commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5 Advanced features of GNU TeXmacs 31 5.1 Compiling a bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.2 Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

6 Compatibility with LaTeX 33 6.1 Conversion from TeXmacs to LaTeX . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.2 Possible sources of conversion problems . . . . . . . . . . . . . . . . . . . . . . . . 34

6.2.1 Specific TeXmacs features . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.2.2 Not yet implemented conversions . . . . . . . . . . . . . . . . . . . . . . . . 35 6.2.3 Bugs in the conversion algorithm . . . . . . . . . . . . . . . . . . . . . . . . 35

6.3 Conversion from LaTeX to TeXmacs . . . . . . . . . . . . . . . . . . . . . . . . . . 35

7 GNU TeXmacs and its port to Guile 37 7.1 Writing your own initialization file . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 7.2 Creating your own dynamic menus . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 7.3 Creating your own key-combinations . . . . . . . . . . . . . . . . . . . . . . . . . . 39 7.4 Other files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

8 Using GNU TeXmacs as an interface 41

8.1 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 8.1.1 Shell sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 8.1.2 Scheme sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 8.1.3 Pari sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

8.2 Link your own system to TeXmacs . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 8.2.1 Connections via pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 8.2.2 Connections via dynamically linked libraries . . . . . . . . . . . . . . . . . . 43

8.3 Communication via pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 8.4 The TeXmacs communication protocol . . . . . . . . . . . . . . . . . . . . . . . . . 45

8.4.1 Version 1 of the TeXmacs communication protocol . . . . . . . . . . . . . . 45

9 About 47 9.1 About GNU TeXmacs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 9.2 Copying policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 9.3 Help and donations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 9.4 Using TeXmacs as an interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 9.5 Thanks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Part B A guide to the source code 51

10 General architecture of TeXmacs 53 10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 10.2 Intern representation of texts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

10.2.1 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 10.2.2 The language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

10.3 Typesetting texts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 10.4 Making modifications in texts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

11 Basic data structures 57 11.1 Memory allocation and data structures in TeXmacs . . . . . . . . . . . . . . . . . . 57 11.2 Array-like structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 11.3 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 11.4 Hash tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 11.5 Other data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

12 The TeXmacs data format 61 12.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 12.2 Leaves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 12.3 Main formatting operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 12.4 Mathematical operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 12.5 Environmental and other invisible operators . . . . . . . . . . . . . . . . . . . . . . 64 12.6 Functional operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 12.7 For private use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 12.8 Planned changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

13 Converters to other data formats 67 13.1 Parsing extern data formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 13.2 The actual converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 13.3 Backward conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

14 The graphical toolkit 69

14.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 14.1.1 Main architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 14.1.2 Widgets and event processing . . . . . . . . . . . . . . . . . . . . . . . . . . 71

14.2 The abstract window interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

14.2.1 Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 14.3 Widget principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

14.3.1 The widget class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 14.3.2 The event class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 14.3.3 The main event loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 14.3.4 Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 14.3.5 Attaching and positioning widgets . . . . . . . . . . . . . . . . . . . . . . . 78 14.3.6 The keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 14.3.7 The mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 14.3.8 The screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 14.3.9 The toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

15 TeXmacs fonts 85 15.1 Classical conceptions of fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 15.2 The conception of a font in TeXmacs . . . . . . . . . . . . . . . . . . . . . . . . . . 86 15.3 String encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 15.4 The abstract font class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 15.5 Implementation of concrete fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 15.6 Font selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

16 Bugs 91 16.1 Known bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Part C Projects and challenges for YOU 93

17 What has changed 95 17.1 Changes between TeXmacs 0.2.3 and TeXmacs 0.2.2 . . . . . . . . . . . . . . . . . 95 17.2 Changes between TeXmacs 0.2.4 and TeXmacs 0.2.3 . . . . . . . . . . . . . . . . . 95 17.3 Changes between TeXmacs 0.2.5 and TeXmacs 0.2.4 . . . . . . . . . . . . . . . . . 96 17.4 Changes between TeXmacs 0.3.0 and TeXmacs 0.2.5 . . . . . . . . . . . . . . . . . 97 17.5 Changes between TeXmacs 0.3.0-1 and TeXmacs 0.3.0-7 . . . . . . . . . . . . . . . 98

18 What will be changed 99 18.1 Memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 18.2 Graphical interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 18.3 Encodings and fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 18.4 Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 18.5 Miscellaneous changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

19 Projects 101 19.1 Typesetting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 19.2 Extra facilities for editing texts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 19.3 Technical pictures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 19.4 Interface with computer algebra systems . . . . . . . . . . . . . . . . . . . . . . . . 102 19.5 Interaction with other GNU-like projects . . . . . . . . . . . . . . . . . . . . . . . . 102 20 How you can help 103

20.1 Use the program! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 20.2 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 20.3 Translations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 20.4 Converters from/to LaTeX, html, etc. . . . . . . . . . . . . . . . . . . . . . . . . . 104 20.5 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 20.6 Other help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 20.7 Contact me . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 6 CONTENTS

Part A

User guide

Chapter 1

Welcome to GNU TeXmacs

1.1 Where to find help

The GNU TEXmacs help is divided in the following parts:

• In the Help→introduction menu, you will find some basic and general explanations about how to use TEXmacs.

• In the Help→keyboard menu, you will find help about how to use the keyboard in TEXmacs’s different modes.

• In the Help→style menu, the different TEXmacs document styles are documented. You will also find out how to create your own styles and preambles.

• In the Help→advanced menu, we explain the more advanced features of TEXmacs, such as the automatic generation of bibliographies or multifile projects.

• In the Help→latex menu, it is explained how to convert TEXmacs files into L^{A}TEX and vice versa. This is useful if you want to submit an article written using TEXmacs to a journal.

• In the Help→scheme menu, you will find help on some of the internal behaviour of TEXmacs and on the Guile Scheme extension language, which enables you to write your own initialization files and to create your own menus.

• In the Help→interface menu, you will find help on how to use TEXmacs as an interface to an extern program, such a computer algebra system.

1.2 About GNU TeXmacs

The TEXmacs program has been written for the following reasons:

• In order to provide you with a free, easy to use and high quality what-you-see-is-what-you-get text editor. By “high quality” we mean that the printed output should be of the quality of what you can find in a book.

• In order to provide writers of computer algebra systems with a free powerful user interface, which can be dynamically linked with their system.

Notice that TEXmacs is a “structured text” editor. This means that we encourage you to write text with a logical meaning rather than text which looks nice on the screen. The advantage of this approach is that it makes it easier for you to reuse your texts for other purposes. In particular, mathematical formulas written using TEXmacs are likely to be fed into compute algebra systems.

Notice also that although TEXmacs is free in price, it has been protected by the “GNU general public license”. Roughly speaking, this license stipulates that TEXmacs comes WITHOUT ANY GUARANTEE and that TEXmacs remains free, even when it is incorporated in other pieces of software.

For more details about TEXmacs, its authors, the “GNU general public license”, its relation to the TEX system, its development and current defaults, take a look at the menu Help→about.

Introduction to GNU TeXmacs

2.1 Getting started

Before starting to type some text, you might want to do one or more of the following operations:

• Give your document a name (click on File→save as) or load an existing document (using File→load).

• If you want to type text in a foreign language, you can set the language of the document in the Document→language menu. In Options→language you can also choose a foreign language for the editor’s menus and messages.

• You usually should specify a document style in the menu Document→style, such as letter, article, book, etc. This provides a standard layout for section numbering, page headers and footers, theorems, etc.

• You should specify your printers paper format in the menu Document→page→size, if you intend to print your document (default is a4).

Remark. When you get more familiar with the editor, you may write your own initialization files, which perform the above operations automatically each time you start up the editor or when starting a new file.

2.2 Typing text

2.2.1 Generalities

As soon as you have performed the preparatory actions as explained above, you can start typing. The usual English characters and punctuation symbols can easily be obtained on most keyboards. Accented characters from foreign languages can systematically be obtained using the escape -key.

For instance, “é” is obtained by typing escape - ’ - e . Similarly, we obtain “à” via escape - ‘ - 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 Document→language.

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

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.2.2 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 Insert→space. 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 Document→page menu. First of all, you can specify the way pages are displayed on the screen: when selecting “paper” as page type in Document→page→type, 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 Document→page→layout. Often, it is convenient to reduce the page margins for usage on the screen; this can be done in Document→page→screen layout.

2.3 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 Document→style, TEXmacs takes care of specific layout issues, such as numbering of sections, pages, theorems, typesetting citations, footnotes and theorems in a nice way and so on.

Currently, four document standard styles have been implemented: letter, article, book and seminar. The seminar style is used for making transparencies. As soon as you have selected such a style, you can organize your text into sections (see Insert→section) and use specific environments. Examples of environments are theorem, proposition, remark and so on (see Insert→environment). Other examples are lists of items (see Insert→itemize) or numbered lists (see Insert→enumerate).

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.

2.4 Typing mathematics

Up till now, we have only considered typing in text mode. You can enter “math mode” by pressing the $ -key or by inserting an equation (using Insert→mathematics→equation). In math mode, you have specific commands and key-combinations to type mathematical symbols and formulas.

The editor favorites typing mathematics with a certain meaning. This feature, which will be developed more in future releases, is useful when communicating with a computer algebra package. At this moment, you should for instance explicitly type the multiplication * between symbols a

and b. By default, typing a - b will yield ab and not ab.

2.4.1 Mathematical symbols

The Greek characters are obtained in TEXmacs by combining the alt -key with a letter. For

instance, alt-a yields α and alt-shift-g yields Γ. Variants are obtained by the ⋆ -key. For

instance, alt-p - ⋆ yields ϖ.

Many other mathematical symbols are obtained by “natural” key-combinations. For instance, − - > yields →, − - − - > yields ⟶ and > - = yields ⩾. Similarly, | - − yields ⊢, | - − -

> yields ↦ and − - > - < - − yields ⇄.

Some general rules hold in order to obtain variants of symbols:

⋆ is the main key for obtaining variants. For instance, > - = yields ⩾, but > - = - ⋆ yields

≥. Similarly, < - ⋆ yields ≺, < - ⋆ - = yields ≼ and < - ⋆ - = - ⋆ yields ⪯.

@ is used for putting symbols into circles or boxes. For instance, @ - + yields ⊕ and @ - x

yields ⊗. Similarly, @ - ⋆ - + yields ⊞.

/ is used for negations. For instance, = - / yields ≠ and < - = - / yields ⩽̸. Notice that

< - = - ⋆ - ⋆ - / yields ≦̸, while < - = - ⋆ - ⋆ - / - ⋆ yields ≨.

2.5 Editing facilities

2.5.1 Cut and paste

You can select text and formulas by maintaining the left mouse button. In order to delete the selected region, use Edit→cut. In order to copy the selected region, first click on Edit→copy. Next, paste it as many times as you want to the location of your cursor, using Edit→paste. 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 Text→colour→red. Similarly, if you select a formula and you click on Insert→mathematics→fraction, then the formula becomes the numerator of some fraction.

2.5.2 Search and replace

You can start searching text by pressing ctrl-s or Edit→search. During a search, the “search string” is displayed at the left hand side of the footer. Each character you type is appended to this search string and the next occurrence of it is surrounded by a red box. When pressing ctrl-s a second time during a search, the next occurrence is being searched. A beep indicates that no more occurrences were found in the document; pressing ctrl-s will continue the search at the beginning

of your document. You may press bs in order to undo keypresses during a search.

Usually, text is being searched for in a forward manner, starting from the current cursor position. You may also search backwards, using ctrl-r . 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.

A query replace is started by pressing ctrl-= or Edit→replace. You are prompted for a string which is to be replaced and the string by which to replace. At each occurrence of the string to be replaced you are prompted and you have to choose between replacing the string (y), not replacing it (n) and replace this and all further occurrences (a). Like in the case of searching, the query-replace command is mode and language sensitive.

2.5.3 Spell checker

If the program ispell has been installed on your system, then you may use it to check your text for misspelled words by pressing esc - i or Edit→spell. 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 grammatic 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.

2.5.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 Edit→undo or using the keystrokes esc - [ or ctrl-/ .

Undone changes can be “redone” using Edit→redo or esc - ] .

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 Help→scheme). When specifying a negative number as your maximal undo depth, any number of actions can be undone.

2.6 Miscellaneous issues

2.6.1 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 L^{A}TEX 2ε, 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 Document→font→size.

2.6.2 Including images

You can include images in the text using the menu Insert→image. 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 size. The following operations are supported on images:

• Clipping the images following a rectangle. The lower left corner of the default image is taken as the origin for specifying a rectangle for clipping.

• Resizing an image. 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.

• Magnifying the image. An alternative way to resize an image, by multiplying the width and the height by a constant.

We also included a script to convert pictures, with optional L^{A}TEX formulas in it, into encapsulated postscript. In order to include a L^{A}TEX formula in an xfig picture, we recall you should enter the formula as text, while selecting a L^{A}TEX font and setting the special flag in the text flags.

2.6.3 Hyperlinks and actions

It is possible to create hyperlinks to other documents using esc - h 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.

In a similar fashion, an action may be associated to a piece of text or graphics using esc - a 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.

2.7 Conversion of TeXmacs documents

2.7.1 Printing

You can print the current file using File→print→print all. By default, TEXmacs assumes that you have a 600dpi printer for a4 paper. These default settings can be changed using File→print→setup printer. You can also print to a postscript file using File→print→print all to file (in which case the default printer settings are used for creating the output) or File→export→postscript (in which case the printer settings are ignored).

As to the WYSYWYG-ness of TEXmacs, the editor guarantees that you get the same output on paper as on screen as long as the screen characters use the same number of dots per inch as your printer (see Document→font→dpi). This is due to the fact that the bounding boxes for the ink of TeX characters are currently computed from the .pk and not from the .tfm files. Hence minor typesetting changes may occur when changing the dpi, which may globally affect the document through line and page breaking. In a future release this drawback should be removed.

For matching dpi’s, if you notice a real change between the appearance on paper and on the screen (apart from pixel order changes in position and boldness), then this means that you found a bug and please let me know.

2.7.2 Compatibility with L^{A}TEX

TEXmacs has not been designed to be fully compatible with L^{A}TEX. As to the conversion from L^{A}TEX to TEXmacs, our main aim is to help you in converting old documents to TEXmacs. As long as you did not define weird environments and as long as you did not use weird style files and commands, you should be able to convert your old documents reasonably well. Otherwise, we suggest to modify your old document in a way that is does convert reasonably well and to apply some final changes in the result.

The conversion from TEXmacs to L^{A}TEX is more reliable, apart from minor changes in the layout, and as long as you do not use specific features of TEXmacs, mainly

• Left primes.

• big separators between big parentheses.

• Mosaics.

• Trees.

• Vertical spaces “before” and “after”.

• Indentation flags “before” and “after”.

You may convert TEXmacs documents to L^{A}TEX using File→export→latex. We have provided a TEXmacs style file in misc/latex/TeXmacs.sty. By default, this style file is included in converted documents, by the usepackage command. If you send such a converted document to someone else (i.e. a publisher), make sure that this person has a copy of the file TeXmacs.sty.

We also notice that it is possible to use L^{A}TEX command names for keyboard input. For instance, in math mode, you can create a fraction by typing \ - f - r - a - c - return .

For more details about the conversion of TEXmacs documents to L^{A}TEX and vice versa can be found in the chapter “compatibility with L^{A}TEX”.

2.7.3 Compatibility with HTML

We have started to implemented the conversion between HTML and TEXmacs. At this moment, it is only possible to import HTML documents using File→import→html. Most of HTML 2.0 and parts of HTML 3.0 are currently supported. However, no browsing facilities have been added yet. In the future, we plan to implement Math-ML.

When importing HTML documents, files whose names start with http: or ftp: will be downloaded from the web using wget. If you compiled TEXmacs yourself, then you can download wget from

  ftp://ftp.gnu.org/pub/gnu/wget/

In the binary distributions, we have included wget.

The keyboard

The way in which TEXmacs reacts on keyboard input depends on the current mode (i.e. text mode, math mode or prog mode) and sometimes on the language. By default, TEXmacs defines a certain number of keyboard actions for each mode. Certain L^{A}TEX commands can also be entered directly from the keyboard.

It is possible for the user to modify the keyboard behaviour. In order to do so, we suggest first to look at the files in the directory $TEXMACS_PATH/progs/keyboard, where the standard keyboard behaviour is defined. Then you may redefine the keyboard behaviour in your private initialization file.

3.1 General keyboard actions

3.1.1 Standard keyboard actions

Some standard keyboard actions which are valid in all modes are ctrl-bs remove an object or environment. shift-home go to the start of the document. shift-end go to the end of the document. ctrl-home manually set start of the selection. ctrl-end manually set end of the selection. esc - & line separator in tables and so. esc - return new line. alt-spc insert a small space.

20 CHAPTER 3. THE KEYBOARD alt-bs insert a small negative space.

3.1.2 Manipulation of dynamic objects

“Dynamic” objects, such as labels or function definitions are temporarily inactive, when being modified and activated by pressing the return -key. Certain dynamic objects take parameters, which are inserted using tab in the deactivated state. The following dynamic objects can be used in any mode: esc - $ insert a symbol. esc - \ Execute a L^{A}TEX command. esc - = assign a variable. esc - f define a function. esc - e define an environment by splitting a function definition in two parts. esc - < apply a function. esc - b transforms an application in a begin-end. esc - s set an environment variable. esc - ! insert a label. esc - ? insert a reference. esc - q insert a quote. esc - + an addition. esc - - a subtraction. esc - ⋆ a multiplication. esc - # insert a number. esc - > translate a word or sentence into another language.

3.2. THE KEYBOARD IN TEXT MODE 21

3.1.3 Latex commands

TEXmacs allows you to enter L^{A}TEX commands directly from the keyboard as follows. You first hit the \ -key in order to enter the hybrid L^{A}TEX/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 return -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) L^{A}TEX command, then the \ -key is equivalent to esc - < .

3.2 The keyboard in text mode

3.2.1 West-European languages

The only extra keyboard actions available in text mode are $ in order to enter math-mode and the following shorthands to create accented characters: esc - ´ like in é. esc - ` like in è. esc - ˆ like in ê. esc - ¨ like in ë. esc - ˜ like in ã. esc - c like in ç. esc - u like in ă. esc - v like in č. esc - H like in ő. esc - . like in ż. esc - o like in å.

22 CHAPTER 3. THE KEYBOARD For instance, esc - ´ - e produces é.

The special characters ß, SS, œ, Œ, æ and Æ are obtained by typing alt-s , alt-S , alt-o - alt-e , alt-O - alt-E , alt-a resp. alt-A .

In french, you may also use the special keybindings < - < and > - > in order to obtain the french guillements. In spanish, the opening exclamation and question marks are obtained by typing ! - * (or ! - ‘ ) resp. ? - * (or ? - ‘ ).

3.2.2 Typing Russian

In order to type Russian text, you should • Select Russian as the language of your document.

• Cyrillic as the default font.

• Select the Russian language in the options menu, if you want the menus to be displayed in

Russian. It is both possible to type Russian characters on a Russian or on a west-European keyboard.

On a west-European keyboard, special Russian characters like ‘ch’, ‘ya’ and so on are naturally obtained by typing c - h , y - a , etc. In order to type a ‘c’ followed by an ‘h’, you should type c - / - h . Some other special Russian characters are obtained via the keystrokes q , w , x and e - * .

3.3 The keyboard in math mode

In math-mode, you can again use $ to re-enter in text-mode. The alt -key in combination with a letter is used for producing Greek characters.

3.3.1 Mathematical objects

The main mathematical objects are created as follows:

create a subscript. ˆ create a superscript. esc - L - create a subscript on the left. esc - L - ˆ create a superscript on the right. ´ create a prime. ` create a “back-prime”.

3.3. THE KEYBOARD IN MATH MODE 23 esc - F or esc - / create a fraction. esc - S create a square root. esc - R create an n-th root. esc - M create a matrix. esc - T create a table. esc - N create a negation. In matrices and tables, esc - left and esc - right are used to insert a column on the left resp. right of the current cursor position. Similarly, rows are created using esc -keyup and esc - down .

3.3.2 Accents in math-mode

The following key combinations are used for creating mathematical accents: esc - ˜ for tildas like in x̃. esc - ˆ for hats like in x̂. esc - v for checks like in x̌. esc - ´ for acute accents like in x́. esc - ` for grave accents like in x̀. esc - V for vectors like in x⃗.

3.3.3 Large symbols

The following key-combinations are used in order to create large symbols: esc - esc - S produces ∑. esc - esc - P produces ∏. esc - esc - I produces ∫. esc - esc - O produces ∮. esc - esc - A produces ⨿.

24 CHAPTER 3. THE KEYBOARD esc - esc - N produces ⋂. esc - esc - N - ⋆ produces ⋀. esc - esc - U produces ⋃. esc - esc - U - ⋆ produces ⋁. esc - esc - U - ⋆ - ⋆ produces ⨆. esc - esc - @ - . produces ⨀. esc - esc - @ - + produces ⨁. esc - esc - @ - x produces ⨂.

3.3.4 Large delimiters

Large delimiters are created as follows: esc - esc - ( produces (. esc - esc - ) produces ). esc - esc - [ produces [. esc - esc - ] produces ]. esc - esc - { produces {. esc - esc - } produces }. esc - esc - < produces ⟨. esc - esc - > produces ⟩. esc - esc - | produces |. esc - esc - | - | produces ||. esc - esc - | - , produces ⌊. esc - esc - | - ’ produces ⌈. esc - esc - , - | produces ⌋.

esc - esc - ’ - | produces ⌉.

esc - esc - / produces /.

esc - esc - \ produces \.

In TEXmacs, large delimiters may either be “left delimiters”, “right delimiters” or “middle delimiters”. By default, (, [, {, ⟨, ⌊ and ⌈ are left delimiters, ),], }, ⟩, ⌋ and ⌉ are right delimiters and |, ||, / and \ are middle delimiters. But there status can be changed using the esc - esc - l , esc -

esc - r and esc - esc - m key combinations. For instance, esc - esc - l - ) produces ), considered as a large left delimiter.

In TEX and L^{A}TEX, “middle delimiters”, or “separators” do not exist; they are used for producing the vertical bars in formulas like

⟨\frac{a}{b + c} |\frac{p}{q + r} | \frac{a}{b + c}⟩ .

There may be as many middle delimiters between a left and a right delimiter as one wishes.

3.3.5 Other mathematical symbols

Other mathematical symbols are obtained by “natural” key-combinations. For instance, − - >

yields →, − - − - > yields ⟶ and > - = yields ⩾. Similarly, | - − yields ⊢, | - − - > yields

↦ and − - > - < - − yields ⇄.

Some general rules hold in order to obtain variants of symbols:

⋆ is the main key for obtaining variants. For instance, > - = yields ⩾, but > - = - ⋆ yields

≥. Similarly, < - ⋆ yields ≺, < - ⋆ - = yields ≼ and < - ⋆ - = - ⋆ yields ⪯.

@ is used for putting symbols into circles or boxes. For instance, @ - + yields ⊕ and @ - x

yields ⊗. Similarly, @ - ⋆ - + yields ⊞.

/ is used for negations. For instance, = - / yields ≠ and < - = - / yields ⩽̸. Notice that

< - = - ⋆ - ⋆ - / yields ≦̸, while < - = - ⋆ - ⋆ - / - ⋆ yields ≨.

Below follows a list of other characters, which are not obtained in a straightforward manner by the above system.

Variants. Small variants of the large delimiters are obtained as follows: esc - esc - a yields ⨿,

esc - esc - n yields ∩, etc.

esc - esc - d yields ∂. esc - esc - x yields ×.

esc - esc - w yields ℘.

3.4 The keyboard in prog mode

You enter programming mode either using pound or by starting a programming session from the menu Insert→session. In programming mode, the current paragraph is executed each time when you type return . If you want to insert a carriage return, type shift-return .

Document styles

4.1 Main architecture

To a document, it is possible to associate one or several document styles, which are either standard or user defined. The main document style of a document is selected in the Document→style menu. Extra styles can be added using Document→use package.

From the editor point of view, each style corresponds to a .ts file. The files corresponding to each style are processed in as if they were usual documents, but at the end, the editor only keeps the final environment as the initial environment for the main document. More precisely, the style files are processed in order as well as there own styles, in a recursive manner.

4.2 Standard document styles

Currently, the following standard document styles have been implemented:

• Book;

• Article;

• Letter;

• Seminar (for transparencies). Each of these styles export a certain number of standard functions and environments listed

below. All future standard document styles are expected to support at least the above commands and environments and we suggest users to write style files which do so too.

• Sectioning commands.

• Itemize and enumerate environments.

• Equation like environments.

• Theorem like environments.

• Programming environments.

We notice that the theorem like environments are not standard in L^{A}TEX, which is a standard source of non compatibility. New “theorems” can be added with the newtheorem command. It is also possible to add new “remarks” with the newremark command; “remarks” are different from “theorems” in the sense that their body is usually not typeset in an emphasized font.

Of course, programming environments are not supported by L^{A}TEX either. Such environments are currently under development.

4.3 User style files

4.3.1 Look at an example

Before writing your own style file, it may be useful to take a look at some standard style files. For instance, you may load book.ts using File→load (no path is necessary here, since the style directory is included in the default file path).

After loading book.ts, you will see many function and environment declarations (these declarations are visible, since style files are written in “preamble mode” (see Options→mode)). Some more declarations are contained in the files basic.ts, list.ts, theorem.ts and program.ts on which book.ts is based. These files respectively contain basic, itemize-like, theorem-like and programming environments.

4.3.2 Some important paths

Before writing your own style file, it is useful to know the following important TEXmacs paths:

• $TEXMACS_PATH is the main path for TEXmacs.

• $TEXMACS_HOME_PATH is the main user path for TEXmacs files (documents, styles or programs). By default, this path is set to ~/.TeXmacs.

• $TEXMACS_STYLE_PATH contains the path for including style files. By default, this path

     contains ., $TEXMACS_PATH/styles and $TEXMACS_HOME_PATH/styles.

• $TEXMACS_FILE_PATH contains the path for searching text files. By default, this path contains

     $TEXMACS_STYLE_PATH, $TEXMACS_PATH/texts and $TEXMACS_HOME_PATH/texts.

4.3.3 Writing your own style file

The main key-combinations that you should know to write style files are the following:

esc - = creates a new assignment. The first argument is a new command name and the second argument an expression.

esc - f creates a function. Arguments to the function can be inserted using the tab -key.

esc - < applies a symbol or a function to zero or more arguments. New arguments are inserted

using the tab -key.

4.3. USER STYLE FILES 29 More precisely, when evaluating a function application ⟨a|x_{1}| ⋯ |x_{n}⟩ created by esc - < , the following action is undertaken:

• The function name a is evaluated. This results either in a command name or a function f.

• If we obtain a command name (which should correspond to a command created by esc - = ), then we evaluate it. If the result f of this evaluation is not a function, then n should vanish and we return f.

• Let y_{1}, …, y_{n} be the arguments of f. We now systematically replace x_{i} for ⟨y_{i}⟩ in the body of f for each 1 ≤ i ≤ n. We return the evaluation of this substitution.

In order to create environments, one may use the following key-combinations: esc - e splits a function body into two parts, in order to form an environment. The first part

becomes the “begin” part of the environment and the second part the “end” part. This command is the counterpart of esc - f .

esc - b starts a new environment. This command is the counter part of esc - < . esc - s set an environment variable, but reset (restore) it afterwards. This command is the

counter part of esc - = . A matching “begin-end” or “set-reset” pair may be removed by moving the cursor just behind the end resp. reset. Next, press ctrl-del .

4.3.4 Other useful commands

The following commands may sometimes be of interest: esc - + add two numbers or lengths. esc - - subtract two numbers or lengths. esc - x multiply two numbers. esc - ⋆ concatenate two strings. esc - # display a number in Arabic, roman, Roman, alpha or Alpha (used for instance in enu-

merations). esc - > translate a word from a source language into a destination language (see the dictionaries

    in $TEXMACS_PATH/data/dic).

30 CHAPTER 4. DOCUMENT STYLES

Advanced features of GNU TeXmacs

5.1 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 L^{A}TEX.

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

5.2 Projects

In order to start a project, create a new buffer of style project, and save it under some name prj.tp ending with .tp. In this project file, you should enter all the files which make up your project. A usual TEXmacs file name.tm is entered by typing esc - < , include-document, tab ,

name.tm, return . Vice versa, you have to attach prj.tp to each such a file name.tm, using Document→project→attach.

Assuming that you have created a project in the above way and that you have attached the project to each of its files, you should now have a Project menu, when you are editing a file in the project. You may update all referencing information of a file w.r.t. the project using Project→compile buffer. The entire project can be recompiled using Project→compile project.

32 CHAPTER 5. ADVANCED FEATURES OF GNU TEXMACS

Compatibility with LaTeX

Although TEXmacs has not been designed to be fully compatible with L^{A}TEX, it is possible to convert documents from TEXmacs to L^{A}TEX and vice versa, although the result will not always be perfect. Also, conversions from TEXmacs to L^{A}TEX will generally yield better results then conversions the other way around. In particular, TEXmacs may reasonably well be used to write articles, which need to be converted to L^{A}TEX for submission purposes. In this chapter, we will describe more precisely the conversion mechanisms, which will help you to obtain a result as satisfactory as possible.

6.1 Conversion from TeXmacs to LaTeX

The most common situation is that you want to convert an article from TEXmacs to L^{A}TEX, in order to submit it to some journal. Given a TEXmacs file name.tm, you may convert it into a L^{A}TEX file name.tex using File→export→latex. At a first stage, you may try to run L^{A}TEX on name.tex, and see whether you obtain a satisfactory result. If so, then you should submit name.tex together with the style file TeXmacs.sty, which can be found in the directory $TEXMACS_PATH/misc/latex.

Often, the journal to which you submit uses its own style file, say journal.sty. In that case, you should also copy the file

    $TEXMACS_PATH/styles/article.ts

to

    ~/.TeXmacs/styles/journal.ts

and use journal as your document style in Document→style→other. You may optionally edit journal.ts, so that the article layout becomes closer to the journal’s style. In some cases, you also have to create a new copy of TeXmacs.sty, and modify some of the environments for compatibility with the journal’s style file journal.sty.

If your first try to convert your document into L^{A}TEX did not yield a satisfactory result, then you will usually observe that only minor parts of the texts were not converted correctly. This may be due to three main reasons:

• Your text uses some specific TEXmacs features.

• You used a TEXmacs feature, which has not yet been implemented in the conversion algorithm.

• You found a bug in the conversion algorithm.

These issues will be discussed in more detail in the next section.

In case of problems, a naive strategy would be to correct the produced L^{A}TEX file and to send it to the journal. However, this strategy has the disadvantage that you have to make these corrections over and over again, each time that you convert your TEXmacs file name.tm, after having made some extra modifications. A better strategy is to use the Insert→specific→latex and Insert→specific→texmacs constructs to write text which is visible in the converted resp. original file only.

For instance, assume that the word “blauwbilgorgel” is hyphenated correctly in the TEXmacs source, but not in the L^{A}TEX conversion. Then you may proceed as follows:

1. Select “blauwbilgorgel”.

2. Click on Insert→specific→texmacs to make the text “blauwbilgorgel” TEXmacs-specific.

3. Click on Insert→specific→latex.

4. Type the latex code blauw\-bil\-gor\-gel with the correct hyphenation.

5. Press return to activate the L^{A}TEX-specific text.

In a similar fashion, you may insert L^{A}TEX-specific line breaks, page breaks, vertical space, style parameter modifications, etc.

6.2 Possible sources of conversion problems

6.2.1 Specific TeXmacs features

Some TEXmacs typesetting primitives have no analogues in L^{A}TEX, and the conversion algorithm will simply transform them into blank space. Some main features which are specific to TEXmacs are the following:

• Left primes.

• Big separators between big parentheses.

• Mosaics.

• Trees.

• Complex user macros.

• Vertical spaces “before” and “after”.

• Indentation flags “before” and “after”.

You should avoid to use these specific TEXmacs features, if your document needs to be converted into L^{A}TEX. Nevertheless, in the far future, the conversion program might generate encapsulated postscript by default of a more intelligible translation.

6.2.2 Not yet implemented conversions

Although we try to keep the conversion algorithm as complete as possible for your needs, certain things have not yet been implemented. Some examples of not yet implemented issues are

• Non standard fonts.

• Conversion of tabulars.

• Style parameters.

Any suggestion about desirable extensions of the conversion algorithm should be reported to

    TeXmacs@math.u-psud.fr

and we will try to incorporate it as quickly as possible. It may take some time to implement the correct conversion of style parameters, since these are not the same in TEXmacs and L^{A}TEX. Furthermore, layout differences between TEXmacs and L^{A}TEX can not entirely be eliminated.

6.2.3 Bugs in the conversion algorithm

The most annoying situation if when a converted TEXmacs document produces lots of errors at the compilation or if the result has nothing to do with the original. In that case you have probably detected a bug in the conversion algorithm (or in the installation of L^{A}TEX on your system). Please try to figure out the source of the bug in this case and report it by sending an email to

    TeXmacs@math.u-psud.fr

6.3 Conversion from LaTeX to TeXmacs

The current aim of the conversion program from L^{A}TEX to TEXmacs, is to help you in translating old documents into TEXmacs. Grosso modo, conversions from L^{A}TEX to TEXmacs are more problematic than conversions the other way around. Nevertheless, as long as you restrict yourself to using the most common L^{A}TEX commands, you should be able to convert your old documents reasonably well. For example, all TEXmacs help files have been written in L^{A}TEX in order to validate the L^{A}TEX to TEXmacs conversion program.

You may convert a L^{A}TEX document name.tex into TEXmacs using File→import→latex and save it under name.tm. If your L^{A}TEX document was written sufficiently well, then the converted result should be more or less acceptable, apart from certain unrecognized commands, which appear in red. A good solution would be to write your own style file for converted documents, based on the original style, and in which the unrecognized commands are defined.

However, in certain less fortunate cases, the converted document will look like a great mess. This usually stems from the fact that TEX and L^{A}TEX allow users to modify the parser dynamically, for instance using the \catcode command. In this case, the conversion program may get confused, by making erroneous assumptions on the mode or the environment. As a result, text may be converted as mathematics, mathematics as verbatim, and so on. Nevertheless, the commands in your source file name.tex which confused the conversion program are usually easily localized by comparing the L^{A}TEX source with its TEXmacs conversion. Modulo some hacking of the source, you should be able to remove the litigious code, so that the document converts reasonably well.

In the future, we also plan to extend the conversion program with a style file converter and some additional features which facilitate the translation of user defined commands, which are defined in another document than the one you want to convert.

GNU TeXmacs and its port to Guile

Like emacs, TEXmacs comes with a lisp-like extension language, namely the Guile Scheme dialect from the Gnome project. For documentation about Guile Scheme, we refer to

   http://www.gnu.org/software/guile/guile.html

Scheme has the advantage that it may be extended with extern C and C++ types and routines. In our case, we have extended Scheme with routines which you can use to create your own menus and key-combinations, and even to write your own extensions to TEXmacs.

If you have downloaded the source files of TEXmacs, then it may be interesting for you to take a look at the files

   Guile/Glue/build-glue-basic.scm
   Guile/Glue/build-glue-editor.scm
   Guile/Glue/build-glue-server.scm

These three “glue” files contain the C++ routines, which are visible within Scheme. In what follows, we will discuss some of the most important routines. We plan to write a more complete reference guide later. You may also take a look at the scheme .scm files in the directory

$TEXMACS_PATH/progs.

7.1 Writing your own initialization file

When starting up, TEXmacs executes the file $TEXMACS_PATH/progs/Init.scm, unless you have specified your own initialization file in $TEXMACS_HOME_PATH/progs/Init.scm. By default, the path $TEXMACS_HOME_PATH equals .TeXmacs. Usually, you want to add some extra actions to the default initialization file. In this case, you should not forget to include the command

    (exec-file "$TEXMACS_PATH/progs" "Init.scm")

in your personal initialization file. Similarly, the file $TEXMACS_PATH/progs/Init-buffer.scm is executed, each time you create a new buffer, unless you provide your own initialization file

$TEXMACS_HOME_PATH/progs/Init-buffer.scm.

7.2 Creating your own dynamic menus

In particular, the default initialization file executes

    $TEXMACS_PATH/progs/menu/main_menu.scm

in order to set up the TEXmacs main menu. We suggest you to have a look at this file in order to see how menus are created.

Actually, any menu or part of a menu is represented by a program. The program consists of a list of programs of one of the following forms:

    (=> "pulldown menu name" menu-definition)
    (-> "pullright menu name" menu-definition)
    ("entry" action)
    ("entry" "shorthand" action)
    ---
    (if condition menu-definition)
    (link variable)

The constructors => and -> are used to create pulldown or pullright menus and menu-definition should contain a program which creates the submenu. The constructor ("entry" action) creates an ordinary entry, where action will be compiled and executed when you click on entry. The optional "shorthand" stands for a keyboard macro with the same action. Items of a menu may be separated using ---. The constructor if is used for inserting menu items only if a certain condition is satisfied (for instance, if we are in math mode).

Finally, if we declared a TEXmacs variable to be a menu by

    (define variable menu-definition)

then we may use this menu indirectly using the link constructor. This indirect way of declaring submenus has two advantages

• An “indirect” submenu may be linked to as many menus as we like.

• New items may be added to “indirect” submenus a posteriori using

         (set! variable (menu-merge variable menu-declaration))

Actually, existing terms may also be overwritten in this way.

Some standard TEXmacs indirect menus are texmacs-menu, file-menu, edit-menu, insert-menu,
text-menu, paragraph-menu, document-menu, options-menu and help-menu. The command
    (menu-main menu-declaration)

is used in order to actually set the main menu. For instance, at initialization, we execute

    (menu-main '(link texmacs-menu))

7.3. CREATING YOUR OWN KEY-COMBINATIONS 39

7.3 Creating your own key-combinations

Two different types of key-combinations can be distinguished in TEXmacs: keymaps and short-

hands. We suggest you to look at the files $TEXMACS_PATH/progs/keyboard/keymaps.scm and
$TEXMACS_PATH/progs/keyboard/shorthands.scm in order to see how the default key-combinations

are defined.

Keymaps are specified using the command

    (set-keymap '(list of modes) '(list of maps))

The list of modes specifies the modes for which the keymaps are valid. Each keymap is a couple

    (key-combination action)

where action is an Scheme command associated to key-combination, which is a string Shorthands are specified using the command

    (set-shorthands '(list of modes) less gtr '(list of maps))

The list of modes specifies the modes for which the shorthands are valid. Each shorthand is a couple

    (key-combination result)

where the string result is inserted in the text, when key-combination has been completed. Notice that the symbols < and > are replaced by less and gtr in key-combination Notice also that an advantage of shorthands is that they can be continued into longer shorthands. For instance, when typing − - > , you obtain →; when you type another > , → is replaced by ↠.

7.4 Other files

Some other files may also be worth looking at:

• $TEXMACS_PATH/fonts/enc contains encodings for different TEX fonts.

• $TEXMACS_PATH/fonts/virtual contains definitions of virtual characters.

• $TEXMACS_PATH/langs/natural/dic contains the current dictionaries used by TEXmacs.

• $TEXMACS_PATH/langs/natural/hyphen contains hyphenation patterns for various languages.

• $TEXMACS_PATH/progs/fonts contains Scheme programs for setting up the fonts.

40 CHAPTER 7. GNU TEXMACS AND ITS PORT TO GUILE

Using GNU TeXmacs as an interface

TEXmacs currently supports a very simple interface for communicating with extern programs. Although this interface has to be improved in many ways in the future, it is typically possible to evaluate commands of an extern computer algebra system inside a “TEXmacs-session”, and display the results in a nice, graphical way. It is also possible to evaluate shell commands and Scheme programs inside such sessions.

8.1 Sessions

A session can be started from the Insert→session menu. A session consists of a sequence of input and output environments and possible text between them. When pressing return inside an input environment of a session, the text inside the environment is evaluated and the result is displayed in an output environment.

Now each session environment takes two arguments: the programming language and a name for the session. All input to be evaluated is redirected to the package which implements the programming languages and the session name is passed as an extra argument.

It is possible to redefine the screen layout of sessions as follows. For each session in programming language ‘p’, you then have to modify the environments ‘input-p’ and ‘output-p’ which respectively correspond to the layout of the input and the output.

It is possible to give sessions a name (the default name being “default”): by clicking on Insert→session→other, one both has to enter a session type and a session name. Different sessions which have the same type and the same name share correspond to one instance of the application being executed. Consequently, such sessions share a common environment. By using different session names, one may concurrently launch several instances of the same application.

When entering a command in a session, the application attempts to execute it. Several commands may be launched concurrently in the same document, but the output will only be active in the session where the cursor is and at the place of the cursor. Therefore, we recommend to use different buffers for parallel executions. Executions may be interrupted from the iconbar. it is also possible to disconnect (close) the application; in that case no further commands can be executed in the corresponding session.

8.1.1 Shell sessions

In a ‘shell’ session it is possible to evaluate shell commands. All input and output is verbatim. No particular command-line utilities (such as completion mechanisms) have been implemented yet. The output of the shell command is displayed gradually as the program executes.

8.1.2 Scheme sessions

In a ‘Scheme’ session you can evaluate Guile/Scheme programs. The input should be verbatim text. The input is evaluated and the result is displayed. No gradual output mechanism has been implemented yet for Scheme session.

8.1.3 Pari sessions

I order to use Pari inside TEXmacs, you should first make sure that you downloaded a version newer than Pari-2.1.0 from

    ftp://megrez.math.u-bordeaux.fr/pub/pari

In order to determine the version of an already installed Pari-system, type gp --version.

8.2 Link your own system to TeXmacs

Assume that you have written a computer algebra system (or some other scientific program which requires mathematical input and output), and that you want a graphical interface for your program. In order to link your system to TEXmacs, you have to options:

1. Link your system to TEXmacs via pipes.

2. Link your system as a dynamically linked library.

The first option is usually easier to implement, more robust and provides gradual output; the second option is faster. Let us now describe the steps you have to go through for each of these two options.

8.2.1 Connections via pipes

1. Create a special command line option for your program which allows it to recognize that it has been called by TEXmacs. All communication between TEXmacs and your application will pass through standard input and output.

2. Include a line of the form

         (declare-connection "name" "shell-cmd")

in your personal initialization file Init.scm. Here name must be the name of your package and shell-cmd the shell command to launch it (including special command line options). You should also include a command

    (connection-format "name" "input-format" "output-format")

if your input and output is not merely verbatim text. More details about the available data formats can be found in the next section.

3. Add a command like

    (set! session-menu (menu-merge session-menu
      '(("name" (make-session "name")))))

to your personal initialization file Init.scm, in order to be able to start a TEXmacs-session from the Insert→session menu, in which you can evaluate expressions of your language. You may also redefine the keyboard for your such sessions.

4. Create a style file in which you provide the input and output environments ‘input-name’ and ‘output-name’ for your system.

5. If everything works well, and you wish to make it possible for others to use your system inside the official TEXmacs distribution, then contact me at

    TeXmacs@math.u-psud.fr

I will take care of the inclusion of the necessary initialization commands for your package in the TEXmacs Init.scm file and your input and output styles in the program.ts file.

8.2.2 Connections via dynamically linked libraries

1. Modify the architecture of your system in such a way that the main part of it can be linked as a shared library; your binary should typically become a very small program, which handles verbatim input and output, and which is linked with your shared library at runtime.

2. Copy the include file $TEXMACS_PATH/include/TeXmacs.h into the include directory of your system’s source and write the input/output routines as required by the last TeXmacs communication protocol as explained below.

3. Include a line of the form

    (declare-package "name" "libname.so" "get_name_package" "init")

in your personal initialization file Init.scm. Here name must be the name of your package, libname.so the corresponding shared library, get_name_package the function, which will be called by TEXmacs in order to link your system to TEXmacs, and init some initialization string for your package.

4. Follow the same steps 3, 4 and 5 as above.

8.3 Communication via pipes

By default, all input from the application and all output to the application is verbatim. When including a command like

    (connection-format "name" "input-format" "output-format")

in your personal initialization file, it is possible to use other data formats with more semantics. Currently, we provide only verbatim as an input data format for your application and verbatim, latex, html and generic as output data formats.

We recommend the use of generic as the output format, because you may access to all other data formats via this format and it allows a clean specification of the start and the end of a data package. More precisely, the generic output format comes with three special control characters

    #define DATA_BEGIN   ((char) 2)
    #define DATA_END     ((char) 5)
    #define DATA_ESCAPE  ((char) 27)

Any data package which is send from the application to TEXmacs should start with DATA_BEGIN and with a matching DATA_END. After DATA_BEGIN, you should send the particular data format of your package, followed by the ':' character.

Moreover, the DATA_BEGIN/DATA_END may be used recursively inside your data package. The DATA_ESCAPE character followed by any other character c is used to produce c, even if c is one of the three control characters. The following C++-program illustrates the use of the generic output format.

    #include <stdio.h>
    #include <string.h>
    #include <iostream.h>
    #define DATA_BEGIN   ((char) 2)
    #define DATA_END     ((char) 5)
    #define DATA_ESCAPE  ((char) 27)
    int
    main () {
      cout << DATA_BEGIN << "verbatim:";
      cout << "Welcome to my package\n";
      cout << DATA_END;
      fflush (stdout);
      while (1) {
        char buffer[100];
        cin >> buffer;
        if (strcmp (buffer, "quit") == 0) break;
        cout << DATA_BEGIN << "verbatim:";
        cout << "You typed " << buffer << "\n";
        cout << "And now a LaTeX formula: ";
        cout << DATA_BEGIN << "latex:";

        cout << "$x^2+y^2=z^2$";
        cout << DATA_END;
        cout << DATA_END;
        fflush (stdout);
      }
      return 0;
    }

8.4 The TeXmacs communication protocol

The TEXmacs communication protocol is used for linking libraries dynamically to TEXmacs. The file $TEXMACS_PATH/include/TeXmacs.h contains the declarations of all data structures and functions used by the protocol. Actually, we foresee a succession of different protocols. Each of these protocols have the abstract data structures TeXmacs_exports and package_exports in common, with information about the versions of the protocol, TEXmacs and your package.

The n-th concrete version of the communication protocol should provide two data structures TeXmacs_exports_n and package_exports_n. The first structure contains all routines and data of TEXmacs, which may be necessary for the package. The second structure contains all routines and data of your package, which should be visible inside TEXmacs.

In order to link your system to TEXmacs, you have to implement a function

    package_exports* get_my_package (int version);

This function takes the highest TEXmacs communication protocol supported by your TEXmacs system on input. It should return a pointer to an instance of a concrete structure package_exports_n, where n is inferior or equal to version.

8.4.1 Version 1 of the TeXmacs communication protocol

In the first version of the TeXmacs communication protocol, your package should export an instance of the following data structure:

    typedef struct package_exports_1 {
      char* version_protocol; /* "TeXmacs communication protocol 1" */
      char* version_package;
      char* (*install) (TeXmacs_exports_1* TM, char* options, char** errors);
      char* (*evaluate) (char* what, char* session, char** errors);
      char* (*execute) (char* what, char* session, char** errors);
    } package_exports_1;
The string version_protocol should contain "TeXmacs communication protocol 1" and the

string version_package the version of your package.

The routine install will be called once by TEXmacs in order to initialize your system with options options. It communicates the routines exported by TEXmacs to your system in the form of TM. The routine should return a status message like

    "my-package.version successfully linked to TeXmacs"

If installation failed, then you should return NULL and *errors should contain an error message. Both what and the returned string have a special format, in which it is possible to encode arbitrary TEXmacs documents. This format will be explained in the next section.

The routine evaluate is used to evaluate the expression what inside a TEXmacs-session with name session. It should return the evaluation of what or NULL if an error occurred. *errors either contains one or more warning messages or an error message, if the evaluation failed. The command

    (package-format "name" "input-format" "output-format")

is used in order to specify the input and output formats for evaluations, in a similar way as in the case of pipes.

The routine execute has a similar specification as evaluate, except that it is not used for the evaluation of expressions inside a TEXmacs-session, but rather for other communication purposes between TEXmacs and your package.

Remark. All strings returned by the routines install, evaluate and execute, as well as all warning and error messages should be allocated using malloc. They will be freed by TEXmacs using free.

The first version of the TEXmacs communication protocol also requires TEXmacs to export an instance of the data structure

    typedef struct TeXmacs_exports_1 {
      char* version_protocol; /* "TeXmacs communication protocol 1" */
      char* version_TeXmacs;
    } TeXmacs_exports_1;
The string version_protocol contains the version "TeXmacs communication protocol 1" of the

protocol and version_TeXmacs the current version of TeXmacs.

About

9.1 About GNU TeXmacs

Copyright: (C) 1998 Joris van der Hoeven.

Supported systems: PC/Gnu-linux and Sun/OS.

Email: TeXmacs@math.u-psud.fr.
Web page: http://www.texmacs.org.
Regular mail:  Joris van der Hoeven
         Dépt. de Mathématiques (B^at. 425)
         Université Paris-Sud
         91405 Orsay Cedex
         France

9.2 Copying policy

TEXmacs is protected by the “GNU general public license”. Roughly speaking, this means that you have the following rights:

• You can get TEXmacs for free.

• You can get the source code of TEXmacs for free.

• You may modify the source code of TEXmacs.

Moreover, you have the right to redistribute or sell TEXmacs or modified versions of TEXmacs to other people AS LONG AS these copies also fall under the GNU general public license and AS LONG AS these people have the same rights as you do and they are informed about this.

On the other hand, TEXmacs comes WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

In the home directory ($TEXMACS_PATH) of your TEXmacs distribution, you should have a text file named COPYING with the complete GNU general public license; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

9.3 Help and donations

Our copying policy allows you to support the TEXmacs project in many ways. In the Help→projects and Help→help me menus we respectively explain our future plans for the program and the ways in which you can support these plans.

Of course, the fact that we provide TEXmacs for free does not mean that we do not appreciate money donations for the project. If you feel you can give financial or other, immaterial help, please write to one of the addresses mentioned above.

9.4 Using TeXmacs as an interface

If you plan to write an interface between TEXmacs and a computer algebra system, please contact us. The GNU general public license allows TEXmacs to be linked to free as well as proprietary computer algebra systems (see http://www.gnu.org for precise definitions). However, free computer algebra systems will be given a higher priority and may benefit from extra publicity inside TEXmacs.

Indeed, we are deeply convinced that free computer algebra systems are the only acceptable ones from a mathematical point of view. We have two main reasons for this:

• Just as a mathematician should be able to build theorems on top of other theorems, it should be possible to freely modify and release algorithms in computer algebra systems.

• A result computed by a computer algebra system, whose source code is not public, can not be accepted as part of a mathematical proof.

9.5 Thanks

The GNU TEXmacs system, which is part of the ¡A HREF=”http://www.gnu.org”¿GNU project¡/A¿, was designed and written by Joris van der Hoeven. The system was inspired both by the TEX system, written by D. Knuth, and by Emacs, written by R. Stallman. Special thanks goes to them, as well as to the C.N.R.S. (the French national institute for scientific research), which employs me and authorized me to distribute this program for free.

Further thanks go to the following contributors:

• Dan Grayson, with whose help I implemented communications with computer algebra systems via pipes, who provided some money support for TEXmacs, and who made many useful comments and suggestions.

• Karim Belabas, with whom I designed and developed the first protocol for interfacing TEXmacs with scientific computation or computer algebra systems. He also implemented the interface with the pari system.

• Ralf Treinen for supporting the debian package for TeXmacs and for his corrections in the german dictionary.

• Dan Ignat, for translating the menus and some of the helpfiles into romanian.

• Andrey Grozin for translating the menus into russian and for his further help to support the russian language.

• David Moriano Garcia for translating the menus into spanish.

• Harald Ellmann for translating the menus into swedish.

• Sylvie Lalande and Michael Schmeling for the french and german language supports.

• Bruno Haible, who helped me with porting TEXmacs to the SUN system.

• Rob Clark, for a patch which improves system time support.

• David Allouche, for the TEXmacs icon.

Final thanks go to all others who have contributed to TEXmacs, for instance by sending bug reports or by giving suggestions for future releases: Alexandre Abbes, Till Adam, Guillaume Allègre, Uwe Assmann, Daniel Augot, Olaf Bachmann, Roy C. Bentley, Karl Berry, Matthias Berth, Cédric Bertolini, Matthew Bettencourt, Jim Blandy, Alexander M. Budge, Dominique Caron, António Carvalho, Carlo Cecati, Henri Cohen, Teddy Fen-Chong, Claire M. Connelly, Christoph Conrad, Paulo Correia, Ulf Ekström, Robin Fairbairns, Tony Falcone, Hilaire Fernandes, Jean-Claude Fernandez, Jens Finke, Stefan Freinatis, Lionel Garnier, Patrick Gonzalez, Frédéric Grasset, Laurent Guillon, Harri Haataja, Guillaume Hanrot, James W. Haefner, Karl M. Hegbloom, Jochen Heinloth, Benjamin T. Ingram, Frederic de Jaeger, Pierre Jarillon, Paul E. Johnson, Tim Kaulmann, Mukund S. Kalisi, Jeremy Kephart, Winter Laite, Joerg Lippmann, Pierre Lorenzon, V.S. Lugovsky, Paul Magwene, Bernd Markgraf, Eric Marsden, Evan Martin, Alisdair McDiarmid, Herve le Meur, Amir Michail, Dirk Moebius, Julian Morrison, Nathan Myers, Pierre Pansu, Fernández Pascual, Alen L. Peacock, Francois Pellegrini, Jean Peyratout, Jacques Peyriere, Nguyen-Dai Quy, Adrien Ramparison, Staffan Ringbom, Juan Pablo Romero, Fabien Salvi, Duncan Sands, Breton Saunders, Gilles Schaeffer, Rainer Schöpf, Vasco Alexandre da Silva Costa, Bernard Stloup, Roman Svetlov, Nicolas Thiery, Reuben Thomas, Andreas Umbach, Miguel A. Valle, Harro Verkouter, Sascha Ziemann, Reinhard Zierke, Paul Zimmermann.

50 CHAPTER 9. ABOUT

Part B

A guide to the source code

General architecture of TeXmacs

10.1 Introduction

The TEXmacs program has been written in C++. You need g++ and the makefile utility in order to compile TEXmacs. Moreover, I developed a preprocessor gencc, which is used for the automatic creation of makefiles and generic template expansions (like genclass but more powerful). For more details, look in the doc subdirectory of gencc.

Currently, the source (in the src directory) of the TEXmacs implementation has been divided into the following parts:

• A set of basic and generic data structures in the Basic directory.

• Standard resources for TEXmacs, such as TEX fonts, languages, encodings and dictionaries, in the Resource directory.

• A documented graphical toolkit in the Window directory (although the documentation is a bit outdated).

• The extension language for TEXmacs in the Prg directory.

• The typesetting part of the editor in the directory src/Typeset.

• The editor in the directory src/Edit.

• The TEXmacs server in the directory src/Server.

All parts use the data structures from Basic. The graphical toolkit depends on Resource for the TEX fonts. The extension language is independent from Resource and Window. The typesetting part depends on all other parts except from Prg. The main editor and the TEXmacs server use all previous parts.

The TEXmacs data are contained in the directory edit which corresponds to the TEXmacs distribution without the source code. Roughly speaking, we have the following kind of data

• Font data in fonts (encodings, .pk files, etc.).

• Language data in languages (hyphenation patterns, dictionaries, etc.).

• Document styles in style.

• Initialization and other Scheme programs in progs.

The directory misc contains some miscellaneous data like the edit icon (misc/pixmaps/edit.xpm).

10.2 Intern representation of texts

TEXmacs represents all texts by trees (for a fixed text, the corresponding tree is called the edit tree). The nodes of such a tree are labeled by standard operators which are listed in

Typeset/data.gen.h and Typeset/data/data.gen.cc. The labels of the leaves of the tree are

strings, which are either invisible (such as lengths or macro definitions), or visible (the real text).

The meaning of the text and the way it is typeset essentially depends on the current environment. The environment mainly consists of a relative hash table of type rel_hashmap<string,tree>, i.e. a mapping from the environment variables to their tree values. The current language and the current font are examples of system environment variables; new variables can be defined by the user.

10.2.1 Text

All text strings in TEXmacs consist of sequences of either specific or universal symbols. A specific symbol is a character, different from '\0', '<' and '>'. Its meaning may depend on the particular font which is being used. A universal symbol is a string starting with '<', followed by an arbitrary sequence of characters different from '\0', '<' and '>', and ending with '>'. The meaning of universal characters does not depend on the particular font which is used, but different fonts may render them in a different way.

10.2.2 The language

The language of the text is capable performing a further semantic analysis of a text phrase. At least, it is capable of splitting a phrase up into words (which are smaller phrases) and inform the typesetter about the desired spaces between words and hyphenation information. In the future, additional semantics may be added into languages. For instance, spell checkers might be implemented for natural languages and parsers for mathematical formulas or programming languages.

10.3 Typesetting texts

Roughly speaking, the typesetter of TEXmacs takes a tree on input and produces a box, while accessing and modifying the typesetting environment. The box class is multifunctional. Its principal method is used for displaying the box on a post-script device (either the screen or a printer). But it also contains a lot of typesetting information, such as logical and ink bounding boxes, the positions of scripts, etc.

Another functionality of boxes is to convert between physical cursors (positions on the screen) and logical cursors (paths in the edit tree). Actually, boxes are also organized into a tree, which often simplifies the conversion. However, because of macro expansions and line and page breaking, the conversion routines may become quite intricate. Notice also that, besides a horizontal and vertical position, the physical cursor also contains an infinitesimal horizontal position. Roughly speaking, this infinitesimal coordinate is used to give certain boxes (such as color changes) an extra infinitesimal width.

10.4 Making modifications in texts

In Edit/modify.gen.h and Edit/Modify you find different routines for modifying the edit tree. Modifications go in several steps:

1. A certain input event triggers an action, such as make_fraction, which intends to modify the edit tree.

2. All modifications which make_fraction or its subroutines will make to the edit tree eventually break down to seven elementary modification routines, namely assign, insert, remove,

     split, join, ins_unary and rem_unary.

3. Before performing the required modification, the elementary modification routine first notifies all views of the same text of the modification.

4. On notification, each view updates several things, such as the cursor position. It also notifies the modification to the typesetter of the text, since the typesetter maintains a list of already typeset paragraphs.

5. When all views have been notified of the modification, we really perform it.

6. Each user action like a keystroke or a mouse click is responsable for inserting undo points between sequences of elementary modifications. When undoing a modification, the editor will move to the previous undo point.

56 CHAPTER 10. GENERAL ARCHITECTURE OF TEXMACS

Basic data structures

In this chapter, we give a rough description of TEXmacs’s basic data types in Basic. The description of the exported functions is non exhaustive and we refer to the corresponding header files for more precision.

11.1 Memory allocation and data structures in TeXmacs

The file fast_alloc.gen.h declares the TEXmacs memory allocation routines. These routines are very fast for small sizes, since for each such size, TEXmacs maintains a linked list of freed objects of that size. No garbage collection has been implemented yet.

Modulo a few exceptions, all TEXmacs composite data structures are based on the mod-

ules concrete, abstract, concrete_null and abstract_null. Consequently, these data struc-

tures are pointers to representation classes, which may be abstract in the case of abstract and abstract_null, and which always contain a reference counter. Because of the reference counter, the C++ copy operator is very fast. Most of the implemented data structures also export a function copy, which should be used if one really wants to physically duplicate an object,

For classes constructed using concrete_null or abstract_null, the pointer to the representation class is allowed to be NULL and we have a default constructor which initializes this pointer with NULL. Instances of these classes are tested to be NULL using the function nil. Examples of such classes are lists, files and widgets.

11.2 Array-like structures

TEXmacs implements three “array-like” structures:

• string is the string type, which may contain ’0’ characters.

• tree is the tree type with string labels.

• array<T> is the generic array type with elements of type T.

Array-like structures export the following operations:

• N computes the length of an array.

• [] accesses an element.

• << is used for appending elements or arrays.

For trees t, we notice that t->label yields the label of the tree and t->a the array of its children. The second argument of << for trees is either a tree or an array of trees.

The implementation has been made such that the << operation is fast, which is useful when considering arrays as buffers. Actually, the allocated space for arrays with more than five elements (words for strings) is always a power of two, so that new elements can be appended quickly. Notice that GNU malloc also always allocates blocks, whose sizes are powers of two. Therefore, we do not waste memory for small and large arrays.

11.3 Lists

Generic lists are implemented by the class list<T>. The “nil” list is created using list<T>(), an atom using list<T>(T x) and a general list using list<T>(T x, list<T> next). If l is a list, l->item and l->next correspond to its label and its successor respectively (car and cdr in lisp). The functions nil and atom tests whether a list is nil or an atom. The function N computes the length of a list.

The type list<T> is also denoted by path, because some additional functions are defined for it. Indeed, paths are used for accessing descendents in tree like structures. For instance, we

implemented the function tree subtree (tree t, path p).

11.4 Hash tables

The hashmap<T,U> class implements hash tables with entries in T and values in U. A function hash should be implemented for T. Given a hash table H. We set elements through

    H(x)=y;

and access to elements through

    H[x]

We also implemented a variant rel_hashmap<T,U> of hash tables, which also have a list-like structure, which makes them useful for implementing recursive environments.

11.5 Other data structures

• command implements abstract commands.

• file implements files.

• iterator<T> implements generic iterators.

• rectangles implements rectangles and lists of rectangles.

11.5. OTHER DATA STRUCTURES 59 • space implements stretchable spaces.

• timer implements timers.

60 CHAPTER 11. BASIC DATA STRUCTURES

The TeXmacs data format

12.1 Introduction

TEXmacs represents all texts by trees (for a fixed text, the corresponding tree is called the edit tree). The nodes of such a tree are labeled by standard operators which are listed in

Typeset/data.gen.h and Typeset/data/data.gen.cc. The labels of the leaves of the tree are

strings, which are either invisible (such as lengths or macro definitions), or visible (the real text).

The meaning of the text and the way it is typeset essentially depends on the current environment. The environment mainly consists of a relative hash table of type rel_hashmap<string,tree>, i.e. a mapping from the environment variables to their tree values. The current language and the current font are examples of system environment variables; new variables can be defined by the user.

In what follows, we will describe the meanings of the different stardard TEXmacs operators. We will use Scheme notation. The current TEXmacs data format is unstable and several changes will take place in the near future. In the last section we will describe these changes.

12.2 Leaves

The encoding of normal text is described in the chapter about fonts. The only thing that should be noticed is that large delimiters and (back)primes are currently part of normal text (i.e. the leaves of edit trees). For instance, <left-(> corresponds to a large left bracket. Similarly, ' and ` stand for a prime and a backprime. In the future, these constructs should no longer be part of the leaves.

Certain invisible data can also occur as leaves of TEXmacs trees. Common examples are lengths of boxes and spaces, auxiliairy data, etc.

12.3 Main formatting operators

(document p1 ... pn)

The general form of the edit tree, which is a document consisting of the paragraphs p1, ..., pn.

(concat t1 ... tn)

Horizontal concatenation of the trees t1, ..., tn. Often, but not always, the paragraphs of the main edit tree are concatenations.

(hspace spc) or (hspace spc min max)

Horizontal space of length spc. The optional min and max parameters indicate that the space may be shrinked or extended to these values. We notice that certain units of length, like fn, automatically provide shrinking and extension information.

(vspace* spc) or (vspace* spc min max)

Insert vertical space of length spc before this paragraph.

(vspace spc) or (vspace spc min max)

Insert vertical space of length spc after this paragraph.

(space spc bot top)

Insert horizontal space of length spc, with bottom and top lines at heights bot resp. top.

(htab spc)

Tabbing space of minimal length spc.

(split pos1 ... posn)

Split the current paragraph as a table of n columns, which are alligned following pos1, ..., posn.

(move t x y)

Move the tree n horzontally by length x and vertically by length y.

(resize t "normal" x1 y1 x2 y2)

New logical bounding box of t has (x1,y1) as its lower left corner and (x2,y2) as its upper right corner.

(resize t "extend" x1 y1 x2 y2)

As above, but the new bounding box is forced to include the old one.

(format "line break")

Forces a line break.

(format "new line")

Forces a new line.

(format "line separator")

Like the TEX & command.

(format "next line")

Like the TEX \\ command.

(format "no line break")

Prevents a line break.

(format "no first indentation")

Prevent left indentation for this paragraph.

(format "no last indentation")

Prevent right indentation for this paragraph.

(format "enable first indentation")

Force left indentation for this paragraph.

(format "enable last indentation")

Force right indentation for this paragraph.

(format "page break")

Forces a page break.

(format "new page")

Forces a new page.

(format "no page break before")

Prevents a page break before this line

(format "no page break after")

Prevents a page break after this line

(format "with limits")

Notify that the preceding text has limits. This results subscripts and superscripts to be placed under and over the preceding text.

12.4 Mathematical operators

(group t)

Consider t as an entity (a bit like enclosing t within accolades in TEX).

(below t sub)

Subscript sub below t.

(above t sup)

Superscript sub below t.

(lsub script)

Left subscript script for text which follows.

(lsup script)

Left superscript script for text which follows.

(rsub script)

Right subscript script for preceding text.

(rsup script)

Right superscript script for preceding text.

(frac num den)

Fraction with numerator num and denominator den.

(sqrt t) or (sqrt t n)

Square root of t or n-th root of t.

(wide t accent)

Wide accent above t.

(neg t)

Wipe out t with a negation slash.

(tree root t1 ... tn)

Tree with root root and children t1, ..., tn.

(matrix t11 ... t1m ...... tn1 ... tnm n m)

n by m matrix with entries tij.

(table t11 ... t1m ...... tn1 ... tnm n m)

n by m table with entries tij.

(mosaic t11 ... t1m ...... tn1 ... tnm n m)

n by m tabel whose entries tij can be aligned and merged.

(mosaic item t pos x y bg)

This field in a mosaic contains t, is positioned at pos, spans over x columns and y rows, and has background bg.

12.5 Environmental and other invisible operators

(inactive t)

Deactivate an environmental or invisible operator for editing.

(symbol <>)

For entering a universal symbol.

(latex cmd)

For entering a L^{A}TEX command.

(hybrid cmd)

For entering a TEXmacs function call, a L^{A}TEX command, or a universal symbol.

(; t old)

Used to backup an old value old of an environment variable (which now contains t) for being recovered later.

(' t)

Evaluates to t.

(delay (cmd t1 ... tn))

Evaluates arguments t1, ..., tn to u1, ..., un and returns (cmd u1 ... un).

(:= var t)

Assign the environment variable var with t.

(set var t)

Temporarily set the environment variable var with t.

(reset var)

Reset the environment variable var to its original value.

( f t1 ... tn)

Apply the function f to t1, ..., tn.

(begin env t1 ... tn)

Start the environment env with arguments t1, ..., tn.

(end env)

Ends the environment env.

(func arg1 ... argn body)

Function with arguments arg1, ..., argn and body body.

(env arg1 ... argn open close)

Environment with arguments arg1, ..., argn and begin body open and end body close.

(label name)

Label with name name.

(reference name)

Reference to label with name name.

(write t aux)

Write t to auxiliairy data buffer aux. This construct is used for creating tables of contents, bibliographies, glossaries, etc.

(specific what t)

Specifies that t should only appear when the document is converted to what. If what is "TeXmacs", then t only appears in TEXmacs itself.

(postscript file width height x1 y1 x2 y2)

Postscript (or other kind of) figure in file, of width width, length length, lower left clipping corner (x1,y1) and upper right clipping corner (x2,y2). The parameters width, height, x1, y1, x2, y2 may be empty strings, in which case the default settings of the image are used. The width and the height may also be of the form *mag or /schrink, in which case the default lengths are magnified resp. shrinked by a factor mag resp. schrink.

12.6 Functional operators

(+ t u)

Add the numbers or lengths t and u.

(- t u)

Subtract the numbers or lengths t and u.

(x t u)

Multiply the numbers t and u.

(* t u)

Concatenate the strings t and u.

(nr t what)

The number t in what (roman, alpha, etc.).

(translate t from into)

Translate t from from into into.

12.7 For private use

(() t1 ... tn)
The tuple (t1, ..., tn).
(, t1 ... tn)
The set {t1, ..., tn}.
(-> t u)

The association t -> u.

12.8 Planned changes

1. Currently, the TEXmacs operators are represented by strings. In the future, for cleanness and efficiency, we plan to represent them by integer codes.

2. Currently, the arities of TEXmacs operators are not allowed to vanish (in which case they become leaves). For operators like concat this not very clean nor very handy, so in combination with the above change, we plan to allow arities of zero. The formatting operators of the form (format how) will then become operators of arity zero.

3. Currently, large separators and primes are part of the strings in the leaves. We wish to

replace this by the cleaner constructs (left sep), (mid sep), (right sep), (lprime pr)
and (rprime pr).

4. We are not happy at all with the way tables are formatted. We currently provided imperfect mosaic and split operators, which should be replaced with a single, more powerful operator. However, we are not yet very sure about the right choice.

5. Several extensions of the format should be foreseen. In Typeset/data/data.gen.cc, you will already notice that we have introduced the hlink, graphics, point, line, arc and bezier operators, which have to be implemented. Other future operators will concern footnotes, multicolums, dynamic texts, graphics, computer algebra output, database or spreadsheet facilities, etc.

Converters to other data formats

Currently, we have implemented imperfect converters between TEXmacs and L^{A}TEX and from html to TEXmacs. We hope that someone else will be willing to write better converters from scratch. This chapter has been included in order to give some recommendations in that direction based on our experience from the implementation of the actual conversion programs. We also recommend to take a look at the current implementations in the directory Convert.

13.1 Parsing extern data formats

In order to write a converter from L^{A}TEX html, xml, etc. to TEXmacs, a good first step is to write a parser for the extern data format. For html, xml, etc. this should be rather easy, but for L^{A}TEX, you will probably need to be a real L^{A}TEX guru (which I am not). We recommend the result of the parsing step to be a Scheme expression (something which is regrettable not the case for our actual converters), because this language is very well adapted for the implementation of the actual converter.

This first step should be able to process any correct file having the extern data format; possible incompatibilities should only come into play during the actual conversion. In the case of L^{A}TEX, one should not expand the macros and keep all macro definitions, because TEXmacs will be able to take advantage out of this.

13.2 The actual converter

We recommend the actual converter to proceed in several steps. Often it is convenient to start with a rough, structural, conversion step, which is “polished” by a certain number of additional steps. These additional steps may take care of some very particular layout issues which can not be treated conveniently at the main step.

Actually, the main difficulties usually come from exceptional text, like verbatim, and layout issues which are handled differently in the extern data format and TEXmacs. A good example of such a difference between L^{A}TEX and TEXmacs is the way equations or lists are handled. Consider for instance the following paragraph:

Text before.

a^{2} + b^{2} = c^{2}.

Text after.

In L^{A}TEX, the equation is really seen as a part of the paragraph. Indeed, there will not be any blank line between “Text before” and the equation. However, for efficiency reasons, it is better to see the paragraph as three paragraphs in TEXmacs, because the lines can be typesetted independently. Nevertheless, the equation environment will disable the indentation of “Text after”.

As a result of this anomaly, converted texts have to be postprocessed, so as to insert paragraph breaks at strategic places. It should be noticed that this step may be independent from the format which is actually being converted and that a similar reverse step may be implemented for backward conversions. We also notice that one needs an exhaustive list of all similar exceptional environments for this postprocessing step. Actually, a future version of TEXmacs might come with an additional feature, which permits the automatic detection of such environments. This is also important from a semantical point of view, because one should be able to detect that the above example logically forms only one and not three paragraphs.

13.3 Backward conversions

Conversions from TEXmacs to an extern data format are usually easier to implement, because the TEXmacs data format is semantically rich. However, conversions to an extern data format without a TEX-like macro facility give rise to the problem of macro expansion of non supported TEXmacs functions or environments. We plan to write a facility for this, which you will be able to use when writing a converter from TEXmacs to something else.

The graphical toolkit

14.1 Introduction

14.1.1 Main architecture

The graphical toolkit used by Edit has two main components: an abstract window interface, which is very similar to X Window, and the actual toolkit. At this moment an abstract window interface for X Window has been implemented, but others might be added in the feature.

The abstract window interface consists of two main classes: display and window. The display class is responsible for

• The connection with the (X-)server.

• Managing server resources such as colors and fonts.

• Inter-window communication (i.e. selections and so).

• Redirection of input/output (pointer and keyboard grabs).

The window class is responsible for

• The part of the layout of a window, which is negotiated with the window manager.

• Providing a basic set of postscript-compatible graphical routines.

• Implementation of some clipping and region translation routines.

• Delegation of events to the widget associated to the window.

In particular, the window-class inherits from the ps_device-class, which is responsible for providing the basic set of postscript-compatible graphical routines. Hence, user applications will draw their graphics on a ps_device, since this will both allow them to visualize them in a window or on a printer.

The graphical toolkit built on top of the abstract window interface is widget oriented. A large number of widget classes are implemented, which all inherit from the abstract widget class. Widgets may have a finite number of children and they are responsible for 70 CHAPTER 14. THE GRAPHICAL TOOLKIT

• Their, and their children, sizes and positioning in the window.

• Reaction on events, which are either redraw requests, keyboard or pointer events or other miscellaneous events.

• Other functionalities, which depend on the particular widget class. Later a special widget-style manager will be implemented, which will be able to present widgets according to different “styles”.

A simple example In order to create a window “Test” with the text “Hello world” in it, one first opens the display, then create the widget with the text and finally the window, with the widget attached to it

    display dis= open_display ();
    widget  wid= text_widget ("Hello world");
    window  win= plain_window (wid, dis, "Test");

Technically speaking, the window creation amounts to several actions:

• The widget is questioned for an appropriate size for it (actually, only minimal, default and maximal size hints are computed).

• The window is created.

• The widget is “attached” to the window.

• The subwidgets are “positioned” at their appropriate places and they are given appropriate sizes within their parents.

The next step is to make the window visible by

    win->map ();

At this points repaint request events are generated, which are handled when starting the event loop by

    dis->event_loop ();

Eventually, the window win will be destroyed using

    delete win;

At this point, control is handled back by the event loop and we close and destroy the display by

    close_display (dis)
    delete dis;

The user only has to bother about destroying window and displays; widgets are automatically destroyed if they are no longer being referenced to.

14.1.2 Widgets and event processing

From the implementation point of view, widgets are pointers to instances of the abstract widget representation class widget_rep. Moreover, the widget class supports reference counting. The widget_rep class contains information about the window it is attached to and its location within this window, its size, the position of the origin of its local coordinates (north_west, north, etc.) and its children. The widget_rep class also provides a virtual event handler widget_rep::handle. This handler returns true if the event could be handled.

The implemented widget representation classes are organized in a hierarchy, which contains both concrete and abstract classes. The abstract classes reimplement the virtual event handler widget_rep::handle in such a way that if the event is recognized, then the event is dispatched to a more particular virtual event handler, possibly after some processing.

For example, instances of the basic_widget_rep class can handle the most common events, such as keyboard, mouse, repaint events and so on. If a key is pressed, then the virtual function

basic_widget_rep::handle_keypress is called with an argument of type keypress_event. The

default implementation of this virtual function does nothing.

The user can also create his own events, which he can pass to any widget. For instance in order to invalidate a region for redrawing, one creates an invalidate event using emit_invalidate and sends it to the appropriate widget using the operator <<. Notice that the user is responsible for sending events to widgets which can handle them. Bad matches are only discovered at run time, in which case an error is generated by <<.

A simple example

Suppose that we want to make a widget, which tracks keyboard events and which displays them. Such a widget must have a construction routine and keyboard and repaint handlers:

    class track_widget_rep: basic_widget_rep {
      string last_key;
      track_widget_rep ();
      void handle_keypress (keypress_event ev);
      void handle_repaint (repaint_event ev);
    };

The constructor is taken to be empty and places the origin at the center of the widget

    track_widget_rep::track_widget_rep (): basic_widget (center) {}

In particular last_key is initialized by the empty string. We also define the function

    void
    track_widget () {
      return new track_widget_rep ();
    }

in order to create an instance of a track_widget.

The event handler for keyboard events should just reset the string last_key and invalidate the entire widget region.

void
track_widget_rep::handle_keypress (keypress_event ev) {
last_key= ev->key;
this << emit_invalidate_all ();
}

The event handler for repainting first determines the string to be repainted as a function of last_key, computes its extents and repaints it at the center.

void
track_widget_rep::handle_repaint (repaint_event ev) {
string s= (last_key == ""? "No key pressed": "Pressed " * last_key);
SI x1, y1, x2, y2;
win->get_extents (s, x1, y1, x2, y2); // CHECK THIS
win->set_color (black);
win->fill (ev->x1, ev->y1, ev->x2, ev->y2);
win->set_color (white);
win->draw_string (s, -(x1+x2)>>1, -(y1+y2)>>1);
}

14.2 The abstract window interface

14.2.1 Displays

14.3 Widget principles

14.3.1 The widget class

Widgets are pointers to instances of the abstract widget representation class widget_rep. Widgets support reference counting, so that a widget is automatically destroyed if it is not used any more (except in the case of circular referencing; see below). As a general rule, the user does not have to worry about the creation and destruction of widgets.

The widget representation class

The definition of the widget_rep class goes as follows:

struct widget_rep: rep_struct {
window        win;           // underlying window
SI            ox, oy;        // origin of widget in window
SI            w, h;          // width and height of widget
gravity       grav;          // position of the origin in the widget
array<widget> a;             // children of widget
array<string> name;          // names for the children

      widget_rep (array<widget> a, array<string> name, gravity grav);
      virtual ~widget_rep ();
      virtual operator tree () = 0;
      virtual bool handle (event ev) = 0;
      SI       x1 (); SI y1 (); // lower left window coordinates of widget
      SI       x2 (); SI y2 (); // upper right window coordinates of widget
      bool     attached ();     // tests whether (win != NULL)
      volatile void fatal_error (string mess, string rout="", string fname="");
      friend class widget;
    };

The win field specifies the window to which the widget is attached (win=NULL, by default). The origin (ox,oy) of the widget is specified with respect to the windows origin. Next come the width w and the height h of the widget. The gravity grav determines where the origin of the widget is located (north_west, north, etc.). The array a specifies the children of the widget. The array name gives names to the children of the widget. This is useful for addressing children by comprehensible names; the names are also useful for designing menu widgets.

The virtual type casting operator for trees is used for debugging purposes; mainly in order to print widgets. The virtual member function handle processes an event which is send to the widget and returns TRUE if the event could be handled and FALSE if not.

The widget class

The definition of the widget class goes as follows:

    struct widget {
    #import null_indirect_h (widget, widget_rep)
      inline widget (widget_rep* rep2): rep (rep2) {
        if (rep!=NULL) rep->ref_count++; }
      inline widget operator [] (int i) { return rep->a[i]; }
             widget operator [] (string s);
      inline operator tree () { return (tree) (*rep); }
      inline bool operator == (widget w) { return rep == w.rep; }
      inline bool operator != (widget w) { return rep != w.rep; }
    };

Widgets may be constructed in two ways. First, we may construct a symbolic “nil” widget by widget (). The function bool nil (widget) is provided in order to test whether a widget is “nil”. Secondly, we may construct a widget from a pointer of type widget_rep*.

The reference counting mechanism ensures widgets to be destroyed when they are no longer pointed to. An important exception is when two widgets point one to each other, which fools the reference counter (for instance a scrollbar and the widget which is scrolled need to point one to each other). In order to deal with such “circular dependencies”, one works directly with widget_rep* pointers if one does not want to the pointer to be taken into account in the reference counter.

Child widgets can again be accessed to in two ways. First, we have the direct way, using its index in the array a. Secondly, we can access to a child via its name. Actually, when using this method, a get_widget event is generated. In the basic widget class, the default action for this event is to search in the name array for the child. However, the user may override this default action and provide another child searching method.

14.3.2 The event class

Events are pointers to instances of the abstract event_rep class, which supports reference counting. Actually, concrete event representation classes just contain some information. Hence, events actually provide a safe and generic way to store and communicate information.

The event representation class

The definition of the event_rep structure is as follows:

    struct event_rep: public rep_struct {
      int    type;  // the event type
      inline event_rep (int type2): rep_struct (0), type (type2) {}
      inline virtual ~event_rep () {}
      virtual operator tree () = 0;   // for displaying events (debugging)
    };

The type field gives the type of the event. A complete list of the event types if given in the file

    Window/Event/event_codes.gen.h

For each project which uses new event types, an analogue file should be made and the numbers of the event types should all be different. Unfortunately, there is no safe way in order to let this job be done by the compiler.

The event class

The event structure is defined by

    struct event {
    #import indirect_h (event, event_rep)
      inline event (event_rep* rep2): rep (rep2) {
        if (rep!=NULL) rep->ref_count++; }
      inline operator tree () { return (tree) (*rep); }
    };
    #import indirect_cc (event, event_rep)

Concrete event classes

Concrete event classes again come into two parts: the class itself and its representation class. For instance, the representation class for get_widget events is defined by

struct get_widget_event_rep: public event_rep {
string which; widget& w;
get_widget_event_rep (string which, widget& w);
operator tree ();
};

The corresponding get_widget_event class is defined by

#import event (get_widget_event, get_widget_event_rep)

The module event with two parameters is defined by

#module event (T, R)
struct T {
R* rep;
T (T& ev);
~T ();
T (event& ev);
operator event ();
R* operator -> ();
T& operator = (T ev);
};
#endmodule // event (T, R)

The important thing to notice is that we have converters from and to the generic event class. Moreover, the generic event class and the specific get_widget_event class are compatible from the reference counting point of view.

The implementation of the get_widget_event_rep class is as follows:

get_widget_event_rep::get_widget_event_rep (string ww, widget& w2):
event_rep (GET_WIDGET_EVENT), which (ww), w (w2) {}
get_widget_event_rep::operator tree () {
return tree ("get_widget_event", which); }
#import code_event (get_widget_event, get_widget_event_rep)

The actual events are created by

event get_widget (string which, widget& w) {
return new get_widget_event_rep (which, w); }

Event handlers

Implementations of the generic event handler bool widget_rep::handle(event) usually do the following

• Determine the event type.

• Perform some action, depending on the event type and the widget.

• Dispatch the event to a concrete or abstract specific event handler or to the generic event handler of some other widget representation class.

For instance, the event handler for composite widgets is as follows:

    bool
    composite_widget_rep::handle (event ev) {
      switch (ev->type) {
      case CLEAN_EVENT:
        handle_clean (ev);
        return TRUE;
      case INSERT_EVENT:
        handle_insert (ev);
        return TRUE;
      case REMOVE_EVENT:
        handle_remove (ev);
        return TRUE;
      }
      return basic_widget_rep::handle (ev);
    }

The member function handle_insert is implemented as follows:

    void
    composite_widget_rep::handle_insert (insert_event ev) {
      a << ev->w;
      name << ev->s;
    }

In particular, we can retrieve the fields w and s from insert_event_rep from the insert_event in the member function.

Adding your own event classes

Summarizing, in order to add your own new event classes, you have to take care of the following steps:

• Add a new event type to some event_codes file.

• Declare and implement the event type and its representation type.

• Declare and implement the event creation functions.

• Reimplement the generic event handler bool widget_rep::handle(event) in the abstract or concrete widget representation class, where you want to use your new event class.

14.3.3 The main event loop

The main event loop does the following

• As long as the application did not destroy all its windows, wait for a new event to occur.

• If an event occurs, handle all events on the queue, by creating the appropriate events and sending them to the appropriate widgets (job of the window interface implementation).

• If there are no events left, send an inquire_event to each window. This is useful for complex applications, where regions of the window may be invalidated during this phase. Indeed, the event handling phase may consist of many complex actions, so that the regions to invalidate may be determined easier a posteriori.

• Requests are emitted in order to repaint the regions which have been invalidated during the event processing stages.

14.3.4 Coordinates

Coordinates, pixels and rounding

All coordinates and sizes are represented by instances of type SI, which is nothing but another name for int. The SI constant PIXEL, which is a power of two 1 << PIXEL_SHIFT denotes the size of a pixel on the screen. Since PIXEL>1, coordinates and sizes are not necessarily integer multiples of the pixel size. However, the coordinates of the origin and the size of a widget should always be such multiples.

In order to achieve this, some rounding functions are provided. The function round (SI&) rounds the argument to an integer multiple of PIXEL. Furthermore, the window member functions

    void inner_round (SI& x1, SI& y1, SI& x2, SI& y2);
    void outer_round (SI& x1, SI& y1, SI& x2, SI& y2);

transform a rectangle into a new one with integer multiple of PIXEL coordinates, which is enclosed resp. encloses the original rectangle.

Local and global coordinates

Each widget has an origin (ox,oy) with respect to the window to which it has been attached. This is the origin of the “local coordinates”. The origin of the “global coordinates” is the origin of the window. The location of the local origin in the widget is determined by the widget’s gravity,

which is either one of north_west, north, north_east, west, center, east, south_west, south
or south_east.

As a general rule, events are transmitted in global coordinates. Nevertheless, in widgets which are derived from the abstract basic widget class, by default, all computations are done with respect to local coordinates. This is due to two reasons

• When an event has to be processed, the abstract widget event handler translates global into local coordinates and calls the appropriate virtual event handler using local coordinates.

• When an event has to be emitted, the abstract widget provides event construction routines w.r.t. local coordinates, which override the global event construction routines w.r.t global coordinates.

Screen coordinates

For some very particular purposes, such as popping up windows, one has to perform computations with respect to the screen coordinates. Given a point (x,y) in the coordinates of some window win, the screen coordinates of (x,y) are obtained by adding the windows origin, which is obtained

by calling win->get_position (ox,oy).

14.3.5 Attaching and positioning widgets

Attaching widgets

When a widget is created, the win field of its representation is set to NULL, since it is not yet attached to a window. In order to attach a widget w to a window win, one emits an attach_window_event:

    w << emit_attach_window (win);

Notice that taking win==NULL results in detaching the widget. Notice also that a widget may be attached to at most one window: attempts to reattach a widget, which is already attached, to another window, result in a fatal error.

Some events can be handled by widgets which are not yet attached to a window, such as:

• “get size” events, which determine the default, minimal and maximal size of a widget. Such an event is generated before the creation of the window to which the widget will be attached in order to determine the size of the window.

• “attach window” events, in order to attach (or detach) a window.

• Events for setting (and getting) attributes: after the creation of a widget some attributes of the widget may be given some default value. In order to change them, one might wish to set them to other values before attaching the widget to a window.

• Events for modifying the composite structure of a widget: these events are used for instance in order to construct menus.

For some of these events, such as attribute changes, it may be necessary to emit invalidate events in case when the widget had been attached to some window. In order to test this one uses the member function

    bool widget_rep::attached ();

Positioning widgets

When an appropriate size (w,h) has been determined for a widget (using “get size” events) and when a widget has been attached to some window, the widget is positioned in the main window. By default, all children are recursively positioned at the top left of the window at sizes (w,h). But for complex widgets with children, a specific positioning routine usually has to be implemented.

Such a routine involves positioning of the children within the parent. This is done by emitting position events to the children. For instance,

    a[i] << emit_position (x[i], y[i], w[i], h[i], center);

positions the i-th child, such that the origin of a[i] is at position (x[i], y[i]) w.r.t. the local coordinates of this and such that the origin is situated in the center of a[i]. The width and height of a[i] are set to w[i] resp. h[i].

Repositioning widgets

During execution, it may happen that a particular widget has changed, so that it obtains a different size and/or position. In this case, one emits an update_event to the closest ancestor, whose position and size did not change.

For instance, consider the case of a footer footer, which consists of a left footer footer["left"], followed by some glue footer["middle"] and a right footer footer["right"]. When the left footer changes:

    footer << set_widget ("left", text_widget ("new text"));

the size of footer["left"] changes, and the size and position of the glue should also be changed. Nevertheless, the size and position of footer remain unaltered, whence we update footer:

    footer << emit_update ();

Updating an attached widget results in three actions to take place:

• The widget is reattached to its own window. Indeed, some children of the widget might need be attached.

• The widget is repositioned at its current position and size. Again this will actually affect the children.

• The widget is invalidated, so that it will be repainted.

14.3.6 The keyboard

Keyboard focus

Each window win on the screen determines a main widget win->w which is attached to it and a descendant win->kbd_focus of this widget, which handles the keyboard input directed to the window. This latter widget win->kbd_focus, which is set to win->w by default, is said to have keyboard focus, if the window win has keyboard focus (i.e. if all keyboard events are sent to this window). Consequently, the widget which has keyboard focus receives all keyboard events.

When the keyboard focus of a window win changes, a keyboard_focus_event is sent to win->kbd_focus. The field ev->flag of this event ev is TRUE if the window got the focus, and FALSE if the window lost focus.

The keyboard focus widget win->kbd_focus associated to a window can be changed by calling the window_rep member function

    void window_rep::set_keyboard_focus (widget);

Setting the input focus to another widget than win->w is useful, for instance, if a particular text input field of some form needs keyboard focus after a mouse click on it.

Keyboard events

When a widget has the keyboard focus, and a key is pressed, it receives a keypress_event. The keypress_event_rep class contains a field key, which contains a comprehensible string corresponding to the key which was pressed.

More precisely, key is either a one character string, or a symbolic name like "<return>",

"<right>", "<del>", etc. or a composed name like "<shift-F1>", "<ctrl-esc>" or "<meta-x>".

The complete list of keys is as follows:

    "<F1>", "<F2>", "<F3>", "<F4>", "<F5>", "<F6>",
    "<F7>", "<F8>", "<F9>", "<F10>", "<F11>", "<F12>",
    "<esc>", "<tab>", "<less>", "<gtr>", "<del>", "<return>",
    "<ins>", "<home>", "<end>", "<page-down>", "<page-up>",
    "<left>", "<up>", "<down>", "<right>"

The keys "<less>" and "<gtr>" correspond resp. to "<" and ">". The allowed modifiers are "shift", "ctrl" and "meta" or combinations of these.

14.3.7 The mouse

Mouse events

A mouse event ev occurs on a button change or a mouse movement. The ev->type field contains the type of the event and ev->x and ev->y the corresponding coordinates of the mouse. Finally, the states of the mouse buttons can be questioned using the routine ev->pressed (string).

The possible values of ev->type on button change events are the following:

    "press-left", "press-middle", "press-right",
    "release-left", "release-middle", "release-right"

The possible values for mouse movement events are

    "move", "enter", "leave"

The "enter" and "leave" events occur when the mouse enters resp. leaves the widget. Finally, the states of the left, middle and right mouse buttons can respectively be obtained using the calls

    ev->pressed ("left")
    ev->pressed ("middle")
    ev->pressed ("right")

Grabbing the mouse

For some applications such as popup menus or scrollbars, it is useful to direct all mouse events to a particular widget w. This is done by grabbing the mouse by emitting the event

    w << emit_grab_mouse (TRUE)

After such a grab, all mouse events are directed to w, even those events which occurred before the grab (contrary to X Window). The mouse grab is released by

    w << emit_grab_mouse (FALSE)

Actually, the display keeps track of a list of widgets for which a mouse grab occurred: if the mouse is grabbed by widgets w1 next w2, and again ungrabbed by w2, then all mouse events are again sent to w1. This feature is useful for successive grabs by recursive popup menus.

When a widget w1 grabs the mouse, and a previous mouse grab on a widget w2 is still active, then a "leave" event is sent to w2 and an "enter" event to w1. Similarly, if w1 releases the grab, then a "leave" event is sent to w1 and an "enter" event to w2.

14.3.8 The screen

Each window keeps track of a list of rectangles to be repainted (moreover, redundant rectangles are eliminated automatically and adjacent rectangles are transformed in larger rectangles). During the repaint stage in the event loop, the widget is requested to repaint these rectangles.

Repainting rectangles

The repaint handler takes on input a repaint_event ev, which determines the rectangle to be repainted. Moreover, repaint_event_rep contains a boolean field stop, which can be set in order to indicate that the repaint process was stopped somewhere in the middle.

Indeed, for widgets which take a long time to be repainted, it may be useful to abort repainting if a key is pressed. The arrival of an event which aborts repainting can be checked directly on the postscript device dev:

    if (dev->check_event (EVENT_STATUS)) { ... } // CHECK THIS

In the case of a window, such an event may signify that a key has been pressed; in the case of a printer, it might suggest the printer being turned off.

If the application decides to abort repainting, it sets ev->stop to TRUE. The rectangle which was being repainted is put back on the invalid rectangles list in the event loop; it will be processed again during the next pass through the repaint phase.

Invalidation of rectangles

When window is mapped on the screen or when a region is exposed, the window interface automatically invalidates the corresponding rectangle. The user may also invalidate a rectangle by using either one of the routines

    event emit_invalidate_all ();
    event emit_invalidate (SI x1, SI y1, SI x2, SI y2);

The first routine creates an event to invalidate the entire widget area; the other routine invalidates a specified region.

14.3.9 The toolkit

Other standard widget classes

Many widgets from the toolkit are derived from some other standard abstract widget classes, which can handle some other special events.

Composite widgets

These widgets allow to add or remove children to or from a widget. This makes them particularly useful for menu widgets. They respond to clean, insert and remove events.

Attribute widgets

These widgets allow to set window attributes of some common types such as integers, strings, commands, points, etc. They can be used for instance to retrieve an input string or in order to set the scroll position in a canvas widget.

Glue widgets

Glue widgets are created by

    widget glue_widget (bool hext=TRUE, bool vext=TRUE, SI w=0, SI h=0);

The first two arguments determine whether the widget is extensible horizontally resp. vertically. The last two elements determine the default and minimal size of the widget.

Text widgets

Text widgets are created using

    widget text_widget (string s);

They just display the text s.

Buttons

Two types of buttons have been implemented. First, command buttons are created using

    widget command_button (string s, command cmd);

They display the text s and execute the command cmd when pressed. Secondly, we implemented popup buttons, which popup some window when pressed. Popup buttons are created by one of

    widget pulldown_button (string s, widget m);
    widget pullright_button (string s, widget m);

depending on where the popup window should popup. The main widget attached to the popup window should be created using

    widget popup_widget (widget w, gravity quit);

The quit argument specifies that the popup window should disappear as soon as the pointer leaves the widget in the quit direction.

14.3. WIDGET PRINCIPLES 83

Menus Horizontal and vertical menus are created using

    widget horizontal_menu ();
    widget vertical_menu ();

By default, they are empty. Subsequently, they can be modified as composite widgets. Canvas widgets Canvas widgets are created using

    widget canvas_widget (widget w);

Canvas widget consist of a portion of the widget w and scrollbars, which enable to scroll w. The events

    event set_scrollable (widget w);
    event set_extents    (SI ew, SI ey);
    event set_scroll_pos (SI x, SI y);
    event get_extents    (SI& ew, SI& eh);
    event get_visible    (SI& x1, SI& y1, SI& x2, SI& y2);

enable to change w, to set the extents of w, to set the scroll position, to get the extents of w and to get the rectangle of w, which is currently visible. Input widgets Input widgets enable to type a string and to retrieve it when finished. They are created using

    widget input_text_widget (command call_back);

Some initial text can be put in it using

    event set_input_string (string s);

The command call_back is executed when typing has been finished or aborted (by typing return, escape or ctrl-c). The typed string can then be retrieved using

    event get_input_string (string& s);

Usually, the returned s is a string enclosed between quotes. If typing was aborted, s contains the

string "cancel".

84 CHAPTER 14. THE GRAPHICAL TOOLKIT

TeXmacs fonts

15.1 Classical conceptions of fonts

The way TEXmacs handles fonts is quite different from classical text editors and even from TEX. Let us first analyze some classical ways of conceiving fonts.

• Physical fonts are just given by the name of a file, which contains a character set, i.e. a list of bitmaps. Usually the size of a character set is limited by 256 (or 65536).

• True type fonts essentially work in the same way, except that the bitmaps can now be computed for any desired size.

• In the X-window system, the name of the font is replaced by a more systematic name, which explicitly contains a certain number of font parameters, such as its size, series and shape. This makes it easier for applications to select an appropriate font. However, character sets are still limited in size.

• In TEX, symbols are seen as commands, which select an appropriate physical font (which corresponds to a .tfm and a .pk file), based on symbol font declarations and environment variables (such as size, series and shape).

Clearly, among all these methods, TEX provides the largest flexibility. However, philosophically speaking, we think that it also has some drawbacks:

• There is no distinction between usual commands and commands to make symbols: the current time might be considered as a symbol.

• The encoding of the font is fixed by the names of the commands. For instance, for mathematical symbols, no clean general encoding scheme is provided, except the default naming of symbols by commands.

• For beginners, it remains extremely hard to use non standard fonts.

Actually, in TEX, the notion of “the current font” is ill-defined: it is merely the superposition of all character generating commands.

15.2 The conception of a font in TeXmacs

Philosophically speaking, we think that a font should be characterized by the following two essential properties:

1. A font associates graphical meanings to words. The words can always be represented by strings.

2. The way this association takes place is coherent as a function of the word.

By a word, we either mean a word in a natural language, or a sequence of mathematical, technical or artistic symbols.

This way of viewing fonts has several advantages:

1. A font may take care of kerning and ligatures.

2. A font may consist of several “physical fonts”, which are somehow merged together.

3. A font might in principle automatically build very complicated glyphs like hieroglyphs or large delimiters from words in a well chosen encoding.

4. A font is an irreductable and persistent entity, not a bunch of commands whose actions may depend on some environement.

Notice finally that the “graphical meaning” of a word might be more than just a bitmap: it might also contain some information about a logical bounding box, appropriate places for scripts, etc. Similarly, the “coherence of the association” should be interpreted in its broadest sense: the font might contain additional information for the global typesetting of the words on a page, like the recommended distance between lines, the height of a fraction bar, etc.

15.3 String encodings

All text strings in TEXmacs consist of sequences of either specific or universal symbols. A specific symbol is a character, different from '\0', '<' and '>'. Its meaning may depend on the particular font which is being used. A universal symbol is a string starting with '<', followed by an arbitrary sequence of characters different from '\0', '<' and '>', and ending with '>'. The meaning of universal characters does not depend on the particular font which is used, but different fonts may render them in a different way.

Universal symbols can also be used to represent mathematical symbols of variable sizes like large brackets. The point here is that the shapes of such symbols depend on certain size parameters, which can not conveniently be thought of as font parameters. This problem is solved by letting the extra parameters be part of the symbol. For instance, "<left-(-1>" would be usual bracket and "<left-(-2>" a slightly larger one.

15.4 The abstract font class

The main abstract font class is defined in font.gen.h:

struct font_rep: rep<font> {
display  dis;              // underlying display
encoding enc;              // underlying encoding of the font
SI       design_size;      // design size in points/256
SI       display_size;     // display size in points/PIXEL
double   slope;            // italic slope
space    spc;              // usual space between words
space    extra;            // extra space at end of words
SI       y1;               // bottom y position
SI       y2;               // top y position
SI       yfrac;            // vertical position fraction bar
SI       ysub;             // base line for subscripts
SI       ysup;             // base line for superscripts
SI       wpt;              // width of one point in font
SI       wquad;            // wpt * design size in points
SI       wunit;            // unit width for extendable fonts
SI       wfrac;            // width fraction bar
SI       wsqrt;            // width horzontal line in square root
SI       wneg;             // width of negation line
font_rep (display dis, string name);
font_rep (display dis, string name, font fn);
void copy_math_pars (font fn);
virtual void   get_extents (string s, text_extents& ex) = 0;
virtual void   draw (ps_device dev, string s, SI x, SI y) = 0;
virtual SI     get_sub_base (string s);
virtual SI     get_sup_base (string s);
virtual double get_left_slope  (string s);
virtual double get_right_slope (string s);
virtual SI     get_left_correction  (string s);
virtual SI     get_right_correction (string s);
virtual SI     get_lsub_correction (string s, double level);
virtual SI     get_lsup_correction (string s, double level);
virtual SI     get_rsub_correction (string s, double level);
virtual SI     get_rsup_correction (string s, double level);
void var_get_extents (string s, text_extents& ex);
void var_draw (ps_device dev, string s, SI x, SI y);
virtual bitmap_char get_bitmap (string s);
};

The main abstract routines are get_extents and draw. The first routine determines the logical and physical bounding boxes of a graphical representation of a word, the second one draws the string on the the screen.

The additional data are used for global typesetting using the font. The other virtual routines are used for determening additional properties of typesetted strings.

15.5 Implementation of concrete fonts

Several types of concrete fonts have been implemented in TEXmacs:

TeX text fonts. See src/Resource/Fonts/tex_font.gen.cc.
TeX rubber fonts. See src/Resource/Fonts/tex_rubber_font.gen.cc.
X fonts. See src/Resource/Fonts/ps_font.gen.cc.
Mathematical fonts. See src/Resource/Fonts/math_font.gen.cc.
Virtual fonts. See src/Resource/Fonts/virtual_font.gen.cc.

In most cases, the lowest layer of the implementation consists of a collection of bitmaps, together with some font metric information. The font is responsable for putting these bitmaps together on the screen using some appropriate spacing. The ps_device class comes with a method to display bitmaps in a nice, anti-aliased way, or to print them out.

15.6 Font selection

After having implemented fonts themselves, an important remaining issue is the selection of the appropriate font as a function of a certain number of parameters, such as its name, series, shape and size. For optimal flexibility, TEXmacs comes with a powerful macro-based font-selection scheme (using the Scheme syntax), which allows the user to decide which parameters should be considered meaningful.

At the lowest level, we provide a fixed number of macros which directly correspond to the above types of concrete fonts. For instance, the macro

    (tex $name $size $dpi)

corresponds to the constructor

    font tex_font (display dis, string fam, int size, int dpi, int dsize=10);

of a TEX text font.

At the middle level, it is possible to specify some rewriting rules like

    ((roman rm medium right $s $d) (ec ecrm $s $d))
    ((avant-garde rm medium right $s $d) (tex rpagk $s $d 0))
    ((x-times rm medium right $s $d) (ps adobe-times-medium-r-normal $s $d))

When a left hand pattern is matched, it is recursively substituted by the right hand side. The files in the directory progs/fonts contain a large number of rewriting rules.

At the top level, TEXmacs calls a macro of the form

    ($name $family $series $shape $size $dpi)

as a function of the current environment in the text. In the future, the top level macro call might change in order to enable the user to let the font depend on other environment variables.

90 CHAPTER 15. TEXMACS FONTS

Bugs

16.1 Known bugs

• Shrinked postscript fonts should be anti-aliased.

• Subscripts accented mathematical characters on wrong place.

• Enter math-mode; type minus; select font size “very large”; type minus.

• The inter-paragraph space between paragraph 1 and paragraph 2 should be determined otherwise (see programming session in letter style) as the current environment inter-paragraph space at the end of paragraph 1.

• Make an environment in preamble mode, of the form

      environment { blah } { reset {blah x blah} reset {blah} ... }

If the line is broken after x, then it is impossible to get the cursor before the first reset.

• When compiling <data.o> with optimization, strange errors occur during runtime.

• When deleting a theorem, the numbers of the following theorems are not updated.

• <left-.> and <right-.> do not work.

• Big delimiters are not properly taken into account inside macros.

92 CHAPTER 16. BUGS

Part C

Projects and challenges for YOU

What has changed

17.1 Changes between TeXmacs 0.2.3 and TeXmacs 0.2.2

• Implementation of a TEXmacs server for handling multiple views.

• Facility to execute editing commands using L^{A}TEX command names.

• Correction of several bugs concerning menus.

• Implementation of more dynamical menus.

• Menu items now show equivalent key-bindings.

• Implementation of symbol menus.

17.2 Changes between TeXmacs 0.2.4 and TeXmacs 0.2.3

• Correction of some bugs concerning multiple windows (0.2.3b).

• Incorporation of postscript images (0.2.3c).

• Web pages included in documentation (0.2.3c).

• 0.1 sec delay in displaying popup menus (0.2.3d).

• Better cursor positioning for macro expansions (0.2.3d).

• Typesetting (simple) trees (0.2.3d).

• Easier interface for including images (0.2.3d).

• Loading pk files three times faster (0.2.3e).

• Starting up 50 percent faster (0.2.3e).

• Scrolling 50 percent faster (0.2.3e).

96 CHAPTER 17. WHAT HAS CHANGED

• Corrected bug for making selections (0.2.3e).

• Normal (fast) and professional (slower) hyphenation (0.2.3f).

• Possibility to compile TeXmacs with recent g++ compilers and to compile with optimization. This speeds up the editor about 2 to 3 times, except for displaying text (0.2.3f).

• Normal (fast) and professional (slower) hyphenation (0.2.3f).

• Extra fonts via menus (0.2.3g).

• Better implementation of page sizes; papyrus becomes default (0.2.3h).

• Values of labels are saved (0.2.3h).

• Correction of some scrolling bugs (0.2.4a).

• TEX_PATHS and invalid fonts in user directory (0.2.4a).

• Help files are read only (0.2.4a).

• Popup menus (0.2.4a).

17.3 Changes between TeXmacs 0.2.5 and TeXmacs 0.2.4

• Auto save recovery and “no changes need to be saved” (0.2.4b).

• Nicer recursive dynamic commands (0.2.4b).

• TeXmacs style file for conversions to LaTeX documents (0.2.4b).

• Hybrid LaTeX/TeXmacs commands (0.2.4b).

• Preview with ghostview (0.2.4b).

• First dynamic interface with guile (0.2.4c).

• First implementation of multifile projects (0.2.4c).

• Automatic generation of bibliographies using bibtex (0.2.4c).

• Completely replaced TEXmacs-lisp by Guile Scheme (0.2.4d).

• Automatic generation of tables of contents, except for page references (0.2.4e).

• Added romanian help files (thanks to Dan Ignat) and romanian hyphenation (0.2.4e).

• Romanian menus by Dan Ignat (0.2.4f).

• Configuration using autoconf and simplified installation of interface with guile (0.2.4f).

• Started implementing HTML to TEXmacs converter (0.2.4g).

• Patch for gettimeofday by Rob Clark (0.2.4g).

17.4. CHANGES BETWEEN TEXMACS 0.3.0 AND TEXMACS 0.2.5 97

• Wide hats, scripts with limits, penalties, no line breaks (0.2.4g).

• Easy incorporation of pictures created by xfig, with incorporated LaTeX formulas (0.2.4g).

• Menus translated into swedish by Harald Ellmann (0.2.4h).

• More sophisticated alarm (0.2.4h).

• Added manpage for TeXmacs (0.2.5-1).

• Wrote texmacs.spec file for use with rpm (0.2.5-1).

• New layout for webpage (0.2.5-1).

17.4 Changes between TeXmacs 0.3.0 and TeXmacs 0.2.5

• Replaced convert method in font structure by draw and get_extents methods. Allows fonts to be moved one level down to the Resource directory (0.2.5-2).

• Integrated functionalities of server_font structure into the font structure itself (0.2.5-3).

• Anti-aliasing of X fonts (0.2.5-4).

• Improved anti-aliasing algorithm (0.2.5-5).

• Use ec fonts instead of cm fonts (0.2.5-5).

• Added support for adobe postscript fonts (0.2.5-5).

• First support of the russian language, with help from Andrey Grozin (0.2.5-6).

• Corrected bugs in the russian language support (0.2.5-7).

• Emacs compatability keystrokes (0.2.5-7).

• New implementation of virtual fonts (0.2.5-7).

• Started migration towards cleaner TeXmacs data format (0.2.5-8).

• Implementation of a file chooser (0.2.5-8).

• Menus have been made “sticky” (0.2.5-8).

• Startup banner (0.2.5-9).

• First implementation of communication with extern packages via pipes (0.2.5-9).

• Undo and redo of configurable depth (0.2.5-10).

• Fix of a evolutivity problem in guile-1.4 (0.2.5-10).

• Some brief documentation on the implementation of fonts, the TeXmacs data format and converters to other formats (0.2.5-10).

98 CHAPTER 17. WHAT HAS CHANGED

17.5 Changes between TeXmacs 0.3.0-1 and TeXmacs 0.3.0-

7

• TeXmacs has officially become GNU TeXmacs.

• Special support for xpm pixmaps (0.3.0-1).

• Icon bars (0.3.0-1).

• Increased dynamism of menus and icon bars (0.3.0-1).

• Easier selections using ctrl-spc (0.3.0-1).

• Texts may have a background color (0.3.0-1).

• Help balloons (0.3.0-2).

• Style dependent menus and icons (0.3.0-2).

• Only present fonts are listed in font menus, when using teTeX (0.3.0-2).

• Iconbars can be disabled (0.3.0-2).

• Textual search and query replace (0.3.0-3).

• Conversion of TeX constructs over and pmatrix (0.3.0-4).

• Computer algebra sessions can have names and run in parallel (0.3.0-4).

• Execution of commands in sessions may be interrupted (0.3.0-4).

• Removal of TeXmacs lisp and web pages from distribution (0.3.0-4).

• Spell checker based on ispell (0.3.0-5).

• Man-page for fig2ps (0.3.0-6).

• Hyperlinks and actions associated to text (0.3.0-6).

• Corrections in german dictionary by Ralf Treinen (0.3.0-6).

• Conversion to LaTeX uses babel (0.3.0-7).

• Spanish language support by David Moriano Garcia (0.3.0-7).

• Debian package for TeXmacs by Ralf Treinen (0.3.0-7).

What will be changed

18.1 Memory management

If I have the courage, I might one day write a garbage collector for TEXmacs.

18.2 Graphical interface

We wish to move towards Guile-Gtk.

18.3 Encodings and fonts

• Some changes have still to be made in the way font encodings are handled. This should make it easier to maintain fonts with characters from several physical fonts, virtual fonts, special characters, etc.

• Currently, the current logical font is determined from a fixed set of environment variables only. The current typesetting font should rather be a tree (instead of a string), which is evaluated (so that environment variables are replaced) and then passed to find_font(display,tree). The current font can then be a joined font and future fonts might depend on user environment variables (i.e. colored fonts, using more than one color).

18.4 Speed

In order to speed up the program, we already made the major change that not the whole document is typeset again when making local changes. However, several other main optimizations should still be made:

• Improving the speed of loading (and saving) files. This will accelerate loading fonts.

• Encode the standard operators and system environment variables; this will globally accelerate all parts of the program.

• The way system style environment variables are handled for typesetting concats and paragraphs is far from optimal. Some serious rethinking should be undertaken here.

• The computation of the current context at a given cursor position takes a lot of time, especially the computation of the environment. This slows down the cursor movement for complex texts. using TeX fonts (it scrolls much quicklier when using X fonts).

18.5 Miscellaneous changes

The following ad hoc implementations should be changed or made more robust:

• Cursor movement along lines of a paragraph (when moving to the right at the end of a line, the cursor should jump to the start of the next line).

• Widths of fraction bar, square root upper line and negations.

• Boxes should not have origins; its children should have positions instead.

• Clear separation between files which depend on the system (i.e. gencc, fast_alloc.gen.cc, file.gen.h, dir.gen.h) in some directory and the others.

Projects

In the future, I intend to consolidate the existing implementation by performing the changes as explained in Help→projects→changes. Besides these changes, I personally plan to extend TEXmacs in the directions which are described in this chapter. All (at least most) other changes will then be left to others...

19.1 Typesetting

Some major typesetting facilities which have not yet been implemented are the following • Floating objects, such as pictures.

• Footnotes and marginal notes.

• Multi column styles

• Tables of contents, indexes, glossaries, bibliographies, etc.

• Separation of a document in several parts.

• Dynamical objects like in HTML.

• Environments for computer algebra system interfaces. Many minor facilities should also be completed. We list a few of them:

• Consider fractions as operators ⇒ spaces before and after. Similarly for scripts ⇒ small space before left scripts and after right scripts.

• \left. and \right..

• An operator \big. (which does not exist in TEX) to close the scope of a big operator. Such a construction would be very desirable both for semantical and typesetting reasons. For instance, a small extra space might be inserted at the location of \big. and for alternative fonts, big operators might behave like brackets.

19.2 Extra facilities for editing texts

Although cursor movement, selections, etc. have already been implemented, some other standard editing facilities have not yet been completed. Let us mention a few of these:

• Searching texts, formulas, certain environments etc.

• Query replace.

• Mathematical facilities: simplification of a selected region, substitutions of formulas in other formulas, etc.

• Version control.

• Data compression and protection.

19.3 Technical pictures

I also would like to include a facility for drawing technical pictures. In this implementation you should be able to benefit from the fact that you can define macros for making geometrical constructions. It would for instance be possible to write a style file for drawing electronic circuits or chemical components with a nice icon bar for selecting circuits or components, just as you select lines and circles in usual pictures.

19.4 Interface with computer algebra systems

The following improvements should still be made in order to link TEXmacs to computer algebra systems:

1. Improving the layout of computer algebra sessions.

2. Add extra features to increase the interoperability between TEXmacs and computer algebra systems and to give additional control over the layout of big output.

3. More semantics for the objects being communicated. This may either be hight level information (like Openmath or HTML 4.0 mathematical markup) or low level information (including information about the representation of data), depending on the required speed.

4. Further possibilities for evolution concern highlighting, debugging facilities and so on.

19.5 Interaction with other GNU-like projects

It might be nice to increase the interaction between TEXmacs and other GNU-like projects, such as Gnome or multiplatform GUI’s. This might facilitate the incorporation of extern data into TEXmacs documents or increase the number of supported platforms. On the other hand, several TEXmacs features, such as its font handling, might be interesting for other projects too.

How you can help

20.1 Use the program!

One of the best ways to help me is by using TEXmacs a lot, and to report me about bugs or other unnatural behaviour. As you get more and more experienced with the program, you might also write style files or extensions in Scheme, which might be interesting for others.

20.2 Documentation

A big effort has still to be spent on the documentation of TEXmacs. Not only good documentation is very useful for new users, but writing such documentation is also a nice way for you to learn more about the program. If you are limited in time, then you may consider writing documentation about one particular feature of TEXmacs, such as “typing mathematics”, “using environments” or “writing a style file”. A good idea might be to illustrate your documentation by small, cartoon-like screen samples.

20.3 Translations

The support of a maximal number of foreign languages is another major challenge in which your help would be appreciated. Usually, the procedure is as follows

   • You copy the file english-new.dic to english-mylanguage.dic in langs/natural/dic

and make the corresponding translations.

• You tell me about any special typographical rules in your language and handy keystrokes for producing special characters.

• I take care of the hyphenation and typographical issues, but you test them.

• If you have a lot of time, you may also consider the translation of (part of) the existing documentation.

20.4 Converters from/to LaTeX, html, etc.

If you are a TEX/L^{A}TEX guru, with a good knowledge of the TEX/L^{A}TEX parsing algorithm, PLEASE consider contributing to writing a converter from TEX/L^{A}TEX to TEXmacs.

If you are a specialist on html, xml, sgml, etc. PLEASE consider writing converters from and to these data formats.

In Help→implementation→data format you will find details about the TEXmacs data format and in Help→implementation→data conversion we give some suggestions which might be helpful for these projects.

20.5 Support

Having only access to PC/Linux and SUN systems, I am interested in people who want to port TEXmacs to other Unix systems with X Window and to maintain the corresponding distributions. If you want to do this, you should take a look at the files

    gencc/src/system.h
    src/Basic/fast_alloc.gen.cc

Specialists on autoconf, redhat and rpm packages are also welcome to communicate their suggestions, patches, etc.

20.6 Other help

• A spell checker based on ispell.

• Grammar checkers and automatic translation programs. Does someone know where to find detailed dictionaries and stuff like that?

• Incorporation of a public domain speech recognition program.

• Rewrite the window interface in a way that it becomes based on Gtk instead of X Window (and provide an interface with guile-gtk).

20.7 Contact me

You can contact me by email at

    TeXmacs@math.u-psud.fr

The TEXmacs web page is located at

    http://www.texmacs.org

Via this page, you may find out about the most recent changes in the editor, not yet implemented suggestions, known bugs, etc.