Dokumentenoptimierung - Quelltexte in Dokumenten und auf Web-Seiten

Quelltexte, die Sie lesen und kopieren können …

Zu oft gibt es Quelltexte (oder Ausschnitte davon) in (elektronischen) Dokumenten und auf Web-Seiten nur als Screenshot. Dazu oft noch im Dark-Mode, so dass auch ein Ausdruck vollkommen aussichtslos ist.

Das geht auch besser

In Dokumenten

Screenshots

Häufig werden hier leider Screenshots von Quelltexten verwendet.
Passen diese dann nicht in der Größe, wird das Bild einfach kleiner gemacht und schon können Sie was lesen?

Wenn dann noch JPEG als Grafikformat zum Einsatz kommt, ist es häufig mit der Lesbarkeit ganz vorbei:

Die Variante im PNG-Format ist noch wesentlich besser zu lesen. Beide Grafiken haben ca. die gleiche Dateigröße.

Wenn sich Screenshots wirklich nicht vermeiden lassen …

Quelltexte als Text

1. Copy-and-paste

Kein Problem: Copy-and-Paste – fertig, oder?

Ergebnis als PDF:

Das ist sicher nicht ganz das Erwünschte.

2. Copy-and-paste und als HTML formatiert

Das funktioniert bei allen Editoren (IDEs) etwas anders.
Die Funktionen nennt sich meist in der Art Als HTML kopieren

Schon etwas besser. Wir haben hier allerdings nur einzelne Textzeilen, die nicht zusammengehören.

3. Das Ganze in ein Textfeld einfügen

Schon können wir den ganzen Code-Block an einem Stück verschieben.

4. Noch etwas verschönern

Das Textfeld noch z. B. mit einem Rand, Hintergrund und Abstand versehen.
Die Schrift etwas verkleinern und eine Nichtproportionale Schriftart (Monospace) auswählen.

Besonderheiten bei verschiedenen Textverarbeitungen

LibreOffice

Während MS-Office und Softmaker-Office fast alle Formatierungsmöglichkeiten zentral über einen Dialog anbieten, ist bei LibreOffice / OpenOffice der oben beschriebene Vorgang auf mehrere Stellen verteilt.

Vorgehensweise um bei LibreOffice / OpenOffice ein Textfeld zu formatieren

Eingefügtes Textfeld.
Formatierung des Textes über das Kontextmenü Text, um einen Abstand zum Rand einzustellen.
Formatierung der Fläche über das Kontextmenü Fläche.
Formatierung der Linien über das Kontextmenü Linie.

Softwarepaket zur Vereinfachung der Benutzung des Textsatzprogramms TeX mit Hilfe von Makros. aus Wikipedia

Das Ganze sieht vielleicht kompliziert aus, ist aber in den Gestaltungsmöglichkeiten von keiner normalen Textverarbeitung zu überbieten.
Und mit ein bisschen Übung verwenden Sie Textverarbeitungen nur noch für One-Pager …

LaTeX-Quelle

Eine schöne Möglichkeit mit den Paketen tcolorbox und minted.

\documentclass{article}
\usepackage[dvipsnames]{xcolor}
\usepackage[a4paper,margin=2cm]{geometry}
\renewcommand\familydefault{\sfdefault}

\usepackage{tcolorbox}
\tcbuselibrary{all} % an dieser Stelle wird auch minted fuer die Quellcode-Formatierung geladen

% Formatierung der "Code-Box"
\tcbset{enhanced,
	fuzzy shadow={2mm}{-2mm}{0mm}{1mm} {gray},
	listing only,
	listing engine=minted % minted fuer die Quellcode-Formatierung
}

\begin{document}

% Ueberschriften usw. ----------------------------------------------------------
\part*{Dokumentenoptimierung}
\vskip -5mm%
\textcolor{LimeGreen}{\rule{\textwidth}{0.07cm}}
\vskip 10mm%

\section{Quellcode in LaTeX}

% Ausgabe des Quellcodes -------------------------------------------------------
\begin{tcblisting}{
		title=Beispiel mit den Paketen \textbf{tcolorbox} und \textbf{minted},
		minted language=js,
		minted options={breaklines,
			breakanywhere}
}
function lastModified(uri) {
	return new Promise((resolve, reject) => {
		$.ajax({
			url: uri,
			type: "HEAD"
		}).done((d, s, xhr) => {
			let date = Date.parse(xhr.getResponseHeader("Last-Modified"))
			resolve(date)
		}).fail((xhr, s, err) => {
			reject(s)
		})
	})
}
\end{tcblisting}

\end{document}

Ergebnis als PDF

tcolorbox: Mehr Beispiele …

One-Note und ähnliche Programme …

… sind für eine saubere Dokumentation ungeeignet.

Hier können Sie zwar den HTML-Text einfügen. Mangels Textfeldern, oder anderen Funktionen für ein richtiges Layout, bleiben diese im Fließtext stehen.

Auf Webseiten

Als Grafik

Nein – hier gibt es die gleichen Probleme wie bei Dokumenten.
Meist noch schlimmer: verringern Sie einfach mal die Breite dieses Fensters.

Oder unlesbar als JPEG-Grafik.
Eine ca. gleich große Datei wie oben, dafür in wesentlich schlechterer Qualität:

Viel Spaß beim Abtippen!

Direkt als Quelltext

z. B. mit PrismJS für das Syntax-Highlighting. Damit ist alles schön lesbar und kopierbar.

function lastModified(uri) {
    return new Promise((resolve, reject) => {
        $.ajax({
            url: uri,
            type: "HEAD"
        }).done((d, s, xhr) => {
            let date = Date.parse(xhr.getResponseHeader("Last-Modified"))
            resolve(date)
        }).fail((xhr, s, err) => {
            reject(s)
        })
    })
}

Der Stil ist austauschbar (Beispiel-Theme: Coy).

Zusammenfassung

Checkliste

• Quelltexte immer als echten Text einfügen.
• Für Quelltexte immer eine nichtproportionale Schriftart (Monospace) wählen.
• In Dokumenten Text-Boxen (Text-Felder) verwenden.
• In Dokumenten keinen Dark-Mode verwenden (Druck).
• Auf Web-Seiten immer Funktionen für des Syntax-Highlighting verwenden.

Mehr zum Thema

Software

• PrismJS
• PrismJS Themes
• LibreOffice
• SoftMaker Office
• TeXstudio
• LaTeX-Paket: tcolorbox
• LaTeX-Paket: minted
• LaTeX-Paket minted: Styles und Languages siehe: Pygments
• The LaTeX Project
• TeX Live

Weiterführende Informationen

• PDF-Optimierung

Begriffserklärungen

• Syntaxhervorhebung (Syntax highlighting)
• Nichtproportionale Schriftart (Monospace)
• PDF
• JPG / JPEG
• PNG
• LaTeX

Downloads

---

Titelbild von Elchinator from Pixabay

---