perlpodstyle - En ligne dans le Cloud

PROGRAMME:

Nom

perlpodstyle - Guide de style Perl POD

DESCRIPTION

Ce sont des directives générales sur la façon d'écrire la documentation POD pour les scripts Perl et
modules, basés sur des directives générales pour écrire de bonnes pages de manuel UNIX. Tous ces
les directives sont, bien sûr, facultatives, mais les suivre rendra votre documentation plus
compatible avec d'autres documents sur le système.

Le nom du programme documenté est conventionnellement écrit en gras (en utilisant B<>)
où qu'il se produise, comme le sont toutes les options du programme. Les arguments doivent être écrits en italique
(Je<>). Les noms de fonction sont traditionnellement écrits en italique ; si vous écrivez une fonction comme
une fonction(), Pod::Man s'en occupera pour vous. Le code littéral ou les commandes doivent être
en C<>. Les références à d'autres pages de manuel doivent être sous la forme "page de manuel (section)" ou
"L ", et Pod::Man les formatera automatiquement de manière appropriée. Le
la deuxième forme, avec L<>, est utilisée pour demander qu'un formateur POD fasse un lien vers la page de manuel
si possible. À titre d'exception, on omet normalement la section lorsqu'on se réfère au module
la documentation car il n'est pas clair dans quelle section la documentation du module se trouvera ; utiliser
"L " pour les références de module à la place.

Les références à d'autres programmes ou fonctions sont normalement sous la forme de références de page de manuel
afin que les outils de références croisées puissent fournir à l'utilisateur des liens et autres. C'est
possible d'en faire trop, alors faites attention à ne pas trop encombrer votre documentation
beaucoup de balisage. Références à d'autres programmes qui ne sont pas données comme références de page de manuel
doit être entouré de B<>.

Les en-têtes principaux doivent être définis à l'aide d'une directive "=head1" et sont historiquement
écrit dans le format plutôt surprenant ALL UPPER CASE ; ce n'est pas obligatoire, mais c'est
fortement recommandé afin que les sections aient un nom cohérent sur différents logiciels
paquets. Les en-têtes mineurs peuvent être inclus à l'aide de "=head2" et sont généralement en casse mixte.

Les sections standard d'une page de manuel sont :

Nom
Rubrique obligatoire ; doit être une liste de programmes ou de fonctions séparés par des virgules
documentés par cette page POD, tels que :

foo, bar - programmes pour faire quelque chose

Les indexeurs de pages manuels sont souvent extrêmement pointilleux sur le format de cette section, donc
ne mettez rien dedans sauf cette ligne. Chaque programme ou fonction documenté par
cette page POD doit être répertoriée, séparée par une virgule et un espace. Pour un module Perl,
donnez simplement le nom du module. Un seul tiret, et un seul tiret, doit séparer le
liste des programmes ou des fonctions de la description. N'utilisez aucun balisage tel que C<>
ou B<> n'importe où dans cette ligne. Les fonctions ne doivent pas être qualifiées avec "()" ou le
Comme. La description doit idéalement tenir sur une seule ligne, même si un programme man
remplace le tiret par quelques onglets.

SYNOPSIS
Un bref résumé de l'utilisation des programmes et des fonctions. Cette section est obligatoire pour
rubrique 3 pages. Pour la documentation du module Perl, il est généralement pratique d'avoir le
contenu de cette section soit un bloc textuel montrant quelques (brefs) exemples de
façons dont le module est utilisé.

DESCRIPTION
Description détaillée et discussion du programme ou des fonctions, ou du corps du
documentation pour les pages de manuel qui documentent autre chose. Si particulièrement long, c'est
une bonne idée de diviser cela en sous-sections "=head2" directives comme :

=head2 Utilisation normale

=head2 Fonctionnalités avancées

=head2 Écriture des fichiers de configuration

ou tout ce qui est approprié pour votre documentation.

Pour un module, c'est généralement là que la documentation des interfaces fournie par
le module va, généralement sous la forme d'une liste avec un "=item" pour chaque interface.
Selon le nombre d'interfaces, vous voudrez peut-être mettre cette documentation dans
séparer les sections METHODS, FUNCTIONS, CLASS METHODS ou INSTANCE METHODS à la place et
enregistrez la section DESCRIPTION pour un aperçu.

OPTIONS
Description détaillée de chacune des options de ligne de commande prises par le programme. Cette
doit être séparé de la description pour l'utilisation d'analyseurs tels que Pod::Usage. Cette
est normalement présenté sous forme de liste, avec chaque option sous la forme d'un "=élément" distinct. Le spécifique
La chaîne d'option doit être entourée de B<>. Toutes les valeurs prises par l'option doivent être
enfermé dans I<>. Par exemple, la section pour l'option --section=hommesuivant serait
introduit avec :

=item B<--section>=I

Les options synonymes (comme les formes courte et longue) sont séparées par une virgule et un
espace sur la même ligne "=item", ou éventuellement répertoriés comme leur propre élément avec un
référence au nom canonique. Par exemple, depuis --section peut également être écrit comme
-s, ce qui précède serait :

=item B<-s> I , B<--section>=I

Il est recommandé d'écrire d'abord l'option courte car elle est plus facile à lire. Le long
l'option est assez longue pour attirer l'attention sur elle de toute façon et l'option courte peut autrement
se perdre dans le bruit visuel.

VALEUR DE RETOUR
Ce que le programme ou la fonction renvoie, en cas de succès. Cette section peut être omise pour
programmes dont les codes de sortie précis ne sont pas importants, à condition qu'ils renvoient 0 en cas de succès
et différent de zéro en cas de défaillance comme c'est le cas en standard. Il doit toujours être présent pour les fonctions.
Pour les modules, il peut être utile de résumer les valeurs de retour de l'interface du module
ici, ou il peut être plus utile de discuter des valeurs de retour séparément dans le
documentation de chaque fonction ou méthode fournie par le module.

LES ERREURS
Exceptions, codes de retour d'erreur, états de sortie et paramètres errno. Généralement utilisé pour
la documentation de la fonction ou du module ; la documentation du programme utilise DIAGNOSTICS à la place. le
la règle générale est que les erreurs imprimées sur "STDOUT" ou "STDERR" et destinées à
l'utilisateur final est documenté dans DIAGNOSTICS tandis que les erreurs sont passées en interne à l'appelant
programme et destiné à d'autres programmeurs sont documentés dans ERREURS. Lors de la documentation
une fonction qui définit errno, une liste complète des valeurs possibles d'errno doit être donnée
ici.

DIAGNOSTIC
Tous les messages possibles que le programme peut imprimer et leur signification. Vous pouvez souhaiter
suivre le même style de documentation que la documentation Perl ; voir perldiag(1) pour
plus de détails (et regardez aussi la source du POD).

Le cas échéant, veuillez inclure des détails sur ce que l'utilisateur doit faire pour corriger l'erreur ;
documenter une erreur comme indiquant « le tampon d'entrée est trop petit » sans en informer le
utilisateur comment augmenter la taille du tampon d'entrée (ou au moins leur dire qu'il
n'est pas possible) ne sont pas très utiles.

EXEMPLES
Donnez quelques exemples d'utilisation du programme ou de la fonction. Ne lésinez pas; les utilisateurs trouvent souvent cela
la partie la plus utile de la documentation. Les exemples sont généralement donnés comme
paragraphes textuels.

Ne vous contentez pas de présenter un exemple sans expliquer ce qu'il fait. Ajout d'un court
paragraphe disant ce que l'exemple va faire peut augmenter la valeur de l'exemple
immensément.

ENVIRONNEMENT
Variables d'environnement dont le programme se soucie, normalement présentées sous forme de liste utilisant
"=over", "=item" et "=back". Par example:

=plus de 6

=item ACCUEIL

Utilisé pour déterminer le répertoire personnel de l'utilisateur. F<.foorc> dans ce
Le répertoire est lu pour les détails de configuration, s'il existe.

= retour

Étant donné que les variables d'environnement sont normalement en majuscules, aucun élément spécial supplémentaire
le formatage est généralement nécessaire ; ils sont assez flagrants comme ça.

DES DOSSIERS
Tous les fichiers utilisés par le programme ou la fonction, normalement présentés sous forme de liste, et ce qu'il
les utilise pour. Les noms de fichiers doivent être entourés de F<>. Il est particulièrement important de
fichiers de documents qui seront potentiellement modifiés.

MISES EN GARDE
Choses à prendre en compte, parfois appelées AVERTISSEMENTS.

BOGUES
Des choses qui sont cassées ou qui ne fonctionnent tout simplement pas correctement.

RESTRICTIONS
Bugs que vous ne prévoyez pas de corriger. :-)

NOTES
Commentaire divers.

AUTEUR
Qui l'a écrit (utilisez AUTEURS pour plusieurs personnes). C'est une bonne idée d'inclure votre
adresse e-mail actuelle (ou une adresse e-mail à laquelle les rapports de bogues doivent être envoyés) ou
d'autres informations de contact afin que les utilisateurs aient un moyen de vous contacter. Rappelles toi
que la documentation du programme a tendance à parcourir la nature bien plus longtemps que prévu et
choisissez une méthode de contact qui est susceptible de durer.

HISTOIRE
Les programmes dérivés d'autres sources ont parfois ceci. Certaines personnes gardent un
journal des modifications ici, mais cela devient généralement long et est normalement mieux maintenu dans
un fichier séparé.

DROIT D'AUTEUR ET LICENCE
Pour le droit d'auteur

Copyright ANNÉE(s) VOTRE(S) NOM(s)

(Non, (C) n'est pas nécessaire. Non, "tous droits réservés" n'est pas nécessaire.)

Pour les licences, le moyen le plus simple est d'utiliser les mêmes licences que Perl lui-même :

Cette bibliothèque est un logiciel libre ; vous pouvez le redistribuer et/ou
le modifier dans les mêmes conditions que Perl lui-même.

Cela permet aux gens d'utiliser facilement votre module avec Perl. Notez que cette licence
exemple n'est ni une approbation ni une exigence, vous êtes bien sûr libre de choisir
toute licence.

VOIR ÉGALEMENT
Autres pages de manuel à consulter, comme man(1), man(7), faire ce qui est(8), ou homme chat (8).
Normalement une simple liste de pages de manuel séparées par des virgules, ou un paragraphe donnant le
nom d'un ouvrage de référence. Références de page de manuel, si elles utilisent la norme
forme "nom(section)", ne doivent pas être entourés de L<> (bien que cela soit recommandé),
mais d'autres choses dans cette section devraient probablement être le cas échéant.

Si le package a une liste de diffusion, incluez une URL ou des instructions d'abonnement ici.

Si le package a un site Web, incluez une URL ici.

La documentation des bibliothèques ou modules orientés objet peut vouloir utiliser des CONSTRUCTEURS et
sections MÉTHODES, ou MÉTHODES DE CLASSE et MÉTHODES D'INSTANCE, pour des informations détaillées
documentation des parties de la bibliothèque et enregistrez la section DESCRIPTION pour une
Aperçu. Les grands modules avec une interface de fonction peuvent vouloir utiliser FUNCTIONS pour des
les raisons. Certaines personnes utilisent OVERVIEW pour résumer la description si elle est assez longue.

L'ordre des sections varie, bien que NOM doive toujours être la première section (vous
systèmes de page de manuel autrement), et NOM, SYNOPSIS, DESCRIPTION et OPTIONS généralement toujours
se produisent en premier et dans cet ordre s'il est présent. En général, VOIR AUSSI, AUTEUR, et similaires
le matériel doit être laissé pour la fin. Certains systèmes déplacent également les AVERTISSEMENTS et les NOTES pour durer. le
l'ordre donné ci-dessus devrait être raisonnable dans la plupart des cas.

Certains systèmes utilisent CONFORMING TO pour noter la conformité aux normes pertinentes et MT-LEVEL pour
notez la sécurité d'utilisation dans les programmes filetés ou les gestionnaires de signaux. Ces rubriques sont
principalement utile lors de la documentation de parties d'une bibliothèque C.

Enfin, comme note générale, essayez de ne pas utiliser une quantité excessive de balisage. Comme documenté
ici et dans Pod::Man, vous pouvez laisser en toute sécurité les variables Perl, les noms de fonctions, la page de manuel
références, et autres sans balisage et les traducteurs POD le découvriront
pour vous. Cela rend beaucoup plus facile la modification ultérieure de la documentation. Notez que beaucoup
les traducteurs existants feront la mauvaise chose avec les adresses e-mail lorsqu'elles sont enveloppées dans L<>, donc
ne fais pas ça.

Utilisez perlpodstyle en ligne en utilisant les services onworks.net