Writing a simple style package

Let us explain on an example how to write a simple style package. First of all, you have to create a new buffer using File→New and select the source document style using Document→Style→source. Now save your empty style package in your personal style package directory

    $HOME/.TeXmacs/packages

Notice that the button Texts in the file browser corresponds to the directory

    $HOME/.TeXmacs/texts

Consequently, you can go to the style package directory from there, by double clicking on .. and next on packages. Similarly, the directory

    $HOME/.TeXmacs/styles

contains your personal style files. After saving your empty style package, it should automatically appear in the Document→Package menu. Notice that style files must be saved using the .ts file extension. If you save the style file in a subdirectory of $HOME/.TeXmacs/packages, then it will automatically appear in the corresponding submenu of Document→Package.

Let us now create a simple macro hi which displays “Hello world”. First type A-=, so as to create an assignment. You should see something like

Now enter “hi” as the first argument and type A-m inside the second argument in order to create a macro. You should now see something like

Finally, type the text “Hello world” in the body of the macro. Your document should now consist of the following line:

After saving your style package, opening a new document and selecting your package in the Document→Use package menu, you may now use the macro hi in your document by typing \ h i and hitting return.

In a similar way, you may create macros with arguments. For instance, assume that we started entering a macro hello in a similar way as above. Instead of typing “Hello world”, we first type A-left inside the macro body so as to create an additional argument on the left hand side of the cursor. We next enter the name of the argument, say “name”. You should now see something like below:

In the second argument of the body, we now type “Hello ”, A-#, “name”, right and “, how are you today?”. After this you should see

The A-# shortcut is used to retrieve the macro argument name. Instead of typing A-#, “name” and right, you may also use the hybrid \-key and type \ n a m e followed by return. After saving your style package, you may again use the macro in any document which uses your package by typing \ h e l l o and hitting return.

From the internal point of view, all macro definitions are stored in the environment of the TeXmacs typesetter. Besides macros, the environment also contains normal environment variables, such as section counters or the font size. The environment variables can either be globally changed using the assign primitive, or locally, using the with primitive. For instance, when including the line

in your package, and using article as your major style, then the first section will be numbered 0. Similarly, the variant

of the hello macro displays the name of the person in Small Capitals. Notice that the with primitive can also be used to locally redefine a macro. This is for instance used in the definitions of the standard list environments, where the macro which renders list icons is changed inside the body of the list. Yet another variant of the hello macro relies on the standard person macro:

In order to produce the macro application <person|name>, you first have to start a compound tag using A-c, type the name “person”, insert an argument A-right, and enter the argument name as before. When you are done, you may press return in order to change the compound tag into a person tag. Alternatively, you may type \, “person”, A-right and “name”.

By combining the above constructs, an ordinary user should already be able to produce style packages for all frequently used notations. An interesting technique for writing macros which involve complex formulas with some subformulas which may change goes as follows:

1. Type the formula, say (a₁,…,a_n), in an ordinary document.

2. Create the skeleton of your macro in your style package:

   <assign|n-tuple|<macro|a|>>

3. Copy the formula and paste it into the body of your macro:

   <assign|n-tuple|<macro|a|(a<rsub|1>,…,a<rsub|n>)>>

4. Replace the subformulas you want to parameterize by macro arguments:

   <assign|n-tuple|<macro|a|(a<rsub|1>,…,a<rsub|n>)>>

5. You may now use the macro in documents which use your package:

   (a₁,…,a_n) = (b₁,…,b_n).