Extending TeXmacs: Plugins, Macros, and Custom StylesTeXmacs is a powerful, free, and open-source scientific editing platform that blends the ease-of-use of a WYSIWYG editor with the precision and flexibility of TeX-quality typesetting. While TeXmacs is already feature-rich out of the box, its real strength lies in extensibility: you can create plugins, write macros, and design custom styles to tailor the editor to your exact workflow. This article explores these extension mechanisms in depth, provides practical examples, and offers best practices for creating maintainable extensions.
1. Overview of TeXmacs extensibility
TeXmacs supports extensibility at multiple levels:
- Plugins: compiled or script-based modules that add functionality to the editor (menus, dialogs, interacting with external programs).
- Macros: TeXmacs macros (written in the TeXmacs language or Scheme) that automate document structure, formatting, and repetitive tasks.
- Custom styles: style files that define document classes, sectioning behavior, fonts, and visual design elements.
Each approach serves different needs. Plugins are ideal for complex features and integrations (e.g., interfacing with computer algebra systems), macros are best for automating document-level tasks and creating higher-level semantic elements, and styles are for consistent visual and structural document rules.
2. Plugins: architecture and examples
TeXmacs plugins can be written in C/C++ or Scheme, and they interface with the editor through a well-defined API. Plugins may:
- Add menu items and toolbars
- Open custom dialogs
- Manipulate documents programmatically
- Communicate with external processes (e.g., Sage, Maxima, Python)
Getting started:
- Familiarize yourself with the TeXmacs API and plugin examples bundled with the source.
- Choose the language: C/C++ for performance and native integration; Scheme for rapid prototyping and simpler logic.
- Use the TeXmacs build system to compile and install your plugin; script-based plugins can be loaded directly.
Example plugin ideas:
- Live-preview of plots from Python/Matplotlib.
- An interface to Git for document versioning (commit, diff, log).
- A bibliographic manager connector that inserts citations from BibTeX or Zotero.
Practical tips:
- Keep the UI responsive by running long tasks asynchronously.
- Expose user preferences for configurable behavior.
- Provide clear error messages when external tools are missing.
3. Macros: automating workflows
Macros in TeXmacs are snippets or functions that generate document content or apply formatting. They can be written in TeXmacs’ native language or Scheme. Common uses include:
- Custom theorem/proof environments
- Automated title pages and author blocks
- Reusable templates for lab reports, homework assignments, or lecture notes
Creating a macro:
- Define a semantic name and parameters.
- Implement the generation of the document structure using TeXmacs commands.
- Test interactively and expose the macro via menus or keybindings.
Example: a concise theorem macro (conceptual)
- Parameters: theorem statement, optional label, optional proof body.
- Output: numbered theorem environment, optional label for cross-references, and a proof block.
Best practices:
- Name macros consistently and document parameters.
- Keep macros small and composable.
- Provide fallback behavior for missing optional arguments.
4. Custom styles: designing document classes
Styles control the visual and structural layout of documents: margins, fonts, heading levels, numbering, bibliography appearance, and more. Creating a style allows you to replicate journal formats, university templates, or corporate branding.
Key components of a style:
- Page layout settings (margins, headers/footers)
- Font selections and math font handling
- Sectioning semantics and numbering rules
- Environments for theorems, figures, tables, and listings
- Bibliography and citation formatting
Workflow:
- Start from an existing style that is close to your needs.
- Modify the style file to adjust layout and typography.
- Define or override environments and counters.
- Test with representative documents and refine.
Examples:
- University thesis style with strict margin and citation rules.
- Conference paper style with two-column layout and compact references.
5. Integrating macros and plugins
Combining macros and plugins unlocks powerful workflows. For instance, a plugin that communicates with SageMath can expose computations; macros can format the returned results into theorem-like environments or nicely typeset tables of numerical data.
Example workflow:
- Plugin sends an expression to Sage, receives symbolic result.
- Macro captures the result and inserts a labeled “Computation” environment with the derivation.
- Style defines how “Computation” environments appear in print.
6. Packaging and distribution
Share your extensions by packaging them:
- For styles and macros: distribute style files and installation instructions; consider hosting on GitHub.
- For plugins: provide binaries for major platforms or instructions to build from source.
Include:
- README with usage examples.
- License information.
- Tests or sample documents demonstrating functionality.
7. Debugging and maintenance
Debugging tips:
- Use logging in plugins and verbose output for external calls.
- For Scheme-based code, take advantage of TeXmacs’ interactive REPL if available.
- Create minimal test documents that reproduce issues.
Maintenance:
- Keep compatibility notes for TeXmacs versions.
- Follow semantic versioning for your extensions.
- Encourage community feedback and contributions.
8. Examples and sample code
Below is a small Scheme-style macro conceptual example (pseudo-code) to define a boxed “Note” environment. Adapt for actual TeXmacs syntax and API.
(define (insert-note title body) ;; create a styled box with a title and body (let ((box (make-box 'frame))) (box-set-title box title) (box-set-content box body) (insert-into-document box))) For a real plugin, consult TeXmacs’ developer documentation and examples shipped with the source.
9. Best practices and community resources
- Reuse and adapt existing styles and macros when possible.
- Document parameters and provide examples.
- Keep user-facing options discoverable (menus, toolbars).
- Engage with the TeXmacs community for reviews and testing.
Useful community practices:
- Provide a small demo document.
- Offer issues and pull requests on a public repository.
- Tag releases and maintain changelogs.
10. Conclusion
Extending TeXmacs through plugins, macros, and custom styles allows you to build a personalized scientific publishing environment that matches your workflow. Start small—write a macro or tweak a style—then progressively add plugins or integrations as needed. With careful design and documentation, your extensions can be powerful, reusable, and shareable with the broader TeXmacs community.
Leave a Reply