The Scribe Manual

Getting started

Open a folder as a project with Open Project (⌘O), start one from a template with New Project, or bring one in with Import from Overleaf or Git, which takes Overleaf's zip download or a git link. The paper is the .tex file with \documentclass in it, usually main.tex.

Press ⌘↵ to compile; the PDF appears on the right. If no LaTeX is installed, Scribe offers to install Tectonic, about 20 MB, which fetches the packages a paper needs the first time it compiles. With TeX Live installed, Scribe uses latexmk.

Double-click the PDF to jump to the line that made it, or press ⇧⌘J to go the other way. Select text in the PDF and press Show in source to find it in the LaTeX. Every command is in the menus, and in the command palette, ⇧⌘P.

Notebooks and the paper

A notebook is a Python file whose cells are separated by # %% lines, or a Jupyter .ipynb. A cell marked # %% [markdown] is text, written as comment lines. A cell marked # %% [figure: loss] makes a figure: whatever it plots is saved as figures/loss.pdf.

In the LaTeX, load \usepackage{scribe-figures}, which Scribe writes for you, and bring the figure in with \nbfig{loss}. A figure cell's Insert into paper button writes the whole figure environment. Run a cell with ⇧↵ and every notebook with ⇧⌘↵; a compile runs first the notebooks that changed since they last ran.

# %% [figure: loss]
fig, ax = plt.subplots()
ax.plot(epochs, loss)

# %%
nbval("acc", 0.960, err=0.003, unit=r"\percent")   # \nbval{acc}    96.0 ± 0.3 %
nbval("n", 400)                                    # \nbval{n}      400
nbtable("results", rows, header=["Optimiser", "Loss"])   # \nbtable{results}
nbmath("model", sympy_expression)                        # $\nbmath{model}$

nbval(name, value, unit=, err=, sig=, raw=)

A number or text, read with \nbval{name}. With a unit, an uncertainty or a number of significant figures it is typeset by siunitx, so load \usepackage{siunitx}; the uncertainty is rounded to one significant figure (two if it starts with 1) and the value to the same place. raw=True writes LaTeX as it is.

nbtable(name, rows, header=)

A tabular, read with \nbtable{name}. Rows are lists, or a pandas DataFrame; a cell given as (value, uncertainty) is written value ± uncertainty, and columns of numbers are right-aligned.

nbmath(name, expr)

A formula, used inside maths as \nbmath{name}. SymPy expressions are converted; a string is taken to be LaTeX already.

\nbenv

How the notebooks last ran: Python and package versions, the seed, the git commit and the date. Useful in an appendix on reproducibility.

A value no notebook has exported prints as ?? in the PDF, and Check Before Submitting lists it.

Writing LaTeX

Completion knows your labels, citations, figures and notebook values. Errors come with a line in plain words and an underline at their place; turn on Compile on Save or Compile as You Type in the Build menu or in Settings.

Tables.

With the cursor in a tabular, Edit → Edit Table opens it as a grid; elsewhere it inserts a new table. Paste a block from a spreadsheet into any cell.

Check Before Submitting.

In the Build menu: citations without an entry, references to missing labels, figures the text never mentions, missing images, stale notebook results, TODOs left in, and what arXiv would reject.

Export for Submission.

In the File menu: one zip of plain LaTeX a journal can compile, with every \input inlined and every notebook value written in.

History.

The clock in the sidebar lists earlier versions of the open file, kept at every save. Click one to see what changed since; Restore brings it back, and ⌘Z undoes that.

Git and the terminal.

The git panel commits, pushes and shows diffs; View → Toggle Terminal opens your own shell in the project folder.

Vim keys.

Turn them on in Settings, for the editor and notebook cells: normal, insert and visual modes, with :w, :q and :wq. Line numbers can be absolute, relative, or off.

Notes

Notes are Markdown files: File → New Note, Today's Note (⌥⌘T) for a dated page, or Quick Note (⌥⌘N) to jot a line into notes/Inbox.md without leaving what you're doing. Maths, headings, checkboxes and images show as they will look; the line you are on shows its Markdown.

Links and tags.

[[Lecture 2]] links to another note, ⌘-click to follow; @kingma2015 is a citation; #exam is a tag. The Notes panel searches the text of every note, filters by tag, and shows which notes link to the open one.

Definitions and theorems.

A line starting Definition, Theorem, Lemma, Proposition, Corollary or Example (bold, or as a heading) is listed in the Notes panel, for revision.

Revision cards.

A line starting Q: with the answer on the next line starting A: is a card. Review asks the ones that are due; Again, Hard, Good and Easy (keys 1 to 4) decide when each comes back. File → Export Cards for Anki writes a file Anki imports.

Pictures, sketches and code.

Paste a screenshot or a photo with ⌘V; draw with Insert Sketch (⌥⌘D), and double-click a sketch to draw on it again. Fenced code is highlighted in its language.

Into LaTeX.

Export Note as PDF typesets the note; Edit → Copy Note as LaTeX copies it, or the selection, ready to paste into a paper.

References and reading

The References panel lists the entries of your .bib files. Add one by its DOI or arXiv number with ⇧⌘C, or from Zotero: with Zotero 7 open and Allow other applications on this computer to communicate with Zotero turned on in its Advanced settings, \cite{ completes from your library and adds the entry it needs.

Each reference can have a PDF, papers/<key>.pdf, and a note, notes/<key>.md. Read the PDF in Scribe, select a sentence and press Highlight: the quote goes into the note under Highlights, with a link that opens the PDF at its page.

Keyboard shortcuts