latex-code-ref

latex-code-ref lets you cross-reference source code locations directly from a LaTeX document. You tag lines in your source files with \coderef{name}, run a scanner script to build a database, and then cite those locations in LaTeX just like you would cite a figure or equation.

---

How it works

1. Tag lines in your source code with a comment containing \coderef{name}:

   // \coderef{heat_diffusion_equation}
   for (int i = 1; i < N-1; ++i) { ... }

   # \coderef{boundary_condition}
   grid[0] = grid[-1] = 0.0

2. Scan your source tree to build a database:

   python scan_coderefs.py ./src --extensions "*.cpp" "*.h" "*.py"

   This writes two files:

   • coderef_db.json — human-readable tag database
   • coderef_defs.tex — LaTeX macro definitions (auto-generated, \input into your document)

3. Cite in LaTeX using one of three reference levels:

   Command	Output
   \coderef{heat_diffusion_equation}	solver.cpp, line 42
   \codereffile{heat_diffusion_equation}	solver.cpp
   \coderefline{heat_diffusion_equation}	line 42

---

Quick install

No installation is required beyond copying two files into your project:

File	Purpose
scan_coderefs.py	Python scanner script (Python ≥ 3.10)
coderef.sty	LaTeX package

Place coderef.sty somewhere LaTeX can find it (e.g. the same directory as your .tex file, or in ~/texmf/tex/latex/coderef/ for a system-wide install).

Dependencies:

• Python ≥ 3.10 (standard library only, no pip install needed)
• LaTeX packages: etoolbox (included in any standard TeX distribution)

---

LaTeX usage

\usepackage{coderef}
\input{coderef_defs}   % generated by scan_coderefs.py

% In your text:
The heat equation~\eqref{eq:heat} is implemented in \coderef{heat_diffusion_equation}.

% File name only:
See \codereffile{heat_diffusion_equation} for the full solver.

% Line number only:
The core loop starts at \coderefline{heat_diffusion_equation}.

---

Scanner options

usage: scan_coderefs.py [-h] [-e GLOB [GLOB ...]] [-j FILE] [-l FILE] source_dir

positional arguments:
  source_dir            Root directory to scan recursively.

options:
  -e, --extensions      File glob patterns to scan (default: *.py *.cpp *.cc
                        *.cxx *.c *.h *.hpp *.f90 *.f *.f77 *.F90)
  -j, --json-output     Output JSON file (default: coderef_db.json)
  -l, --latex-output    Output LaTeX definitions file (default: coderef_defs.tex)

---

Duplicate tags

Each \coderef{name} tag must be unique across all scanned files. If the same name appears more than once, scan_coderefs.py exits with an error listing every duplicate and its location — analogous to how LaTeX errors on a duplicate \label.

---

Repository layout

latex-code-ref/
├── scan_coderefs.py     # scanner
├── coderef.sty          # LaTeX package
├── README.md
└── example/
    ├── main.tex         # minimal working example
    ├── src/
    │   ├── diffusion.cpp
    │   └── boundary.py
    ├── coderef_db.json      # generated — do not edit
    └── coderef_defs.tex     # generated — do not edit

coderef_db.json and coderef_defs.tex are build artifacts. Add them to .gitignore or regenerate them as part of your build process (e.g. a Makefile target that runs scan_coderefs.py before pdflatex).