perlpodspec - Online nel cloud

PROGRAMMA:

NOME

perlpodspec - Plain Old Documentation: specifica del formato e note

DESCRIZIONE

Questo documento contiene note dettagliate sul linguaggio di markup Pod. La maggior parte delle persone dovrà solo farlo
leggi perlpod per sapere come scrivere in Pod, ma questo documento potrebbe rispondere ad alcuni incidentali
domande relative all'analisi e al rendering di Pod.

In questo documento, "deve" / "non deve", "dovrebbe" / "non dovrebbe" e "potrebbe" avere la loro
significati convenzionali (cfr. RFC 2119): "X deve fare Y" significa che se X non fa Y, è
contro questa specifica e dovrebbe davvero essere risolto. "X dovrebbe fare Y" significa che lo è
consigliato, ma X potrebbe non riuscire a fare Y, se c'è una buona ragione. "X può fare Y" è semplicemente a
nota che X può fare Y a piacimento (sebbene spetterà al lettore rilevare qualsiasi connotazione di
"e penso che lo sarebbe bello se X facesse Y" contro "non lo farebbe davvero preoccuparsi me se X lo facesse
Y").

In particolare, quando dico "il parser dovrebbe fare Y", il parser potrebbe non riuscire a fare Y, se la chiamata
l'applicazione richiede esplicitamente che il parser non è un do Y. Lo esprimo spesso come "il
parser dovrebbe, per impostazione predefinita, fare Y." Questo non lo fa richiedere il parser per fornire un'opzione
per disattivare qualsiasi funzione Y sia (come espandere le schede nei paragrafi letterali),
anche se implica che tale opzione può essere fornito.

Baccello Definizioni

Pod è incorporato nei file, in genere file di origine Perl, sebbene tu possa scrivere un file
non è altro che Pod.

A linea in un file è costituito da zero o più caratteri non di nuova riga, terminati da a
newline o la fine del file.

A nuova linea sequenza di solito è un concetto dipendente dalla piattaforma, ma i parser Pod dovrebbero
capisci che significa uno qualsiasi dei CR (ASCII 13), LF (ASCII 10) o un CRLF (seguito ASCII 13
immediatamente da ASCII 10), oltre a qualsiasi altro significato specifico del sistema. Il primo
La sequenza CR/CRLF/LF nel file può essere utilizzata come base per identificare la nuova riga
sequenza per analizzare il resto del file.

A vuoto linea è una riga composta interamente da zero o più spazi (ASCII 32) o tabulazioni
(ASCII 9) e terminato con una nuova riga o fine file. UN non vuoto linea è una linea
contenente uno o più caratteri diversi da spazio o tabulazione (e terminati da una nuova riga o
fine file).

(Nota: Molti vecchi parser Pod non accettavano una riga composta da spazi/schede e quindi a
nuova riga come riga vuota. Le uniche righe che consideravano vuote erano righe costituite da no
caratteri at contro tutti i, terminato da una nuova riga.)

spazio bianco è usato in questo documento come termine generale per spazi, tabulazioni e newline
sequenze. (Di per sé, questo termine di solito si riferisce a spazi bianchi letterali. Cioè,
sequenze di caratteri di spazi vuoti nell'origine Pod, al contrario di "E<32>", che è a
codice di formattazione che denota uno spazio vuoto.)

A Baccello parser è un modulo pensato per l'analisi di Pod (indipendentemente dal fatto che ciò comporti
chiamando callback o costruendo un albero di analisi o formattandolo direttamente). UN Baccello formattatore
(o Baccello traduttore) è un modulo o programma che converte Pod in un altro formato (HTML,
testo in chiaro, TeX, PostScript, RTF). UN Baccello processore potrebbe essere un formattatore o un traduttore, o
potrebbe essere un programma che fa qualcos'altro con il Pod (come contare le parole, scansionare
per punti indice, ecc.).

Il contenuto del pod è contenuto in Baccello blocchi. Un blocco Pod inizia con una linea che corrisponde
"m/\A=[a-zA-Z]/", e continua fino alla riga successiva che corrisponde a "m/\A=cut/" o fino al
fine del file se non è presente la riga "m/\A=cut/".

All'interno di un blocco Pod, ci sono Baccello paragrafi. Un paragrafo Pod è costituito da righe non vuote
di testo, separati da una o più righe vuote.

Ai fini dell'elaborazione Pod, ci sono quattro tipi di paragrafi in un blocco Pod:

· Un paragrafo di comando (chiamato anche "direttiva"). La prima riga di questo paragrafo
deve corrispondere a "m/\A=[a-zA-Z]/". I paragrafi di comando sono in genere di una riga, come in:

=head1 NOTE

= articolo *

Ma possono estendersi su più righe (non vuote):

=per commento
Hm, mi chiedo come sarebbe se
hai provato a scrivere un BNF per Pod da questo.

=head3 Il dottor Stranamore, oppure: Come ho imparato a farlo
Smettila di preoccuparti e ama la bomba

Alcuni i paragrafi di comando consentono di formattare i codici nel loro contenuto (ad esempio, dopo la parte
che corrisponde a "m/\A=[a-zA-Z]\S*\s*/"), come in:

=head1 Ti sei ricordato di C ?

In altre parole, il gestore di elaborazione Pod per "head1" applicherà la stessa elaborazione
a "Ti sei ricordato di C ?" che si tratterebbe di un paragrafo ordinario (cioè,
codici di formattazione come "C<...>") vengono analizzati e presumibilmente formattati in modo appropriato e
gli spazi bianchi sotto forma di spazi e/o tabulazioni letterali non sono significativi.

· A Verbatim paragrafo. La prima riga di questo paragrafo deve essere uno spazio letterale o
tab e questo paragrafo non deve trovarsi all'interno di un "=begin identificatore", ... "=fine
identificatore" sequenza a meno che "identificatore" inizia con due punti (":"). Cioè, se a
il paragrafo inizia con uno spazio letterale o una tabulazione, ma is all'interno di un "=inizio identificatore", ...
"= fine identificatore" regione, allora è un paragrafo di dati, a meno che "identificatore" inizia con
un colon.

spazio bianco is significativo nei paragrafi letterali (sebbene, nell'elaborazione, le schede siano
probabilmente ampliato).

· Un ordinario paragrafo. Un paragrafo è un paragrafo normale se la sua prima riga corrisponde
né "m/\A=[a-zA-Z]/" né "m/\A[ \t]/", e se non è all'interno di un "=begin
identificatore", ... "=fine identificatore" sequenza a meno che "identificatore" inizia con i due punti
(":").

· A dati paragrafo. Questo è un paragrafo che is all'interno di un "=inizio identificatore" ... "=fine
identificatore" sequenza dove "identificatore" fa non è un iniziano con i due punti letterali (":"). Nel
in un certo senso, un paragrafo di dati non fa affatto parte di Pod (cioè, in effetti è "fuori-
of-band"), poiché non è soggetto alla maggior parte dei tipi di analisi Pod; ma è specificato
qui, poiché i parser Pod devono essere in grado di chiamare un evento o archiviarlo in alcuni
formare in un albero di analisi, o almeno solo analizzare circa esso.

Ad esempio: considera i seguenti paragrafi:

# <- questa è la 0a colonna

=testa1 Pippo

Roba

$pippo->barra

=tagliare

Qui, "=head1 Foo" e "=cut" sono paragrafi di comando perché la prima riga di ciascuno
corrisponde a "m/\A=[a-zA-Z]/". "[spazio][spazio]$foo->bar" è un paragrafo letterale, perché è
la prima riga inizia con uno spazio vuoto letterale (e non c'è "=begin"..."=end"
regione intorno).

Il "= inizio identificatore" ... "=fine identificatore" i comandi fermano i paragrafi che circondano
dall'essere analizzati come paragrafi ordinari o letterali, se identificatore non inizia con a
colon. Questo è discusso in dettaglio nella sezione "Informazioni sui dati Paragrafi e
"=inizio/=fine" Regioni".

Baccello Comandi

Questa sezione ha lo scopo di integrare e chiarire la discussione nel "Comando Paragrafo"
in perlpod. Questi sono i comandi Pod attualmente riconosciuti:

"=testa1", "=testa2", "=testa3", "=testa4"
Questo comando indica che il testo nel resto del paragrafo è un'intestazione.
Quel testo può contenere codici di formattazione. Esempi:

= attributi oggetto head1

=head3 Cosa B da fare!

"= baccello"
Questo comando indica che questo paragrafo inizia un blocco Pod. (Se siamo già dentro
nel mezzo di un blocco Pod, questo comando non ha alcun effetto.) Se è presente del testo
in questo paragrafo di comando dopo "=pod", deve essere ignorato. Esempi:

= pod

Questo è un semplice paragrafo Pod.

=pod Questo testo viene ignorato.

"=tagliare"
Questo comando indica che questa riga è la fine di questo blocco Pod avviato in precedenza.
Se c'è del testo dopo "=cut" sulla riga, deve essere ignorato. Esempi:

=tagliare

=cut La documentazione finisce qui.

=tagliare
# Questa è la prima riga di testo del programma.
sub foo { # Questo è il secondo.

È un errore tentare di farlo inizia a un blocco Pod con un comando "=cut". In tal caso, il
Il processore pod deve interrompere l'analisi del file di input e, per impostazione predefinita, deve emettere un avviso.

"= finita"
Questo comando indica che questo è l'inizio di una regione elenco/rientro. Se c'è
qualsiasi testo che segue "=over", deve essere costituito solo da un numero positivo diverso da zero.
La semantica di questo numero è spiegata in "About =over...=back Regions"
sezione, più sotto. I codici di formattazione non vengono espansi. Esempi:

=oltre 3

=oltre 3.5

=oltre

"= oggetto"
Questo comando indica che un elemento in un elenco inizia qui. I codici di formattazione sono
elaborato. La semantica del testo (facoltativo) nel resto di questo paragrafo
sono spiegati nella sezione "Informazioni su =over...=back Regions", più avanti. Esempi:

= oggetto

= articolo *

= articolo *

=elemento 14

=elemento 3.

=elemento C<< $cosa->roba(I ) >>

=item Per trasportarci al di là dei mari da provare per finta
reati

=item In questo momento sta trasportando grandi eserciti di stranieri
mercenari per completare le opere di morte, desolazione e
tirannia, già iniziata con circostanze di crudeltà e perfidia
non ha quasi eguali nelle epoche più barbare, e totalmente
indegno capo di una nazione civile.

"= indietro"
Questo comando indica che questa è la fine della regione iniziata dal più recente
Comando "= finito". Non consente alcun testo dopo il comando "=back".

"=inizio nomeformato"
"=inizio parametro nomeformato"
Questo contrassegna i paragrafi seguenti (fino alla corrispondenza "=end formatname").
per un tipo speciale di lavorazione. A meno che "nomeformato" non inizi con due punti, il file
i paragrafi non di comando contenuti sono paragrafi di dati. Ma se "nome formato" effettua iniziare
con i due punti, i paragrafi non di comando sono paragrafi ordinari o paragrafi di dati.
Questo è discusso in dettaglio nella sezione "Informazioni sui paragrafi dei dati e "=begin/=end"
Regioni".

Si consiglia che i nomi di formato corrispondano all'espressione regolare "m/\A:?[-a-zA-Z0-9_]+\z/". Qualunque cosa
dopo lo spazio bianco dopo il formatname è un parametro che può essere utilizzato da
formattatore quando si tratta di questa regione. Questo parametro non deve essere ripetuto nel
paragrafo "=fine". Gli implementatori dovrebbero anticipare l'espansione futura della semantica
e la sintassi del primo parametro in "=begin"/"=end"/"=for".

"=nomeformato finale"
Questo segna la fine della regione aperta dalla regione "=begin formatname" corrispondente.
Se "nomeformato" non è il nomeformato dell'ultimo "=begin nomeformato" aperto
regione, si tratta di un errore e deve generare un messaggio di errore. Questo è discusso
in dettaglio nella sezione "Informazioni sui paragrafi dei dati e sulle regioni "=begin/=end".

"=per il testo del nome formato..."
Questo è sinonimo di:

=inizia nomeformato

testo...

=nomeformato finale

Cioè, crea una regione composta da un solo paragrafo; quel paragrafo deve essere
trattato come un normale paragrafo se "formatname" inizia con ":"; se "nome formato"
non iniziare con due punti, quindi "testo..." costituirà un paragrafo di dati. C'è
non c'è modo di usare "=for formatname text..." per esprimere "text..." come paragrafo letterale.

"=codifica nomecodifica"
Questo comando, che dovrebbe comparire all'inizio del documento (almeno prima di qualsiasi
Dati ASCII!), dichiara che questo documento è codificato nella codifica nomecodifica,
che deve essere un nome di codifica riconosciuto da Encode. (L'elenco di codifica di supportati
codifiche, in Encode::Supported, è utile qui.) Se il parser Pod non è in grado di decodificare il file
codificata dichiarata, dovrebbe emettere un avviso e potrebbe interrompere l'analisi del documento
del tutto.

Un documento con più di una riga "=encoding" dovrebbe essere considerato un errore. Pod
i processori possono tollerarlo silenziosamente se le righe "=encoding" non iniziali sono giuste
duplicati del primo (ad esempio, se c'è una riga "=encoding utf8" e successivamente
un'altra riga "=encoding utf8"). Ma i processori Pod dovrebbero lamentarsi se ci sono
righe "=encoding" contraddittorie nello stesso documento (ad esempio, se è presente un "=encoding
utf8" all'inizio del documento e "=encoding big5" più avanti). Processori Pod that
riconoscere le distinte base può anche lamentarsi se vedono una riga "=encoding" che contraddice il
BOM (ad esempio, se un documento con una BOM UTF-16LE ha una riga "=encoding shiftjis").

Se un processore Pod vede un comando diverso da quelli sopra elencati (come "=head" o
"=haed1" o "=stuff" o "=seppia" o "=w123"), quel processore deve trattare di default
questo come un errore. Non deve elaborare il paragrafo che inizia con quel comando, deve entro
l'impostazione predefinita avverte di ciò come un errore e potrebbe interrompere l'analisi. Un parser Pod può consentire un modo
per applicazioni particolari da aggiungere all'elenco di comandi noti di cui sopra e stipulare,
per ogni comando aggiuntivo, se devono essere elaborati i codici di formattazione.

Le versioni future di questa specifica potrebbero aggiungere ulteriori comandi.

Baccello formattazione Codici

(Si noti che nelle bozze precedenti di questo documento e di perlpod, i codici di formattazione erano
denominate "sequenze interne", e questo termine può ancora essere trovato nella documentazione
per parser Pod e nei messaggi di errore dai processori Pod.)

Esistono due sintassi per la formattazione dei codici:

· Un codice di formattazione inizia con una lettera maiuscola (solo US-ASCII [AZ]) seguita da a
"<", qualsiasi numero di caratteri e termina con il primo ">" corrispondente. Esempi:

Questo è quello che io pensare!

Cos'è C? per?

X e C In diversi sistemi operativi>

· Un codice di formattazione inizia con una lettera maiuscola (solo US-ASCII [AZ]) seguita da due
o più "<", uno o più spazi bianchi, qualsiasi numero di caratteri, uno o
più spazi bianchi e termina con la prima sequenza corrispondente di due o più
">", dove il numero di ">" è uguale al numero di "<" nell'apertura di questo
codice di formattazione. Esempi:

Questo è quello che io<< tu >> penso!

C<<< open(X, ">>thing.dat") || muori $! >>>

B<< $pippo->bar(); >>

Con questa sintassi, i caratteri di spazio bianco dopo "C<<<" e prima di ">>>"
(o qualunque lettera) siano non è un renderizzabile. Non significano spazi bianchi, sono semplicemente
parte dei codici di formattazione stessi. Cioè, questi sono tutti sinonimi:

C
C<< cosa >>
C<< cosa >>
C<<< cosa >>>
C<<<
cosa
>>>>

e così via.

Infine, la forma con parentesi angolari multiple lo fa non è un alterare l'interpretazione di nidificato
codici di formattazione, il che significa che le quattro righe di esempio seguenti sono identiche in
senso:

B =E $b>>

B $b >>>

B =E $b >>>

B<<< esempio: C<< $a E =E $b >> >>>

Nell'analisi di Pod, una parte particolarmente difficile è l'analisi corretta di (potenzialmente annidato!)
codici di formattazione. Gli implementatori dovrebbero consultare il codice nella routine "parse_text" in
Pod::Parser come esempio di corretta implementazione.

"IO " -- testo in corsivo
Vedi la breve discussione in "Formattazione dei codici" in perlpod.

"B " -- testo grassetto
Vedi la breve discussione in "Formattazione dei codici" in perlpod.

"C " -- code text
Vedi la breve discussione in "Formattazione dei codici" in perlpod.

"F " -- stile per i nomi di file
Vedi la breve discussione in "Formattazione dei codici" in perlpod.

"X " -- una voce di indice
Vedi la breve discussione in "Formattazione dei codici" in perlpod.

Questo codice è insolito in quanto la maggior parte dei formattatori elimina completamente questo codice e il suo
contenuto. Altri formattatori lo renderanno con codici invisibili che possono essere utilizzati in
costruire un indice del documento corrente.

"Z<>" -- un codice di formattazione nullo (effetto zero)
Discusso brevemente in "Codici di formattazione" in perlpod.

Questo codice è insolito è che non dovrebbe avere contenuto. Cioè, un processore può
lamentarsi se vede "Z ". Che si lamenti o meno, il patate testo
dovrebbe ignorare.

"L " -- un collegamento ipertestuale
Le complicate sintassi di questo codice sono discusse a lungo in "Codici di formattazione" in
perlpod, e i dettagli sull'implementazione sono discussi di seguito, in "Informazioni sui codici L<...>".
Analizzando il contenuto di L è difficile. In particolare, il contenuto deve essere controllato
per sapere se assomiglia a un URL o se deve essere diviso sul letterale "|" e/o
"/" (nell'ordine corretto!), e così via, prima I codici E<...> sono stati risolti.

"E " -- un personaggio in fuga
Vedere "Codici di formattazione" in perlpod e diversi punti in "Note sull'implementazione del Pod
Processori".

"S " -- il testo contiene spazi unificatori
Questo codice di formattazione è sintatticamente semplice, ma semanticamente complesso. Cosa significa
è che ogni spazio nel contenuto stampabile di questo codice indica una non interruzione
spazio.

Prendere in considerazione:

C<$x ? $y : $z>

S >

Entrambi indicano il testo monospazio (stile c[ode]) composto da "$x", uno spazio, "?", uno
spazio, ":", uno spazio, "$z". La differenza è che in quest'ultimo, con il codice S,
quegli spazi non sono spazi "normali", ma invece sono spazi unificatori.

Se un processore Pod vede un codice di formattazione diverso da quelli sopra elencati (come in
"N<...>" o "Q<...>", ecc.), quel processore deve per impostazione predefinita trattarlo come un errore. UN
Il parser di pod può consentire un modo per aggiungere applicazioni particolari all'elenco di noti sopra
codici di formattazione; un parser Pod potrebbe anche consentire un modo per stabilire, per ogni aggiuntivo
comando, se richiede una qualche forma di elaborazione speciale, come fa L<...>.

Le versioni future di questa specifica potrebbero aggiungere codici di formattazione aggiuntivi.

Nota storica: alcuni vecchi processori Pod non vedrebbero un ">" come chiusura di un codice "C<",
se il ">" è stato immediatamente preceduto da un "-". Questo era così che questo:

C<$pippo->barra>

analizzerebbe come equivalente a questo:

C<$pippo-E barra>

anziché come equivalente a un codice di formattazione "C" contenente solo "$foo-", e quindi a
"bar>" al di fuori del codice di formattazione "C". Questo problema è stato poi risolto dal
aggiunta di sintassi come questa:

C<< $pippo->barra >>

I parser conformi non devono considerare "->" come speciale.

I codici di formattazione non possono assolutamente comprendere paragrafi. Se un codice viene aperto in un paragrafo,
e nessun codice di chiusura viene trovato entro la fine di quel paragrafo, il parser Pod deve chiuderlo
codice di formattazione e dovrebbe lamentarsi (come in "Codice I non terminato nel paragrafo che inizia
alla riga 123: 'Gli oggetti temporali non sono...'"). Quindi questi due paragrafi:

io

Non farmelo ripetere!>

...dovere non è un essere analizzato come due paragrafi in corsivo (con il codice I che inizia in uno
paragrafo e che iniziano in un altro.) Il primo paragrafo dovrebbe invece generare a
avviso, ma a parte questo, il codice sopra deve essere analizzato come se fosse:

io

Non farmelo ripetere!E

(Nel gergo SGML, tutti i comandi Pod sono come elementi a livello di blocco, mentre tutti i Pod
i codici di formattazione sono come elementi a livello di linea.)

Note on Implementazione Baccello Processori

Quella che segue è una lunga sezione di vari requisiti e suggerimenti da affrontare
Elaborazione pod.

· I formattatori di pod dovrebbero tollerare le righe nei blocchi letterali di qualsiasi lunghezza, anche
se ciò significa doverli spezzare (possibilmente più volte, per file molto lunghe) a
evitare che il testo fuoriesca dal lato della pagina. I formattatori di pod possono avvertire di tale linea-
rottura. Tali avvisi sono particolarmente appropriati per le righe superiori a 100
caratteri lunghi, che di solito non sono intenzionali.

· I parser Pod devono riconoscere contro tutti i dei tre noti formati di nuova riga: CR, LF e
CRLF. Vedi perlport.

· I parser di pod dovrebbero accettare righe di input di qualsiasi lunghezza.

· Poiché Perl riconosce un Byte Order Mark Unicode all'inizio dei file come segnale
che il file è codificato Unicode come in UTF-16 (sia big-endian o little-endian) o
UTF-8, i parser Pod dovrebbero fare lo stesso. In caso contrario, la codifica dei caratteri dovrebbe essere
inteso come UTF-8 se la prima sequenza di byte highbit nel file sembra valida
come sequenza UTF-8, o altrimenti come CP-1252 (versioni precedenti di questa specifica
usato Latin-1 invece di CP-1252).

Le versioni future di questa specifica potrebbero specificare come Pod può accettare altre codifiche.
Presumibilmente il trattamento di altre codifiche nell'analisi Pod sarebbe come nell'analisi XML:
qualunque sia la codifica dichiarata da un particolare file Pod, il contenuto deve essere archiviato
memoria come caratteri Unicode.

· I noti Unicode Byte Order Mark sono i seguenti: se il file inizia con il
due valori di byte letterali 0xFE 0xFF, questa è la distinta base per big-endian UTF-16. Se il file
inizia con il valore di due byte letterali 0xFF 0xFE, questa è la distinta base per little-endian
UTF-16. Su una piattaforma ASCII, se il file inizia con i tre valori di byte letterali
0xEF 0xBB 0xBF, questa è la distinta base per UTF-8. Un meccanismo portabile su piattaforme EBCDIC
è quello di:

mio $utf8_bom = "\x{FEFF}";
utf8::encode($utf8_bom);

· Un'euristica ingenua, ma spesso sufficiente sulle piattaforme ASCII, per testare la prima
sequenza di byte highbit in un file senza BOM (sia nel codice che nel Pod!), per vedere se
quella sequenza è valida come UTF-8 (RFC 2279) per verificare se il primo byte in
la sequenza è nell'intervallo 0xC2 - 0xFD e se il byte successivo è nell'intervallo
0x80 - 0xBF. In tal caso, il parser potrebbe concludere che questo file è in UTF-8 e tutto il resto
le sequenze highbit nel file dovrebbero essere considerate UTF-8. Altrimenti il ​​parser
dovrebbe trattare il file come se fosse in CP-1252. (Un controllo migliore e che funziona su EBCDIC
piattaforme, è passare una copia della sequenza a utf8::decodifica() che esegue
un controllo di validità completo sulla sequenza e restituisce TRUE se è valido UTF-8, FALSE
altrimenti. Questa funzione è sempre precaricata, è veloce perché scritta in C,
e verrà chiamato al massimo una volta, quindi non è necessario evitarlo
problemi di prestazioni.) Nell'improbabile circostanza che la prima sequenza highbit
in un file veramente non UTF-8 sembra essere UTF-8, si può soddisfare il nostro
euristica (così come qualsiasi euristica più intelligente) premettendo quella riga con a
riga di commento contenente una sequenza highbit che è chiaramente non è un valido come UTF-8. Una linea
costituito semplicemente da "#", un e-acute e qualsiasi byte non highbit, è sufficiente per
stabilire la codifica di questo file.

· I processori del pod devono considerare il paragrafo "=for [etichetta] [contenuto...]" come se avesse lo stesso significato
cosa come un paragrafo "=begin [etichetta]", contenuto e un paragrafo "=end [etichetta]". (Il
parser può confondere questi due costrutti, o può lasciarli distinti, nel
aspettativa che il formattatore li tratterà comunque allo stesso modo.)

· Quando si esegue il rendering del Pod in un formato che consente commenti (ad esempio, in quasi tutti i formati diversi
rispetto al testo normale), un formattatore Pod deve inserire un testo di commento che ne identifichi il nome e
numero di versione e il nome e i numeri di versione di tutti i moduli su cui potrebbe essere utilizzato
elaborare il Pod. Esempi minimi:

%% POD::Pod2PS v3.14159, utilizzando POD::Parser v1.92



{\doccomm generato da Pod::Tree::RTF 3.14159 utilizzando Pod::Tree 1.08}

.\" Pod::Man versione 3.14159, utilizzando POD::Parser versione 1.92

I formattatori possono anche inserire commenti aggiuntivi, tra cui: la data di rilascio del Pod
programma di formattazione, l'indirizzo di contatto dell'autore/i del formattatore, l'attuale
ora, il nome del file di input, le opzioni di formattazione in vigore, la versione di Perl utilizzata,
ecc.

I formattatori possono anche scegliere di annotare errori/avvisi come commenti, in aggiunta o al posto di
emettendoli in altro modo (come nei messaggi a STDERR o "morire").

· Parser di pod può emettono avvisi o messaggi di errore ("Unknown E code E !") a STDERR
(sia attraverso la stampa su STDERR, o "warn"ing/"carp"ing, o "die"ing/"gracidio"),
ma devono obbligatoriamente: consentire la soppressione di tutto questo output STDERR e consentire invece un'opzione per
segnalazione di errori/avvisi in altro modo, sia attivando una richiamata, sia
notando errori in qualche attributo dell'oggetto del documento, o in altri altrettanto discreti
meccanismo -- o anche aggiungendo una sezione "Errori Pod" alla fine del modulo analizzato
del documento.

· In casi di documenti eccezionalmente aberranti, i parser Pod possono interrompere l'analisi. Persino
quindi, l'uso di "morire"/"gracchiare" è da evitare; ove possibile, la libreria del parser
può semplicemente chiudere il file di input e aggiungere testo come "*** Formattazione interrotta ***" al file
fine del (parziale) documento in memoria.

· Nei paragrafi in cui si intendono codici di formattazione (come E<...>, B<...>) (es. non è un
paragrafi letterali, ma Compreso paragrafi ordinari e comandi ai paragrafi che
produrre testo renderizzabile, come "=head1"), gli spazi bianchi letterali dovrebbero generalmente esserlo
considerato "insignificante", in quanto uno spazio letterale ha lo stesso significato di qualsiasi altro
(diverso da zero) numero di spazi letterali, newline letterali e tabulazioni letterali (purché
questo non produce righe vuote, poiché quelle chiuderebbero il paragrafo). Analizzatori di pod
dovrebbe compattare gli spazi bianchi letterali in ogni paragrafo elaborato, ma può fornire un
opzione per sovrascriverlo (poiché alcune attività di elaborazione non lo richiedono) o può
seguire regole speciali aggiuntive (ad esempio, trattando in modo speciale periodo-spazio-spazio o
sequenze punto-nuova riga).

· I parser di pod non dovrebbero, per impostazione predefinita, tentare di forzare l'apostrofo (') e le virgolette (") in
virgolette intelligenti (piccoli 9, 66, 99, ecc.), né provare a trasformare il backtick (`) in qualcosa
altrimenti ma un singolo carattere backtick (distinto da un carattere di virgolette aperte!), né
"--" in tutt'altro che due segni meno. Essi devono obbligatoriamente: mai fare una di queste cose a
testo nei codici di formattazione C<...> e mai mai testo in paragrafi letterali.

· Quando si esegue il rendering di Pod in un formato che ha due tipi di trattini (-), uno che non è un
trattino spezzato e un altro che è un trattino spezzabile (come in "orientato agli oggetti", che
può essere suddiviso su righe come "oggetto-", newline, "orientato"), i formattatori lo sono
incoraggiato a tradurre generalmente "-" con un trattino unificato, ma può applicare l'euristica
per convertire alcuni di questi in trattini spezzati.

· I formattatori di pod dovrebbero compiere ogni ragionevole sforzo per evitare che le parole del codice Perl siano visibili
spezzato attraverso le linee. Ad esempio, "Foo::Bar" in alcuni sistemi di formattazione è visto come
idoneo per essere suddiviso su più righe come "Foo::" newline "Bar" o anche "Foo::-"
nuova riga "Bar". Questo dovrebbe essere evitato ove possibile, disabilitando tutte le linee-
rompendo a metà parola o avvolgendo parole particolari con punteggiatura interna
codici "non romperlo su più righe" (che in alcuni formati potrebbero non essere un codice singolo,
ma potrebbe trattarsi di inserire spazi di larghezza zero unificatore tra ogni coppia
di caratteri in una parola.)

· I parser di pod dovrebbero, per impostazione predefinita, espandere le schede nei paragrafi letterali come sono
elaborati, prima di passarli al formattatore o altro processore. I parser possono anche
consentire un'opzione per ignorarlo.

· I parser di pod dovrebbero, per impostazione predefinita, rimuovere le nuove righe dalla fine di ordinario e letterale
paragrafi prima di passarli al formattatore. Ad esempio, mentre il paragrafo
stai leggendo ora potrebbe essere considerato, nel sorgente Pod, per terminare con (e contenere) il
newline che lo termina, dovrebbe essere elaborato come terminante con (e contenente) il
carattere punto che termina questa frase.

· I parser di pod, quando segnalano errori, dovrebbero fare uno sforzo per segnalare un'approssimazione
numero di riga ("E nidificato <> nel paragrafo n. 52, vicino alla riga 633 di Thing/Foo.pm!"), invece
di annotare semplicemente il numero di paragrafo ("Nested E<>'s in Paragraph #52 of
Thing/Foo.pm!"). Laddove ciò sia problematico, il numero del paragrafo dovrebbe almeno esserlo
accompagnato da un estratto dal paragrafo ("Nested E<>'s in Paragraph #52 of
Thing/Foo.pm, che inizia 'Accesso di lettura/scrittura per C
attributo...'").

· I parser di pod, quando elaborano una serie di paragrafi letterali uno dopo l'altro, dovrebbero
considerali come un grande paragrafo letterale che contiene righe vuote.
Cioè, queste due righe, che hanno una riga vuota tra di loro:

usa Foo;

stampa Foo->VERSIONE

dovrebbe essere unificato in un paragrafo ("\tuse Foo;\n\n\tprint Foo->VERSION") prima
passato al formattatore o altro processore. I parser possono anche consentire un'opzione
per scavalcare questo.

Anche se questo potrebbe essere troppo ingombrante da implementare nei parser Pod basati su eventi, lo è
semplice per i parser che restituiscono alberi di analisi.

· Si consiglia ai formattatori di pod, ove possibile, di evitare di suddividere alla lettera il breve
paragrafi (sotto dodici righe, diciamo) attraverso le pagine.

· I parser di pod devono trattare una riga con solo spazi e/o tabulazioni come una "linea vuota"
come separa i paragrafi. (Alcuni parser più vecchi ne riconoscevano solo due adiacenti
newline come una "linea vuota" ma non riconoscerebbe una nuova riga, uno spazio e una nuova riga,
come riga vuota. Questo è un comportamento non conforme.)

· Gli autori di formattatori/processori Pod dovrebbero fare ogni sforzo per evitare di scrivere i loro
proprio parser Pod. Ce ne sono già diversi in CPAN, con un'ampia gamma di interfacce
stili -- e uno di questi, Pod::Parser, viene fornito con versioni moderne di Perl.

· I caratteri nei documenti Pod possono essere trasmessi sia come letterali, sia per numero in E
codici, o da un mnemonico equivalente, come in E che è esattamente equivalente a
E<233>. I numeri sono i valori Latin1/Unicode, anche su piattaforme EBCDIC.

Quando si fa riferimento ai caratteri usando una E codice numerico, numeri nell'intervallo 32-126
fare riferimento a quei ben noti caratteri US-ASCII (definiti anche lì da Unicode, con l'estensione
stesso significato), che tutti i formattatori di Pod devono rendere fedelmente. Personaggi la cui E<>
i numeri sono compresi negli intervalli 0-31 e 127-159 non devono essere usati (né come letterali,
né come E codici), ad eccezione delle sequenze di byte letterali per newline (ASCII 13,
ASCII 13 10 o ASCII 10) e scheda (ASCII 9).

I numeri nell'intervallo 160-255 si riferiscono ai caratteri Latin-1 (definiti anche lì da
Unicode, con lo stesso significato). I numeri superiori a 255 devono essere intesi come riferiti
Caratteri Unicode.

· Tieni presente che alcuni formattatori non possono eseguire il rendering affidabile di caratteri al di fuori di 32-126; e
molti sono in grado di gestire 32-126 e 160-255, ma niente al di sopra di 255.

· Oltre al noto "E " e "E " codici per minore e maggiore di, Pod
i parser devono comprendere "E " per "/" (solido, barra) e "E " per "|"
(barra verticale, tubo). I parser di pod dovrebbero anche comprendere "E " e
"E " come codici legacy per i caratteri 171 e 187, ovvero "doppio che punta a sinistra
virgolette angolo" = "Guillemet che punta a sinistra" e "doppio angolo che punta a destra
virgolette" = "guillemet che punta a destra". (Sembrano piccoli "<<" e ">>",
e ora sono preferibilmente espressi con i codici HTML/XHTML "E " e
"E ".)

· I parser di pod dovrebbero comprendere tutti i "E " codici come definiti nell'entità
dichiarazioni nella più recente specifica XHTML su "www.W3.org". I parser di pod devono
comprendere almeno le entità che definiscono i caratteri nell'intervallo 160-255
(Latino-1). I parser di pod, di fronte a uno sconosciuto "Eidentificatore>" codice, non dovrebbe
sostituiscilo semplicemente con nullstring (almeno per impostazione predefinita), ma puoi passarlo come a
stringa composta dai caratteri letterali E, minore di, identificatore, più grande di.
Oppure i parser Pod possono offrire l'opzione alternativa di elaborare tale sconosciuto
"Eidentificatore>" codici attivando un evento specifico per tali codici o aggiungendo a
tipo di nodo speciale per l'albero dei documenti in memoria. Tale "Eidentificatore>" può avere
significato speciale per alcuni processori, oppure alcuni processori possono scegliere di aggiungerli a a
rapporto di errore speciale.

· I parser Pod devono supportare anche i codici XHTML "E " per il carattere 34 (virgolette,
"), "E " per il carattere 38 (e commerciale, &) e "E " per il carattere 39
(apostrofo, ').

· Si noti che in tutti i casi di "E ", qualunque (se un htmlname o un numero in
qualsiasi base) deve essere composta solo da caratteri alfanumerici, ovvero qualunque deve guardare
"m/\A\w+\z/". Quindi "E< 0 1 2 3 >" non è valido, perché contiene spazi, che non lo sono
caratteri alfanumerici. Questo presumibilmente no bisogno trattamento speciale da parte di un Pod
processore; " 0 1 2 3 " non sembra un numero in nessuna base, quindi presumibilmente lo sarebbe
essere cercato nella tabella dei nomi simili a HTML. Dal momento che non c'è (e non può esserci) un
Entità simile a HTML chiamata " 0 1 2 3 ", verrà trattata come un errore. Tuttavia, il Pod
i trasformatori possono trattare "E< 0 1 2 3 >" o "E " come sintatticamente non valido,
potenzialmente guadagnando un messaggio di errore diverso dal messaggio di errore (o avviso, o
event) generato da un nome html semplicemente sconosciuto (ma teoricamente valido), come in
"E " [sic]. Tuttavia, i parser Pod non sono tenuti a fare questa distinzione.

· Si noti che E devono obbligatoriamente: non è un essere interpretato semplicemente come "codepoint numero nel
set di caratteri corrente/nativo". Significa sempre solo "il carattere rappresentato da
punto di codice numero in Unicode." (Questo è identico alla semantica di &#numero, In
XML.)

Ciò richiederà probabilmente che molti formattatori abbiano la mappatura delle tabelle da Unicode trattabile
codepoint (come "\xE9" per il carattere e-acute) alle sequenze di escape o
codici necessari per trasmettere tali sequenze nel formato di output di destinazione. Un convertitore
a *roff dovrebbe, ad esempio, sapere che "\xE9" (se trasmesso letteralmente o tramite a
E<...> sequenza) deve essere trasmesso come "e\\*'". Allo stesso modo, un programma che esegue il rendering di Pod in
una finestra dell'applicazione Mac OS, presumibilmente dovrebbe sapere che "\xE9" esegue il mapping a
codepoint 142 nella codifica MacRoman che (al momento della scrittura) è nativa per Mac OS.
Tali mappature Unicode2whatever sono presumibilmente già ampiamente disponibili per il comune
formati di output. (Tali mappature potrebbero essere incomplete! Gli implementatori non dovrebbero farlo
piegarsi all'indietro nel tentativo di rendere sillabiche Cherokee, rune etrusche,
Simboli musicali bizantini o qualsiasi altra cosa strana che Unicode può codificare.)
E se un documento Pod utilizza un carattere non trovato in tale mappatura, il formattatore
dovrebbe considerarlo un personaggio irreprensibile.

· Se, sorprendentemente, l'implementatore di un formattatore Pod non riesce a trovare un pre-
mappatura della tabella esistente dai caratteri Unicode agli escape nel formato di destinazione (ad es.
una tabella decente di caratteri Unicode per *roff escape), sarà necessario costruire
un tale tavolo. Se ti trovi in ​​questa circostanza, dovresti iniziare con i personaggi
nell'intervallo 0x00A0 - 0x00FF, che sono principalmente i caratteri accentati molto utilizzati.
Quindi procedi (come la pazienza lo consente e la meticolosità obbliga) attraverso i personaggi
che i gruppi di standard (X)HTML hanno ritenuto sufficientemente importante da meritare mnemonici.
Questi sono dichiarati nelle specifiche (X)HTML sul sito www.W3.org. Al momento di
scrivendo (settembre 2001), i file di dichiarazione di entità più recenti sono:

http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent

Quindi puoi avanzare attraverso tutti i restanti caratteri Unicode importanti nell'intervallo
0x2000-0x204D (consultare le tabelle dei caratteri su www.unicode.org) e quant'altro
colpisce la tua fantasia. Ad esempio, nel simbolo-xhtml.ent, c'è la voce:



Mentre la mappatura "infin" al carattere "\x{221E}" (si spera) sarà stata
già gestito dal parser Pod, la presenza del carattere in questo file significa
che è abbastanza importante da includere nella tabella di un formattatore da cui eseguire il mapping
caratteri Unicode notevoli ai codici necessari per renderli. Quindi per un
Ad esempio, la mappatura Unicode-to-*roff meriterebbe la voce:

"\x{221E}" => '\(in',

Si spera vivamente che in futuro, un numero crescente di formati (e formattatori)
supporterà direttamente i caratteri Unicode (come (X)HTML fa con "∞", "∞",
o "∞"), riducendo la necessità di mappature idiosincratiche di Unicode-to-le mie_fughe.

· Spetta al singolo formattatore di pod mostrare un buon giudizio quando si confronta con un
carattere non renderizzabile (che è distinto da un E sequenza che il
il parser non è stato in grado di risolvere nulla, renderizzabile o meno). È buona norma mappare
Lettere latine con segni diacritici (come "E "/"E<233>") al corrispondente
lettere US-ASCII non accentate (come un semplice carattere 101, "e"), ma chiaramente lo è
spesso non è fattibile e un carattere non renderizzabile può essere rappresentato come "?", o il
piace. Nel tentativo di un sano fallback (come da E<233> a "e"), i formattatori di pod possono utilizzare
la tabella %Latin1Code_to_fallback in Pod::Escapes o Text::Unidecode, se disponibile.

Ad esempio, questo testo Pod:

magic è abilitato se si imposta C<$Currency> su 'E '.

può essere visualizzato come: "la magia è abilitata se imposti $Currency su '?'" o come "la magia è
abilitato se imposti $Currency su '[Euro]'", o come "la magia è abilitata se hai impostato
$Valuta a '[x20AC]', ecc.

Un formattatore di pod può anche annotare, in un commento o in un avviso, un elenco di ciò che non è renderizzabile
personaggi sono stati incontrati.

· E<...> può apparire liberamente in qualsiasi codice di formattazione (diverso da un altro E<...> o in un
Z<>). Cioè "X 1,000,000 Soluzione>" è valido, così come "L
e 1,000,000 di soluzione|Milioni::Euro>".

· Alcuni formattatori Pod generano l'output in formati che implementano spazi unificatori come file
carattere individuale (che chiamerò "NBSP") e altri output in formato che
implementa gli spazi unificatori proprio come gli spazi racchiusi in un "non romperlo attraverso
linee". Si noti che a livello di Pod possono verificarsi entrambi i tipi di codici: Pod can
contengono un carattere NBSP (sia come letterale, sia come "E<160>" o "E " codice);
e Pod possono contenere "S baz>" codici, dove "semplici spazi" (carattere 32) in
tali codici sono presi per rappresentare spazi unificatori. I parser di pod dovrebbero considerare
supportando l'analisi facoltativa di "S baz>" come se lo fosse
"pippo"NBSPioNBSPbaz", e, andando dall'altra parte, l'analisi facoltativa dei gruppi di
parole unite da NBSP come se ogni gruppo fosse in un codice S<...>, in modo che i formattatori possano farlo
utilizzare la rappresentazione che corrisponde meglio a ciò che richiede il formato di output.

· Alcuni processori potrebbero scoprire che il codice "S<...>" è più facile da implementare sostituendo
ogni spazio nell'albero di analisi sotto il contenuto della S, con un NBSP. Ma nota: il
dovrebbe applicarsi la sostituzione non è un agli spazi dentro contro tutti i testo, ma esclusivamente agli spazi dentro stampabile
testo. (Questa distinzione può essere o meno evidente nel particolare modello albero/evento
implementato dal parser Pod.) Ad esempio, considera questo caso insolito:

S >

Ciò significa che lo spazio al centro del testo del link visibile non deve essere interrotto
attraverso le linee. In altre parole, è lo stesso di questo:

L<"AutoloadedE<160>Funzioni"/Funzioni caricate automaticamente>

Tuttavia, una sostituzione da spazio a NBSP applicata in modo errato potrebbe (erroneamente) produrre qualcosa
equivalente a questo:

L<"AutoloadedE<160>Funzioni"/AutoloadedE<160>Funzioni>

...che quasi sicuramente non funzionerà come collegamento ipertestuale (supponendo che questo
formattatore restituisce un formato che supporta l'ipertesto).

I formattatori possono scegliere di non supportare il codice in formato S, specialmente nei casi in cui
il formato di output semplicemente non ha carattere/codice NBSP e nessun codice per "non romperlo
roba oltre le righe".

· Oltre al carattere NBSP discusso sopra, agli implementatori viene ricordata l'esistenza
dell'altro carattere "speciale" in Latin-1, noto anche il carattere "trattino morbido".
come "trattino discrezionale", ovvero "E<173>" = "E<0xAD>" = "E "). Questo personaggio
esprime un punto di sillabazione facoltativo. Cioè, normalmente esegue il rendering come nulla, ma
può essere visualizzato come "-" se un formattatore interrompe la parola in quel punto. Formattatori di cialde
dovrebbe, a seconda dei casi, eseguire una delle seguenti operazioni: 1) eseguire il rendering con un codice con
stesso significato (ad esempio, "\-" in RTF), 2) lo trasmettono nell'aspettativa che il
formattatore comprende questo carattere come tale, oppure 3) eliminalo.

Per esempio:

sig azione
manuE sceneggiatura
Jark E ko Ciao E taE nieE mi

Questi segnalano a un formattatore che se deve sillabare "sigazione" o "manoscritto",
quindi dovrebbe essere fatto come "sig-[interruzione di linea]azione" o "manu-[interruzione di linea]copione" (e se
non sillaba, quindi "E " non si presenta affatto). E se lo è
trattino "Jarkko" e/o "Hietaniemi", può farlo solo nei punti dove c'è
un "E " codice.

In pratica, si prevede che questo carattere non verrà utilizzato spesso, ma
i formattatori dovrebbero supportarlo o eliminarlo.

· Se pensi di voler aggiungere un nuovo comando al Pod (come, ad esempio, un "=biblio"
comando), considera se potresti ottenere lo stesso effetto con un for o inizio/fine
sequenza: "=for biblio ..." oppure "=begin biblio" ... "=end biblio". Processori Pod che
non capisco "=per biblio", etc, semplicemente lo ignoreranno, mentre potrebbero lamentarsi
ad alta voce se vedono "=biblio".

· In tutto questo documento, "Pod" è stata l'ortografia preferita per il nome del
formato della documentazione. Si può anche usare "POD" o "pod". Per la documentazione che è
(tipicamente) nel formato Pod, puoi usare "pod" o "Pod" o "POD". Comprensione
queste distinzioni sono utili; ma l'ossessione su come scriverli, di solito non lo è.

Chi Siamo L<...> Codici

Come puoi vedere da uno sguardo a perlpod, il codice L<...> è il più complesso del Pod
codici di formattazione. Si spera che i punti seguenti chiariscano cosa significa e come
i processori dovrebbero occuparsene.

· Nell'analisi di un codice L<...>, i parser Pod devono distinguere almeno quattro attributi:

Primo:
Il link-testo. Se non ce n'è, questo deve essere "undef". (Ad esempio, in "L
Funzioni|perlfunc>", il testo del collegamento è "Funzioni Perl". In "L " e
anche "L<|Time::HiRes>", non c'è il testo del collegamento. Si noti che il testo del collegamento può contenere
formattazione.)

Secondo:
Il testo del collegamento eventualmente dedotto; cioè, se non c'era un vero testo di collegamento, allora questo
è il testo che dedurremo al suo posto. (Es. per "L ", il
il testo del collegamento dedotto è "Getopt::Std".)

Terzo:
Il nome o l'URL, o "undef" se nessuno. (Ad esempio, in "L ", il
il nome (a volte chiamato anche pagina) è "perlfunc". In "L ", il nome
è "undef".)

Il quarto:
La sezione (AKA "item" nei perlpod più vecchi) o "undef" se nessuno. Ad esempio, dentro
"L ", "DESCRIZIONE" è la sezione. (Nota che questo è
non è la stessa di una sezione di una manpage come "5" in "man 5 crontab". "Sezione Foo"
in senso Pod si intende la parte di testo introdotta dall'intestazione o
elemento il cui testo è "Foo".)

I parser di pod possono anche notare attributi aggiuntivi tra cui:

Quinto:
Un flag per indicare se l'elemento 3 (se presente) è un URL (come "http://lists.perl.org" è),
nel qual caso non dovrebbe esserci alcun attributo di sezione; un nome Pod (come "perldoc" e
"Getopt::Std" sono); o eventualmente un nome di pagina man (come "crontab(5)" è).

Sesto:
Il contenuto originale L<...> grezzo, prima che il testo sia diviso su "|", "/", ecc. e prima
I codici E<...> vengono espansi.

(Di seguito sono stati numerati solo per riferimento conciso. Non è un requisito
che questi vengano passati come un elenco o un array effettivo.)

Per esempio:

l
=> indef, # testo del collegamento
"Foo::Bar", # testo del collegamento eventualmente dedotto
"Foo::Bar", # nome
undef, # sezione
'pod', # che tipo di collegamento
"Foo::Bar" # contenuto originale

l
=> "Sezione di Perlport sulle NL", # testo del collegamento
"Sezione di Perlport sui NL", # testo del collegamento eventualmente dedotto
"perlport", # nome
"Nuove righe", # sezione
'pod', # che tipo di collegamento
"Sezione di Perlport su NL's|perlport/Newlines"
# contenuto originale

l
=> indef, # testo del collegamento
'"Nuove righe" in perlport', # eventualmente dedotto il testo del collegamento
"perlport", # nome
"Nuove righe", # sezione
'pod', # che tipo di collegamento
"perlport/Newlines" # contenuto originale

L<crontab(5)/"DESCRIZIONE">
=> indef, # testo del collegamento
'"DESCRIZIONE" in crontab(5)', # testo del collegamento eventualmente dedotto
"crontab(5)", # nome
"DESCRIZIONE", # sezione
'uomo', # che tipo di collegamento
'crontab(5)/"DESCRIZIONE"' # contenuto originale

l
=> indef, # testo del collegamento
'"Attributi oggetto"', # testo link eventualmente dedotto
indefinito, # nome
"Attributi dell'oggetto", # sezione
'pod', # che tipo di collegamento
"/Attributi oggetto" # contenuto originale

L<http://www.perl.org/>
=> indef, # testo del collegamento
"http://www.perl.org/", # testo del collegamento eventualmente dedotto
"http://www.perl.org/", # nome
undef, # sezione
'url', # che tipo di collegamento
"http://www.perl.org/" # contenuto originale

lhttp://www.perl.org/>
=> "Perl.org", # testo del collegamento
"http://www.perl.org/", # testo del collegamento eventualmente dedotto
"http://www.perl.org/", # nome
undef, # sezione
'url', # che tipo di collegamento
"Perl.org|http://www.perl.org/" # contenuto originale

Nota che puoi distinguere i collegamenti URL da qualsiasi altra cosa per il fatto che corrispondono
"m/\A\w+:[^:\s]\S*\z/". Quindi "Lhttp://www.perl.com>" è un URL, ma "L "
non lo è.

· In caso di codici L<...> senza "testo|" parte di essi, hanno esposto i formattatori più vecchi
grande variazione nella visualizzazione effettiva del collegamento o del riferimento incrociato. Per esempio,
L<crontab(5)> renderebbe come "il crontab(5) manpage" o "nella crontab(5) pagina man"
o semplicemente "crontab(5)".

I processori pod ora devono trattare i collegamenti "text|"-less come segue:

l => L
l => L<"sezione"|/sezione>
l => L<"sezione" in nome|nome/sezione>

· Si noti che i nomi delle sezioni potrebbero contenere markup. Ad esempio, se una sezione inizia con:

=head2 Informazioni sull'operatore C<-M>

o con:

=item Informazioni sull'operatore C<-M>

quindi un link ad esso sarebbe simile a questo:

l Operatore>

I formattatori possono scegliere di ignorare il markup ai fini della risoluzione del collegamento e dell'utilizzo
solo i caratteri renderizzabili nel nome della sezione, come in:

Circa il -M
Operatore

...

Circa il -M
Operatore" in somedoc

· Le versioni precedenti di perlpod distinguevano "L " link da
"L " link (e relativi target). Questi sono stati uniti sintatticamente e
semanticamente nella specifica attuale, e pagina può fare riferimento a un "=headn
Contenuti dell'intestazione" o a un comando "=elemento Contenuto dell'elemento". Questa specifica
non specifica quale comportamento dovrebbe essere nel caso di un determinato documento avente
molte cose sembrano tutte produrre la stessa cosa pagina identificatore (ad esempio, in HTML,
molte cose che producono tutte la stessa cosa nome di ancoraggio innome di ancoraggio">...
elementi). Laddove i processori Pod possono controllare questo comportamento, dovrebbero utilizzare il primo
tale ancora. Cioè "L " si riferisce a prima di tutto Sezione "Bar" in Foo.

Ma per alcuni processori/formati questo non può essere facilmente controllato; come con l'HTML
esempio, il comportamento di più ambiguinome di ancoraggio">... è il massimo
facilmente lasciato solo ai browser per decidere.

· In una "L " code, il testo può contenere codici di formattazione per la formattazione o per
E<...> esce, come in:

l roba>|...>

Per codici "L<...>" senza "nome|" parte, possono essere presenti solo i codici "E<...>" e "Z<>".
Cioè, gli autori non dovrebbero usare ""L >"".

Si noti, tuttavia, che i codici di formattazione e le Z<> possono essere presenti in qualsiasi parte di un file
L<...> (cioè, in Nome, pagina, testoe al direttore della fotografia URL).

Gli autori non devono annidare i codici L<...>. Ad esempio, "L pagina man>" dovrebbe
essere trattato come un errore.

· Si noti che gli autori Pod possono utilizzare codici di formattazione all'interno della parte "testo" di
"L " (e così via per L ).

In altre parole, questo è valido:

Vai a leggere L |perlvar/"$.">

Alcuni formati di output che consentono il rendering di codici "L<...>" come ipertesto, potrebbero non farlo
consentire la formattazione del testo del collegamento; in tal caso, i formattatori dovranno semplicemente ignorare
quella formattazione.

· Nel momento in cui scrivo, "L " i valori sono di due tipi: o il nome di una pagina Pod
come "L " (che potrebbe essere un vero modulo o programma Perl in un @INC / PATH
directory o un file .pod in quei luoghi); o il nome di una pagina man Unix, come
"Lcrontab(5)>". In teoria, "L " in ambiguo tra una pagina Pod chiamata
"chmod", o la pagina man di Unix "chmod" (in qualsiasi sezione man). comunque, il
presenza di una stringa tra parentesi, come in "crontab(5)", è sufficiente per segnalare che cosa
viene discussa non è una pagina Pod, e quindi presumibilmente è una pagina man di Unix. Il
la distinzione non ha importanza per molti processori Pod, ma per alcuni processori questo
il rendering in formati ipertestuali potrebbe aver bisogno di distinguerli per sapere come farlo
rendere un dato "L " codice.

· Le versioni precedenti di perlpod consentivano un "L " sintassi (come in "L
Attributi>"), che non era facilmente distinguibile da "L " sintassi e per
"L<"sezione">" che era solo leggermente meno ambigua. Questa sintassi non è più presente
il disciplinare, ed è stata sostituita dalla "L " sintassi (dove la barra
prima era facoltativo). I parser di pod dovrebbero tollerare la sintassi "L<"section">" per a
mentre almeno. L'euristica suggerita per distinguere "L " da
"L " è che se contiene spazi bianchi, è a pagina. Processori a pod
dovrebbe avvertire che questa sintassi è deprecata.

Chi Siamo =oltre...=indietro Regioni

Le regioni "=over"..."=back" vengono utilizzate per vari tipi di strutture simili a elenchi. (io uso il
termine "regione" qui semplicemente come termine collettivo per tutto, dal "= oltre" al
corrispondente a "= indietro".)

· Il valore numerico diverso da zero livello di rientro in "= finita livello di rientro" ... "=indietro" è usato per
dando al formattatore un indizio su quanti "spazi" (ems o unità approssimativamente equivalenti)
dovrebbe scorrere, anche se molti formattatori dovranno convertirlo in un assoluto
misura che potrebbe non corrispondere esattamente alla dimensione degli spazi (o delle M) nel
carattere di base del documento. Altri formattatori potrebbero dover ignorare completamente il numero. Il
mancanza di alcun esplicito livello di rientro parametro è equivalente a un livello di rientro valore di 4.
I processori Pod potrebbero lamentarsi se livello di rientro è presente ma non è un numero positivo
corrispondente a "m/\A(\d*\.)?\d+\z/".

· Si ricorda agli autori dei formattatori di Pod che "=over" ... "=back" può essere mappato a diversi
diversi costrutti nel formato di output. Ad esempio, convertendo Pod in
(X)HTML, può essere mappato a qualsiasi di ... , ... , ... , o
... . Allo stesso modo, "=item" può essere mappato a o .

· Ciascuna regione "=over" ... "=back" deve essere una delle seguenti:

· Una regione "=over" ... "=back" contenente solo comandi "=item *", ciascuno seguito da
un certo numero di paragrafi ordinari/verbatili, altri annidati "=over" ... "=back"
regioni, paragrafi "=per..." e regioni "=inizio"..."=fine".

(I processori Pod devono tollerare un semplice "=item" come se fosse "=item *".) Se
"*" è reso come un asterisco letterale, una "o" o come una sorta di vero proiettile
carattere, è lasciato al formattatore Pod e può dipendere dal livello di
Nidificazione.

· Una regione "=over" ... "=back" contenente solo "m/\A=item\s+\d+\.?\s*\z/"
paragrafi, ciascuno (o ogni gruppo di essi) seguito da un certo numero di
paragrafi ordinari/verbatim, altre regioni nidificate "=over" ... "=back", "=for..."
paragrafi e/o codici "=inizio"..."=fine". Nota che i numeri devono iniziare da 1
in ogni sezione, e deve procedere in ordine e senza saltare i numeri.

(I processori Pod devono tollerare righe come "=item 1" come se fossero "=item 1.",
con il punto.)

· Una regione "=over" ... "=back" contenente solo comandi "=item [testo]", ciascuno
(o ogni gruppo di essi) seguito da un certo numero di paragrafi ordinari/letterali,
altre regioni nidificate "=over" ... "=back" o "=per..." paragrafi e
regioni "=inizio"..."=fine".

Il paragrafo "=item [testo]" non deve corrispondere a "m/\A=item\s+\d+\.?\s*\z/" oppure
"m/\A=item\s+\*\s*\z/", né dovrebbe corrispondere solo a "m/\A=item\s*\z/".

· Una regione "=over" ... "=back" che non contiene alcun paragrafo "=item" e
contenente solo un certo numero di paragrafi ordinari/verbatili, ed eventualmente anche
alcune regioni nidificate "=over" ... "=back", "=per..." paragrafi e
regioni "=inizio"..."=fine". Una tale regione "=over" ... "=back" senza elementi in Pod lo è
equivalente nel significato di un " ... " elemento in HTML.

Nota che con tutti i casi precedenti, puoi determinare quale tipo di "=over" ...
"=back" hai, esaminando il primo paragrafo Pod (non-"=cut", non-"=pod") dopo
il comando "= sopra".

· Formattatori di pod devono obbligatoriamente: tollerare quantità arbitrariamente grandi di testo in "=item testo..."
paragrafo. In pratica, la maggior parte di questi paragrafi sono brevi, come in:

=item Per interrompere il nostro commercio con tutte le parti del mondo

Ma possono essere arbitrariamente lunghi:

=item Per trasportarci al di là dei mari da provare per finta
reati

=item In questo momento sta trasportando grandi eserciti di stranieri
mercenari per completare le opere di morte, desolazione e
tirannia, già iniziata con circostanze di crudeltà e perfidia
non ha quasi eguali nelle epoche più barbare, e totalmente
indegno capo di una nazione civile.

· I processori Pod dovrebbero tollerare "=item *" / "=item numero" comandi con n
paragrafo di accompagnamento. L'elemento centrale è un esempio:

=oltre

=elemento 1

Ritira il lavaggio a secco.

=elemento 2

=elemento 3

Passa in negozio. Prendi Abba Zabas, Stoli e sedie a sdraio economiche.

=indietro

· Nessuna regione "=over" ... "=back" può contenere intestazioni. I responsabili del trattamento possono trattare tale a
voce come un errore.

· Nota che una regione "=over" ... "=back" dovrebbe avere dei contenuti. Cioè, autori
non dovrebbe avere una regione vuota come questa:

=oltre

=indietro

I processori pod che vedono una tale regione "=over" ... "=back" priva di contenuto, potrebbero ignorarla o
potrebbe segnalarlo come un errore.

· I responsabili del trattamento devono tollerare un elenco "=over" che va alla fine del documento (ad es.
che non ha "=back" corrispondente), ma potrebbero avvertire di tale elenco.

· Gli autori dei formattatori di Pod devono tenere presente che questo costrutto:

=elemento Neque

=oggetto Porro

=elemento Quisquam Est

Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
velit, sed quia non numquam eius modi tempora incidunt ut
labore et dolore magnam aliquam quaerat voluptatem.

=elemento Ut Enim

è semanticamente ambiguo, in un modo che rende un po' difficili le decisioni di formattazione.
Da un lato, potrebbe essere menzione di un elemento "Neque", menzione di un altro elemento
"Porro", e menzione di un altro "Quisquam Est", con solo l'ultimo che richiede
il paragrafo esplicativo "Qui dolorem ipsum quia dolor..."; e poi una voce "Ut
Enim". In tal caso, vorresti formattarlo in questo modo:

Neque

spinello

Quisquam est
Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
velit, sed quia non numquam eius modi tempora incidunt ut
labore et dolore magnam aliquam quaerat voluptatem.

Ut Enim

Ma potrebbe anche trattarsi di una discussione su tre elementi (correlati o equivalenti),
"Neque", "Porro" e "Quisquam Est", seguiti da un paragrafo che li spiega tutti, e
poi una nuova voce "Ut Enim". In tal caso, probabilmente vorrai formattarlo in questo modo:

Neque
spinello
Quisquam est
Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
velit, sed quia non numquam eius modi tempora incidunt ut
labore et dolore magnam aliquam quaerat voluptatem.

Ut Enim

Ma (per il prossimo futuro), Pod non fornisce alcun modo agli autori di Pod
distinguere quale raggruppamento è inteso dalla struttura del cluster "=item" sopra. Così
i formattatori dovrebbero formattarlo in questo modo:

Neque

spinello

Quisquam est

Qui dolorem ipsum quia dolor sit amet, consectetur, adipisci
velit, sed quia non numquam eius modi tempora incidunt ut
labore et dolore magnam aliquam quaerat voluptatem.

Ut Enim

Cioè, dovrebbe esserci (almeno approssimativamente) una spaziatura uguale tra gli elementi come in mezzo
paragrafi (sebbene tale spaziatura possa essere inferiore all'intera altezza di una riga di
testo). Questo lascia al lettore la possibilità di usare indizi (con)testuali per capire se
il paragrafo "Qui dolorem ipsum..." si applica alla voce "Quisquam Est" oa tutte
tre voci "Neque", "Porro" e "Quisquam Est". Anche se non è una situazione ideale, questa
è preferibile fornire indicazioni di formattazione che potrebbero essere effettivamente contrarie al
intento dell'autore.

Chi Siamo Dati I paragrafi e "=inizio/=fine" Regioni

I paragrafi di dati vengono in genere utilizzati per incorporare dati non Pod che devono essere utilizzati (in genere
passato) durante il rendering del documento in un formato specifico:

= inizio rtf

\par{\pard\qr\sa4500{\i Stampato\~\chdate\~\chtime}\par}

=fine rtf

Lo stesso identico effetto potrebbe, per inciso, essere ottenuto con un singolo paragrafo "=per":

=per rtf \par{\pard\qr\sa4500{\i Stampato\~\chdate\~\chtime}\par}

(Sebbene non sia formalmente un paragrafo di dati, ha lo stesso significato di uno e Pod
i parser possono analizzarlo come uno.)

Un altro esempio di paragrafo dati:

=inizia html

mi piace la torta !

Soprattutto torta di noci pecan!

=fine html

Se questi fossero paragrafi ordinari, il parser Pod cercherebbe di espandere la "E" (nel
primo paragrafo) come codice di formattazione, proprio come "E " o "E ". Ma poiché questo
è in un "=inizio identificatore"..."=fine identificatore"regione e l'identificatore "html" non lo fa
iniziano ad avere un prefisso ":", i contenuti di questa regione sono memorizzati come paragrafi di dati,
invece di essere elaborati come normali paragrafi (o se iniziavano con spazi e/o
tabulazioni, come paragrafi letterali).

Come ulteriore esempio: al momento della scrittura, nessun identificatore "biblio" è supportato, ma supponiamo
alcuni elaboratori sono stati scritti per riconoscerlo come un modo (diciamo) di denotare un bibliografico
riferimento (necessariamente contenenti codici di formattazione nei paragrafi ordinari). Il fatto che
I paragrafi "biblio" destinati all'ordinaria elaborazione sarebbero indicati da prefazione
ogni identificatore "biblio" con i due punti:

=inizio :biblio

Wirth, Niklaus. 1976. I
Programmi.> Prentice-Hall, Englewood Cliffs, NJ.

=fine :biblio

Ciò segnalerebbe al parser che i paragrafi in questa regione inizio...fine sono soggetti a
trattamento normale come paragrafi ordinari/verbatili (sebbene ancora contrassegnati come destinati solo a
processori che comprendono l'identificatore "biblio"). Lo stesso effetto si potrebbe avere con:

=per :biblio
Wirth, Niklaus. 1976. I
Programmi.> Prentice-Hall, Englewood Cliffs, NJ.

Il ":" su questi identificatori significa semplicemente "elaborare questa roba normalmente, anche se il
il risultato sarà per un target speciale". Suggerisco che le API del parser riportino "biblio" come
l'identificatore di destinazione, ma segnala anche che aveva un prefisso ":". (E allo stesso modo, con il
sopra "html", riporta "html" come identificatore di destinazione e annota il mancanza di un prefisso ":".)

Nota che un "=begin identificatore"..."=fine identificatore" regione dove identificatore inizia con a
colon, può contengono comandi. Per esempio:

=inizio :biblio

Il classico di Wirth è disponibile in diverse edizioni, tra cui:

=per commento
hm, controlla abebooks.com per quanto costano le copie usate.

=oltre

= oggetto

Wirth, Niklaus. 1975. I
Teubner, Stoccarda. [Sì, è in tedesco.]

= oggetto

Wirth, Niklaus. 1976. I
Programmi.> Prentice-Hall, Englewood Cliffs, NJ.

=indietro

=fine :biblio

Nota, tuttavia, un "=begin identificatore"..."=fine identificatore" regione dove identificatore effettua non è un
iniziare con due punti, non dovrebbe contenere direttamente i comandi "=head1" ... "=head4", né
"=over", né "=back", né "=item". Ad esempio, questo può essere considerato non valido:

=comincia alcuni dati

Questo è un paragrafo di dati.

=head1 Non farlo!

Anche questo è un paragrafo di dati.

=fine alcuni dati

Un processore Pod può segnalare che quanto sopra (nello specifico il paragrafo "=head1") è un
errore. Si noti, tuttavia, che quanto segue dovrebbe non è un essere considerato un errore:

=comincia alcuni dati

Questo è un paragrafo di dati.

=tagliare

# Sì, questo non è più Pod.
sub escl { (rand() > .5) ? "hoo!" : "ah!" }

= pod

Anche questo è un paragrafo di dati.

=fine alcuni dati

E vale anche questo:

=comincia in qualche formato

Questo è un paragrafo di dati.

E questo è un paragrafo di dati.

=inizia in un altro formato

Anche questo è un paragrafo di dati.

E anche questo è un paragrafo di dati.

=inizio :ancorainformat

=head2 Questo è un paragrafo di comando!

Questo è un paragrafo normale!

E questo è un paragrafo letterale!

=fine :ancoraaltroformato

=fine con un altro formato

Un altro paragrafo di dati!

=finisci un formato

Il contenuto della precedente regione "=begin :yetanotherformat" ... "=end :yetanotherformat"
non lo sono paragrafi di dati, perché l'identificatore della regione immediatamente contenente
(":yetanotherformat") inizia con i due punti. In pratica, la maggior parte delle regioni che contengono dati
i paragrafi conterranno esclusivamente paragrafi di dati; tuttavia, la nidificazione di cui sopra è sintatticamente
valido come Pod, anche se raro. Tuttavia, i gestori per alcuni formati, come "html",
accetterà solo paragrafi di dati, non regioni nidificate; e possono lamentarsi se vedono
(mirati a loro) regioni nidificate o comandi diversi da "=end", "=pod" e "=cut".

Considera anche questa valida struttura:

=inizio :biblio

Il classico di Wirth è disponibile in diverse edizioni, tra cui:

=oltre

= oggetto

Wirth, Niklaus. 1975. I
Teubner, Stoccarda. [Sì, è in tedesco.]

= oggetto

Wirth, Niklaus. 1976. I
Programmi.> Prentice-Hall, Englewood Cliffs, NJ.

=indietro

Compra compra compra!

=inizia html





=fine html

Ora ora ora!

=fine :biblio

Lì, la regione "=begin html"..."=end html" è nidificata all'interno del più grande "=begin
:biblio"..."=end :biblio". Si noti che il contenuto della regione "=begin html"..."=end
html" è il paragrafo o i paragrafi di dati, poiché l'identificatore della regione che contiene immediatamente
("html") non iniziare con i due punti.

I parser di pod, quando elaborano una serie di paragrafi di dati uno dopo l'altro (all'interno di a
singola regione), dovrebbero considerarli come un paragrafo di dati di grandi dimensioni a cui capita
contengono righe vuote. Quindi il contenuto del precedente "=begin html"..."=end html" può be
memorizzati come due paragrafi di dati (uno composto da "
src='wirth_spokesmodeling_book.png'>\n" e un altro composto da " \n"), ma dovrebbero be
memorizzato come un unico paragrafo di dati (composto da "
src='wirth_spokesmodeling_book.png'>\n\n \n").

I processori pod dovrebbero tollerare "=begin qualcosa"..."=fine qualcosa" regioni, vuoto
"=inizio:qualcosa"..."=fine:qualcosa" regioni e senza contenuto "=per qualcosa" e
"=per:qualcosa" paragrafi. Vale a dire, questi dovrebbero essere tollerati:

=per HTML

=inizia html

=fine html

=inizio :biblio

=fine :biblio

Per inciso, nota che non esiste un modo semplice per esprimere un paragrafo di dati che inizia con
qualcosa che sembra un comando. Ritenere:

= Iniziare le cose

= Shazbot

= roba finale

Lì, "=shazbot" verrà analizzato come un comando Pod "shazbot", non come un paragrafo di dati
"=shazbot\n". Tuttavia, puoi esprimere un paragrafo di dati composto da "=shazbot\n" utilizzando
questo codice:

=per roba =shazbot

La situazione in cui ciò è necessario è presumibilmente piuttosto rara.

Nota che i comandi =end devono corrispondere al comando =begin attualmente aperto. Cioè, devono
nidificare correttamente. Ad esempio, questo è valido:

=inizio esterno

X

= inizio interiore

Y

=fine interiore

Z

=fine esterno

mentre questo non è valido:

=inizio esterno

X

= inizio interiore

Y

=fine esterno

Z

=fine interiore

Quest'ultimo è improprio perché quando viene visualizzato il comando "=end esterno", attualmente è aperto
la regione ha il nome di formato "interno", non "esterno". (Succede solo che "esterno" è il
nome del formato di una regione più in alto.) Questo è un errore. I processori devono per impostazione predefinita segnalare
questo come un errore e potrebbe interrompere l'elaborazione del documento contenente quell'errore. Un corollario
di questo è che le regioni non possono "sovrapporre". Cioè, l'ultimo blocco sopra non lo fa
rappresentano una regione chiamata "esterna" che contiene X e Y, sovrapponendosi a una regione chiamata
"inner" che contiene Y e Z. Ma perché non è valido (come tutti apparentemente sovrapposti
le regioni lo sarebbero), non rappresenta questo, o niente del tutto.

Allo stesso modo, questo non è valido:

= inizio cosa

=fine

Questo è un errore perché la regione viene aperta da "thing" e "=end" tenta di chiudersi
"hting" [sic].

Anche questo non è valido:

= inizio cosa

=fine

Questo non è valido perché ogni comando "=end" deve avere un parametro formatname.

Usa perlpodspec online usando i servizi onworks.net