Falls Sie eine Dokumentation schreiben, die einen Umfang von 30 kB oder mehr hat, sollten Sie sie in kleine Häppchen aufteilen. Diese Dateien können dann mit dem !include an passender Stelle eingeladen werden.
Das Aufteilen bietet den Vorteil, dass Sie die Dokumentation durch einfaches Verschieben nur einer einzigen Zeile neu gliedern können. Wäre der gesamte Quelltext in einer Datei, müssten Sie mit einem Editor gleich ganze Blöcke umkopieren.
Ein weiterer Vorteil des Aufteilens ist, dass Sie bestimmte Kapitel schnell wiederfinden können, sofern Sie den Dateien sinnvolle Namen geben.
Denken Sie auch an mehrsprachige Dokumentationen. Wenn Sie – wie wir es tun – z.B. alle deutschen Texte in Dateien mit dem Suffix .de und alle englischen Texte in .en-Dateien pflegen, behalten Sie noch besseren Überblick über die einzelnen Sprachen und können z.B. aus den .en-Dateien rasch Kopien für z.B. Französisch erstellen, die Datei-Suffixe der Kopien in .fr ändern und dem französischen Übersetzer nur diese Dateien geben.
Außerdem können Sie leicht und schnell nur Teile der Dokumentation auf syntaktische Korrektheit testen. Nehmen wir an, wir haben einen Quelltext mit fünf Kapiteln. Erstellen Sie eine Datei mit den globalen Schaltern, eine Hauptdatei und fünf Dateien mit dem Kapiteltext:
[main.u] !include header.ui !begin_document !maketitle !tableofcontents !include kapitel1.ui !include kapitel2.ui !include kapitel3.ui !include kapitel4.ui !include kapitel5.ui !end_document [header.ui] !docinfo [title] ... !docinfo [program] ... !docinfo [author] ... [kapitel1.ui] !node Kapitel 1 ... [kapitel2.ui] !node Kapitel 2 ... [usw.]
Falls Sie nun einmal nur ein Kapitel umwandeln wollen, erstellen Sie ganz einfach eine zusätzliche Hauptdatei, die Sie dann umwandeln:
[kap5test.u] !include header.ui !begin_document !maketitle !tableofcontents !include kapitel5.ui !end_document
Gerade bei sehr umfangreichen Dokumentationen können Sie so die Fehlersuche und -korrektur drastisch beschleunigen.
Falls Sie sich ein Bild davon machen wollen, wie so eine Aufteilung aussehen kann, dann schauen Sie sich die Quelltexte dieses UDO-Handbuchs an. Stünde diese Dokumentation in einer einzigen, großen Datei, hätten wir schon längst den Überblick verloren.