Skip to content

bbtex vs TeXShop, LaTeXTools and AUCTeX ​

How bbtex in BBEdit compares with the editors people usually mean when they say "a good LaTeX setup": TeXShop (the Mac's own LaTeX editor, with its built-in PDF viewer), LaTeXTools for Sublime Text, and AUCTeX (with RefTeX and preview-latex) for Emacs. It describes bbtex v0.2.0; see the handoff for open work.

"Yes" means a supported workflow in the stock package; many gaps in the other tools can be filled with configuration or engine scripts. The bbtex column is checked against the code and tests. The others come from each project's documentation, and "Unknown" means I haven't confirmed it. Corrections are welcome. bbtex relies on TexLab (through BBEdit's language-server support) for as-you-type completion and adds its own explicit commands on top.

Magic comments ​

TeXShop started the % !TEX convention; LaTeXTools adopted and extended it. bbtex reads root and program (plus TeXShop's TS-program spelling), and maps the comments that change the build onto its own settings: build settings in comments explains the order, and why shell escape needs a .bbtex file. bbtex doesn't drop the rest silently: Doctor lists each comment with what to do instead, and a build names the ones that don't fully apply.

CommentTeXShopLaTeXToolsbbtex
% !TEX root = …YesYesYes, in the first 50 lines, %!TEX or % !TEX
% !TEX TS-program = …YesYesYes, as an alias of program
% !TEX program = …NoYesYes
TeXShop engine names (pdflatexmk, xelatexmk, …)Yes (engine scripts)UnknownBuilt-in names map to pdfLaTeX, XeLaTeX, LuaLaTeX; custom engine scripts are not run
% !TEX encoding = …YesNoParsed but not used
% !TEX spellcheck = …YesYesNo
% !TEX parameter = …YesNoYes, as extra options; shell escape only from .bbtex
% !BIB TS-program = …YesNoChecked against what latexmk ran; bibtex8, upbibtex, pbibtex become latexmk's BibTeX
% !TEX options = …NoYesYes, after .bbtex options; shell escape only from .bbtex
% !TEX output_directory = …NoYesYes, unless .bbtex sets one
% !TEX jobname = … / aux_directoryNoYesNo
Emacs TeX-master / TeX-engineNoNoNo (AUCTeX's own format)

Build ​

FeatureTeXShopLaTeXToolsAUCTeXbbtex
One-key build⌘T (Typeset)⌘BC-c C-c⌘K
latexmk buildsVia …mk engine scriptsYes (default)Via add-on or custom commandYes
pdfLaTeX / XeLaTeX / LuaLaTeXYesYesYes (TeX-engine)Yes
TectonicCustom engine scriptNoCustom commandYes, direct pipeline
BibTeX / BiberSeparate command, or latexmk enginesVia latexmkVia command chainVia latexmk; tested with MacTeX Biber ≥ 2.21
Named build variantsEngine menuBuilder settingsTeX-command-list.bbtex profiles; Compile With… (⇧⌘K)
Save before buildCurrent fileCurrent fileAsksSaves modified open project inputs
Cancel a buildYes (Abort)YesYes (TeX-kill-job)Yes, whole process group
Clean auxiliary filesYes (Trash Aux Files)YesYes (TeX-clean)Clean (keeps PDF) / Clean All Build Output
Custom build logicEngine shell scriptsPython buildersEmacs LispA project latexmkrc (bbtex keeps the output folder and engine); profiles cover engine and options

Project settings ​

FeatureTeXShopLaTeXToolsAUCTeXbbtex
Main file for included files% !TEX root% !TEX root, project fileTeX-master%!TEX root, root = in .bbtex, or the one document nearby that includes the file
Project settings fileNo.sublime-project.dir-locals.el.bbtex (root, engine, output, options, profiles)
Guided setupNoNoAsks for master on first buildConfigure Document… writes root/program comments
Global user configPreferencesJSON settingsEmacs LispNo
Setup diagnosticsNoSystem check commandNoLaTeX — Doctor

Errors and logs ​

FeatureTeXShopLaTeXToolsAUCTeXbbtex
Error listConsole outputOutput panelC-c ` BBEdit results browser
Jump to the source lineUnknownYesYesYes, click the entry
Warnings and bad boxesIn the logYes (toggle)Yes (toggle)Show Build Results, no rebuild
Full logYesYesYesOpen Build Log
79-column line unwrappingUnknownPartialYesYes

PDF viewing and SyncTeX ​

FeatureTeXShopLaTeXToolsAUCTeXbbtex
ViewerBuilt-in (external optional)Skim, Preview, othersAny configuredSkim
Forward searchYesYesYes (TeX-source-correlate-mode)Yes; updates Skim without taking focus
Inverse searchYes (⌘-click)YesYes (Emacs server)Yes (⌘-click), after Skim's sync setting
FeatureTeXShopLaTeXToolsAUCTeXbbtex
Section listTags menu (current file)Yes (project-wide)RefTeX C-c =Project Outline Window, project-wide, refreshes on save
Search labels, equations, captionsUnknownSections and labelsRefTeX TOC and labelsYes, across included files, with kind: filters
Go to label definitionNoYesRefTeXTexLab Go to Definition
Jump to an \input fileUnknownYesPartialNo dedicated command
Stale-target protectionNoNoNoJumps refuse changed or unsaved targets

Citations and references ​

FeatureTeXShopLaTeXToolsAUCTeXbbtex
Citation completionUnknown (BibDesk integration)YesRefTeX C-c [TexLab completion
Citation search pickerUnknownQuick panelRefTeX regexp searchInsert Citation: key, author, title, year; multiple keys
Accent- and case-insensitive searchUnknownUnknownPartialYes
Reference picker with contextUnknownQuick panelRefTeX label menuInsert Reference: label plus nearby text
Duplicate-key handlingUnknownUnknownWarnsRefuses ambiguous keys

Editing ​

FeatureTeXShopLaTeXToolsAUCTeXbbtex
Insert environmentMacros, command completionSnippetsC-c C-eClippings
Change environmentNoYesC-u C-c C-eChange Environment, one undo, nested-aware
Toggle starred environmentNoYesPartialToggle Starred Environment
Wrap selectionMacrosYesC-c C-e on regionWrap in Environment; clippings
Command completionYes (Esc, completion list)CWL filesStyle filesTexLab and BBEdit clippings
Symbol palettesYes (LaTeX and Matrix panels)NoMath menuNo
FoldingUnknownNoTeX-fold-modeNo
Package documentationYes (texdoc)Yes (texdoc)Yes (texdoc)Package Documentation (texdoc)

Previews ​

FeatureTeXShopLaTeXToolsAUCTeXbbtex
Equation previewUnknownInline phantomsInline images (preview-latex)Separate reusable BBEdit window
Uses the document preambleUnknownConfigurableYesYes, the main file's saved preamble
Follows the cursor or selectionNoYes (phantoms update)On demandRefresh on save or live selection (both opt-in)
Refresh when a macro file changesNoNoNoYes, for recorded inputs
Image preview on hoverNoYesNoNo

Where bbtex is ahead ​

  1. Your editor stays BBEdit. TeXShop is a good LaTeX editor, but if you already live in BBEdit, bbtex brings builds, SyncTeX and previews to it instead of asking you to switch.
  2. Project safety. Builds save the project's inputs, run one at a time per project, and cancel whole process groups. Outline jumps and picker insertions refuse stale targets instead of landing on the wrong line.
  3. Project-wide tools. The outline, pickers and previews follow \input and \include across the whole project.
  4. Tested against real engines. Builds and log parsing run against pdfLaTeX, XeLaTeX, LuaLaTeX and Tectonic corpora with BibTeX and Biber.
  5. Standalone CLI and Doctor. Every feature is a bbtex subcommand, and Doctor checks the setup.

Where bbtex is behind ​

  1. Magic comments. Only root and program are read. TeXShop's spellcheck, parameter and % !BIB, and LaTeXTools' options, output_directory and jobname, are ignored.
  2. No built-in viewer. TeXShop has its own PDF window; bbtex needs Skim.
  3. Inline previews. BBEdit has no API for images in the text view, so previews live in a separate window.
  4. As-you-type help. Completion depends on TexLab and an explicit Complete command; there are no symbol palettes, math-mode snippets or folding.
  5. Extensibility. TeXShop engine scripts, LaTeXTools builders and AUCTeX's Emacs Lisp let you script your own builds; bbtex has profiles and options.
  6. Unsaved buffers. The outline, pickers and previews read saved files.

Candidate follow-ups ​

  • Read more of the magic comments TeXShop and LaTeXTools users already have (options and output_directory are the likely ones), mapping them onto the existing .bbtex settings.
  • A command to open the file under an \input/\include at the cursor.
  • Unsaved-buffer snapshots for preview dependencies and the outline.

Deliberately out of scope: builder plugin APIs, running TeXShop engine scripts, viewers other than Skim, and reimplementing completion that TexLab already provides.

MIT licensed. Vibe coded with Claude Code. Part of LouLouLibs.