Macro

conceptions

Congratulations! You have learnt most of the basic usage of Liii STEM. For more advanced features, you need to learn the following terms. (note that the terms here may be a bit different from those you've learnt in the Quick Start ).

Environment

A structured region. Content inside follows a specific format.

Markup

The name of an environment. Such as section

Focus

The currently selected environment.

Primitive

The most basic, indivisible commands that Liii STEM can directly understand and execute. Such as <with|>,<if|>and <equal|>

Macro

A combination of primitives, and can be customized. Such as <assign|test-equal|<macro|arg1|arg2|msg|<if|<equal|arg1|arg2>|Same quantity:arg1|Not equal:msg>>>

Tag

Tags are the fundamental building blocks in TeXmacs that represent structural elements and formatting commands in documents.

Structure

The visual result of content, produced by the action of primitives.

Structured editing

Structured editing requires Liii STEM to understand a document's internal logic—such as mathematical formulas, code blocks, tables, or sections and allows users to manipulate these logical units directly. For example, in a table: Alt + ← / Alt + → inserts columns. Alt + ↑ / Alt + ↓ inserts rows. Similarly, for deletion: Alt + Backspace deletes the column before the cursor. Alt + Delete deletes the column after the cursor.

What is a macro?

We aim to to simplify complex formulas or lengthy names. Customing macros allows us to achieve that.

• A macro is a pre-recorded command, customized to our needs, used to handle repetitive tasks.

A simple example: suppose you need to frequently use the “Southern University of Science and Technology” in a document. In Liii STEM, you can custom a macro (e.g., sustech) as an abbreviation for these five words.

Macro Usage

Creating a Macro

Click Tools → Macro → New Macro in the menu bar.

Enter your needed macro name into the enter-name.

Enter the content of the macro into the enter-body.

Enter command mode (press \), enter your macro name, and press Enter to the macro.

Macro Parameters

Switch the bottom to math mode in the Macro Editor as shown below, to define math-type macros.

You can also add macro parameters to input different content for parameters each time the macro is used. For example, you can modify the symbols x and n as parameters in a matrix.

Customize Macros

Liii STEM includes many pre-defined macros. To customize them, open the Macro Editor by clicking Preference for tag → Edit macro in the environment toolbar.

For advanced users or complex edits, we recommend:

• Switch the Macro Editor to Source Code mode (see section 4 of this guide).
• Edit macros in the Preamble (see section 3 of this guide).

Editing Macros in the Preamble

Enter the preamble

Click Document → Part → Show Preamble in the menu bar.

Or use the shortcut Ctrl + Shift + P .

Editing Macros in the Preamble

In the preamble, you can view previously created macros.

You can directly modify their parameters, names, or content in the preamble.

Creating Macros in the Preamble

You can also create macros directly in the preamble:

After pressing Enter, the <assign||> will appear. Insert the macro name after the first |. Insert the macro content after the second |.

Tips:

• When defining parameters, wrap the macro content with the macro command (type \macro), then use Alt + → to add cells for parameters.
• You may nest existing macros within new definitions. As it for complex macros (e.g., matrices), type \matrix and activate it from the mode toolbar to expand the structure for easier editing.
• Use the math command (\math) to enter math mode, where you can use macros available in math mode.
• Creating macros in the preamble allows the use of conditional statements like if.

Example

The following macro checks whether two parameters are equal:

<assign|test-equal|<macro|arg1|arg2|msg|<if|<equal|arg1|arg2>|Same quantity:arg1|Not equal:msg>>>

Pasting Macros from $\LaTeX$

Liii STEM supports direct macro paste from $\LaTeX$. Copy the $\LaTeX$ macro command. Enter the preamble. Right-click and select Paste from → LaTeX to complete the paste.

Mogan Style-Sheet Language

previously, we. have provied examples of macro commands. This section teaches you how to create these macros.

Assignments

You can permanently change the value of an environment variable suing the assign primitive, as in the example:

<assign|hi|<macro|Hi there!>>

You may also locally change the values of one or several environment variables using the with primitive:

<with|font-series|bold|color|red|Bold red text>

The value of an environment variable may be retrieved using the value primitive.

• Both left-hand sides of assignments and values of environment variables are emphasized in green, while macro arguments can be recognized by their brown color.

Macro expansion

Ordinary macrosare defined using:

<assign|my-macro|<macro|x1|...|xn|body>>

After such an assignment, my-macro becomes a new primitive with n arguments, which may be called using:

<my-macro|y1|...|yn>

Inside the body of the macro, the arg primitive may be used to retrieve the values of the arguments to the macro. Notice that the default rendering of <arg|name> inside source code is name:

<assign|hello|<macro|name|Hello name, you look nice today!>>

After created:

When called:

It is possible to call a macro with fewer or more arguments than the expected number. Superfluous arguments are simply ignored. Missing arguments take the nullary uninit primitive as value:

<assign|hey|
  <macro|first|second|
    <if|
      <equal|second|?>|
      Hey <arg|first>, you look lonely today...|
      Hey <arg|first> and <arg|second>, you form a nice couple!>>>

After created:

When called:

You are allowed to use macros as values:

<assign|my-macro-copy|my-macro>

Formatting primitives

Most TeXmacs presentation tags can be divided in two main categories: inline tags and block tags. Inline tags are used for small pieces of text, whereas block tags can contain text that spans over several paragraphs. For instance, frac is a typical inline tag, whereas theorem is a typical block tag. Some tags (such as strong) are inline if their argument is inline and block otherwise.

• The concat and document tags are so common that their names are actually hidden for the default rendering of source code.

When writing macros, it is important to be aware of the inline or block nature of tags,because block tags inside a horizontal concatenation are not rendered in an adequate way.

• If you need to surround a block tag with inline text, then you must use the surround primitive:

<assign|my-theorem|
  <macro|body|
    <surround|<no-indent><with|font-series|bold|Theorem. >|<right-flush>|
      body>>>

After created:

When called:

you sometimes may wish to force a tag to be a block environment. For instance, the tag very-important defined by:

<assign|very-important|<macro|body|<with|font-series|bold|color|red|body>>>

may be used both as an inline tag and as a block environment. When placing your cursor just before the with-tag and hitting ↵, you obtain:

<assign|very-important|
  <macro|body|
    <with|font-series|bold|color|red|
      <document|body>>>>

After created:

When called:

Another important property of tags is they tabular content. For example, consider the definition of the standard eqnarray* tag (with a bit of the presentation markup being suppressed):

<assign|eqnarray*|
  <macro|body|
    <with|par-mode|center|mode|math|math-display|true|par-sep|0.45fn|
      <surround|<no-page-break*><vspace*|0.5fn>|<vspace|0.5fn><no-indent*>|
        <tformat|
          <twith|table-hyphen|y>
          <twith|table-width|1par>
          <twith|table-min-cols|3>
          <twith|table-max-cols|3>
          <cwith|1|-1|1|1|cell-hpart|1>
          <cwith|1|-1|-1|-1|cell-hpart|1>
          body>>>>>

The use of surround indicates that eqnarray* is a block environment and the use of tformat specifies that it is also a tabular environment. Moreover, the twith and cwith are used to specify further formatting information.

A Briefly Describtion of Tags Structure of tables.

Basic Table Structure Tag Example:

<tabular|  
  <tformat|
    <table|
      <row|<cell|A1>|<cell|B1>>
      <row|<cell|A2>|<cell|B2>>>>>

After created:

When called:

• Complete Table Syntax:

<tabular|  
  <tformat|
    <!-- Table-level property settings -->
    <twith|property-name|property-value>
    <twith|property-name|property-value>
    ...
  
    <!-- Cell-level property settings -->
    <cwith|row-range|column-range|property-name|property-value>
    <cwith|row-range|column-range|property-name|property-value>
    ...
  
    <!-- Table content -->
      <table|
        <row|<cell||>|<cell||>>|
        <row|<cell||>|<cell||>>>>>

For a deeper understanding of underlying language, consult Scheme Quick Start