mirror of https://github.com/texmacs/doc.git
188 lines
7.2 KiB
Tcl
188 lines
7.2 KiB
Tcl
<TeXmacs|1.0.3.6>
|
|
|
|
<style|tmdoc>
|
|
|
|
<\body>
|
|
<tmdoc-title|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 <menu|File|New> and select the
|
|
<tmstyle|source> document style using <menu|Document|Style|source>. Now
|
|
save your empty style package in your personal style package directory
|
|
|
|
<verbatim| \ \ \ $HOME/.TeXmacs/packages>
|
|
|
|
Notice that the button <menu|Texts> in the file browser corresponds to the
|
|
directory
|
|
|
|
<verbatim| \ \ \ $HOME/.TeXmacs/texts>
|
|
|
|
Consequently, you can go to the style package directory from there, by
|
|
double clicking on <verbatim|..> and next on <verbatim|packages>.
|
|
Similarly, the directory
|
|
|
|
<verbatim| \ \ \ $HOME/.TeXmacs/styles>
|
|
|
|
contains your personal style files. After saving your empty style package,
|
|
it should automatically appear in the <menu|Document|Package> menu. Notice
|
|
that style files must be saved using the <verbatim|.ts> file extension. If
|
|
you save the style file in a subdirectory of
|
|
<verbatim|$HOME/.TeXmacs/packages>, then it will automatically appear in
|
|
the corresponding submenu of <menu|Document|Package>.
|
|
|
|
Let us now create a simple macro <markup|hi> which displays ``Hello
|
|
world''. First type <shortcut|(make 'assign)>, so as to create an assignment. You should
|
|
see something like
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign||>>
|
|
</tm-fragment>
|
|
|
|
Now enter ``hi'' as the first argument and type <shortcut|(make 'macro)> inside the second
|
|
argument in order to create a macro. You should now see something like
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|hi|<macro|>>>
|
|
</tm-fragment>
|
|
|
|
Finally, type the text ``Hello world'' in the body of the macro. Your
|
|
document should now consist of the following line:
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|hi|<macro|Hello world>>>
|
|
</tm-fragment>
|
|
|
|
After saving your style package, opening a new document and selecting your
|
|
package in the <menu|Document|Use package> menu, you may now use the macro
|
|
<markup|hi> in your document by typing <key|\\ h i> and hitting
|
|
<shortcut|(kbd-return)>.
|
|
|
|
In a similar way, you may create macros with arguments. For instance,
|
|
assume that we started entering a macro <markup|hello> in a similar way as
|
|
above. Instead of typing ``Hello world'', we first type <shortcut|(structured-insert-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:
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|hello|<macro|name|>>>
|
|
</tm-fragment>
|
|
|
|
In the second argument of the body, we now type ``Hello '', <shortcut|(make 'arg)>,
|
|
``name'', <key|right> and ``, how are you today?''. After this you
|
|
should see
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|hello|<macro|name|Hello <arg|name>, how are you
|
|
today?>>>
|
|
</tm-fragment>
|
|
|
|
The <shortcut|(make 'arg)> shortcut is used to retrieve the macro argument
|
|
<src-arg|name>. Instead of typing <shortcut|(make 'arg)>, ``name'' and
|
|
<key|right>, you may also use the hybrid <key|\\>-key and type
|
|
<key|\\ n a m e> followed by <shortcut|(kbd-return)>. After saving your style
|
|
package, you may again use the macro in any document which uses your
|
|
package by typing <key|\\ h e l l o> and hitting <key|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 <markup|assign> primitive, or locally, using the <markup|with>
|
|
primitive. For instance, when including the line
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|section-nr|-1>>
|
|
</tm-fragment>
|
|
|
|
in your package, and using <tmstyle|article> as your major style, then the
|
|
first section will be numbered <no-break><with|mode|math|0>. Similarly, the
|
|
variant
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|hello|<macro|name|Hello
|
|
<with|font-shape|small-caps|<arg|name>>!>>>
|
|
</tm-fragment>
|
|
|
|
of the <markup|hello> macro displays the name of the person in
|
|
<with|font-shape|small-caps|Small Capitals>. Notice that the <markup|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 <markup|hello> macro relies on the standard
|
|
<markup|person> macro:
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|hello|<macro|name|Hello <person|<arg|name>>!>>>
|
|
</tm-fragment>
|
|
|
|
In order to produce the macro application <inactive*|<person|<arg|name>>>,
|
|
you first have to start a compound tag using <shortcut|(make 'compound)>, type the name
|
|
``person'', insert an argument <shortcut|(structured-insert-right)>, and enter the argument
|
|
<src-arg|name> as before. When you are done, you may press
|
|
<shortcut|(kbd-return)> in order to change the <markup|compound> tag into a
|
|
<markup|person> tag. Alternatively, you may type <key|\\>, ``person'',
|
|
<shortcut|(structured-insert-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:
|
|
|
|
<\enumerate>
|
|
<item>Type the formula, say <with|mode|math|(a<rsub|1>,\<ldots\>,a<rsub|n>)>,
|
|
in an ordinary document.
|
|
|
|
<item>Create the skeleton of your macro in your style package:
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|n-tuple|<macro|a|>>>
|
|
</tm-fragment>
|
|
|
|
<item>Copy the formula and paste it into the body of your macro:
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|n-tuple|<macro|a|(a<rsub|1>,\<ldots\>,a<rsub|n>)>>>
|
|
</tm-fragment>
|
|
|
|
<item>Replace the subformulas you want to parameterize by macro
|
|
arguments:
|
|
|
|
<\tm-fragment>
|
|
<inactive*|<assign|n-tuple|<macro|a|(<arg|a><rsub|1>,\<ldots\>,<arg|a><rsub|n>)>>>
|
|
</tm-fragment>
|
|
|
|
<item>You may now use the macro in documents which use your package:
|
|
|
|
<\equation*>
|
|
<with|n-tuple|<macro|a|(<arg|a><rsub|1>,\<ldots\>,<arg|a><rsub|n>)>|<n-tuple|a>=<n-tuple|b>.>
|
|
</equation*>
|
|
</enumerate>
|
|
|
|
<tmdoc-copyright|1998--2002|Joris van der Hoeven>
|
|
|
|
<tmdoc-license|Permission is granted to copy, distribute and/or modify this
|
|
document under the terms of the GNU Free Documentation License, Version 1.1
|
|
or any later version published by the Free Software Foundation; with no
|
|
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
|
|
Texts. A copy of the license is included in the section entitled "GNU Free
|
|
Documentation License".>
|
|
</body>
|
|
|
|
<\initial>
|
|
<\collection>
|
|
<associate|language|english>
|
|
<associate|page-bot|30mm>
|
|
<associate|page-even|30mm>
|
|
<associate|page-odd|30mm>
|
|
<associate|page-reduce-bot|15mm>
|
|
<associate|page-reduce-left|25mm>
|
|
<associate|page-reduce-right|25mm>
|
|
<associate|page-reduce-top|15mm>
|
|
<associate|page-right|30mm>
|
|
<associate|page-top|30mm>
|
|
<associate|page-type|a4>
|
|
<associate|par-width|150mm>
|
|
<associate|sfactor|4>
|
|
</collection>
|
|
</initial> |