Skip to content

README-en.md

Latest commit

 

History

History
84 lines (61 loc) · 3.8 KB

README-en.md

File metadata and controls

84 lines (61 loc) · 3.8 KB
Raw

LaTeX MathSymbol

English | 简体中文

LaTeX MathSymbol is a productivity tool designed specifically for researchers and LaTeX developers. It accurately extracts mathematical symbols from .tex source files and generates an interactive, traceable symbol catalog.

By leveraging deep lexical and syntactic analysis (Flex/Bison), the tool parses formulas into an Abstract Syntax Tree (AST). It utilizes Normalization Rendering to automatically map logically equivalent notations—such as a^b_c and a_c^b—to a unified representation, effectively eliminating redundancy in symbol indexing.

✨ Key Features

  • Intelligent Symbol Extraction: Automatically scans formulas throughout the document to identify variables, Greek letters, and complex mathematical structures.
  • Equivalence Unification: Based on AST rendering, the tool normalizes the order of subscripts and superscripts, ensuring that "equivalent symbols share the same name."
  • Seamless Jump & Preview: Click any entry in the symbol table to pinpoint its exact location in the source code, complete with a preview of the surrounding formula context.
  • Cross-Platform Support: Provides pre-compiled backends for multiple platforms, enabling high-performance local parsing.

🚀 Installation

This extension is no longer published to the VS Code Marketplace. Please download the .vsix package from this repository’s Releases and install it locally:

  1. Download the latest latex-math-symbol-*.vsix from Releases.
  2. Open VS Code → Extensions view.
  3. Click the ... menu → Install from VSIX..., then select the downloaded .vsix file.

Optional: you can also install via CLI:

code --install-extension path/to/latex-math-symbol-*.vsix

📖 Usage Guide

  1. Activate View: Open any .tex file and click the 「 $a^b_c$ 」 icon in the VS Code Activity Bar to open the sidebar.
  2. Parse Source: Click the "Refresh" button in the sidebar.
  3. Trace Symbols: In the generated symbol table, click any item to jump to its source location and highlight the parent formula.

⚙️ Configuration

You can adjust the following settings (default values are usually sufficient):

  • latexMathSymbol.backendToolPath: The path to the backend executable.
    • Supports absolute paths or relative paths (relative to the extension's root directory).
    • Default: bin/latex_math_symbol

🛠️ Development Guide

Backend Compilation

If a pre-compiled version for your platform is unavailable, you can build the backend from source:

Prerequisites

  • CMake 3.10+
  • C++14 Compiler
  • Flex (Lexical Analysis)
  • Bison 3.0+ (Syntax Parsing)

Build Steps

cd backend/cpp
mkdir -p build && cd build
cmake ..
cmake --build .

After compilation, place the generated latex_math_symbol executable into the bin/ folder within the VS Code extension directory.

Backend Interface (CLI)

The backend can be invoked independently, making it easy to integrate into other toolchains:

1. Symbol Extraction and Analysis

./latex_math_symbol --symbols-from-tex --input sample.tex > symbols.json

symbols.json aggregates results based on normalized symbols and includes:

  • line, column: Row and column numbers in the original .tex file.
  • source_offset, span: Byte offset and length for precise navigation.
  • formula: The full text of the formula containing the symbol.
  • context_before/after: Text snippets surrounding the formula.

2. AST Normalization Rendering

Parses input symbols into an AST and re-renders them to eliminate syntactic redundancy:

# Example: Unified rendering of a^b_c into a_c^b (depending on internal normalization rules)
printf '%s' 'a^b_c' | ./latex_math_symbol --render-ast