perlpodstyle – Online in der Cloud

PROGRAMM:

NAME/FUNKTION

perlpodstyle – Perl POD-Styleguide

BESCHREIBUNG

Dies sind allgemeine Richtlinien zum Schreiben der POD-Dokumentation für Perl-Skripte und
Module, basierend auf allgemeinen Richtlinien zum Schreiben guter UNIX-Manpages. Alle von denen
Richtlinien sind natürlich optional, aber wenn Sie sie befolgen, wird Ihre Dokumentation besser
im Einklang mit anderen Dokumentationen zum System stehen.

Der Name des zu dokumentierenden Programms wird üblicherweise fett geschrieben (mit B<>)
wo auch immer es vorkommt, ebenso wie alle Programmoptionen. Argumente sollten kursiv geschrieben werden
(ICH<>). Funktionsnamen werden traditionell kursiv geschrieben; wenn Sie eine Funktion schreiben als
Funktion(), Pod::Man wird das für Sie erledigen. Literaler Code oder Befehle sollten sein
in C<>. Verweise auf andere Manpages sollten in der Form „manpage(section)“ oder vorliegen
„L ", und Pod::Man formatiert diese automatisch entsprechend. Die
Die zweite Form mit L<> wird verwendet, um einen POD-Formatierer aufzufordern, einen Link zur Manpage zu erstellen
wenn möglich. Ausnahmsweise lässt man den Abschnitt normalerweise weg, wenn auf Module Bezug genommen wird
Dokumentation, da nicht klar ist, in welchem ​​Abschnitt die Moduldokumentation enthalten sein wird; verwenden
„L " stattdessen für Modulverweise.

Verweise auf andere Programme oder Funktionen erfolgen normalerweise in Form von Manpage-Referenzen
damit Querverweistools dem Benutzer Links und Ähnliches bereitstellen können. Es ist
Es ist jedoch möglich, dies zu übertreiben. Achten Sie also darauf, Ihre Dokumentation nicht damit zu überladen
viel Aufschlag. Verweise auf andere Programme, die nicht als Manpage-Referenzen angegeben sind
sollte in B<> eingeschlossen werden.

Die Hauptheader sollten mit einer „=head1“-Direktive festgelegt werden und sind historisch
geschrieben im ziemlich verblüffenden Format ALLES IN GROSSBUCHSTABEN; das ist nicht zwingend, aber es ist
Es wird dringend empfohlen, Abschnitte in verschiedenen Softwareprogrammen konsistent zu benennen
Pakete. Kleinere Header können mit „=head2“ eingefügt werden und werden normalerweise in gemischter Groß- und Kleinschreibung verwendet.

Die Standardabschnitte einer Handbuchseite sind:

NAME/FUNKTION
Pflichtteil; sollte eine durch Kommas getrennte Liste von Programmen oder Funktionen sein
dokumentiert durch diese POD-Seite, wie zum Beispiel:

foo, bar – Programme, um etwas zu tun

Manuelle Seitenindexer sind oft äußerst wählerisch, was das Format dieses Abschnitts angeht
Fügen Sie nichts außer dieser Zeile ein. Jedes Programm oder jede Funktion dokumentiert von
Diese POD-Seite sollte aufgelistet werden, getrennt durch ein Komma und ein Leerzeichen. Für ein Perl-Modul:
Geben Sie einfach den Modulnamen ein. Ein einzelner Bindestrich, und nur ein einzelner Bindestrich, sollte die trennen
Liste der Programme oder Funktionen aus der Beschreibung. Verwenden Sie kein Markup wie C<>
oder B<> irgendwo in dieser Zeile. Funktionen sollten nicht mit „()“ oder dem qualifiziert werden
wie. Die Beschreibung sollte idealerweise in eine einzige Zeile passen, auch wenn es sich um ein Man-Programm handelt
ersetzt den Bindestrich durch ein paar Tabulatoren.

ZUSAMMENFASSUNG
Eine kurze Zusammenfassung der Verwendung von Programmen und Funktionen. Dieser Abschnitt ist obligatorisch für
Abschnitt 3 Seiten. Für die Dokumentation von Perl-Modulen ist es normalerweise praktisch, das zu haben
Der Inhalt dieses Abschnitts besteht aus einem wörtlichen Block, der einige (kurze) typische Beispiele zeigt
wie das Modul verwendet wird.

BESCHREIBUNG
Ausführliche Beschreibung und Diskussion des Programms oder der Funktionen oder des Hauptteils
Dokumentation für Manpages, die etwas anderes dokumentieren. Wenn es besonders lang ist, ist es
Es ist eine gute Idee, dies in Unterabschnitte mit „=head2“-Anweisungen zu unterteilen, wie zum Beispiel:

=head2 Normale Verwendung

=head2 Erweiterte Funktionen

=head2 Konfigurationsdateien schreiben

oder was auch immer für Ihre Dokumentation geeignet ist.

Bei einem Modul ist dies im Allgemeinen der Ort, an dem die Dokumentation der bereitgestellten Schnittstellen erfolgt
Das Modul besteht normalerweise aus einer Liste mit einem „=item“ für jede Schnittstelle.
Je nachdem, wie viele Schnittstellen vorhanden sind, möchten Sie diese Dokumentation möglicherweise hinzufügen
separate Abschnitte „METHODS“, „FUNCTIONS“, „CLASS METHODS“ oder „INSTANCE METHODS“ stattdessen und
Speichern Sie den Abschnitt BESCHREIBUNG für eine Übersicht.

OPTIONAL
Detaillierte Beschreibung aller vom Programm genutzten Befehlszeilenoptionen. Das
sollte von der Beschreibung für die Verwendung von Parsern wie Pod::Usage getrennt sein. Das
wird normalerweise als Liste dargestellt, mit jeder Option als separatem „=item“. Das spezifische
Optionszeichenfolge sollte in B<> eingeschlossen werden. Alle Werte, die die Option annimmt, sollten sein
eingeschlossen in I<>. Zum Beispiel der Abschnitt für die Option --Sektion=manext wäre
eingeleitet mit:

=Artikel B<--Abschnitt>=I

Synonymoptionen (sowohl die Kurz- als auch die Langform) werden durch ein Komma und ein getrennt
Leerzeichen in derselben „=item“-Zeile oder optional als eigenes Element mit a aufgeführt
Verweis auf den kanonischen Namen. Zum Beispiel seit --Sektion kann auch geschrieben werden als
-s, das obige wäre:

=Punkt B<-s> I , B<--Abschnitt>=I

Es wird empfohlen, zuerst die kurze Option zu schreiben, da diese einfacher zu lesen ist. Das lange
Die Option ist ohnehin lang genug, um die Aufmerksamkeit auf sich zu ziehen, die kurze Option hingegen schon
sich im visuellen Rauschen verlieren.

RÜCKGABEWERT
Was das Programm oder die Funktion zurückgibt, wenn erfolgreich. Dieser Abschnitt kann weggelassen werden
Programme, deren genaue Exit-Codes nicht wichtig sind, vorausgesetzt, sie geben bei Erfolg 0 zurück
und bei Fehler ungleich Null, wie es standardmäßig der Fall ist. Es sollte für Funktionen immer vorhanden sein.
Bei Modulen kann es sinnvoll sein, Rückgabewerte der Modulschnittstelle zusammenzufassen
hier, oder es kann sinnvoller sein, Rückgabewerte separat im zu besprechen
Dokumentation jeder Funktion oder Methode, die das Modul bereitstellt.

FEHLER
Ausnahmen, Fehlerrückgabecodes, Exit-Status und Fehlernummerneinstellungen. Wird normalerweise verwendet für
Funktions- oder Moduldokumentation; Die Programmdokumentation verwendet stattdessen DIAGNOSTICS. Der
Als allgemeine Faustregel gilt, dass Fehler auf „STDOUT“ oder „STDERR“ gedruckt und bestimmt werden
Der Endbenutzer wird in der DIAGNOSE dokumentiert, während Fehler intern an den Anrufer weitergegeben werden
Programm und für andere Programmierer gedacht sind, sind in FEHLER dokumentiert. Beim Dokumentieren
eine Funktion, die errno setzt, sollte eine vollständige Liste der möglichen errno-Werte angegeben werden
.

DIAGNOSE
Alle möglichen Meldungen, die das Programm ausdrucken kann und was sie bedeuten. Vielleicht möchten Sie es
folgen Sie dem gleichen Dokumentationsstil wie die Perl-Dokumentation; sehen perldiag(1) für
Weitere Details (und schauen Sie sich auch die POD-Quelle an).

Geben Sie gegebenenfalls Einzelheiten dazu an, was der Benutzer tun sollte, um den Fehler zu beheben.
Dokumentieren eines Fehlers als Hinweis auf „Der Eingabepuffer ist zu klein“, ohne es dem mitzuteilen
Benutzer, wie sie die Größe des Eingabepuffers erhöhen können (oder ihnen zumindest sagen, dass dies der Fall ist).
ist nicht möglich) sind nicht sehr nützlich.

Beispiele:
Nennen Sie einige Anwendungsbeispiele für das Programm oder die Funktion. Sparen Sie nicht; Benutzer finden dies oft
der nützlichste Teil der Dokumentation. Die Beispiele werden im Allgemeinen als angegeben
wörtliche Absätze.

Präsentieren Sie nicht einfach ein Beispiel, ohne zu erklären, was es bewirkt. Einen Kurzfilm hinzufügen
Ein Absatz, der sagt, was das Beispiel bewirken wird, kann den Wert des Beispiels steigern
immens.


Umgebungsvariablen, die das Programm berücksichtigt, werden normalerweise als Liste dargestellt
„=over“, „=item“ und „=back“. Zum Beispiel:

=über 6

=item HOME

Wird verwendet, um das Home-Verzeichnis des Benutzers zu bestimmen. F<.foorc> dabei
Das Verzeichnis wird auf Konfigurationsdetails gelesen, sofern es vorhanden ist.

=zurück

Da Umgebungsvariablen normalerweise ausschließlich in Großbuchstaben geschrieben sind, gibt es keine zusätzlichen Sonderzeichen
Im Allgemeinen ist eine Formatierung erforderlich. Sie sind ohnehin schon auffällig genug.

DATEIEN
Alle vom Programm oder der Funktion verwendeten Dateien, normalerweise als Liste dargestellt, und deren Bedeutung
nutzt sie für. Dateinamen sollten in F<> eingeschlossen werden. Es ist besonders wichtig
Dokumentdateien, die möglicherweise geändert werden.

VORSICHTEN
Dinge, auf die Sie besonders achten sollten, manchmal auch WARNUNGEN genannt.

Fehler
Dinge, die kaputt sind oder einfach nicht richtig funktionieren.

RESTRICTIONS
Fehler, die Sie nicht beheben möchten. :-)

ANMERKUNG
Verschiedener Kommentar.

AUTOR
Wer hat es geschrieben (verwenden Sie AUTOREN für mehrere Personen). Es ist eine gute Idee, Ihre einzubeziehen
aktuelle E-Mail-Adresse (oder eine E-Mail-Adresse, an die Fehlerberichte gesendet werden sollen) oder
einige andere Kontaktinformationen, damit Benutzer Sie kontaktieren können. Erinnern
dass die Programmdokumentation viel länger als erwartet im Umlauf ist und
Wählen Sie eine Kontaktmethode, die wahrscheinlich von Dauer ist.

HISTORIEN
Bei aus anderen Quellen abgeleiteten Programmen ist dies manchmal der Fall. Manche Leute behalten eine
Änderungsprotokoll hier, aber das wird normalerweise lang und ist normalerweise besser darin zu pflegen
eine separate Datei.

URHEBERRECHT UND LIZENZ
Für Urheberrecht

Copyright JAHR(e) IHR(E) NAME(N)

(Nein, (C) ist nicht erforderlich. Nein, „Alle Rechte vorbehalten“ ist nicht erforderlich.)

Für die Lizenzierung ist es am einfachsten, die gleiche Lizenzierung wie Perl selbst zu verwenden:

Bei dieser Bibliothek handelt es sich um freie Software. Sie dürfen es weiterverbreiten und/oder
Ändern Sie es unter den gleichen Bedingungen wie Perl selbst.

Dadurch wird es einfacher, Ihr Modul mit Perl zu verwenden. Beachten Sie, dass diese Lizenzierung
Beispiel stellt weder eine Empfehlung noch eine Anforderung dar, Sie können dies selbstverständlich frei wählen
jegliche Lizenzierung.

SIEHE AUCH
Andere Manpages zum Ausprobieren, z Mann(1) Mann(7) machen was ist(8) oder catman(8).
Normalerweise eine einfache Liste von Manpages, die durch Kommas getrennt sind, oder ein Absatz, der das angibt
Name eines Nachschlagewerks. Manpage-Referenzen, wenn sie den Standard verwenden
„Name(Abschnitt)“-Formular, muss nicht in L<> eingeschlossen werden (obwohl dies empfohlen wird),
aber andere Dinge in diesem Abschnitt sollten wahrscheinlich angebracht sein.

Wenn das Paket über eine Mailingliste verfügt, geben Sie hier eine URL oder Abonnementanweisungen ein.

Wenn das Paket über eine Website verfügt, geben Sie hier eine URL ein.

Für die Dokumentation objektorientierter Bibliotheken oder Module können CONSTRUCTORS und verwendet werden
Weitere Informationen finden Sie in den Abschnitten „METHODEN“ oder in den Abschnitten „KLASSENMETHODEN“ und „INSTANZMETHODEN“.
Dokumentation der Teile der Bibliothek und speichern Sie den Abschnitt BESCHREIBUNG für eine
Überblick. Große Module mit einer Funktionsschnittstelle möchten möglicherweise FUNCTIONS für ähnliche Zwecke verwenden
Gründe dafür. Manche Leute verwenden OVERVIEW, um die Beschreibung zusammenzufassen, wenn sie sehr lang ist.

Die Reihenfolge der Abschnitte variiert, allerdings muss NAME immer der erste Abschnitt sein (dadurch werden einige unterbrochen).
(andernfalls in Manpage-Systemen) und NAME, SYNOPSIS, BESCHREIBUNG und OPTIONEN im Allgemeinen immer
treten zuerst und in dieser Reihenfolge auf, falls vorhanden. Im Allgemeinen SIEHE AUCH AUTOR und ähnliches
Material sollte zum Schluss aufbewahrt werden. Einige Systeme verschieben auch WARNUNGEN und HINWEISE auf die letzte Seite. Der
Die oben angegebene Reihenfolge sollte für die meisten Zwecke angemessen sein.

Einige Systeme verwenden CONFORMING TO, um die Konformität mit relevanten Standards und MT-LEVEL zu vermerken
Beachten Sie die Sicherheit für die Verwendung in Thread-Programmen oder Signalhandlern. Diese Überschriften sind
Dies ist vor allem bei der Dokumentation von Teilen einer C-Bibliothek nützlich.

Abschließend gilt als allgemeine Anmerkung: Versuchen Sie, nicht zu viel Markup zu verwenden. Wie dokumentiert
Hier und in Pod::Man können Sie Perl-Variablen, Funktionsnamen und Manpages bedenkenlos belassen
Referenzen und dergleichen ohne Markup, und die POD-Übersetzer werden es herausfinden
für dich. Dies erleichtert die spätere Bearbeitung der Dokumentation erheblich. Beachten Sie, dass viele
Bestehende Übersetzer werden mit E-Mail-Adressen das Falsche tun, wenn sie in L<> eingeschlossen sind
Tu das nicht.

Nutzen Sie Perlpodstyle online über die Dienste von onworks.net