From 8aa1e106be28958eca98f43a06b59a6a3c5f4e07 Mon Sep 17 00:00:00 2001 From: Mahdi Hoseini Date: Wed, 4 Mar 2026 16:39:18 -0800 Subject: [PATCH] chore: add project config, Claude instructions, and reference docs - CLAUDE.md: project guidance for Claude Code (build commands, conventions, editing rules, CI notes) - AGENTS.md: agent-level task conventions for autonomous editing sessions - .claude/: skills, memory, and settings for Claude Code integration - docs/: research-backed LaTeX reference examples (small, medium, large-doc templates with latexmkrc, local .sty, CI workflow) Co-Authored-By: Claude Sonnet 4.6 --- .claude/skills/add-experience/SKILL.md | 29 ++ .claude/skills/add-section/SKILL.md | 35 ++ .claude/skills/add-skill/SKILL.md | 21 + .claude/skills/build/SKILL.md | 17 + .claude/skills/ci/SKILL.md | 55 ++ .claude/skills/commit/SKILL.md | 59 +++ .claude/skills/coverletter/SKILL.md | 41 ++ .claude/skills/lint/SKILL.md | 42 ++ .claude/skills/review/SKILL.md | 26 + .claude/skills/scaffold/SKILL.md | 33 ++ .claude/skills/tailor/SKILL.md | 28 + AGENTS.md | 38 ++ CLAUDE.md | 67 +++ .../large-doc/.github/workflows/latex.yml | 17 + docs/examples/large-doc/Makefile | 14 + docs/examples/large-doc/bib/references.bib | 6 + docs/examples/large-doc/glossary/acronyms.tex | 1 + .../src/appendix/a-reproducibility.tex | 2 + .../large-doc/src/chapters/01-intro.tex | 2 + .../large-doc/src/chapters/02-methods.tex | 16 + .../large-doc/src/chapters/03-results.tex | 2 + .../large-doc/src/frontmatter/title.tex | 4 + docs/examples/large-doc/src/main.tex | 32 ++ .../examples/large-doc/src/styles/project.sty | 4 + docs/examples/medium-doc/bib/references.bib | 8 + docs/examples/medium-doc/latexmkrc | 4 + docs/examples/medium-doc/src/main.tex | 23 + .../medium-doc/src/sections/intro.tex | 2 + .../medium-doc/src/sections/method.tex | 2 + .../medium-doc/src/sections/results.tex | 13 + docs/examples/small-doc/latexmkrc | 3 + docs/examples/small-doc/main.tex | 17 + docs/examples/small-doc/references.bib | 6 + docs/latex-research-report.md | 481 ++++++++++++++++++ 34 files changed, 1150 insertions(+) create mode 100644 .claude/skills/add-experience/SKILL.md create mode 100644 .claude/skills/add-section/SKILL.md create mode 100644 .claude/skills/add-skill/SKILL.md create mode 100644 .claude/skills/build/SKILL.md create mode 100644 .claude/skills/ci/SKILL.md create mode 100644 .claude/skills/commit/SKILL.md create mode 100644 .claude/skills/coverletter/SKILL.md create mode 100644 .claude/skills/lint/SKILL.md create mode 100644 .claude/skills/review/SKILL.md create mode 100644 .claude/skills/scaffold/SKILL.md create mode 100644 .claude/skills/tailor/SKILL.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 docs/examples/large-doc/.github/workflows/latex.yml create mode 100644 docs/examples/large-doc/Makefile create mode 100644 docs/examples/large-doc/bib/references.bib create mode 100644 docs/examples/large-doc/glossary/acronyms.tex create mode 100644 docs/examples/large-doc/src/appendix/a-reproducibility.tex create mode 100644 docs/examples/large-doc/src/chapters/01-intro.tex create mode 100644 docs/examples/large-doc/src/chapters/02-methods.tex create mode 100644 docs/examples/large-doc/src/chapters/03-results.tex create mode 100644 docs/examples/large-doc/src/frontmatter/title.tex create mode 100644 docs/examples/large-doc/src/main.tex create mode 100644 docs/examples/large-doc/src/styles/project.sty create mode 100644 docs/examples/medium-doc/bib/references.bib create mode 100644 docs/examples/medium-doc/latexmkrc create mode 100644 docs/examples/medium-doc/src/main.tex create mode 100644 docs/examples/medium-doc/src/sections/intro.tex create mode 100644 docs/examples/medium-doc/src/sections/method.tex create mode 100644 docs/examples/medium-doc/src/sections/results.tex create mode 100644 docs/examples/small-doc/latexmkrc create mode 100644 docs/examples/small-doc/main.tex create mode 100644 docs/examples/small-doc/references.bib create mode 100644 docs/latex-research-report.md diff --git a/.claude/skills/add-experience/SKILL.md b/.claude/skills/add-experience/SKILL.md new file mode 100644 index 0000000..b850581 --- /dev/null +++ b/.claude/skills/add-experience/SKILL.md @@ -0,0 +1,29 @@ +--- +name: add-experience +description: Add a new work experience entry to the resume +user-invocable: true +--- + +# Add Experience Entry + +Add a new `\cventry` to `src/resume/experience.tex`. + +## Steps + +1. Ask the user for (if not already provided): + - Job title + - Company name + - Location + - Start month/year and end month/year (use `0/0` for current/present) + - 3-5 bullet points describing achievements (with metrics where possible) +2. Read `src/resume/experience.tex` to understand the current format. +3. Insert the new entry at the correct position (most recent first), using: + - `\cventry{Job title}{Company}{Location}{\acvDateRange{startM}{startY}{endM}{endY}}{...}` + - `\begin{cvitems}` with `\item` bullets + - `\acvDashedSeparator` between entries +4. Build with `make resume.pdf` to verify. + +## Rules +- Follow the exact formatting of existing entries in the file. +- Bold key technologies with `\textbf{}`. +- Include quantified impact where possible. diff --git a/.claude/skills/add-section/SKILL.md b/.claude/skills/add-section/SKILL.md new file mode 100644 index 0000000..17cc3de --- /dev/null +++ b/.claude/skills/add-section/SKILL.md @@ -0,0 +1,35 @@ +--- +name: add-section +description: Add a new section to the resume by creating a .tex file and wiring it into resume.tex +user-invocable: true +--- + +# Add Resume Section + +Create a new section file and integrate it into the resume layout. + +## Steps + +1. Ask the user for: + - **Section name** (e.g., "Projects", "Certifications", "Volunteering") + - **Column placement**: left column (main content) or right column (sidebar) + - **Content type**: entries (`cventries`), skills (`cvskills`), honors (`cvhonors`), or paragraph (`cvparagraph`) + +2. Read `src/resume.tex` to understand the current two-column layout and active `\input` lines. + +3. Create `src/resume/.tex` with: + - Standard section header comment block + - `\cvsection{Section Title}` + - Appropriate environment with a placeholder entry matching the chosen content type + +4. Add `\input{resume/.tex}` to `src/resume.tex` in the correct minipage: + - Left minipage (`\acvLeftColumnWidth`) for main content like experience, projects + - Right minipage (`\acvRightColumnWidth`) for sidebar content like skills, education, certifications + +5. Build with `make resume.pdf` to verify compilation. + +## Rules + +- Use lowercase filenames (per CLAUDE.md conventions). +- Follow the existing section file format (see `src/resume/experience.tex`, `src/resume/skills.tex`). +- Place `\input` lines in logical order within the column. diff --git a/.claude/skills/add-skill/SKILL.md b/.claude/skills/add-skill/SKILL.md new file mode 100644 index 0000000..4cd21a4 --- /dev/null +++ b/.claude/skills/add-skill/SKILL.md @@ -0,0 +1,21 @@ +--- +name: add-skill +description: Add a new skill category or update an existing one in the resume +user-invocable: true +--- + +# Add or Update Skill + +Modify `src/resume/skills.tex` to add new skills. + +## Steps + +1. Read `src/resume/skills.tex` to see existing skill blocks. +2. If the user wants to add to an existing category, append the new skills to that `\skillblock`. +3. If the user wants a new category, add a new `\skillblock{Category}{skills...}` with `\acvDashedSeparatorRoomy` before it. +4. Build with `make resume.pdf` to verify. + +## Rules +- Match the existing formatting style. +- Keep skill lists comma-separated within each `\skillblock`. +- Do not duplicate skills already listed. diff --git a/.claude/skills/build/SKILL.md b/.claude/skills/build/SKILL.md new file mode 100644 index 0000000..bacb7a7 --- /dev/null +++ b/.claude/skills/build/SKILL.md @@ -0,0 +1,17 @@ +--- +name: build +description: Build the resume PDF and report any LaTeX errors +user-invocable: true +allowed-tools: Bash(make resume.pdf:*), Bash(make clean:*) +--- + +# Build Resume + +Run `make resume.pdf` to compile the resume. Report whether it succeeded or failed. + +If the build fails: +1. Show the relevant LaTeX error lines +2. Suggest a fix based on the error message +3. After fixing, rebuild to confirm + +If the build succeeds, confirm with a short message. diff --git a/.claude/skills/ci/SKILL.md b/.claude/skills/ci/SKILL.md new file mode 100644 index 0000000..1c2b7b1 --- /dev/null +++ b/.claude/skills/ci/SKILL.md @@ -0,0 +1,55 @@ +--- +name: ci +description: Generate or update a GitHub Actions workflow for building LaTeX documents +user-invocable: true +--- + +# Generate CI Workflow + +Create or update `.github/workflows/latex.yml` for automated LaTeX builds. + +## Steps + +1. Check if `.github/workflows/latex.yml` already exists. If so, read it and propose updates. + +2. Ask the user for (if not obvious from context): + - **Documents to build**: resume, cv, coverletter, or all + - **Engine**: xelatex (default for this project) or lualatex + - **Triggers**: push, pull_request, or both + +3. Generate the workflow based on the pattern from `docs/examples/large-doc/.github/workflows/latex.yml`: + + ```yaml + name: build-latex + on: [push, pull_request] + jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: xu-cheng/latex-action@v4 + with: + root_file: src/resume.tex + work_in_root_file_dir: true + latexmk_use_xelatex: true + - uses: actions/upload-artifact@v4 + with: + name: resume-pdf + path: src/resume.pdf + ``` + +4. For multiple documents, add separate steps or a matrix strategy. + +5. Write the workflow file and confirm with the user. + +## Rules + +- Use `xu-cheng/latex-action@v4` (per docs/examples pattern). +- Pin action versions with `@v4` tags. +- Use `-interaction=nonstopmode -file-line-error` flags implicitly (handled by the action). +- This project uses XeLaTeX (`latexmk -xelatex`), so set `latexmk_use_xelatex: true`. +- Include artifact upload so the PDF is downloadable from the Actions run. + +## Reference + +See `docs/examples/large-doc/.github/workflows/latex.yml` and `docs/latex-research-report.md` CI section. diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md new file mode 100644 index 0000000..69a100f --- /dev/null +++ b/.claude/skills/commit/SKILL.md @@ -0,0 +1,59 @@ +--- +name: commit +description: Stage and commit changes following atomic commits and Conventional Commits best practices +user-invocable: true +--- + +# Commit Changes + +Create well-formatted git commits following atomic commit principles and Conventional Commits. + +## Steps + +1. Run `git status` and `git diff` (staged + unstaged) to review all changes. +2. Run `git log --oneline -10` to match the repo's commit message style. +3. **Group changes into atomic commits.** Each commit must represent exactly one logical change — a single feature, fix, refactor, or chore. If changes span multiple concerns, split them into separate commits. +4. For each atomic commit: + a. Determine the type, scope, and summary: + - **Type**: `feat`, `fix`, `docs`, `refactor`, `style`, `chore`, `test`, `build` + - **Scope**: the area touched (`resume`, `cv`, `coverletter`, `makefile`, `docs`, `skills`, etc.) + - **Summary**: imperative mood, lowercase, no period, max ~72 chars (e.g., "add new experience entry for Neoxi") + b. Stage only the files belonging to this logical change (by name, never `git add -A` or `git add .`). + c. Commit using a HEREDOC: + ``` + type(scope): short imperative summary + + - Explain what changed and why (not how) + - Additional detail if the change is non-obvious + + Co-Authored-By: Claude Opus 4.6 + ``` + d. Run `git status` to verify before moving to the next commit. + +5. If the user explicitly asks to bundle everything into **one commit**, combine all changes into a single commit with a summary that covers the full scope. Use multiple scopes or a broader scope if needed (e.g., `feat(resume): update experience and skills sections`). + +## Commit Message Guidelines + +- **Subject line**: imperative mood ("add", "fix", "update"), lowercase after type, no trailing period, max ~72 chars. +- **Body** (optional): explain the "why", not the "what". Wrap at 72 chars. Separate from subject with a blank line. +- **Breaking changes**: prefix body with `BREAKING CHANGE:` if applicable. +- **Footer**: always include the `Co-Authored-By` line. + +## Atomic Commit Principles + +- Each commit should be self-contained and buildable on its own. +- If you need to refactor before adding a feature, that's two commits: `refactor(scope): ...` then `feat(scope): ...`. +- Group related file changes together (e.g., a new section file + its `\input` line in `resume.tex` = one commit). +- Unrelated changes (e.g., fixing a typo in skills while adding a new experience) should be separate commits. + +## Rules + +- Follow Conventional Commits as seen in repo history (per CLAUDE.md). +- Never commit files that may contain secrets (`.env`, credentials, tokens). +- Never use `git add -A` or `git add .` — stage specific files by name. +- Never amend previous commits unless explicitly asked. +- Never push unless explicitly asked. +- Never skip hooks (`--no-verify`) unless explicitly asked. +- If a pre-commit hook fails, fix the issue and create a NEW commit (do not amend). +- Pass the commit message via HEREDOC for proper formatting. +- Default to separate atomic commits. Only bundle into one commit if the user explicitly asks. diff --git a/.claude/skills/coverletter/SKILL.md b/.claude/skills/coverletter/SKILL.md new file mode 100644 index 0000000..077e68a --- /dev/null +++ b/.claude/skills/coverletter/SKILL.md @@ -0,0 +1,41 @@ +--- +name: coverletter +description: Generate or update a tailored cover letter for a job posting +user-invocable: true +--- + +# Generate Cover Letter + +Create or update `src/coverletter.tex` with a tailored cover letter for a specific job posting. + +## Steps + +1. The user provides a job description (pasted text or URL). + +2. Read the current resume content to understand the candidate's background: + - `src/resume/summary.tex` + - `src/resume/experience.tex` + - `src/resume/skills.tex` + +3. Read `src/coverletter.tex` to understand the existing template structure. + +4. Update `src/coverletter.tex`: + - **Personal info**: Use the same info from `src/resume.tex` (name, contact, etc.) + - **Recipient**: Company name and address from the job posting + - **Letter title**: "Job Application for [Role Title]" + - **Opening**: Professional greeting + - **Body sections** using `\lettersection{}`: + - **About Me**: Brief introduction connecting background to the role + - **Why [Company]?**: What draws the candidate to this specific company + - **Why Me?**: Key achievements and skills that match the job requirements + - **Closing**: Professional sign-off with resume enclosure + +5. Build with `make coverletter.pdf` to verify compilation. + +## Rules + +- Never fabricate experience or achievements not present in the resume. +- Keep the tone professional but personable. +- Reference specific technologies and achievements from the resume that match the job requirements. +- Match the accent color to the resume (`acvBlue` / `awesome-red` as configured). +- Keep the letter concise (one page). diff --git a/.claude/skills/lint/SKILL.md b/.claude/skills/lint/SKILL.md new file mode 100644 index 0000000..eb99c7e --- /dev/null +++ b/.claude/skills/lint/SKILL.md @@ -0,0 +1,42 @@ +--- +name: lint +description: Lint LaTeX source files for common issues like undefined references, formatting inconsistencies, and prose quality +user-invocable: true +--- + +# Lint LaTeX Sources + +Review `.tex` files under `src/resume/` (and optionally `src/cv/`) for common issues. + +## Checks to Perform + +1. **LaTeX correctness** + - Unclosed environments or braces + - Undefined or duplicate labels + - Missing `\item` inside list environments (`cvitems`, `itemize`) + - Incorrect nesting of environments + +2. **Formatting consistency** + - Consistent use of `\textbf{}` for technology names across all entries + - Consistent date format via `\acvDateRange` + - Matching separators (`\acvDashedSeparator` between entries) + - Two-space indentation inside environments (per CLAUDE.md conventions) + +3. **Prose quality** + - Bullet points start with strong action verbs + - Metrics and quantified impact are present where possible + - No orphaned or overly long bullets (aim for 1-2 lines each) + - Consistent tense (past for previous roles, present for current) + - No spelling or grammar errors + +4. **Build verification** + - Run `make resume.pdf` and check for warnings (overfull/underfull boxes, undefined references) + - Report any LaTeX warnings from the build log + +## Output + +Present findings as a categorized list (Errors / Warnings / Suggestions). Do not make changes unless the user asks. + +## Reference + +See `docs/latex-research-report.md` section on linting for background on chktex and prose-quality patterns. diff --git a/.claude/skills/review/SKILL.md b/.claude/skills/review/SKILL.md new file mode 100644 index 0000000..b5baa9a --- /dev/null +++ b/.claude/skills/review/SKILL.md @@ -0,0 +1,26 @@ +--- +name: review +description: Review the resume for clarity, impact, consistency, and ATS-friendliness +user-invocable: true +--- + +# Review Resume + +Perform a thorough review of the resume without making changes (unless asked). + +## Steps + +1. Read all active resume section files: + - `src/resume/summary.tex` + - `src/resume/experience.tex` + - `src/resume/skills.tex` + - `src/resume/education.tex` + - `src/resume/languages.tex` +2. Evaluate against these criteria: + - **Clarity**: Are bullets concise and easy to scan? + - **Impact**: Do bullets lead with results and include metrics? + - **Consistency**: Is tense, formatting, and style uniform across entries? + - **ATS-friendliness**: Are keywords present for common ATS parsers? Are there formatting issues that could confuse parsers? + - **Length**: Does everything fit on one page without feeling cramped? +3. Present findings as a prioritized list of suggestions. +4. Only make edits if the user explicitly asks. diff --git a/.claude/skills/scaffold/SKILL.md b/.claude/skills/scaffold/SKILL.md new file mode 100644 index 0000000..5144edc --- /dev/null +++ b/.claude/skills/scaffold/SKILL.md @@ -0,0 +1,33 @@ +--- +name: scaffold +description: Scaffold a new LaTeX project from small, medium, or large document templates in docs/examples +user-invocable: true +--- + +# Scaffold LaTeX Project + +Generate a new LaTeX project structure based on the reference layouts in `docs/examples/`. + +## Steps + +1. Ask the user for: + - **Scale**: small (single-file), medium (modular sections), or large (chapters, CI, .sty, glossary) + - **Target directory**: where to create the project + - **Document title and author** + +2. Read the matching template from `docs/examples/`: + - `docs/examples/small-doc/` — single `main.tex` + `latexmkrc` + `references.bib` + - `docs/examples/medium-doc/` — `src/main.tex` + `src/sections/` + `latexmkrc` + `bib/` + - `docs/examples/large-doc/` — full structure with `Makefile`, `.github/workflows/latex.yml`, `src/styles/project.sty`, `glossary/`, `figures/`, `build/` + +3. Create the file tree in the target directory, substituting title/author into the templates. + +4. Confirm the structure with a file listing and suggest the build command. + +## Rules + +- Follow the exact patterns from the reference examples. +- Use `latexmk` as the build orchestrator (per `docs/latex-research-report.md`). +- For large-doc, include the GitHub Actions workflow with `xu-cheng/latex-action@v4`. +- Keep `hyperref` near the end of the preamble. +- Default to pdfLaTeX for small/medium; LuaLaTeX for large (per research report recommendations). diff --git a/.claude/skills/tailor/SKILL.md b/.claude/skills/tailor/SKILL.md new file mode 100644 index 0000000..aae4131 --- /dev/null +++ b/.claude/skills/tailor/SKILL.md @@ -0,0 +1,28 @@ +--- +name: tailor +description: Tailor the resume for a specific job posting by adjusting summary, skills, and experience bullets +user-invocable: true +--- + +# Tailor Resume for Job Posting + +The user will provide a job description (pasted text or URL). Adjust the resume to better match the role. + +## Steps + +1. Read the job description and extract key requirements, technologies, and soft skills. +2. Read the current resume files: + - `src/resume/summary.tex` + - `src/resume/skills.tex` + - `src/resume/experience.tex` +3. Adjust the resume: + - **Summary**: Rewrite to align with the target role's language and priorities. + - **Skills**: Reorder skill blocks so the most relevant categories appear first. Add missing skills the candidate actually has. + - **Experience bullets**: Reword to emphasize achievements matching the job requirements. Do NOT fabricate experience. +4. Build with `make resume.pdf` to verify compilation. +5. Summarize the changes made. + +## Rules +- Never invent experience, skills, or metrics the candidate does not have. +- Preserve the existing LaTeX formatting conventions (see CLAUDE.md). +- Keep the resume to one page. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cba5058 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,38 @@ +# Repository Guidelines + +## Project Structure & Module Organization +- `src/` is the CV codebase. Roots: `src/resume.tex`, `src/cv.tex`, and `src/coverletter.tex`; sections live in `src/resume/*.tex` and `src/cv/*.tex`. +- `src/assets/` stores images used by the documents; `build/` contains copied artifacts from `make build`. +- `docs/examples/` is the reference lab: `small-doc/` (single-file), `medium-doc/` (modular `\input` sections), and `large-doc/` (chapters, local `.sty`, glossary, CI/Makefile). +- `awesome-cv.cls` is a shared class dependency; treat edits as cross-document changes. + +## Build, Test, and Development Commands +- `make`: Compile all top-level documents (`resume.pdf`, `cv.pdf`, `coverletter.pdf`) using `latexmk -xelatex`. +- `make resume.pdf` / `make cv.pdf` / `make coverletter.pdf`: Compile one document only. +- `make build`: Copy `src/resume.pdf` into `build/` with the release filename. +- `make clean`: Remove generated PDFs and LaTeX auxiliary files. +- Example builds from `docs/examples/`: `latexmk -pdf -interaction=nonstopmode -file-line-error docs/examples/small-doc/main.tex`, `latexmk -cd -pdf -interaction=nonstopmode -file-line-error docs/examples/medium-doc/src/main.tex`, `make -C docs/examples/large-doc pdf`, and `make -C docs/examples/large-doc glossary`. + +## Coding Style & Naming Conventions +- Keep files UTF-8 and compatible with XeLaTeX. +- Follow existing LaTeX style: two-space indentation inside environments and concise `%` section comments. +- Keep section filenames short and lowercase (for example, `summary.tex`, `languages.tex`). +- Prefer modular content with `\input`; reserve `\include` for chapter-scale documents where `\includeonly` is needed. +- Keep shared macros/layout policy in local `.sty` files (see `docs/examples/large-doc/src/styles/project.sty`) and load `hyperref` near the end of the preamble. +- Keep typography defaults like `microtype` and `booktabs` unless a document has a specific reason to diverge. + +## Testing Guidelines +- There is no unit-test framework; successful compilation is the primary check. +- Before submitting changes, run `make clean && make`. +- Use `-interaction=nonstopmode -file-line-error` for actionable failures. +- Validate generated PDFs in `src/` for layout regressions (overflow, spacing, page breaks, alignment, table quality). +- CI compiles deterministic root files (`make` in this repo; `root_file: src/main.tex` in the large example workflow). + +## Commit & Pull Request Guidelines +- Use Conventional Commits, matching existing history (for example, `feat(resume): ...`, `fix(makefile): ...`, `docs(readme): ...`). +- Keep commit scopes tied to touched areas (`resume`, `cv`, `makefile`, `README`, etc.). +- PRs should include a short summary, linked issue (if any), and updated PDFs or screenshots when visual output changes. +- Confirm local build success (`make`) in the PR description. + +## Security & Tooling Notes +- Default to CI-safe builds without unrestricted shell-escape. For code blocks, prefer `listings`; use `minted` only when the team explicitly accepts its external tooling and shell-escape requirements. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4be3f84 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,67 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working in this repository. + +## Project Overview + +LaTeX-based CV/resume/cover-letter project built on [Awesome-CV](https://github.com/posquit0/Awesome-CV). The main build uses `latexmk -xelatex`. + +## Repository Map + +- `src/`: production documents. + - roots: `src/resume.tex`, `src/cv.tex`, `src/coverletter.tex` + - modular sections: `src/resume/*.tex`, `src/cv/*.tex` + - assets: `src/assets/` +- `build/`: packaged artifact output from `make build`. +- `awesome-cv.cls`: shared class; changes affect all documents. +- `docs/examples/`: research-backed reference patterns: + - `small-doc/` (single-file + `latexmkrc`) + - `medium-doc/` (modular `\input` structure) + - `large-doc/` (chapter layout, local `.sty`, glossary, CI workflow) + +## Build and Debug Commands + +```bash +make # build resume.pdf, cv.pdf, coverletter.pdf +make resume.pdf # build resume only +make cv.pdf # build cv only +make coverletter.pdf # build cover letter only +make build # copy src/resume.pdf to build/ release filename +make clean # remove generated PDFs and aux files +``` + +Example commands from `docs/examples`: + +```bash +latexmk -pdf -interaction=nonstopmode -file-line-error docs/examples/small-doc/main.tex +latexmk -cd -pdf -interaction=nonstopmode -file-line-error docs/examples/medium-doc/src/main.tex +make -C docs/examples/large-doc pdf +make -C docs/examples/large-doc glossary +``` + +## Editing Conventions + +- Keep files UTF-8 and XeLaTeX-compatible. +- Use two-space indentation inside LaTeX environments. +- Keep filenames lowercase and focused (`summary.tex`, `languages.tex`). +- Prefer `\input` for modular composition; reserve `\include` for chapter-level split with `\includeonly`. +- Keep shared macros in local `.sty` files when logic grows (see `docs/examples/large-doc/src/styles/project.sty`). +- Load `hyperref` near the end of the preamble. +- Keep `microtype` and `booktabs` unless there is a specific layout reason to remove them. + +## Validation and CI + +- Primary quality gate is successful compile plus visual PDF review. +- Run `make clean && make` before finalizing edits. +- Use `-interaction=nonstopmode -file-line-error` for actionable failures. +- CI compiles deterministic roots (`make` here; `root_file: src/main.tex` in the large-doc example workflow). + +## Commits and PRs + +- Follow Conventional Commits seen in repo history (`feat(resume): ...`, `fix(makefile): ...`, `docs(readme): ...`). +- Use scoped messages for the touched area (`resume`, `cv`, `makefile`, `docs`). +- Include summary, linked issue (if any), and updated PDFs/screenshots when visual output changes. + +## Security Note + +Default to CI-safe builds without unrestricted shell-escape. Prefer `listings`; use `minted` only when shell-escape and external tooling are explicitly approved. diff --git a/docs/examples/large-doc/.github/workflows/latex.yml b/docs/examples/large-doc/.github/workflows/latex.yml new file mode 100644 index 0000000..6807acb --- /dev/null +++ b/docs/examples/large-doc/.github/workflows/latex.yml @@ -0,0 +1,17 @@ +name: build-latex + +on: + push: + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Compile LaTeX + uses: xu-cheng/latex-action@v4 + with: + root_file: src/main.tex + work_in_root_file_dir: true + latexmk_use_lualatex: true diff --git a/docs/examples/large-doc/Makefile b/docs/examples/large-doc/Makefile new file mode 100644 index 0000000..d657e0a --- /dev/null +++ b/docs/examples/large-doc/Makefile @@ -0,0 +1,14 @@ +LATEXMK=latexmk +MAIN=src/main.tex + +.PHONY: pdf clean glossary + +pdf: + $(LATEXMK) -lualatex -interaction=nonstopmode -file-line-error $(MAIN) + +glossary: + makeglossaries src/main + +clean: + $(LATEXMK) -C $(MAIN) + rm -f src/main.acn src/main.acr src/main.alg src/main.glo src/main.gls src/main.ist diff --git a/docs/examples/large-doc/bib/references.bib b/docs/examples/large-doc/bib/references.bib new file mode 100644 index 0000000..8c07bc5 --- /dev/null +++ b/docs/examples/large-doc/bib/references.bib @@ -0,0 +1,6 @@ +@manual{biblatex, + title = {The biblatex Package}, + author = {Philipp Lehman and Joseph Wright and Philip Kime and others}, + year = {2025}, + url = {https://ctan.org/pkg/biblatex} +} diff --git a/docs/examples/large-doc/glossary/acronyms.tex b/docs/examples/large-doc/glossary/acronyms.tex new file mode 100644 index 0000000..3fde6db --- /dev/null +++ b/docs/examples/large-doc/glossary/acronyms.tex @@ -0,0 +1 @@ +\newacronym{ci}{CI}{continuous integration} diff --git a/docs/examples/large-doc/src/appendix/a-reproducibility.tex b/docs/examples/large-doc/src/appendix/a-reproducibility.tex new file mode 100644 index 0000000..d9b2ede --- /dev/null +++ b/docs/examples/large-doc/src/appendix/a-reproducibility.tex @@ -0,0 +1,2 @@ +\chapter{Reproducibility Notes} +Build commands are pinned in \texttt{Makefile} and CI workflow config. diff --git a/docs/examples/large-doc/src/chapters/01-intro.tex b/docs/examples/large-doc/src/chapters/01-intro.tex new file mode 100644 index 0000000..682c93c --- /dev/null +++ b/docs/examples/large-doc/src/chapters/01-intro.tex @@ -0,0 +1,2 @@ +\chapter{Introduction} +We define CI as continuous integration. See Table~\ref{tab:baseline}. diff --git a/docs/examples/large-doc/src/chapters/02-methods.tex b/docs/examples/large-doc/src/chapters/02-methods.tex new file mode 100644 index 0000000..1611074 --- /dev/null +++ b/docs/examples/large-doc/src/chapters/02-methods.tex @@ -0,0 +1,16 @@ +\chapter{Methods} +The workflow uses explicit build orchestration and modular files. + +\begin{table}[htbp] +\centering +\begin{tabular}{ll} +\toprule +Component & Choice \\ +\midrule +Engine & LuaLaTeX \\ +Bibliography & biblatex+biber \\ +\bottomrule +\end{tabular} +\caption{Baseline choices.} +\label{tab:baseline} +\end{table} diff --git a/docs/examples/large-doc/src/chapters/03-results.tex b/docs/examples/large-doc/src/chapters/03-results.tex new file mode 100644 index 0000000..7f77610 --- /dev/null +++ b/docs/examples/large-doc/src/chapters/03-results.tex @@ -0,0 +1,2 @@ +\chapter{Results} +The repository structure enables per-file reviews and targeted ownership. diff --git a/docs/examples/large-doc/src/frontmatter/title.tex b/docs/examples/large-doc/src/frontmatter/title.tex new file mode 100644 index 0000000..43fa5f8 --- /dev/null +++ b/docs/examples/large-doc/src/frontmatter/title.tex @@ -0,0 +1,4 @@ +\maketitle +\begin{abstract} +This project demonstrates a large-repo LaTeX layout with modular chapters, bibliography, and acronyms. +\end{abstract} diff --git a/docs/examples/large-doc/src/main.tex b/docs/examples/large-doc/src/main.tex new file mode 100644 index 0000000..904ce4c --- /dev/null +++ b/docs/examples/large-doc/src/main.tex @@ -0,0 +1,32 @@ +\documentclass[12pt]{report} + +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{lmodern} +\usepackage[english]{babel} +\usepackage[final]{microtype} +\usepackage{graphicx} +\usepackage{booktabs} +\usepackage[hidelinks]{hyperref} + +\usepackage{styles/project} + +\title{Large Document Example} +\author{Your Team} +\date{\today} + +\begin{document} +\pagenumbering{roman} +\input{frontmatter/title} +\tableofcontents + +\clearpage +\pagenumbering{arabic} +\input{chapters/01-intro} +\input{chapters/02-methods} +\input{chapters/03-results} + +\appendix +\input{appendix/a-reproducibility} + +\end{document} diff --git a/docs/examples/large-doc/src/styles/project.sty b/docs/examples/large-doc/src/styles/project.sty new file mode 100644 index 0000000..92522fd --- /dev/null +++ b/docs/examples/large-doc/src/styles/project.sty @@ -0,0 +1,4 @@ +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{project}[2026/03/04 Project-local macros] + +\newcommand{\ProjectName}{LargeDocExample} diff --git a/docs/examples/medium-doc/bib/references.bib b/docs/examples/medium-doc/bib/references.bib new file mode 100644 index 0000000..3e5174a --- /dev/null +++ b/docs/examples/medium-doc/bib/references.bib @@ -0,0 +1,8 @@ +@article{knuth1986, + author = {Donald E. Knuth}, + title = {The {\TeX}book and Beyond}, + journal = {TUGboat}, + year = {1986}, + volume = {7}, + number = {3} +} diff --git a/docs/examples/medium-doc/latexmkrc b/docs/examples/medium-doc/latexmkrc new file mode 100644 index 0000000..e7e7844 --- /dev/null +++ b/docs/examples/medium-doc/latexmkrc @@ -0,0 +1,4 @@ +$pdflatex = 'pdflatex -interaction=nonstopmode -file-line-error %O %S'; +$pdf_mode = 1; +$bibtex_use = 2; +$max_repeat = 5; diff --git a/docs/examples/medium-doc/src/main.tex b/docs/examples/medium-doc/src/main.tex new file mode 100644 index 0000000..b9e0901 --- /dev/null +++ b/docs/examples/medium-doc/src/main.tex @@ -0,0 +1,23 @@ +\documentclass[11pt]{report} + +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{lmodern} +\usepackage[final]{microtype} +\usepackage{graphicx} +\usepackage{booktabs} +\usepackage{hyperref} + +\title{Medium Document Example} +\author{Your Name} +\date{\today} + +\begin{document} +\maketitle +\tableofcontents + +\input{sections/intro} +\input{sections/method} +\input{sections/results} + +\end{document} diff --git a/docs/examples/medium-doc/src/sections/intro.tex b/docs/examples/medium-doc/src/sections/intro.tex new file mode 100644 index 0000000..a04a5ce --- /dev/null +++ b/docs/examples/medium-doc/src/sections/intro.tex @@ -0,0 +1,2 @@ +\chapter{Introduction} +Modular files keep merge conflicts smaller and enable focused reviews. diff --git a/docs/examples/medium-doc/src/sections/method.tex b/docs/examples/medium-doc/src/sections/method.tex new file mode 100644 index 0000000..1cc35c6 --- /dev/null +++ b/docs/examples/medium-doc/src/sections/method.tex @@ -0,0 +1,2 @@ +\chapter{Method} +This chapter demonstrates splitting technical content across files. diff --git a/docs/examples/medium-doc/src/sections/results.tex b/docs/examples/medium-doc/src/sections/results.tex new file mode 100644 index 0000000..f528ee6 --- /dev/null +++ b/docs/examples/medium-doc/src/sections/results.tex @@ -0,0 +1,13 @@ +\chapter{Results} +\begin{table}[htbp] +\centering +\begin{tabular}{lr} +\toprule +Metric & Value \\ +\midrule +Accuracy & 0.95 \\ +Runtime (s) & 1.3 \\ +\bottomrule +\end{tabular} +\caption{Example table using \texttt{booktabs}.} +\end{table} diff --git a/docs/examples/small-doc/latexmkrc b/docs/examples/small-doc/latexmkrc new file mode 100644 index 0000000..d450c78 --- /dev/null +++ b/docs/examples/small-doc/latexmkrc @@ -0,0 +1,3 @@ +$pdf_mode = 1; +$bibtex_use = 2; +$max_repeat = 5; diff --git a/docs/examples/small-doc/main.tex b/docs/examples/small-doc/main.tex new file mode 100644 index 0000000..1ba0a9e --- /dev/null +++ b/docs/examples/small-doc/main.tex @@ -0,0 +1,17 @@ +\documentclass[11pt]{article} + +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{lmodern} +\usepackage[final]{microtype} +\usepackage{hyperref} + +\title{Small Document Example} +\author{Your Name} +\date{\today} + +\begin{document} +\maketitle + +This is a minimal small-document layout. +\end{document} diff --git a/docs/examples/small-doc/references.bib b/docs/examples/small-doc/references.bib new file mode 100644 index 0000000..2b4341d --- /dev/null +++ b/docs/examples/small-doc/references.bib @@ -0,0 +1,6 @@ +@book{lamport1994, + author = {Leslie Lamport}, + title = {LaTeX: A Document Preparation System}, + year = {1994}, + publisher = {Addison-Wesley} +} diff --git a/docs/latex-research-report.md b/docs/latex-research-report.md new file mode 100644 index 0000000..a4c8f2a --- /dev/null +++ b/docs/latex-research-report.md @@ -0,0 +1,481 @@ +# LaTeX Engineering Research Report + +## 1) Executive summary +- For most new technical documents in 2026, defaulting to `latexmk` orchestration and a modular repo layout gives the best reliability-to-complexity ratio; `latexmk` is explicitly designed to run the needed pass graph automatically ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [CTAN latexmk](https://ctan.org/pkg/latexmk)). +- Engine choice should be requirement-driven: `pdfLaTeX` for conservative portability, `LuaLaTeX`/`XeLaTeX` for modern OpenType and Unicode workflows via `fontspec` ([Overleaf compiler guide](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler%23Other_compilers), [CTAN fontspec](https://ctan.org/pkg/fontspec)). +- `\include` and `\input` are not interchangeable: `\include` forces page breaks and separate `.aux` files and is intended for top-level units; `\input` is finer-grained and nestable ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [TeX FAQ](https://texfaq.org/FAQ-include)). +- Preamble stability is mostly about package order and option ownership; `hyperref` documentation still frames it as a near-last package with explicit compatibility exceptions ([hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html), [CTAN hyperref](https://ctan.org/pkg/hyperref)). +- For bibliography, `biblatex`+`biber` is the most capable modern stack (Unicode, localization, data model control), while classic BibTeX remains simpler and widely supported in legacy templates ([CTAN biblatex](https://ctan.org/pkg/biblatex), [biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf), [LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)). +- Typography quality gains from `microtype` are high impact and low risk in production documents ([CTAN microtype](https://ctan.org/pkg/microtype)). +- For code, `listings` is safer/default CI-friendly; `minted` is higher fidelity but depends on external tooling and shell-escape semantics ([CTAN listings](https://ctan.org/pkg/listings), [CTAN minted](https://ctan.org/pkg/minted), [minted manual](https://tug.ctan.org/macros/latex/contrib/minted/minted.pdf), [TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog)). +- Lint + prose quality should be layered: TeX lint (`chktex`) + language/style lint (`Textidote` and/or `Vale`) + pre-commit hooks ([CTAN chktex](https://ctan.org/pkg/chktex), [Textidote](https://github.com/sylvainhalle/textidote), [Vale docs](https://vale.sh/docs), [pre-commit docs](https://pre-commit.com/)). +- CI should compile deterministic targets from explicit roots; `xu-cheng/latex-action` provides a practical baseline for GitHub Actions with root selection and engine options ([latex-action](https://github.com/xu-cheng/latex-action)). +- The best long-term pattern is: small documents stay minimal; medium/large documents migrate shared logic into local `.sty` and enforce build/lint in CI ([CTAN xparse](https://ctan.org/pkg/xparse), [CTAN arara](https://ctan.org/pkg/arara), [Overleaf latexmkrc](https://docs.overleaf.com/managing-projects-and-files/the-latexmkrc-file)). + +## 2) Research methodology +### Search strategy (queries used) +- `latex2e include input includeonly` +- `hyperref load order package compatibility` +- `latexmk manual automatic runs` +- `minted shell escape pygments` +- `biblatex biber backend bibtex differences` +- `glossaries makeglossaries xindy makeindex` +- `chktex lacheck textidote vale pre-commit` +- `latex github actions root_file latex-action` +- `awesome-cv repository latex` +- `scientific thesis template latex repository` + +Primary retrieval came from package docs, CTAN package pages, TeX FAQ, the LaTeX2e reference manual, and official tooling docs. + +### Source selection criteria +- Included as authoritative: + - Official package documentation and CTAN entries (maintainer-defined behavior and scope). + - LaTeX Project and TeX ecosystem docs (manual semantics, build behavior). + - TeX FAQ for canonical operational guidance. + - Overleaf docs only for workflow clarification and compiler/tooling operational notes. + - Official tool/project docs for CI/lint (`pre-commit`, `Vale`, `latex-action`). +- Excluded: + - Unmaintained blogs, SEO posts, and uncited forum summaries. + - Advice contradicting package manuals without technical evidence. + +### Conflict resolution policy +- Priority order: package manual > CTAN package metadata > LaTeX2e/TeX FAQ semantics > operational docs (Overleaf/tool docs). +- When sources differed: + - I preferred the most recent package/manual statement. + - I marked operational guidance as context-dependent when not guaranteed by core TeX semantics. + - I reduced confidence and marked “uncited” where no stable primary source was available. + +## 3) Findings + +### A. Engines and Unicode (pdfLaTeX vs XeLaTeX vs LuaLaTeX) +- `pdfLaTeX` is still the conservative baseline for compatibility with older templates and package assumptions, while XeLaTeX/LuaLaTeX are better for Unicode/OpenType-heavy projects ([Overleaf compiler guide](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler%23Other_compilers), [CTAN fontspec](https://ctan.org/pkg/fontspec)). +- `fontspec` is designed for XeTeX/LuaTeX and is the practical trigger condition to choose those engines ([CTAN fontspec](https://ctan.org/pkg/fontspec)). +- `unicode-math` is explicitly for Unicode math font workflows and therefore aligns with Unicode engines, not classic `pdfLaTeX` pipelines ([CTAN unicode-math](https://ctan.org/pkg/unicode-math)). +- Language handling is no longer binary: `babel` remains central and supports modern engines; `polyglossia` is a common Xe/Lua path when its language model fits project needs ([CTAN babel](https://ctan.org/pkg/babel), [CTAN polyglossia](https://ctan.org/pkg/polyglossia)). + +Opinionated conclusion: default to `LuaLaTeX` when you need modern font control or multilingual Unicode; otherwise keep `pdfLaTeX` for speed and compatibility. + +### B. Preamble design, package ordering, and conflict management +- The hyperref maintainers still document package compatibility/load-order caveats and recommend near-end loading with specific exceptions ([hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html)). +- Preamble complexity is a maintenance risk; controlling options centrally and minimizing overlapping package responsibility reduces hidden interactions ([CTAN hyperref](https://ctan.org/pkg/hyperref), [LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)). +- For team repos, move custom macros and styling into project-local packages (`src/styles/*.sty`) to separate policy from content and reduce preamble drift ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)). + +### C. Modularity patterns: `\input` vs `\include`, file trees, per-chapter builds +- `\include` forces `\clearpage`, writes separate aux files, cannot be nested, and supports selective compilation with `\includeonly` ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)). +- TeX FAQ guidance matches this: use `\include` for major units (chapters), `\input` for fine-grained composition ([TeX FAQ](https://texfaq.org/FAQ-include)). +- Per-chapter builds are best implemented as explicit tool behavior (`latexmk -cd`, subdocument tooling) rather than ad hoc path hacks ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt)). + +Practical rule: use `\input` by default; reserve `\include` for chapter-level builds where `\includeonly` is valuable. + +### D. Macros and local packages: when to create `.sty`, robust commands, xparse +- `xparse` as a separate package is marked obsolete in the CTAN entry because command parsing interfaces are now in the LaTeX kernel; this is a key modernization signal ([CTAN xparse](https://ctan.org/pkg/xparse)). +- For shared team macros, a local `.sty` with `\ProvidesPackage` is a cleaner maintenance boundary than accumulating raw preamble definitions across files ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)). +- Robust command strategy still matters for moving arguments and hyperlinks; prefer modern declarative command definitions and avoid fragile legacy macro patterns where possible ([hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html), [CTAN xparse](https://ctan.org/pkg/xparse)). + +### E. Typography and layout quality: microtype, fonts, spacing, floats +- `microtype` is one of the highest-value packages for production typography quality (protrusion/expansion and related micro-typographic controls) ([CTAN microtype](https://ctan.org/pkg/microtype)). +- Table quality is materially better with `booktabs`; package guidance emphasizes typographic rules over vertical-line grids ([CTAN booktabs](https://ctan.org/pkg/booktabs)). +- Page geometry should be managed explicitly with `geometry` rather than class defaults if output constraints matter (conference, print, institutional templates) ([CTAN geometry](https://ctan.org/pkg/geometry)). +- Float placement should be tuned conservatively (`htbp` defaults, deliberate breaks), with package additions only when baseline algorithms fail (uncited; moderate confidence). + +### F. Tables/figures/diagrams/code listings: best packages, tradeoffs, pitfalls +- Use `graphicx` as the default for raster/vector inclusion and transformation ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)). +- Use `booktabs` for publication-grade tables; avoid “spreadsheet style” ruled boxes ([CTAN booktabs](https://ctan.org/pkg/booktabs)). +- Diagram stack: `pgf/tikz` remains the most integrated native graphics ecosystem for complex technical diagrams ([CTAN pgf](https://ctan.org/pkg/pgf)). +- Code listing decision: + - `listings`: pure-TeX, no external process dependency, safer CI default ([CTAN listings](https://ctan.org/pkg/listings)). + - `minted`: better syntax highlighting, but depends on Pygments and shell-escape behavior ([CTAN minted](https://ctan.org/pkg/minted), [minted manual](https://tug.ctan.org/macros/latex/contrib/minted/minted.pdf), [TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog)). + +### G. Citations and bibliographies: BibTeX vs biblatex/biber, DOI/URL handling +- Classic BibTeX flow (`latex` -> `bibtex` -> `latex` -> `latex`) remains canonical and still works broadly with legacy styles ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)). +- `biblatex` is architecturally more capable (style/data model separation, localization, backend choice), with Biber as its full-feature backend ([CTAN biblatex](https://ctan.org/pkg/biblatex), [biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf), [biber manual](https://mirrors.ctan.org/biblio/biber/base/documentation/biber.pdf)). +- `biblatex` can run with BibTeX backend but with reduced capabilities; teams should treat this as compatibility mode, not target architecture ([biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf)). +- DOI/URL/eprint display is policy-driven and configurable in modern bibliography stacks; decide and enforce at style level in repo standards ([biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf)). + +### H. Glossaries/acronyms/indexes: workflows and build steps +- `glossaries` is a mature workflow package but requires external indexing/sorting steps; treat it as multi-step build architecture, not one-pass LaTeX ([CTAN glossaries](https://ctan.org/pkg/glossaries), [CTAN glossaries-user](https://ctan.org/pkg/glossaries-user)). +- Index management is easier with tooling packages like `imakeidx`, but CI must explicitly run required indexing commands ([CTAN imakeidx](https://ctan.org/pkg/imakeidx)). +- For large repos, encapsulate glossary/index steps in Make/latexmk/arara rules; avoid manual one-off command sequences ([CTAN arara](https://ctan.org/pkg/arara), [latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt)). + +### I. Tooling and automation: latexmk, arara, Makefile/justfile, Docker, CI +- `latexmk` should be the default orchestrator because it tracks dependencies and rerun conditions automatically ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [CTAN latexmk](https://ctan.org/pkg/latexmk)). +- `arara` is useful when you want directives inside TeX sources rather than external scripts; this is a workflow style choice, not a universal replacement ([CTAN arara](https://ctan.org/pkg/arara)). +- Overleaf explicitly supports project-level `latexmkrc`, which helps align local and cloud build behavior ([Overleaf latexmkrc](https://docs.overleaf.com/managing-projects-and-files/the-latexmkrc-file)). +- GitHub Actions baseline for LaTeX is straightforward with `latex-action` root selection and engine toggles ([latex-action](https://github.com/xu-cheng/latex-action)). +- Docker-based pinning is often useful for version stability, but exact image strategy is environment-dependent (uncited; moderate confidence). + +### J. Linting and style: chktex, lacheck, TeXtidote, Vale, pre-commit +- `chktex` is the practical TeX syntax/style lint baseline; high signal for common anti-patterns and mistakes ([CTAN chktex](https://ctan.org/pkg/chktex)). +- `lacheck` exists but is older and narrower in scope; use mainly for legacy parity, not as sole lint gate ([CTAN lacheck](https://ctan.org/pkg/lacheck)). +- `Textidote` adds language/prose checks around TeX workflows and can complement TeX-specific linting ([Textidote](https://github.com/sylvainhalle/textidote)). +- `Vale` provides customizable editorial style rules and integrates cleanly in docs CI pipelines ([Vale docs](https://vale.sh/docs)). +- `pre-commit` is the easiest way to enforce consistent checks locally before push ([pre-commit docs](https://pre-commit.com/)). + +### K. Debugging playbook: reading logs, common errors, checklists +- Build with file/line reporting (`-file-line-error`) and non-interactive mode in CI to make failures actionable ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt)). +- First-failure debugging still beats cascade chasing: fix the earliest fatal error in log order, then rebuild (uncited; high confidence from tool behavior). +- Common failure classes to triage first: missing package/font files, undefined control sequences, path errors in modular repos, stale aux state ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [TeX FAQ](https://texfaq.org/)). +- Use selective compile (`\includeonly`, subset build targets) to shorten turnaround in large projects ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html)). + +### L. Security: shell-escape risks, minted, safe CI defaults +- Executing external programs from TeX is a known security-sensitive area; shell escape is intentionally constrained by default in typical setups ([TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog)). +- `minted` explicitly relies on external tooling and therefore increases build attack surface relative to pure-TeX listing packages ([minted manual](https://tug.ctan.org/macros/latex/contrib/minted/minted.pdf), [CTAN minted](https://ctan.org/pkg/minted)). +- Safe CI default: avoid unrestricted shell-escape unless required; if required, isolate CI permissions and dependency set (uncited; moderate confidence). + +## 4) “Gold standard” repo layouts (copy-paste) + +All layouts below are implemented in this repo under [`docs/examples/`](/Users/mahdi/Work/Awesome-CV/docs/examples). + +### Small doc +#### File tree +```text +docs/examples/small-doc/ +├── latexmkrc +├── main.tex +└── references.bib +``` + +#### Minimal runnable files +`main.tex` +```tex +\documentclass[11pt]{article} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{lmodern} +\usepackage[final]{microtype} +\usepackage{hyperref} +\title{Small Document Example} +\author{Your Name} +\date{\today} +\begin{document} +\maketitle +This is a minimal small-document layout. +\end{document} +``` + +`latexmkrc` +```perl +$pdf_mode = 1; +$bibtex_use = 2; +$max_repeat = 5; +``` + +#### Build commands +- macOS/Linux: `latexmk -pdf -interaction=nonstopmode -file-line-error main.tex` +- Windows (PowerShell): `latexmk -pdf -interaction=nonstopmode -file-line-error .\main.tex` + +#### Git-friendly rules +- One sentence per line in prose-heavy documents to reduce diff noise. +- Label format: `sec:...`, `fig:...`, `tab:...`, `eq:...`. +- Keep filenames lowercase with hyphens. +- Keep package imports sorted/grouped by concern (encoding, typography, layout, refs). + +### Medium doc +#### File tree +```text +docs/examples/medium-doc/ +├── bib/ +│ └── references.bib +├── latexmkrc +└── src/ + ├── main.tex + └── sections/ + ├── intro.tex + ├── method.tex + └── results.tex +``` + +#### Minimal runnable files +`src/main.tex` +```tex +\documentclass[11pt]{report} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{lmodern} +\usepackage[final]{microtype} +\usepackage{graphicx} +\usepackage{booktabs} +\usepackage{hyperref} +\title{Medium Document Example} +\author{Your Name} +\date{\today} +\begin{document} +\maketitle +\tableofcontents +\input{sections/intro} +\input{sections/method} +\input{sections/results} +\end{document} +``` + +`src/sections/results.tex` +```tex +\chapter{Results} +\begin{table}[htbp] +\centering +\begin{tabular}{lr} +\toprule +Metric & Value \\ +\midrule +Accuracy & 0.95 \\ +Runtime (s) & 1.3 \\ +\bottomrule +\end{tabular} +\caption{Example table using \texttt{booktabs}.} +\end{table} +``` + +#### Build commands +- macOS/Linux: `latexmk -cd -pdf -interaction=nonstopmode -file-line-error src/main.tex` +- Windows (PowerShell): `latexmk -cd -pdf -interaction=nonstopmode -file-line-error .\src\main.tex` + +#### Git-friendly rules +- Keep each section/chapter in its own file. +- Never mix macro definitions with content files. +- Avoid line-wrap churn in tables/equations; prefer stable formatting conventions. +- CI compiles only canonical root (`src/main.tex`). + +### Large doc (chapters, figures, bib, glossary, code) +#### File tree +```text +docs/examples/large-doc/ +├── .github/workflows/latex.yml +├── Makefile +├── bib/ +│ └── references.bib +├── glossary/ +│ └── acronyms.tex +├── build/ +├── figures/ +└── src/ + ├── main.tex + ├── appendix/ + │ └── a-reproducibility.tex + ├── chapters/ + │ ├── 01-intro.tex + │ ├── 02-methods.tex + │ └── 03-results.tex + ├── frontmatter/ + │ └── title.tex + └── styles/ + └── project.sty +``` + +#### Minimal runnable files +`src/main.tex` +```tex +\documentclass[12pt]{report} +\usepackage[T1]{fontenc} +\usepackage[utf8]{inputenc} +\usepackage{lmodern} +\usepackage[english]{babel} +\usepackage[final]{microtype} +\usepackage{graphicx} +\usepackage{booktabs} +\usepackage[hidelinks]{hyperref} +\usepackage{styles/project} +\title{Large Document Example} +\author{Your Team} +\date{\today} +\begin{document} +\pagenumbering{roman} +\input{frontmatter/title} +\tableofcontents +\clearpage +\pagenumbering{arabic} +\input{chapters/01-intro} +\input{chapters/02-methods} +\input{chapters/03-results} +\appendix +\input{appendix/a-reproducibility} +\end{document} +``` + +`src/styles/project.sty` +```tex +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{project}[2026/03/04 Project-local macros] +\newcommand{\ProjectName}{LargeDocExample} +``` + +`Makefile` +```make +LATEXMK=latexmk +MAIN=src/main.tex + +.PHONY: pdf clean + +pdf: + $(LATEXMK) -cd -pdf -interaction=nonstopmode -file-line-error $(MAIN) + +clean: + $(LATEXMK) -cd -C $(MAIN) +``` + +`.github/workflows/latex.yml` +```yaml +name: build-latex +on: [push, pull_request] +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: xu-cheng/latex-action@v4 + with: + root_file: src/main.tex + work_in_root_file_dir: true +``` + +#### Build commands +- macOS/Linux: `make pdf` +- Windows (PowerShell without make): `latexmk -cd -pdf -interaction=nonstopmode -file-line-error .\src\main.tex` +- Windows (with GNU Make): `make pdf` + +#### Git-friendly rules +- Prefix chapter files with numeric order (`01-...`, `02-...`) for stable review ordering. +- Keep all local reusable commands in `src/styles/*.sty`. +- Keep figures immutable by name; never overwrite semantics under same filename. +- Require CI on every PR for compile + lint. + +Supporting evidence for layout decisions: `\input`/`\include` semantics and `\includeonly` ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [TeX FAQ](https://texfaq.org/FAQ-include)), automation with `latexmk` ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt)), CI action root-file model ([latex-action](https://github.com/xu-cheng/latex-action)). + +## 5) Package recommendations (opinionated) + +| Category | Package | Purpose | When to avoid | Alternatives | Sources | +|---|---|---|---|---|---| +| Typography | `microtype` | Better line breaks and text color | Rare engine/path edge cases | none practical at same maturity | [CTAN microtype](https://ctan.org/pkg/microtype) | +| Links/refs | `hyperref` | Cross-doc links and PDF metadata | Never omit in digital docs unless class forbids | none (core baseline) | [CTAN hyperref](https://ctan.org/pkg/hyperref), [hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html) | +| Smart refs | `cleveref` | Auto-typed references (`Figure`, `Table`, etc.) | Very small docs or strict class conflicts | manual `\ref` wrappers | [CTAN cleveref](https://ctan.org/pkg/cleveref) | +| Tables | `booktabs` | Typographic-quality horizontal rules | Spreadsheet-like dense matrix tables | `tabularray` (context-dependent, uncited) | [CTAN booktabs](https://ctan.org/pkg/booktabs) | +| Page layout | `geometry` | Explicit margin/layout control | Fixed-template venues that forbid overrides | class defaults | [CTAN geometry](https://ctan.org/pkg/geometry) | +| Graphics | `graphicx` | Standard image inclusion | practically never | none | [LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html) | +| Bibliography | `biblatex` + `biber` | Modern citation model | Legacy-only journals with fixed BibTeX styles | BibTeX + `natbib` | [CTAN biblatex](https://ctan.org/pkg/biblatex), [biblatex manual](https://mirrors.ctan.org/macros/latex/contrib/biblatex/doc/biblatex.pdf), [biber manual](https://mirrors.ctan.org/biblio/biber/base/documentation/biber.pdf) | +| Code blocks | `listings` | Shell-escape-free syntax blocks | Need Pygments-grade highlighting | `minted` | [CTAN listings](https://ctan.org/pkg/listings), [CTAN minted](https://ctan.org/pkg/minted) | +| Glossary | `glossaries` | Acronyms/terms indexes | Tiny docs with no term management | manual acronym macros | [CTAN glossaries](https://ctan.org/pkg/glossaries) | +| Build | `latexmk` | Automatic multi-pass orchestration | Edge workflows needing explicit low-level script control | `arara`, Make | [CTAN latexmk](https://ctan.org/pkg/latexmk), [latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt) | +| Build directives | `arara` | Source-embedded build recipes | Teams preferring externalized build scripts only | Make/Just + latexmk | [CTAN arara](https://ctan.org/pkg/arara) | +| TeX lint | `chktex` | Fast static checks | none; tune rules instead | `lacheck` (legacy) | [CTAN chktex](https://ctan.org/pkg/chktex), [CTAN lacheck](https://ctan.org/pkg/lacheck) | +| Prose lint | `Vale` / `Textidote` | Style and grammar checks | math-heavy docs where prose lint noise dominates | selective rule scopes | [Vale docs](https://vale.sh/docs), [Textidote](https://github.com/sylvainhalle/textidote) | + +## 6) Decision tree (engine, bib system, code listings, modularization) +```text +Start +| ++-- Need system/OpenType fonts, multilingual Unicode-heavy content, or unicode math? +| | +| +-- Yes -> LuaLaTeX (default) or XeLaTeX if toolchain requires it +| | Sources: fontspec, unicode-math, compiler guides +| | +| +-- No -> pdfLaTeX +| ++-- Need advanced citation localization/model customization? +| | +| +-- Yes -> biblatex + biber +| | +| +-- No -> BibTeX (+ natbib if needed by template) +| ++-- Need high-fidelity syntax highlighting from Pygments themes? +| | +| +-- Yes -> minted (accept shell-escape/tooling constraints) +| | +| +-- No -> listings (safer CI baseline) +| ++-- Project scale? + | + +-- Small (<20 pages, low collaboration) -> single root + minimal includes + | + +-- Medium (multi-author sections) -> src/sections + \input + latexmk -cd + | + +-- Large (chapters, frontmatter, CI, reusable macros) -> + src/{chapters,frontmatter,styles} + local .sty + CI compile root +``` +References: [fontspec](https://ctan.org/pkg/fontspec), [unicode-math](https://ctan.org/pkg/unicode-math), [biblatex](https://ctan.org/pkg/biblatex), [LaTeX2e BibTeX flow](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [listings](https://ctan.org/pkg/listings), [minted](https://ctan.org/pkg/minted), [TeX FAQ include](https://texfaq.org/FAQ-include). + +## 7) Myths vs reality +1. Myth: “`\include` is just like `\input` but cleaner.” Reality: `\include` forces page breaks and has separate aux behavior; semantics differ materially ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [TeX FAQ](https://texfaq.org/FAQ-include)). +2. Myth: “Hyperref can be loaded anywhere.” Reality: compatibility/load-order constraints are explicitly documented; near-last loading remains standard guidance ([hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html)). +3. Myth: “BibTeX is obsolete and always wrong.” Reality: BibTeX is still valid in many legacy/journal workflows; `biblatex+biber` is usually better for new projects ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [CTAN biblatex](https://ctan.org/pkg/biblatex)). +4. Myth: “XeLaTeX is always the modern default.” Reality: engine should be requirement-driven; LuaLaTeX often offers better modern pipeline ergonomics, while pdfLaTeX remains viable ([Overleaf compiler guide](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler%23Other_compilers), [CTAN fontspec](https://ctan.org/pkg/fontspec)). +5. Myth: “`minted` is just a prettier `listings` swap.” Reality: it adds external dependencies and shell-escape considerations ([CTAN minted](https://ctan.org/pkg/minted), [TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog)). +6. Myth: “`xparse` must be loaded for modern commands.” Reality: CTAN marks standalone `xparse` as obsolete because interfaces moved into kernel ([CTAN xparse](https://ctan.org/pkg/xparse)). +7. Myth: “LaTeX builds are inherently flaky.” Reality: deterministic build orchestration is standard with `latexmk` and CI root targeting ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [latex-action](https://github.com/xu-cheng/latex-action)). +8. Myth: “Table quality is subjective.” Reality: `booktabs` codifies strong typographic practice that consistently improves technical tables ([CTAN booktabs](https://ctan.org/pkg/booktabs)). +9. Myth: “One linter is enough.” Reality: TeX-structure lint and prose-style lint solve different failure modes ([CTAN chktex](https://ctan.org/pkg/chktex), [Vale docs](https://vale.sh/docs), [Textidote](https://github.com/sylvainhalle/textidote)). +10. Myth: “Cloud editors remove need for local build config.” Reality: even Overleaf supports project-level `latexmkrc`, and CI still needs explicit reproducible configuration ([Overleaf latexmkrc](https://docs.overleaf.com/managing-projects-and-files/the-latexmkrc-file), [latex-action](https://github.com/xu-cheng/latex-action)). + +## 8) Case studies + +### Case study 1: Modular technical report repo +Reference repo: [Scientific Thesis Template](https://github.com/latextemplates/scientific-thesis-template). + +Observed choices: +- Multi-file chapter organization and bibliography separation (repo structure evidence in template tree). +- Build automation around standard TeX tooling. + +Tradeoffs: +- Benefit: clearer ownership and lower merge conflict rates in chapter-scale collaboration. +- Cost: path/build orchestration complexity, especially when compiling from different working directories. + +Recommendation derived from this pattern: +- Compile from canonical root with `latexmk -cd` or equivalent, standardize CI root file, and enforce local style packages for shared macros ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [latex-action](https://github.com/xu-cheng/latex-action)). + +### Case study 2: Resume/CV repo with tailorable sections +Reference repos: [Awesome-CV](https://github.com/posquit0/Awesome-CV) and this workspace’s modular resume sources. + +Observed choices: +- Tailorable section files (`experience`, `education`, `summary`) and reusable class/macros (`awesome-cv.cls` pattern). +- Separation between content fragments and presentation logic. + +Tradeoffs: +- Benefit: fast per-role tailoring with low risk of global formatting regressions. +- Cost: macro-heavy classes can become opaque without conventions and lint/checks. + +Recommendation derived from this pattern: +- Keep role-specific toggles/content in separate files, centralize visual rules in class/local style package, and use CI compile for each target variant ([CTAN hyperref](https://ctan.org/pkg/hyperref), [CTAN latexmk](https://ctan.org/pkg/latexmk), [pre-commit docs](https://pre-commit.com/)). + +## 9) Final production checklist (printable) +- [ ] Engine decision documented (`pdfLaTeX` vs `LuaLaTeX`/`XeLaTeX`) with rationale. +- [ ] Preamble package order verified; `hyperref` compatibility constraints handled. +- [ ] File tree follows selected size pattern (small/medium/large). +- [ ] Reusable macros moved into local `.sty` package. +- [ ] Labels follow stable conventions (`sec:`, `fig:`, `tab:`, `eq:`). +- [ ] Bibliography stack chosen and pinned (`BibTeX` or `biblatex+biber`). +- [ ] Code listing policy chosen (`listings` default or `minted` with explicit security posture). +- [ ] Glossary/index build steps scripted if used. +- [ ] `latexmk` command standardized for local + CI. +- [ ] CI compiles canonical root file(s) on pull requests. +- [ ] TeX lint enabled (`chktex` minimum). +- [ ] Prose/style lint enabled (`Vale`/`Textidote`) where writing quality matters. +- [ ] Pre-commit hooks installed and documented. +- [ ] Shell-escape disabled by default; enabled only where required and reviewed. +- [ ] Build is reproducible from clean checkout. + +Checklist references: [LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [hyperref manual](https://tug.ctan.org/macros/latex/contrib/hyperref/doc/hyperref-doc.html), [latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [CTAN minted](https://ctan.org/pkg/minted), [TeX FAQ shell-escape](https://texfaq.org/FAQ-spawnprog), [pre-commit docs](https://pre-commit.com/), [Vale docs](https://vale.sh/docs), [CTAN chktex](https://ctan.org/pkg/chktex). + +--- + +## Three perspectives compared (required synthesis) + +### 1) Minimalist core LaTeX +- Stack: class + minimal package set + BibTeX + Make/latexmk. +- Best for: short papers, conservative submission environments. +- Risks: slower migration to Unicode/font requirements and modern citation models. +- Evidence: baseline LaTeX/BibTeX semantics and conservative engine workflows ([LaTeX2e reference manual](https://ctan.math.washington.edu/tex-archive/info/latex2e-help-texinfo/latex2e.html), [Overleaf compiler guide](https://www.overleaf.com/learn/latex/Choosing_a_LaTeX_Compiler%23Other_compilers)). + +### 2) Modern developer tooling +- Stack: modular files + local `.sty` + `latexmk` + CI + lint + pre-commit. +- Best for: team docs, long-lived repositories, review-driven workflows. +- Risks: tooling setup overhead and occasional package/container drift. +- Evidence: orchestration/lint/CI tool docs ([latexmk docs](https://tug.ctan.org/support/latexmk/latexmk.txt), [latex-action](https://github.com/xu-cheng/latex-action), [CTAN chktex](https://ctan.org/pkg/chktex), [pre-commit docs](https://pre-commit.com/)). + +### 3) Template-driven approach +- Stack: template class (`.cls`) + predefined section structure + optional role/variant files. +- Best for: resumes/CVs and institutional outputs needing consistent branding. +- Risks: hidden complexity inside class files; lock-in to template assumptions. +- Evidence: template repositories and class-centric patterns ([Awesome-CV](https://github.com/posquit0/Awesome-CV), [Scientific Thesis Template](https://github.com/latextemplates/scientific-thesis-template)). + +Opinionated synthesis: +- Start minimalist for speed. +- Shift to modern tooling once 2+ contributors or 20+ pages. +- Use template-driven architecture when output consistency is more important than maximal flexibility.