\section{\ldeen{Serien}{Series}}
\label{sec:series}

\ldeen{Eine Serie ist mehr als eine Menge von Verzeichnissen. Ihre Einheiten
können voneinander abhängen: Kapitelnummern sollen fortlaufen, ein Querverweis
benötigt ein Ziel aus einer anderen Unit, und ein Gesamtdokument benötigt die
gebauten Einzelkapitel. \OLLM\ speichert dafür den Zustand erfolgreicher Builds und kann
veraltete Produzenten mit \option{--resolve} neu bauen. Ohne diesen
Serienzustand könnte ein lokaler \LaTeX-Lauf nur die aktuelle Quelldatei sehen.}{A
series is more than a set of directories. Its units may depend on one another:
chapter numbers should continue, a cross-reference needs a target from another
unit, and a combined document needs the built individual chapters. \OLLM\ keeps
the state of successful builds for these purposes and can rebuild stale producers with
\option{--resolve}. Without this series state, a local \LaTeX\ run could only
see the current source file.}

\subsection{\ldeen{Zähler fortsetzen}{Continuing Counters}}

\ldeen{Jede Unit wird als eigenständiges Dokument gebaut. Das löst das Problem
getrennter Ausgabe und inkrementeller Builds, führt aber zunächst zu einem
neuen Problem: \LaTeX\ würde Kapitel, Abschnitte und Seiten in jeder Unit wieder
bei eins beginnen lassen. Für ein später integriertes Skript wären dann etwa
mehrere Kapitel~1 vorhanden. Die Fortsetzungsfunktion importiert deshalb
ausgewählte Endstände der vorherigen, für den Dokumenttyp passenden Unit.}{Each
unit is built as an independent document. This enables separate distribution
and incremental builds, but initially creates another problem: \LaTeX\ would
restart chapters, sections, and pages at one in every unit. A subsequently
integrated set of notes would then contain several Chapter~1s. Counter
continuation therefore imports selected final values from the preceding unit
applicable to the document type.}

\ldeen{Welche Zähler fortlaufen, ist eine Darstellungsentscheidung. Folien
benötigen meist keine durchgehenden Seitenzahlen; ein Skript dagegen häufig
schon. Die Einstellung gehört deshalb zum Modus \code{longform} in
\File{Include/projectconfig.tex}}{Which counters should continue is a rendering
decision. Slides usually do not need page numbers that run across units,
whereas lecture notes often do. The setting therefore belongs to the
\code{longform} mode in \File{Include/projectconfig.tex}}:

\begin{verbatim}
\OsgLectureSetup{
  mode/longform={
    continuation={counters={page,chapter,section}}
  }
}
\end{verbatim}

\ldeen{Angenommen, \code{010-introduction} endet mit Abschnitt~2. Dann beginnt
der erste \cs{section}-Aufruf in \code{020-processes} mit Abschnitt~3. Ein
nicht genannter Zähler wie \code{figure} beginnt weiterhin neu. Diese explizite
Auswahl ist wichtig: Lokale Zähler sollen nicht versehentlich eine Bedeutung
über Unit-Grenzen erhalten. Soll eine Langform überhaupt nichts fortsetzen,
kann \code{continuation={none}} verwendet werden.}{Suppose
\code{010-introduction} ends with Section~2. The first \cs{section} call in
\code{020-processes} then produces Section~3. A counter not listed, such as
\code{figure}, still restarts. This explicit selection matters: local counters
should not accidentally acquire meaning across unit boundaries. To disable
continuation entirely for a long form, use \code{continuation={none}}.}

\ldeen{Die vorherige Instanz muss mindestens einmal erfolgreich gebaut worden
sein, damit ihr Zählerstand vorliegt. Nach dem Einfügen eines neuen Abschnitts
in eine frühe Unit aktualisiert folgender Lauf die abhängigen deutschen
Skriptinstanzen}{The preceding instance must have been built successfully at
least once so that its counter state is available. After inserting a new
section in an early unit, the following command updates the dependent German
script instances}:

\begin{verbatim}
ollm build script --language=de --scope=series --resolve
\end{verbatim}

\subsection{Integration}
\ldeen{Die Dokumente der Lehreinheiten einer Serie können einzeln verwendet werden.
Dies ist in der Regel bei Präsentationen sinnvoll.
Sie können jedoch auch zu einem gesamten Dokument integriert werden.
So könnte jede Lehreinheit ein Kapitel eines Skripts bilden, die dann zu einem Gesamtskript
integriert werden. Es kann aber z.\,B. auch eine Handoutsammlung angelegt
werden.
}{The documents produced for the course units in a series can be used
individually, as is usually appropriate for presentations. They can also be
integrated into a single document. Each course unit might, for example, form a
chapter that is integrated into a complete set of lecture notes; a collection
of handouts can be assembled in the same way.}
\ldeen{Ein Gesamtskript entsteht in \osglecture\ in der Regel nicht durch
\cs{include} der TeX-Quellen, sondern durch Zusammenfügen bereits
übersetzter Dokumente.}{In \osglecture, a complete set of lecture notes is
normally not created by applying \cs{include} to the TeX sources, but by
combining documents that have already been compiled.}
\ldeen{Dafür muss es eine eigene Integrationseinheit
mit einem Rahmendokument geben.
Diese Einheit ist durch den Buchstaben "`i"' beim Rollenelement gekennzeichnet.
Die laufende Nummer des Verzeichnisses ist unerheblich, weil sie bei der Zählung
nicht berücksichtigt wird. Es empfiehlt sich aber, hierfür entweder die kleinste
oder die größte Nummer zu wählen, so dass die zu integrierenden Einheiten
aufeinander folgen können.
}{This requires a separate integration unit containing a wrapper document. Its
role element is marked with the letter "`i"'. The directory's sequence number
does not affect numbering. It is nevertheless advisable to use either the
smallest or the largest number so that all units to be integrated can remain
adjacent.}

\begin{verbatim}
course/
  ollmconfig.toml
  Include/
    projectconfig.tex
    documentmetadata.tex
  010-introduction/main.tex
  020-processes/main.tex
  900-i-collection/main.tex
\end{verbatim}

\ldeen{Der normale Workflow der Integration ist inkrementell:
Zunächst bauen Sie beim Schreiben die zu integrierenden Dokumente und erst zuletzt
das Rahmendokument.
Es empfiehlt sich, vor dem Bau des Rahmendokuments mit \code{ollm check} zu überprüfen,
ob alle zu integrierenden Dokumente erstellt und alle Referenzen aufgelöst sind.
Falls nicht, müssen Sie ggf.\ weitere Übersetzungsläufe anstoßen.
Auch hier kann Sie \code{ollm} unterstützen:
Mit Hilfe der Option \option{--resolve} werden Abhängigkeiten bis zu einer
vorgegebenen Tiefe erkannt und ausgelöst.}{The normal integration workflow is
incremental: while writing, first build the documents to be integrated and
build the wrapper document last. Before building the wrapper, use
\code{ollm check} to verify that all documents to be integrated have been
created and all references have been resolved. Further compilation runs may be
necessary. OLLM can help here as well: the \option{--resolve} option discovers
and triggers dependencies up to a specified depth.}

\begin{verbatim}
cd 020-processes
ollm script --language=de
ollm script --language=de --scope=series --resolve
ollm script --language=de --scope=collection --resolve
ollm check --scope=series
\end{verbatim}

\subsection{\ldeen{Rahmendokumentunit}{Wrapper Document}}
\ldeen{ Die Klasse erkennt diese Rolle am Verzeichnisnamen und lädt den
Integrationsdienst automatisch. Das Dokument nennt die einzubindenden
logischen Units in der gewünschten Reihenfolge}{A complete script is not
created by applying \cs{include} to the TeX sources. Instead, the
wrapper document is a separate unit with role \code{i}. The class recognizes
this role from the directory name and loads the integration service
automatically. The document names the logical units to include in the desired
order}:

\begin{verbatim}
\documentclass{osglecture}

\begin{document}
\includeunit{introduction}
\includeunit{processes}
\includeunit{synchronization}
\end{document}
\end{verbatim}

\ldeen{\cs{includeunit} wählt automatisch dieselbe Sprache und
denselben Dokumenttyp wie das Rahmendokument. Es importiert also bei einem
deutschen Skript genau die deutschen Skriptinstanzen. OLLM baut die
Collection mit \keyis*{--scope}{collection}; existieren keine oder mehrere
passende Integrationsunits für den Dokumenttyp, ist die Auswahl nicht
eindeutig und der Build schlägt fehl.}{\cs{includeunit}
automatically selects the same language and document type as the wrapper. Thus
a German script imports exactly the German script instances. OLLM builds the
collection with \keyis*{--scope}{collection}; if there is no matching
integration unit for the document type, or more than one, the selection is
ambiguous and the build fails.}

\ldeen{Jede einzubindende Dokumentinstanz muss zuvor mindestens einmal gebaut sein.
Der Integrationslauf protokolliert den tatsächlich verwendeten Buildstand als
Abhängigkeit. Nach Änderungen genügt deshalb normalerweise ein erneuter Lauf
mit \option{--resolve}. Die Reihenfolge der
\cs{includeunit}-Befehle ist die Reihenfolge im Ergebnis; sie wird
nicht aus den Verzeichnisnummern erraten.}{Every document instance to be included must
have been built at least once. The integration run records the build
actually used as a dependency. After changes, another run with
\option{--resolve} is therefore normally sufficient. The order of the
\cs{includeunit} commands is the order in the result; it is not
inferred from directory numbers.}

\subsection{\ldeen{Tags, Links und Fallback}{Tags, Links, and Fallback}}

\ldeen{Sind Rahmendokument und importierte Units als Tagged PDF gebaut,
übernimmt \pkg{tagpax} Seiten, Strukturbaum, Ziele, Links,
Inhaltsverzeichniseinträge und Lesezeichen. Dadurch bleiben
Barrierefreiheitsstruktur und Navigation über Unit-Grenzen erhalten. Dafür
muss das Target \cs{DocumentMetadata} erlauben beziehungsweise verlangen,
und \File{documentmetadata.tex} muss Tagging aktivieren.}{If the wrapper and
imported units are built as Tagged PDF, \pkg{tagpax} carries across pages,
the structure tree, destinations, links, table-of-contents entries, and
bookmarks. This preserves accessibility structure and navigation across unit
boundaries. The target must permit or require \cs{DocumentMetadata}, and
\File{documentmetadata.tex} must enable tagging.}

\begin{verbatim}
\DocumentMetadata{
  lang=\OsgLectureRequestedLanguage,
  tagging=on
}
\end{verbatim}

\ldeen{Für ungetaggte Dokumentinstanzen verwendet die Integration einen Fallback
über \pkg{pdfpages} und \pkg{newpax}. Links und Gliederung bleiben dabei
weitgehend funktionsfähig, die importierten Seiten werden jedoch als Artefakt
eingebunden und besitzen keine erschlossene Lesereihenfolge oder
Überschriftenstruktur. Gemischte getaggte und ungetaggte Units zwingen für den
betroffenen Dokumenttyp den ungetaggten Pfad und erzeugen eine deutliche
Warnung. Eine vollständig getaggte Serie ist daher nicht nur qualitativ besser,
sondern auch vorhersehbarer.}{For untagged document instances, integration uses a
fallback based on \pkg{pdfpages} and \pkg{newpax}. Links and document
navigation largely remain functional, but imported pages are included as an
artifact and have no accessible reading order or heading structure. Mixing
tagged and untagged units forces the untagged path for the affected document
type and produces a prominent warning. A consistently tagged series is
therefore both higher quality and more predictable.}

\subsection{\ldeen{Referenzübersicht}{Reference Summary}}
\begin{commands}
  \command{includeunit}[\marg{unit ID}]
    \ldeen{bindet in einer
    Integrationseinheit die bereits gebaute Instanz derselben Sprache und
    desselben Dokumenttyps ein; die Aufrufreihenfolge bestimmt die
    Dokumentreihenfolge}{includes, in an integration unit, the already built
    instance with the same language and document type; call order determines
    document order}.
\end{commands}

\ldeen{Integration ist nur in einer Serie mit genau einer passenden Unit der
Rolle \code{i} pro Dokumenttyp verfügbar. Sie setzt erfolgreich gebaute
Quelldokumente voraus. Serienübergreifende Referenzen, Counter-Fortsetzung und
Integration werden über OLLMs Zustands- und Abhängigkeitsmodell aufgelöst;
lokale LaTeX-Läufe ohne diesen Zustand können sie nicht rekonstruieren.}{
Integration is available only in a series with exactly one matching unit of
role \code{i} per document type. It requires successfully built source documents.
Cross-unit references, counter continuation, and integration are resolved
through OLLM's state and dependency model; local LaTeX runs without that state
cannot reconstruct them.}