perlpod - En ligne dans le Cloud

PROGRAMME:

Nom

perlpod - le format de documentation classique

DESCRIPTION

Pod est un langage de balisage simple à utiliser utilisé pour écrire de la documentation pour Perl, Perl
programmes et modules Perl.

Des traducteurs sont disponibles pour convertir Pod en différents formats tels que du texte brut, HTML, man
pages, et plus encore.

Le balisage Pod se compose de trois types de paragraphes de base : ordinaire, textuel et de commande.

Ordinaire paragraphe
La plupart des paragraphes de votre documentation seront des blocs de texte ordinaires, comme celui-ci.
vous pouvez simplement saisir votre texte sans aucune balise et avec juste une ligne vide
avant et après. Une fois formaté, il subira un formatage minimal, comme s'il était
réemballé, probablement mis dans une police à espacement proportionnel, et peut-être même justifié.

Vous pouvez utiliser des codes de formatage dans des paragraphes ordinaires, par exemple goupille, italique, "style de code",
hyperliens, etc. Ces codes sont expliqués dans la section « Codes de formatage » ci-dessous.

Textuellement paragraphe
Les paragraphes verbatim sont généralement utilisés pour présenter un bloc de code ou un autre texte qui ne
ne nécessite aucune analyse ou formatage particulier et ne doit pas être enveloppé.

Un paragraphe textuel se distingue par le fait que son premier caractère est un espace ou une tabulation.
(Et généralement, toutes ses lignes commencent par des espaces et/ou des tabulations.) Il doit être reproduit
Exactement, les tabulations étant supposées être sur des limites de 8 colonnes. Il n'y a pas de formatage particulier.
codes, donc impossible de mettre en italique ou quoi que ce soit de ce genre. Un \ signifie \, et rien d'autre.

Command paragraphe
Un paragraphe de commande est utilisé pour le traitement spécial de morceaux entiers de texte, généralement comme
titres ou parties de listes.

Tous les paragraphes de commande (qui ne font généralement qu'une seule ligne) commencent par « = », suivi
par un identifiant, suivi d'un texte arbitraire que la commande peut utiliser comme elle le souhaite.
Les commandes actuellement reconnues sont

= gousse
=head1 Texte du titre
=head2 Texte du titre
=head3 Texte du titre
=head4 Texte du titre
=sur le niveau d'indentation
=objet trucs
= retour
=début du format
=format de fin
=pour formater le texte...
=type d'encodage
=couper

Pour les expliquer chacun en détail :

"=tête1 Titre Texte"
"=tête2 Titre Texte"
"=tête3 Titre Texte"
"=tête4 Titre Texte"
Les titres de la section « Titre 1 à Titre 4 » produisent des titres, le titre 1 étant le niveau le plus élevé. Le texte dans le
Le reste de ce paragraphe correspond au contenu du titre. Par exemple :

=head2 Attributs de l'objet

Le texte « Attributs d'objet » constitue le titre. Le texte de ce titre
les commandes peuvent utiliser des codes de formatage, comme indiqué ici :

=head2 Valeurs possibles pour C<$/>

Ces commandes sont expliquées dans la section « Codes de formatage » ci-dessous.

"=plus de niveau de retrait"
"=élément truc..."
"=retour"
Item, over et back nécessitent un peu plus d'explications : "=over" démarre une région
spécifiquement pour la génération d'une liste à l'aide des commandes « =item », ou pour l'indentation
(groupes de) paragraphes normaux. À la fin de votre liste, utilisez « =back » pour la terminer.
niveau d'indentation l'option « =over » indique jusqu'où indenter, généralement en ems
(où un em est la largeur d'un « M » dans la police de base du document) ou à peu près
unités comparables ; s'il n'y a pas niveau d'indentation option, la valeur par défaut est quatre. (Et certains
les formateurs peuvent simplement ignorer tout ce qui niveau d'indentation vous fournissez.) Dans le étoffe dans "=élément
truc...", vous pouvez utiliser des codes de formatage, comme indiqué ici :

=item Utilisation de C<$|> pour contrôler la mise en mémoire tampon

Ces commandes sont expliquées dans la section « Codes de formatage » ci-dessous.

Notez également qu'il existe quelques règles de base pour l'utilisation des régions « =over » ... « =back » :

· N'utilisez pas de « =item » en dehors d'une région « =over » ... « =back ».

· La première chose après la commande « =over » doit être un « =item », à moins qu'il n'y ait
il n'y aura aucun élément du tout dans cette région "=over" ... "=back".

· Ne mettez pas "=headn" commandes à l'intérieur d'une région "=over" ... "=back".

· Et peut-être plus important encore, gardez les éléments cohérents : utilisez soit « =item * » pour
tous, pour produire des puces ; ou utilisez « =élément 1. », « =élément 2. », etc., pour produire
listes numérotées ; ou utilisez « =item foo », « =item bar », etc. — à savoir, des choses qui ressemblent
rien de tel que des balles ou des chiffres.

Si vous commencez avec des puces ou des numéros, conservez-les, car les formateurs utilisent le premier
Tapez « =item » pour décider comment formater la liste.

"=couper"
Pour terminer un bloc Pod, utilisez une ligne vide, puis une ligne commençant par « =cut », et un espace vide
ligne après. Cela permet à Perl (et au formateur Pod) de savoir que c'est ici que Perl
le code reprend. (La ligne vide avant le « =cut » n'est pas techniquement nécessaire, mais
de nombreux anciens processeurs Pod l'exigent.)

"=pod"
La commande « =pod » en elle-même ne fait pas grand-chose, mais elle signale à Perl (et
Formateurs de pods) qu'un bloc Pod commence ici. Un bloc Pod commence par tout commander
paragraphe, donc une commande « =pod » est généralement utilisée uniquement lorsque vous souhaitez démarrer un bloc Pod
avec un paragraphe ordinaire ou un paragraphe textuel. Par exemple :

=objet trucs()

Cette fonction fait des choses.

=couper

sous-trucs {
...
}

= gousse

N'oubliez pas de vérifier sa valeur de retour, comme dans :

stuff() || die "Impossible de faire des trucs !";

=couper

"=début nom du format"
"=fin nom du format"
"=pour nom du format texte..."
Pour, commencer et finir vous permettront d'avoir des régions de texte/code/données qui ne sont généralement pas
interprété comme du texte Pod normal, mais transmis directement à des formateurs particuliers, ou
sont par ailleurs spécifiques. Un formateur capable d'utiliser ce format utilisera la région,
sinon il sera complètement ignoré.

Une commande « =begin nom du format", quelques paragraphes et une commande "=fin nom du format", signifier
que le texte/les données intermédiaires sont destinés aux formateurs qui comprennent le formatage spécial
format appelé nom du format. Par exemple,

=début html


Ceci est un paragraphe HTML brut

=fin html

La commande « =for » nom du format texte..." précise que le reste de ceci
paragraphe (commençant juste après nom du format) est dans ce format spécial.

=pour html
Ceci est un paragraphe HTML brut

Cela signifie la même chose que la région "=begin html" ... "=end html" ci-dessus.

Autrement dit, avec « =for », vous ne pouvez avoir qu'un seul paragraphe de texte (c'est-à-dire le texte
dans "=foo targetname text..."), mais avec "=begin targetname" ... "=end targetname", vous
peut contenir n'importe quelle quantité de choses entre les deux. (Notez qu'il doit toujours y avoir une ligne vide
après la commande « =begin » et une ligne vide avant la commande « =end ».)

Voici quelques exemples de la façon de les utiliser :

=début html

Figure 1.

=fin html

=début du texte

---------------
| foo |
| barre |
---------------

^^^^ Figure 1. ^^^^

=fin du texte

Certains noms de formats que les formateurs acceptent actuellement incluent « roff », « man »,
« latex », « tex », « text » et « html ». (Certains formateurs traiteront certains de ces éléments comme
synonymes.)

Le nom de format « commentaire » est courant pour simplement prendre des notes (probablement pour vous-même)
qui n'apparaîtra dans aucune version formatée du document Pod :

=pour commentaire
Assurez-vous que toutes les options disponibles sont documentées !

Certain noms de format nécessitera un deux-points initial (comme dans « =for :formatname » ou « =begin
:formatname" ... "=end :formatname"), pour signaler que le texte n'est pas une donnée brute, mais
plutôt ; is Texte de pod (c'est-à-dire contenant éventuellement des codes de formatage) qui n'est tout simplement pas destiné
formatage normal (par exemple, peut ne pas être un paragraphe d'utilisation normale, mais peut être pour
formatage sous forme de note de bas de page).

"=encodage nomencodage"
Cette commande permet de déclarer l'encodage d'un document. La plupart des utilisateurs n'en auront pas besoin.
ceci; mais si votre encodage n'est pas US-ASCII, alors mettez un "=encoding nomencodage" commander
très tôt dans le document afin que les formateurs de pod sachent comment décoder le
document. Pour nomencodage, utilisez un nom reconnu par le module Encode::Supported.
Certains formateurs de pods peuvent essayer de deviner entre un Latin-1 ou un CP-1252 par rapport à un UTF-8
l'encodage, mais ils peuvent se tromper. Il est préférable d'être explicite si vous utilisez quoi que ce soit.
en plus de l'ASCII strict. Exemples :

=encodage latin1

=encodage utf8

=encodage koi8-r

=encodage ShiftJIS

=encodage big5

« =encoding » affecte l'ensemble du document et ne doit apparaître qu'une seule fois.

Et n'oubliez pas, toutes les commandes sauf "=encoding" durent jusqu'à la fin de son paragraphe, Pas
sa ligne. Dans les exemples ci-dessous, vous pouvez voir que chaque commande nécessite une ligne vide.
après cela, pour terminer son paragraphe. (Et certains traducteurs Pod plus anciens peuvent nécessiter le
La ligne « =encoding » doit également être suivie d'une ligne vide, même si cela devrait être légal.
omettre.)

Voici quelques exemples de listes :

=plus de

= élément *

Premier élément

= élément *

Second élément

= retour

=plus de

=élément Foo()

Description de la fonction Foo

=élément Bar()

Description de la fonction Bar

= retour

formatage Codes
Dans les paragraphes ordinaires et dans certains paragraphes de commande, divers codes de formatage (alias
« séquences intérieures ») peuvent être utilisées :

"JE " -- texte en italique
Utilisé pour mettre l'accent (« être moi ») "") et paramètres (""redo I "")

"B " -- texte en gras
Utilisé pour les commutateurs (« commutateur B<-n> de Perl »), les programmes (« certains systèmes fournissent un
B pour cela""), l'emphase (""soyez B ""), et ainsi de suite (""et cette fonctionnalité est
connu sous le nom de B "").

"C " -- code text
Affiche le code dans une police de machine à écrire ou donne une autre indication que cela représente
texte du programme (« C "") ou une autre forme de jargon informatique
(« C "").

"L " -- un hyperlien
Il existe différentes syntaxes, listées ci-dessous. Parmi les syntaxes proposées, on trouve « texte », « nom » et
« section » ne peut pas contenir les caractères « / » et « | » ; et tout « < » ou « > » doit être
assorti.

· "L "

Lien vers une page de manuel Perl (par exemple, « L "). Notez que "nom" ne doit pas
contiennent des espaces. Cette syntaxe est également parfois utilisée pour les références à des manuels Unix.
pages, comme dans « Lcrontab(5)>".

· "L " ou "L "

Lien vers une section d'une autre page de manuel. Par exemple : « L "

· "L " ou "L "

Lien vers une section de cette page de manuel. Par exemple : « L "

Une section commence par le titre ou l'élément nommé. Par exemple, « L » " ou
"L " les deux renvoient à la section démarrée par « =item $. » dans Perlvar. Et
"L " ou "L " les deux liens vers la section commencée par
"Boucles For =head2" dans perlsyn.

Pour contrôler le texte utilisé pour l'affichage, vous utilisez ""L "", comme dans :

· "L "

Associez ce texte à cette page de manuel. Par exemple, « L "

· "L " ou "L "

Associez ce texte à la section correspondante de la page de manuel. Par exemple : « L
"si"|perlsyn/"Modificateurs d'instruction">"

· "L " ou "L " ou "L "

Associez ce texte à la section correspondante de cette page de manuel. Par exemple : « L
attributs|/"Données des membres">"

Ou vous pouvez créer un lien vers une page Web :

· "L "

"L "

Liens vers une URL absolue. Par exemple, « L »http://www.perl.org/>" ou "L
Page d'accueil |http://www.perl.org/>".

"E " -- une évasion de personnage
Très similaire à HTML/XML "&foo ;" « références d'entité » :

· "E " -- un littéral < (inférieur à)

· "E " -- un littéral > (supérieur à)

· "E " -- un littéral | (voirtique Bar)

· "E " -- un littéral / (soleilidus)

Les quatre ci-dessus sont facultatifs, sauf dans d'autres codes de formatage, notamment « L<...> »,
et lorsqu'il est précédé d'une majuscule.

· "E "

Un nom d'entité HTML non numérique, tel que « E » ", signifiant la même chose que
« é » en HTML – c'est-à-dire un e minuscule avec un accent aigu (en forme de /).

· "E "

Le caractère ASCII/Latin-1/Unicode correspondant à ce numéro. Un « 0x » initial signifie que
nombre est hexadécimal, comme dans « E<0x201E> ». Un « 0 » initial signifie que nombre est octal, comme dans
« E<075> ». Sinon nombre est interprété comme étant en décimal, comme dans "E<181>".

Notez que les anciens formateurs Pod peuvent ne pas reconnaître les échappements numériques octaux ou hexadécimaux,
et que de nombreux formateurs ne peuvent pas restituer de manière fiable les caractères supérieurs à 255. (Certains
les formateurs peuvent même être amenés à utiliser des rendus compromis de Latin-1/CP-1252
caractères, comme le rendu « E " comme un simple « e ».)

"F " -- utilisé pour les noms de fichiers
Généralement affiché en italique. Exemple : « F<.cshrc> »

"S " -- le texte contient des espaces insécables
Cela signifie que les mots dans texte ne doit pas être divisé en plusieurs lignes. Exemple :
"S<$x ? $y : $z>".

"X " -- une entrée d'index
Ceci est ignoré par la plupart des formateurs, mais certains peuvent l'utiliser pour créer des index.
s'affiche toujours sous forme de chaîne vide. Exemple : « X » "

"Z<>" – un code de formatage nul (sans effet)
C'est rarement utilisé. C'est une façon de contourner l'utilisation d'un code E<...>.
exemple, au lieu de ""NE 3"" (pour "N<3") vous pourriez écrire ""NZ<><3"" (le "Z<>"
sépare le « N » et le « < » afin qu'ils ne puissent pas être considérés comme faisant partie d'un (fictif)
(code "N<...>")

La plupart du temps, vous n'aurez besoin que d'un seul ensemble de crochets angulaires pour délimiter le
début et fin des codes de formatage. Cependant, il peut être utile d'insérer un code réel.
crochet droit (signe supérieur à, « > ») à l'intérieur d'un code de formatage. Ceci est
particulièrement courant lors de l'utilisation d'un code de formatage pour fournir un type de police différent pour un
extrait de code. Comme pour tout en Perl, il existe plusieurs façons de procéder. Une
La méthode consiste simplement à échapper à la parenthèse fermante en utilisant un code « E » :

C<$a E =E $b>

Cela produira : ""$a <=> $b""

Une manière plus lisible et peut-être plus « simple » consiste à utiliser un ensemble alternatif de délimiteurs.
qui ne nécessite pas d'échappement d'un seul « > ». Crochets angulaires doublés (« << » et « >> »)
peut être utilisé if et uniquement if là is whitespace bien après le ouverture délimiteur et
whitespace bien avant le fermeture délimiteur! Par exemple, ce qui suit fera l'affaire
tour:

C<< $a <=> $b >>

En fait, vous pouvez utiliser autant de crochets angulaires répétés que vous le souhaitez, à condition que vous ayez le
le même nombre d'entre eux dans les délimiteurs d'ouverture et de fermeture, et assurez-vous que les espaces
suit immédiatement le dernier « < » du délimiteur d'ouverture et précède immédiatement le
premier '>' du délimiteur de fermeture. (L'espace est ignoré.) Donc ce qui suit
fonctionne également :

C<<< $a <=> $b >>>
C<<<< $a <=> $b >>>>

Et ils signifient tous exactement la même chose :

C<$a E =E $b>

La forme à crochets multiples n'affecte pas l'interprétation du contenu du
formatage du code, uniquement la manière dont il doit se terminer. Cela signifie que les exemples ci-dessus sont également
exactement la même chose que ça :

C<< $a E =E $b >>

À titre d’exemple supplémentaire, cela signifie que si vous vouliez mettre ces morceaux de code en « C »
(code) style :

open(X, ">>chose.dat") || meurs $!
$foo->bar();

tu pourrais le faire comme ça :

C<<< open(X, ">>thing.dat") || die $! >>>
C<< $foo->bar(); >>

ce qui est probablement plus facile à lire que l'ancienne méthode :

C E chose.dat") || mourir $!>
C<$foo-E barre();>

Ceci est actuellement pris en charge par pod2text (Pod::Text), pod2man (Pod::Man) et tout autre
Traducteurs pod2xxx ou Pod::Xxxx qui utilisent Pod::Parser 1.093 ou version ultérieure, ou Pod::Tree 1.02 ou
plus tard.

Le manuel de formation Intention
L'objectif est la simplicité d'utilisation, et non la puissance d'expression. Les paragraphes ressemblent à des paragraphes.
(format bloc), afin qu'ils ressortent visuellement et que je puisse les parcourir
"fmt" pour les reformater facilement (c'est F7 dans ma version de vi, ou Esc Q dans ma version de
emacs). Je voulais que le traducteur laisse toujours les guillemets "'", "`" et """ seuls, dans
mode verbatim, afin que je puisse insérer un programme fonctionnel, le décaler de quatre espaces et avoir
Il s'imprime textuellement, probablement dans une police monospace.

Le format Pod n'est pas forcément suffisant pour écrire un livre. Pod est juste là pour être
une source commune à toute épreuve pour nroff, HTML, TeX et d'autres langages de balisage, tels qu'utilisés pour
documentation en ligne. Des traducteurs existent pour pod2texte, pod2html, pod2man (c'est pour
nroffde Géographie (1) et avec la trof(sept)), pod2latexet pod2fm. Plusieurs autres sont disponibles dans CPAN.

Enrobage Pods in Perl Modules
Vous pouvez intégrer la documentation Pod dans vos modules et scripts Perl. Démarrez votre
documentation avec une ligne vide, une commande "=head1" au début et terminez-la par un
Commande « =cut » et une ligne vide. perl L'exécutable ignorera le texte du Pod. Vous pouvez
placez une instruction Pod où perl attend le début d'une nouvelle déclaration, mais pas dans
une instruction, car cela entraînerait une erreur. Voir les modules de bibliothèque fournis.
pour des exemples.

Si vous souhaitez placer votre Pod à la fin du fichier et que vous utilisez un "__END__" ou
Marque de coupe "__DATA__", assurez-vous d'y placer une ligne vide avant la première commande Pod.

__FINIR__

=head1 NOM

Time::Local - calcule efficacement l'heure à partir de l'heure locale et de l'heure GMT

Sans cette ligne vide avant le "=head1", de nombreux traducteurs n'auraient pas reconnu le
"=head1" comme démarrage d'un bloc Pod.

Allusions pour Écriture Cosse
·

Le manuel de formation vérificateur de pod une commande est fournie pour vérifier la syntaxe du Pod pour les erreurs et les avertissements.
Par exemple, il vérifie les lignes complètement vides dans les blocs Pod et les lignes inconnues
commandes et codes de formatage. Vous devriez également faire passer votre document par un
ou plusieurs traducteurs et relisez le résultat, ou imprimez le résultat et relisez
Certains des problèmes rencontrés peuvent être des bugs dans les traducteurs, que vous pouvez ou non
je ne souhaite pas travailler autour.

· Si vous êtes plus familier avec l'écriture en HTML qu'avec l'écriture en Pod, vous pouvez essayer
votre main pour écrire de la documentation en HTML simple et la convertir en Pod avec le
module expérimental Pod::HTML2Pod (disponible dans CPAN), et en regardant le résultat
code. Le module expérimental Pod::PXML dans CPAN pourrait également être utile.

· De nombreux traducteurs Pod plus anciens nécessitent les lignes avant chaque commande Pod et après chaque
La commande Pod (y compris « =cut » !) doit être une ligne vide. On obtient alors un résultat similaire à ceci :

# - - - - - - - - - - - -
=item $pétard->boom()

Cela fait exploser bruyamment l'objet pétard.
=couper
sous-boom {
...

...empêchera complètement ces traducteurs Pod de voir le bloc Pod.

Au lieu de cela, faites-le comme ceci :

# - - - - - - - - - - - -

=item $pétard->boom()

Cela fait exploser bruyamment l'objet pétard.

=couper

sous-boom {
...

· Certains traducteurs Pod plus anciens nécessitent des paragraphes (y compris des paragraphes de commande comme
"=head2 Fonctions") à séparer par complètement lignes vides. Si vous avez un
ligne apparemment vide avec quelques espaces dessus, cela pourrait ne pas compter comme un séparateur pour
ces traducteurs, et cela pourrait entraîner un formatage étrange.

· Les traducteurs plus anciens pourraient ajouter une formulation autour d'un lien L<>, de sorte que « L " peut
devenir « la page de manuel Foo::Bar », par exemple. Il ne faut donc pas écrire des choses comme « la
L documentation", si vous souhaitez que le document traduit soit lisible. Au lieu de cela,
écrivez "le L documentation" ou "L
documentation|Foo::Bar>", pour contrôler la façon dont le lien sort.

· Dépasser la 70e colonne dans un bloc textuel pourrait être maladroitement emballé par certains
formateurs.

Utiliser Perlpod en ligne avec les services onworks.net