CommonMark\Render\Man — Funktion · PHP-Referenz

Signatur

CommonMark\Render\Man(CommonMark\Node $node, int $options = 0, int $width = 0): string

Beschreibung

CommonMark\Render\Man ist eine Funktion aus der PHP-Erweiterung CommonMark (pecl/commonmark) und wandelt einen geparsten CommonMark-Dokumentbaum in das Man-Page-Format (troff/groff) um. Man-Pages sind das traditionelle Unix-Dokumentationsformat und werden mit dem Befehl man angezeigt.

Diese Funktion ist sinnvoll, wenn PHP-Anwendungen Dokumentationen, Handbücher oder Hilfeseiten direkt aus Markdown-Quellen als Unix-Man-Pages erzeugen sollen, ohne externe Werkzeuge wie pandoc zu benötigen. Der Eingabeknoten sollte typischerweise durch CommonMark\Parse erzeugt worden sein.

Über den Parameter options lassen sich Render-Optionen als Bitmask übergeben (z. B. CommonMark\Option\HARDBREAKS). Der Parameter width steuert die Textbreite für den Umbruch; der Wert 0 deaktiviert den automatischen Zeilenumbruch.

Erfordert die PECL-Erweiterung commonmark (>= 1.0.0).
Das Ausgabeformat ist direkt kompatibel mit man, nroff und groff.

Parameter

Name	Typ	Default	Beschreibung
$node Pflicht	CommonMark\Node		Der Wurzelknoten des geparsten CommonMark-Dokumentbaums, üblicherweise ein Rückgabewert von `CommonMark\Parse()`.
$options	int	0	Optionale Bitmask aus `CommonMark\Option\*`-Konstanten, die das Render-Verhalten steuern, z. B. `CommonMark\Option\HARDBREAKS` für harte Zeilenumbrüche.
$width	int	0	Maximale Zeilenbreite für den automatischen Textumbruch. Der Wert `0` deaktiviert den Umbruch vollständig.

Rückgabewert

Typ

string

Beschreibung

Gibt den gerenderten Dokumentinhalt als troff/groff-formatierte Zeichenkette zurück, die direkt als Man-Page verwendet werden kann.

Beispiele

Einfaches Markdown-Dokument als Man-Page rendern

<?php
// Markdown-Quelle
$markdown = "# meinprogramm(1)\n\n## BESCHREIBUNG\n\nDies ist eine **Beispiel**-Man-Page, erzeugt aus Markdown.\n\n## OPTIONEN\n\n- `-h` — Hilfe anzeigen\n- `-v` — Version ausgeben\n";

// Parsen des Markdown-Textes in einen Dokumentbaum
$document = CommonMark\Parse($markdown);

// Rendern als Man-Page
$manPage = CommonMark\Render\Man($document);

echo $manPage;

.SH meinprogramm(1) .SS BESCHREIBUNG ...

Man-Page mit Zeilenbreite und Optionen erzeugen

<?php
$markdown = "# beispiel(1)\n\n## SYNOPSIS\n\n`beispiel [OPTIONEN] DATEI`\n\n## BESCHREIBUNG\n\nEin längerer Beschreibungstext, der bei Bedarf umgebrochen werden soll.\n";

$document = CommonMark\Parse($markdown);

// Rendern mit Zeilenbreite 80 und aktivierten Hard-Breaks
$manPage = CommonMark\Render\Man(
    $document,
    CommonMark\Option\HARDBREAKS,
    80
);

// Ausgabe in eine Datei schreiben
file_put_contents('/usr/share/man/man1/beispiel.1', $manPage);
echo "Man-Page erfolgreich gespeichert.\n";

Man-Page erfolgreich gespeichert.

// Wichtig · Fallstricke

Hinweis zur Erweiterung: CommonMark\Render\Man ist Teil der PECL-Erweiterung commonmark, die separat installiert werden muss (pecl install commonmark). Sie ist nicht im PHP-Kern enthalten.

Das Ausgabeformat entspricht dem klassischen troff/groff-Format. Für eine korrekte Darstellung mit man muss die erzeugte Datei im richtigen Verzeichnis (/usr/share/man/man1/ etc.) abgelegt und mit mandb indiziert werden.

Ungültige oder null-Knoten als Eingabe führen zu einem Error. Stelle sicher, dass CommonMark\Parse() einen gültigen Knoten zurückgegeben hat, bevor du ihn an diese Funktion übergibst.

Siehe auch

CommonMark\Parse CommonMark\Render\Html CommonMark\Render\Latex CommonMark\Render\Xml