perlpod - Online în cloud

PROGRAM:

NUME

perlpod - formatul Plain Old Documentation

DESCRIERE

Pod este un limbaj de marcare simplu de utilizat folosit pentru scrierea documentației pentru Perl, Perl
programe și module Perl.

Traducătorii sunt disponibili pentru conversia Pod în diferite formate, cum ar fi text simplu, HTML, man
pagini și multe altele.

Markup pod constă din trei tipuri de bază de paragrafe: obișnuit, text și comandă.

Obișnuit Paragraf
Majoritatea paragrafelor din documentația dvs. vor fi blocuri obișnuite de text, ca acesta. Tu
poate pur și simplu să tastați textul fără nici un fel de marcare și doar cu o linie goală
inainte si dupa. Când este formatat, va suferi o formatare minimă, ca și cum ar fi
reînfășurat, probabil pus într-un font distanțat proporțional și poate chiar justificat.

Puteți folosi coduri de formatare în paragrafe obișnuite, pt , cursiv, „stil cod”,
hyperlinkuri și multe altele. Astfel de coduri sunt explicate în secțiunea „Coduri de formatare”, de mai jos.

Textual Paragraf
Paragrafele textuale sunt de obicei folosite pentru a prezenta un cod sau alt text care o face
nu necesită nicio analiză sau formatare specială și care nu ar trebui să fie împachetate.

Un paragraf literal se distinge prin faptul că primul său caracter este un spațiu sau o tabulație.
(Și în mod obișnuit, toate liniile sale încep cu spații și/sau file.) Ar trebui reprodus
exact, cu file presupus a fi pe granițele de 8 coloane. Nu există formatări speciale
coduri, deci nu poți scrie italice sau ceva de genul ăsta. A \ înseamnă \ și nimic altceva.

Comandă Paragraf
Un paragraf de comandă este folosit pentru tratarea specială a bucăților întregi de text, de obicei ca
titluri sau părți ale listelor.

Toate paragrafele de comandă (care au de obicei doar un rând) încep cu „=", urmat
de un identificator, urmat de text arbitrar pe care comanda îl poate folosi oricum dorește.
Comenzile recunoscute în prezent sunt

=pod
=head1 Textul titlului
=head2 Textul titlului
=head3 Textul titlului
=head4 Textul titlului
=peste indentlevel
= chestii de articol
=spate
=begin format
= format final
=pentru format text...
=tip de codificare
=tăiat

Pentru a le explica fiecare în detaliu:

„=cap1 Rubrică Text"
„=cap2 Rubrică Text"
„=cap3 Rubrică Text"
„=cap4 Rubrică Text"
Head1 prin head4 produc titluri, head1 fiind cel mai înalt nivel. Textul din
restul acestui paragraf este conținutul titlului. De exemplu:

=head2 Atribute obiect

Textul „Atribute obiect” cuprinde titlul de acolo. Textul din aceste titluri
comenzile pot folosi coduri de formatare, așa cum se vede aici:

=head2 Valori posibile pentru C<$/>

Astfel de comenzi sunt explicate în secțiunea „Coduri de formatare”, de mai jos.

„=peste indentlevel"
„=articol chestie..."
„=înapoi”
Elementul, peste și înapoi necesită puțin mai multă explicație: „=peste” începe o regiune
special pentru generarea unei liste folosind comenzi „=item” sau pentru indentare
(grupuri de) paragrafe normale. La sfârșitul listei, folosiți „=back” pentru a o încheia. The
indentlevel opțiunea pentru „=peste” indică cât de departe este indentată, în general în ems
(unde un em este lățimea unui „M” în fontul de bază al documentului) sau aproximativ
unități comparabile; dacă nu există indentlevel opțiunea, este implicit patru. (Si ceva
Formatatorii pot ignora orice indentlevel oferiți.) În chestii în „=item
chestie...", puteți utiliza coduri de formatare, așa cum se vede aici:

=item Folosind C<$|> pentru a controla tamponarea

Astfel de comenzi sunt explicate în secțiunea „Coduri de formatare”, de mai jos.

Rețineți, de asemenea, că există câteva reguli de bază pentru utilizarea regiunilor „=peste” ... „=înapoi”:

· Nu folosiți „=item” în afara unei regiuni „=peste” ... „=înapoi”.

· Primul lucru după comanda „=over” ar trebui să fie „=item”, dacă nu există
nu vor fi deloc elemente în această regiune „=peste” ... „=înapoi”.

· Nu pune „=capn" comenzi într-o regiune "=peste" ... "=înapoi".

· Și poate cel mai important, păstrați elementele consistente: fie folosiți „=item *” pentru
toate, să producă gloanțe; sau folosiți „=item 1.”, „=item 2.”, etc., pentru a produce
liste numerotate; sau folosiți „=item foo”, „=item bar”, etc.--și anume, lucruri care arată
nimic ca gloanțe sau numere.

Dacă începeți cu marcatori sau numere, rămâneți cu ele, deoarece formatatorii folosesc primul
Tastați „=item” pentru a decide cum să formatați lista.

"=cut"
Pentru a încheia un bloc Pod, utilizați o linie goală, apoi o linie care începe cu „=cut” și un gol
rând după ea. Acest lucru îi permite lui Perl (și formatatorului Pod) să știe că aici este locul în care Perl
codul se reia. (Linia goală înainte de „=cut” nu este necesară din punct de vedere tehnic, dar
multe procesoare Pod mai vechi o necesită.)

„=pod”
Comanda „=pod” în sine nu face mare lucru, dar semnalează lui Perl (și
formatatoare de pod) că un bloc de pod începe aici. Un bloc Pod începe cu Orice comandă
paragraf, deci o comandă „=pod” este de obicei folosită doar atunci când doriți să porniți un bloc Pod
cu un paragraf obișnuit sau cu un paragraf literal. De exemplu:

=lucruri articol()

Această funcție face lucruri.

=tăiat

chestii secundare {
...
}

=pod

Nu uitați să verificați valoarea returnată, ca în:

chestii() || die „Nu am putut face lucruri!”;

=tăiat

„=începe formatname"
„=termină formatname"
„=pentru formatname text..."
Căci, începutul și sfârșitul vă vor permite să aveți regiuni de text/cod/date care nu sunt în general
interpretat ca text Pod obișnuit, dar sunt transmise direct către anumite formatoare sau
sunt de altfel speciale. Un formatator care poate folosi acel format va folosi regiunea,
altfel va fi complet ignorat.

O comandă „=begin formatname", unele paragrafe și o comandă "=end formatname", Rău
că textul/datele dintre acestea sunt destinate formatorilor care înțeleg specialul
format numit formatname. De exemplu,

=începe html


Acesta este un paragraf HTML brut

=termină html

Comanda „=pentru formatname text..." precizează că restul doar din aceasta
paragraf (începând imediat după formatname) este în acel format special.

=pentru html
Acesta este un paragraf HTML brut

Aceasta înseamnă același lucru ca și regiunea de mai sus „=begin html” ... „=end html”.

Adică, cu „=for”, puteți avea doar un singur paragraf de text (adică textul
în „=foo targetname text...”), dar cu „=begin targetname” ... „=end targetname”,
poate avea orice cantitate de lucruri între ele. (Rețineți că trebuie să existe încă o linie goală
după comanda „=begin” și o linie goală înainte de comanda „=end”.)

Iată câteva exemple de utilizare a acestora:

=începe html

Figura 1.

=termină html

=începe text

---------------
| foo |
| bar |
---------------

^^^^ Figura 1. ^^^^

=text final

Unele nume de format pe care se știe că le acceptă formatatorii includ „roff”, „man”,
„latex”, „tex”, „text” și „html”. (Unii formatatori vor trata unele dintre acestea ca
sinonime.)

Un nume de format de „comentare” este obișnuit doar pentru a face notițe (probabil pentru dvs.)
care nu va apărea în nicio versiune formatată a documentului Pod:

=pentru comentariu
Asigurați-vă că toate opțiunile disponibile sunt documentate!

niste nume de format va necesita două două puncte (ca în „=for :formatname”, sau „=begin
:formatname" ... "=end :formatname"), pentru a semnala că textul nu este date brute, ci
in schimb is Text pod (adică, posibil să conțină coduri de formatare) pentru care pur și simplu nu este pentru
formatare normală (de exemplu, poate să nu fie un paragraf de utilizare normală, dar ar putea fi pentru
formatare ca notă de subsol).

„=codare codificare nume"
Această comandă este folosită pentru a declara codificarea unui document. Majoritatea utilizatorilor nu vor avea nevoie
acest; dar dacă codarea dvs. nu este US-ASCII, atunci puneți un „=encoding codificare nume" comandă
foarte devreme în document, astfel încât formatorii de pod să știe cum să decodeze fișierul
document. Pentru codificare nume, utilizați un nume recunoscut de modulul Encode::Supported.
Unii formatatori de pod pot încerca să ghicească între un Latin-1 sau CP-1252 față de UTF-8
codificare, dar ei pot ghici greșit. Cel mai bine este să fii explicit dacă folosești ceva
în afară de ASCII strict. Exemple:

=codare latin1

=codarea utf8

=codificarea koi8-r

=codarea ShiftJIS

=coding big5

„=encoding” afectează întregul document și trebuie să apară o singură dată.

Și nu uitați, toate comenzile, cu excepția „=encoding”, durează până la sfârșitul acesteia paragraf, Nu
linia sa. Deci, în exemplele de mai jos, puteți vedea că fiecare comandă are nevoie de linia goală
după el, pentru a-și termina paragraful. (Și unii traducători Pod mai vechi pot necesita
Linia „=encoding” să aibă și următoarea linie goală, chiar dacă ar trebui să fie legal
omite.)

Câteva exemple de liste includ:

=peste

=articol *

Primul articol

=articol *

Al doilea element

=spate

=peste

=articol Foo()

Descrierea funcției Foo

=bara de articole()

Descrierea funcției Bar

=spate

Formatarea Coduri
În paragrafele obișnuite și în unele paragrafe de comandă, diverse coduri de formatare (alias
„secvențe interioare”) pot fi utilizate:

„Eu " -- text italic
Folosit pentru accentuare (""fii eu "") și parametrii (""redo I "")

„B " -- text îngroșat
Folosit pentru comutatoare ("„perl’s B<-n> switch”), programe („„unele sisteme oferă o
B pentru asta""), accent (""fii B "") și așa mai departe (""și acea caracteristică este
cunoscut sub numele de B "").

„C " -- code text
Redă codul într-un font de mașină de scris sau oferă alte indicații pe care aceasta îl reprezintă
textul programului (""C "") sau o altă formă de computerese
(""C "").

„L " -- un hyperlink
Există diverse sintaxe, enumerate mai jos. În sintaxele date, „text”, „nume” și
„secțiunea” nu poate conține caracterele „/” și „|”; și orice „<” sau „>” ar trebui să fie
potrivite.

· „L "

Link către o pagină de manual Perl (de exemplu, „L „). Rețineți că „nume” nu ar trebui
conțin spații. Această sintaxă este, de asemenea, folosită ocazional pentru referințe la Man Unix
pagini, ca în „Lcrontab(5)>".

· „L " sau " L "

Link către o secțiune din altă pagină de manual. De exemplu, „L "

· „L " sau " L "

Link către o secțiune din această pagină de manual. De exemplu, „L "

O secțiune este începută cu titlul sau elementul numit. De exemplu, „L " sau
„L " ambele link la secțiunea începută de ""=item $."" în perlvar. Și
„L " sau " L " ambele link la secțiunea începută de
""=head2 For Loops"" în perlsyn.

Pentru a controla ce text este utilizat pentru afișare, utilizați „”L "", ca în:

· „L "

Legați acest text la pagina respectivă de manual. De exemplu, „L "

· „L " sau " L "

Legați acest text la acea secțiune din pagina respectivă de manual. De exemplu, „L
„dacă”|perlsyn/„Modificatori de instrucțiuni”>”

· „L " sau " L " sau " L "

Legați acest text la acea secțiune din această pagină de manual. De exemplu, „L
atribute|/"Date membri">"

Sau puteți face un link către o pagină web:

· „L "

„L "

Linkuri către o adresă URL absolută. De exemplu, „Lhttp://www.perl.org/>" sau "L
Pagina principală|http://www.perl.org/>>".

„E " -- o evadare a personajului
Foarte asemănător cu HTML/XML „&prost;" "referințe la entitate":

· „E " -- un literal < (mai mic decât)

· „E " -- un literal > (mai mare decât)

· „E " -- un literal | (Vertical bar)

· „E " -- un literal / (soareidus)

Cele patru de mai sus sunt opționale, cu excepția altor coduri de formatare, în special „L<...>”,
iar când este precedată de o literă mare.

· „E "

Unele nume de entitate HTML non-numerice, cum ar fi „E ", adică același lucru ca
„é” în HTML - adică, un e minuscul cu un accent acut (în formă de /).

· „E "

Caracterul ASCII/Latin-1/Unicode cu acel număr. Un „0x” înainte înseamnă asta
număr este hex, ca în „E<0x201E>”. Un „0” înainte înseamnă că număr este octal, ca în
„E<075>”. In caz contrar număr este interpretat ca fiind în zecimală, ca în „E<181>”.

Rețineți că formatatoarele mai vechi de pod ar putea să nu recunoască evadările numerice octale sau hexadecimale,
și că mulți formatatori nu pot reda în mod fiabil caracterele peste 255. (Unii
Formatatorii ar putea chiar să fie nevoiți să folosească redări compromise ale Latin-1/CP-1252
caractere, cum ar fi redarea „E „ ca doar un simplu „e”.)

„F " -- folosit pentru numele de fișiere
Afișat de obicei cu caractere cursive. Exemplu: ""F<.cshrc>""

„S " -- textul conține spații care nu se rup
Aceasta înseamnă că cuvintele în a) Sport and Nutrition Awareness Day in Manasia Around XNUMX people from the rural commune Manasia have participated in a sports and healthy nutrition oriented activity in one of the community’s sports ready yards. This activity was meant to gather, mainly, middle-aged people from a Romanian rural community and teach them about the benefits that sports have on both their mental and physical health and on how sporting activities can be used to bring people from a community closer together. Three trainers were made available for this event, so that the participants would get the best possible experience physically and so that they could have the best access possible to correct information and good sports/nutrition practices. b) Sports Awareness Day in Poiana Țapului A group of young participants have taken part in sporting activities meant to teach them about sporting conduct, fairplay, and safe physical activities. The day culminated with a football match. nu ar trebui să fie întrerupte peste linii. Exemplu:
„S<$x ? $y : $z>”.

"X " -- o intrare de index
Acest lucru este ignorat de majoritatea formatatorilor, dar unii îl pot folosi pentru construirea de indici. Aceasta
se redă întotdeauna ca șir gol. Exemplu: „X "

„Z<>” -- un cod de formatare nul (cu efect zero).
Acesta este rar folosit. Este o modalitate de a vă deplasa folosind un cod E<...> uneori. Pentru
exemplu, în loc de „”NE 3"" (pentru "N<3") ai putea scrie ""NZ<><3"" („Z<>"
desparte „N” și „<” astfel încât să nu poată fi considerate ca parte a unui (fictiv)
codul „N<...>”).

De cele mai multe ori, veți avea nevoie doar de un singur set de paranteze unghiulare pentru a delimita
începutul și sfârșitul codurilor de formatare. Cu toate acestea, uneori veți dori să puneți un real
paranteză în unghi drept (un semn mai mare decât, „>”) în interiorul unui cod de formatare. Aceasta este
deosebit de comun atunci când se utilizează un cod de formatare pentru a furniza un tip de font diferit pentru a
fragment de cod. Ca și în cazul tuturor lucrurilor în Perl, există mai multe modalități de a face acest lucru. unu
modalitatea este de a scăpa pur și simplu din paranteza de închidere folosind un cod „E”:

C<$a E =E $b>

Aceasta va produce: ""$a <=> $b""

O modalitate mai lizibilă și poate mai „clară” este utilizarea unui set alternativ de delimitatori
care nu necesită un singur „>” pentru a fi scăpat. Paranteze unghiulare dublate ("<<" și ">>")
Poate fi folosit if si if acolo is spatiu alb dreapta după il de deschidere delimitator si
spatiu alb dreapta înainte il închidere delimitator! De exemplu, următoarele vor face
truc:

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

De fapt, puteți folosi oricâte paranteze repetate doriți, atâta timp cât aveți
același număr dintre ele în delimitatorii de deschidere și de închidere și asigurați-vă că spațiul alb
urmează imediat ultimul „<” al delimitatorului de deschidere și precede imediat
primul „>” al delimitatorului de închidere. (Spațiul alb este ignorat.) Deci următoarele vor
functioneaza si:

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

Și toate înseamnă exact același lucru:

C<$a E =E $b>

Forma cu paranteze multiple nu afectează interpretarea conținutului
codul de formatare, doar cum trebuie să se termine. Asta înseamnă că și exemplele de mai sus sunt
exact la fel ca acesta:

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

Ca un exemplu suplimentar, aceasta înseamnă că dacă ați vrut să puneți acești bucăți de cod în „C”
stil (cod):

deschide(X, ">>lucru.dat") || mor $!
$foo->bar();

ai putea sa faci asa:

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

care este probabil mai ușor de citit decât vechiul mod:

C E lucru.dat") || die $!>
C<$foo-E bara();>

Acest lucru este acceptat în prezent de pod2text (Pod::Text), pod2man (Pod::Man) și orice alte
traducători pod2xxx sau Pod::Xxxx care utilizează Pod::Parser 1.093 sau o versiune ulterioară sau Pod::Tree 1.02 sau
mai târziu.

Scop
Intenția este simplitatea utilizării, nu puterea de exprimare. Paragrafele arată ca niște paragrafe
(format bloc), astfel încât să iasă în evidență vizual și să le pot trece prin ele
„fmt” pentru a le reformata cu ușurință (acesta este F7 în versiunea mea de vi, sau Esc Q în versiunea mea de
emacs). Am vrut ca traducătorul să lase întotdeauna ghilimelele "'" și "`" și """ singure, în
modul textual, astfel încât să pot sorb într-un program de lucru, să-l deplasez pe patru spații și să am
se tipărește, er, textual. Și probabil într-un font monospațiu.

Formatul Pod nu este neapărat suficient pentru a scrie o carte. Podul este doar menit să fie
o sursă comună pentru nroff, HTML, TeX și alte limbaje de marcare, așa cum este folosit pentru
documentație online. Traducătorii există pentru pod2text, pod2html, pod2man (asta e pentru
nroff(1) și troff(1)), pod2latex și pod2fm. Diverse altele sunt disponibile în CPAN.

încorporarea pods in Perl Module
Puteți încorpora documentația Pod în modulele și scripturile dvs. Perl. Începeți-vă
documentație cu o linie goală, o comandă „=head1” la început și se încheie cu a
Comanda „=cut” și o linie goală. The perl executabilul va ignora textul Pod. Puteți
plasați o declarație Pod unde perl așteaptă începutul unei noi declarații, dar nu în interior
o declarație, deoarece aceasta ar duce la o eroare. Vedeți oricare dintre modulele bibliotecii furnizate
de exemplu.

Dacă veți pune Podul la sfârșitul fișierului și utilizați un „__END__” sau
Semn de tăiere „__DATA__”, asigurați-vă că puneți o linie goală acolo înainte de prima comandă Pod.

__SFÂRȘIT__

=head1 NUME

Time::Local - calculează eficient ora din ora locală și GMT

Fără acea linie goală înainte de „=head1”, mulți traducători nu ar fi recunoscut
„=head1” ca pornirea unui bloc Pod.

sugestii pentru Scris Păstaie
·

podchecker comanda este furnizată pentru verificarea sintaxei Pod pentru erori și avertismente.
De exemplu, verifică linii complet goale în blocurile Pod și necunoscute
comenzi și coduri de formatare. De asemenea, ar trebui să treceți documentul printr-unul
sau mai mulți traducători și corectează rezultatul sau tipăriți rezultatul și corectați
acea. Unele dintre problemele găsite pot fi erori ale traducătorilor, pe care le puteți sau le puteți
nu doresc să lucreze.

· Dacă sunteți mai familiarizat cu scrierea în HTML decât cu scrierea în Pod, puteți încerca
mâna dvs. la scrierea documentației în HTML simplu și convertirea acesteia în Pod cu ajutorul
Modul experimental Pod::HTML2Pod, (disponibil în CPAN) și analizează rezultatul
cod. Modulul experimental Pod::PXML din CPAN ar putea fi, de asemenea, util.

· Mulți traducători Pod mai vechi necesită linii înainte de fiecare comandă Pod și după fiecare
Comanda pod (inclusiv „=cut”!) să fie o linie goală. Avand asa ceva:

# - - - - - - - - - - - -
=articol $petard->boom()

Acest lucru detonează zgomotos obiectul petardei.
=tăiat
sub boom {
...

... va face ca astfel de traducători Pod să nu vadă deloc blocul Pod.

În schimb, ai-o astfel:

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

=articol $petard->boom()

Acest lucru detonează zgomotos obiectul petardei.

=tăiat

sub boom {
...

· Unii traducători pod mai vechi necesită paragrafe (inclusiv paragrafe de comandă, cum ar fi
„=head2 Functions”) pentru a fi separate prin complet linii goale. Dacă aveți un
linie aparent goală, cu câteva spații pe ea, aceasta ar putea să nu conteze ca un separator pentru
acești traducători și asta ar putea cauza formatări ciudate.

· Traducătorii mai vechi pot adăuga cuvinte în jurul unui link L<>, astfel încât „L " Mai
deveniți „pagina de manual Foo::Bar”, de exemplu. Deci nu ar trebui să scrieți lucruri precum „the
L documentație", dacă doriți ca documentul tradus să citească cu atenție. În schimb,
scrie „L documentație” sau „L
documentation|Foo::Bar>", pentru a controla cum iese linkul.

· Trecerea dincolo de coloana a 70-a într-un bloc textual ar putea fi împachetat fără grație de unii
formatatoare.

Utilizați perlpod online folosind serviciile onworks.net