Migrating from LaTeX to TeXmacs: A Practical Workflow

Customizing Layouts and Macros in TeXmacs

Overview

TeXmacs is a WYSIWYG scientific text editor that combines structured document editing with powerful typesetting. Customizing layouts and macros lets you adapt the appearance and behavior of documents—changing document classes, page geometry, styles, and creating reusable commands or environments—to speed up writing and enforce consistent formatting.

Key Concepts

• Style files (.spt): TeXmacs uses style files to define document classes, sectioning, spacing, fonts, and environment behavior.
• Macros (schemes/SS): Macros are written in TeXmacs’ Scheme-based extension language (SME) and can generate document elements, automate tasks, or define new semantic constructs.
• Templates: Save entire document structures (title pages, headers, custom environments) as templates to reuse across projects.
• Paragraph/element properties: Individual elements (paragraphs, sections, lists, math) expose properties (alignment, spacing, font, numbering) you can tweak via the GUI or style files.
• Plugins and scripts: Extend functionality with scripts that manipulate the document tree or integrate external tools.

Customizing Layouts

1. Start from an existing style: Open Format → Document style → Select style → Edit. Modify spacing, margins, fonts, and sectioning rules.
2. Page geometry: Adjust paper size, margins, headers/footers in the style’s layout section or via the GUI (Format → Page).
3. Section and heading styles: Edit section macros (title, section, subsection) to change numbering, font size, spacing, and whether they appear in the table of contents.
4. Environment styling: Redefine environments (theorem, proof, example) in the style file to control labels, framing, and spacing.
5. Fonts and sizes: Define font families and size mappings in the style; use the GUI for quick overrides.
6. Saving and sharing: Save edited styles as new style files and distribute them with your project or install in TeXmacs’ style directory for reuse.

Creating Macros

1. Macro recorder: Use Insert → Macro → Record to capture a sequence of actions and save as a macro for basic automation.
2. Scheme macros: For robust macros, write Scheme code using TeXmacs’ API (document nodes, element constructors). Place macros in your personal style or in ~/.TeXmacs/ to load automatically.
3. Defining commands: Create semantic commands that accept arguments and options; implement argument parsing and generate appropriate document nodes (text, displayed math, environments).
4. Reusable environments: Define environment macros that wrap content with automatic numbering, labels, and custom rendering.
5. Keyboard shortcuts: Assign shortcuts to macros via Preferences → Keys for faster access.
6. Testing and debugging: Use the TeXmacs Scheme console and inspect the document tree to test macro output and fix issues.

Practical Examples (high-level)

• Create a custom theorem environment that numbers per-section and formats the heading in bold italics.
• Write a macro that inserts a labeled figure block with preconfigured caption style and placement hints.
• Implement a “proof” macro that places a QED symbol automatically at the end of the environment.

Tips and Best Practices

• Begin by copying and adapting an existing style rather than building from scratch.
• Keep macros small and composable; prefer building blocks that can be reused.
• Document macros and style changes inside the style file for future maintainers.
• Use version control for style and macro files when collaborating.
• Test across output targets (PDF via TeX, HTML, LaTeX export) because rendering can differ.

Where to Look Next

• Consult TeXmacs’ built-in manual (Help → Manual) for the style and Scheme API.
• Explore community style files and examples to learn idiomatic patterns.