---
title: "Famulus Notebook"
subtitle: "A teaching book: writing, running, checking, annotating, sharing and publishing scholarly notebooks"
running-title: "Famulus Notebook"
author:
  - name: Gerd Graßhoff
    email: gerd.grasshoff@hu-berlin.de
    orcid: 0000-0002-4450-357X
    affiliations:
      - name: Humboldt-Universität zu Berlin
        department: Philosophisches Institut
        address: Unter den Linden 6
        city: Berlin
        country: Germany
        postal-code: 10099
      - name: Deutsches Museum
        department: Forschungsinstitut
        address: Museumsinsel 1
        city: München
        country: Germany
        postal-code: 80538
date: "2026-10-20"
lang: en
engine: markdown
bibliography: bibliography.bib
book: false
number-sections: true
toc: true
toc-depth: 2
filters:
  - filters/lehrbuch.lua
format:
  html:
    theme:
      - sandstone
      - _extensions/lettreai/lettreai.scss
      - _extensions/lettreai/lettreai-paper.scss
      - _extensions/lettreai/_identity.scss
      - lehrbuch.scss
    toc: true
    toc-location: left
    toc-depth: 2
  arxivai-typst:
    keep-typ: false
    include-in-header:
      - file: lehrbuch-header.typ
abstract: |
  Famulus Notebook is a document form for scholarly questions put to a
  research system. A notebook is ordinary text with executable *blocks*. A
  block states its scope and its plan in a short preamble and asks its
  question in ordinary language; running it leaves a result, the declared
  artefacts, and a *verdict* that compares the result with an expectation
  determined independently of the run. Notebooks live in *projects*; every
  artefact has a *reference name*, a version and a checksum, so that one
  block can build on another, in the same project, in another project, or on
  another machine, and a project can be brought up to date by re-running
  exactly what has become stale. This book teaches the whole cycle in the
  manner of a language manual: a first notebook in the first chapter, one
  extension per chapter after that, and a complete reference manual at the
  end. The reader learns to write and run blocks, to read and check their
  results, to name and version artefacts, to annotate and revise the text
  with a Lektor, to work with coauthors and commentators across machines, and
  to publish a notebook with its generated artefacts as HTML and PDF. Beside
  questions answered by a chain of steps or by the query pipeline, a block
  may ask for an answer with its grounds: a request whose answer is the
  conclusion of a recorded argument, the enfolding of a goal, or the check
  of a single claim, each judged relative to a named version of the
  evidence. Sources are cited by `fr:` addresses that the formulation guard
  resolves. Every
  example is a block of a companion project that was run for this book; its
  source and its result are printed side by side, and its reference name
  lets the reader open the same block in the viewer. A casebook of six
  research projects (Pirckheimer, Schöner, Kepler twice, Kármán, and an
  LWgrammar check of a damaged paper) shows the notebook at work, including
  the disagreements it made visible. Boxes marked "For famuli" state the
  exact grammar and the machine consequence of each rule for the second
  audience of the book: the software agents that read and write notebooks
  themselves. Appendices give the reference manual, the command line, the
  HTTP interface, the setup of a second machine, a measured baseline of the
  query pipeline, the collected rules for famuli, and solutions to all
  exercises.
keywords:
  - Famulus
  - notebook
  - literate computing
  - reproducible research
  - oracle
  - versioned artefacts
  - annotation
  - scholarly publishing
  - digital humanities
  - PDAI
  - justification
---

{{< include chapters/00-preface.qmd >}}

# Part I · Getting started {.part}

{{< include chapters/01-first-notebook.qmd >}}

{{< include chapters/02-block.qmd >}}

{{< include chapters/03-display.qmd >}}

{{< include chapters/04-checking.qmd >}}

# Part II · Carrying on {.part}

{{< include chapters/05-projects.qmd >}}

{{< include chapters/06-references.qmd >}}

{{< include chapters/07-versions.qmd >}}

{{< include chapters/08-scope.qmd >}}

# Part III · Working with others {.part}

{{< include chapters/09-annotating.qmd >}}

{{< include chapters/10-refining.qmd >}}

{{< include chapters/11-coauthors.qmd >}}

# Part IV · Publishing {.part}

{{< include chapters/12-publishing.qmd >}}

{{< include chapters/13-casebook.qmd >}}

# Part V · Beneath the surface {.part}

{{< include chapters/14-execution.qmd >}}

{{< include chapters/15-errors.qmd >}}

{{< include chapters/16-design.qmd >}}

# Appendices {.part .appendices}

{{< include chapters/a-reference.qmd >}}

{{< include chapters/b-cli.qmd >}}

{{< include chapters/c-http.qmd >}}

{{< include chapters/d-two-machines.qmd >}}

{{< include chapters/e-baseline.qmd >}}

{{< include chapters/f-famuli.qmd >}}

{{< include chapters/g-solutions.qmd >}}

::: {.content-visible when-format="html"}
# References {.unnumbered}

::: {#refs}
:::
:::

# Index {.unnumbered}

::: {#book-index}
:::