perlpodspec - Dalam talian dalam Awan

JADUAL:

NAMA

perlpodspec - Dokumentasi Lama Biasa: spesifikasi format dan nota

DESCRIPTION

Dokumen ini adalah nota terperinci tentang bahasa penanda Pod. Kebanyakan orang hanya perlu melakukannya
baca perlpod untuk mengetahui cara menulis dalam Pod, tetapi dokumen ini mungkin menjawab beberapa perkara sampingan
soalan yang berkaitan dengan menghurai dan membuat Pod.

Dalam dokumen ini, "mesti" / "tidak boleh", "sepatutnya" / "tidak boleh", dan "boleh" mempunyai
konvensional (rujuk RFC 2119) bermaksud: "X mesti melakukan Y" bermakna jika X tidak melakukan Y, ia adalah
terhadap spesifikasi ini, dan harus benar-benar diperbaiki. "X sepatutnya melakukan Y" bermakna ia adalah
disyorkan, tetapi X mungkin gagal melakukan Y, jika ada sebab yang kukuh. "X boleh buat Y" hanyalah a
ambil perhatian bahawa X boleh melakukan Y sesuka hati (walaupun terpulang kepada pembaca untuk mengesan sebarang konotasi
"dan saya fikir ia akan menjadi baik jika X melakukan Y" berbanding "ia tidak akan benar mengganggu saya jika X melakukannya
Y").

Terutama, apabila saya menyebut "penghuraikan harus melakukan Y", penghurai mungkin gagal melakukan Y, jika panggilan
aplikasi secara eksplisit meminta penghurai tidak adakah Y. Saya sering menyebut ini sebagai "the
parser sepatutnya, secara lalai, melakukan Y." Ini tidak memerlukan penghurai untuk menyediakan pilihan
untuk mematikan apa sahaja ciri Y (seperti mengembangkan tab dalam perenggan verbatim),
walaupun ia membayangkan bahawa pilihan sedemikian mungkin disediakan.

Pod Definisi

Pod dibenamkan dalam fail, biasanya fail sumber Perl, walaupun anda boleh menulis fail
itu tidak lain hanyalah Pod.

A selaras dalam fail mengandungi sifar atau lebih aksara bukan baris baharu, ditamatkan oleh sama ada a
baris baharu atau penghujung fail.

A baris baru turutan biasanya merupakan konsep yang bergantung pada platform, tetapi penghurai Pod sepatutnya
fahami ia bermaksud mana-mana CR (ASCII 13), LF (ASCII 10), atau CRLF (ASCII 13 diikuti
serta-merta oleh ASCII 10), sebagai tambahan kepada sebarang makna khusus sistem yang lain. Yang pertama
Urutan CR/CRLF/LF dalam fail boleh digunakan sebagai asas untuk mengenal pasti baris baharu
urutan untuk menghuraikan seluruh fail.

A kosong selaras ialah garis yang terdiri sepenuhnya daripada sifar atau lebih ruang (ASCII 32) atau tab
(ASCII 9), dan ditamatkan oleh baris baharu atau akhir fail. A tidak kosong selaras ialah garisan
mengandungi satu atau lebih aksara selain daripada ruang atau tab (dan ditamatkan oleh baris baharu atau
akhir fail).

(Catatan: Banyak penghurai Pod yang lebih lama tidak menerima baris yang terdiri daripada ruang/tab dan kemudian a
baris baharu sebagai baris kosong. Satu-satunya baris yang mereka anggap kosong ialah baris yang terdiri daripada tidak
aksara at semua, ditamatkan oleh baris baharu.)

Whitespace digunakan dalam dokumen ini sebagai istilah selimut untuk ruang, tab dan baris baharu
urutan. (Dengan sendirinya, istilah ini biasanya merujuk kepada ruang kosong literal. Iaitu,
jujukan aksara ruang putih dalam sumber Pod, berbanding "E<32>", yang merupakan
kod pemformatan yang menandakan watak ruang putih.)

A Pod parser ialah modul yang dimaksudkan untuk menghuraikan Pod (tidak kira sama ada ini melibatkan
memanggil panggilan balik atau membina pokok parse atau memformatkannya secara terus). A Pod pemformat
(Atau Pod penterjemah) ialah modul atau program yang menukar Pod kepada beberapa format lain (HTML,
plaintext, TeX, PostScript, RTF). A Pod pemproses mungkin seorang pemformat atau penterjemah, atau
mungkin program yang melakukan sesuatu yang lain dengan Pod (seperti mengira perkataan, mengimbas
untuk mata indeks, dsb.).

Kandungan pod terkandung dalam Pod blok. Blok Pod bermula dengan garisan yang sepadan
"m/\A=[a-zA-Z]/", dan meneruskan sehingga ke baris seterusnya yang sepadan dengan "m/\A=cut/" atau sehingga ke
hujung fail jika tiada baris "m/\A=cut/".

Dalam blok Pod, terdapat Pod perenggan. Perenggan Pod terdiri daripada baris bukan kosong
teks, dipisahkan oleh satu atau lebih baris kosong.

Untuk tujuan pemprosesan Pod, terdapat empat jenis perenggan dalam blok Pod:

· Perenggan arahan (juga dipanggil "arahan"). Baris pertama perenggan ini
mesti sepadan dengan "m/\A=[a-zA-Z]/". Perenggan arahan biasanya satu baris, seperti dalam:

=head1 CATATAN

=item *

Tetapi mereka mungkin menjangkau beberapa baris (tidak kosong):

=untuk komen
Hm, saya tertanya-tanya bagaimana rupanya jika
anda cuba menulis BNF untuk Pod daripada ini.

=head3 Dr Strangelove, atau: Bagaimana Saya Belajar
Berhenti Bimbang dan Suka Bom

Sesetengah perenggan arahan membenarkan pemformatan kod dalam kandungannya (iaitu, selepas bahagian
yang sepadan dengan "m/\A=[a-zA-Z]\S*\s*/"), seperti dalam:

=head1 Adakah Anda Ingat C ?

Dengan kata lain, pengendali pemprosesan Pod untuk "head1" akan menggunakan pemprosesan yang sama
kepada "Adakah Anda Ingat C ?" bahawa ia akan menjadi perenggan biasa (iaitu,
kod pemformatan seperti "C<...>") dihuraikan dan mungkin diformatkan dengan sewajarnya, dan
ruang putih dalam bentuk ruang literal dan/atau tab tidak penting.

· AT kata demi kata perenggan. Baris pertama perenggan ini mestilah ruang literal atau
tab, dan perenggan ini mestilah tidak berada di dalam "=begin pengecam", ... "=tamat
pengecam"urutan melainkan"pengecam" bermula dengan titik bertindih (":"). Iaitu, jika a
perenggan bermula dengan ruang atau tab literal, tetapi is di dalam "=begin pengecam",...
"=akhir pengecam"rantau, maka ia adalah perenggan data, melainkan "pengecam" bermula dengan
kolon.

Whitespace is penting dalam perenggan verbatim (walaupun, dalam pemprosesan, tab adalah
mungkin berkembang).

· An biasa perenggan. Perenggan ialah perenggan biasa jika baris pertamanya sepadan
bukan "m/\A=[a-zA-Z]/" mahupun "m/\A[ \t]/", and jika ia tidak berada di dalam "=begin
pengecam", ... "=tamat pengecam"urutan melainkan"pengecam"bermula dengan kolon
(":").

· AT data perenggan. Ini adalah perenggan yang is di dalam "=begin pengecam" ... "=tamat
pengecam"urutan di mana"pengecam" adakah tidak mulakan dengan titik bertindih literal (":"). Dalam
entah bagaimana, perenggan data bukan sebahagian daripada Pod sama sekali (iaitu, secara berkesan ia "keluar-
of-band"), kerana ia tidak tertakluk kepada kebanyakan jenis penghuraian Pod; tetapi ia ditentukan
di sini, kerana penghurai Pod perlu boleh memanggil acara untuknya, atau menyimpannya dalam beberapa
bentuk dalam pokok parse, atau sekurang-kurangnya hanya parse sekitar ia.

Sebagai contoh: pertimbangkan perenggan berikut:

# <- itu lajur ke-0

=kepala1 Foo

Stuff

$foo->bar

= potong

Di sini, "=head1 Foo" dan "=cut" ialah perenggan arahan kerana setiap baris pertama
sepadan dengan "m/\A=[a-zA-Z]/". "[ruang][ruang]$foo->bar" ialah perenggan verbatim, kerana ia
baris pertama bermula dengan aksara ruang kosong literal (dan tiada "=mula"..."=akhir"
kawasan sekitar).

"=mulakan pengecam" ... "=tamat pengecam" perintah menghentikan perenggan yang mereka kelilingi
daripada dihuraikan sebagai perenggan biasa atau verbatim, jika pengecam tidak bermula dengan a
kolon. Ini dibincangkan secara terperinci dalam bahagian "Mengenai Perenggan Data dan
"=mula/=akhir" Kawasan".

Pod arahan

Bahagian ini bertujuan untuk menambah dan menjelaskan perbincangan dalam "Perenggan Perintah"
dalam perlpod. Ini adalah arahan Pod yang diiktiraf pada masa ini:

"=head1", "=head2", "=head3", "=head4"
Perintah ini menunjukkan bahawa teks dalam baki perenggan adalah tajuk.
Teks itu mungkin mengandungi kod pemformatan. Contoh:

=head1 Atribut Objek

=head3 Apa B untuk Lakukan!

"=pod"
Perintah ini menunjukkan bahawa perenggan ini memulakan blok Pod. (Jika kita sudah masuk
tengah blok Pod, arahan ini tidak mempunyai kesan sama sekali.) Jika terdapat sebarang teks
dalam perenggan arahan ini selepas "=pod", ia mesti diabaikan. Contoh:

=pod

Ini ialah perenggan Pod biasa.

=pod Teks ini diabaikan.

"=potong"
Perintah ini menunjukkan bahawa baris ini adalah penghujung blok Pod yang dimulakan sebelum ini.
Jika terdapat sebarang teks selepas "=cut" pada baris, ia mesti diabaikan. Contoh:

= potong

=cut Dokumentasi berakhir di sini.

= potong
# Ini ialah baris pertama teks program.
sub foo { # Ini adalah yang kedua.

Ia adalah satu kesilapan untuk mencuba permulaan blok Pod dengan arahan "=cut". Dalam kes itu, yang
Pemproses pod mesti menghentikan penghuraian fail input, dan mesti secara lalai mengeluarkan amaran.

"=over"
Perintah ini menunjukkan bahawa ini adalah permulaan senarai/rantau inden. Jika ada
mana-mana teks yang mengikuti "=over", ia mesti mengandungi hanya angka positif bukan sifar.
Semantik angka ini dijelaskan dalam "Perihal =over...=back Regions"
bahagian, lebih jauh di bawah. Kod pemformatan tidak dikembangkan. Contoh:

=lebih 3

=lebih 3.5

= berakhir

"=item"
Perintah ini menunjukkan bahawa item dalam senarai bermula di sini. Kod pemformatan ialah
telah di proses. Semantik teks (pilihan) dalam baki perenggan ini
dijelaskan dalam bahagian "Perihal =over...=back Regions", lebih jauh di bawah. Contoh:

=item

=item *

=item *

=item 14

=item 3.

=item C<< $benda->barang(I ) >>

=item Untuk mengangkut kami ke luar laut untuk dicuba untuk berpura-pura
kesalahan

=item Dia pada masa ini mengangkut tentera asing yang besar
tentera upahan untuk menyelesaikan kerja-kerja kematian, kebinasaan dan
kezaliman, sudah dimulakan dengan keadaan kezaliman dan kezaliman
hampir tidak sejajar pada zaman yang paling biadab, dan sama sekali
tidak layak menjadi ketua negara yang bertamadun.

"=belakang"
Perintah ini menunjukkan bahawa ini adalah penghujung wilayah yang dimulakan oleh yang paling terkini
arahan "=over". Ia tidak membenarkan teks selepas arahan "=back".

"=mulakan nama format"
"=mulakan parameter nama format"
Ini menandakan perenggan berikut (sehingga padanan "=nama format akhir") sebagai wujud
untuk beberapa jenis pemprosesan khas. Melainkan "nama format" bermula dengan titik bertindih, the
yang terkandung perenggan bukan perintah ialah perenggan data. Tetapi jika "nama format" tidak memulakan
dengan bertindih, maka perenggan bukan perintah ialah perenggan biasa atau perenggan data.
Ini dibincangkan secara terperinci dalam bahagian "Perihal Perenggan Data dan "=mula/=akhir"
Kawasan".

Adalah dinasihatkan bahawa nama format sepadan dengan regexp "m/\A:?[-a-zA-Z0-9_]+\z/". Semuanya
ruang kosong berikut selepas nama format ialah parameter yang boleh digunakan oleh
pemformat apabila berurusan dengan rantau ini. Parameter ini tidak boleh diulang dalam
"=end" perenggan. Pelaksana harus menjangka pengembangan masa depan dalam semantik
dan sintaks parameter pertama kepada "=begin"/"=end"/"=for".

"=nama format akhir"
Ini menandakan penghujung rantau yang dibuka oleh rantau "=mulakan formatname" yang sepadan.
Jika "nama format" bukan nama format bagi nama format "=begin formatname" yang paling terkini
rantau, maka ini adalah ralat, dan mesti menjana mesej ralat. Ini dibincangkan
secara terperinci dalam bahagian "Perihal Perenggan Data dan "=mula/=akhir" Wilayah".

"=untuk teks nama format..."
Ini sinonim dengan:

=mulakan nama format

teks ...

=nama format akhir

Iaitu, ia mewujudkan wilayah yang terdiri daripada satu perenggan; perenggan itu adalah untuk menjadi
dianggap sebagai perenggan biasa jika "nama format" bermula dengan ":"; jika "nama format"
tidak mulakan dengan titik bertindih, kemudian "teks..." akan membentuk perenggan data. Terdapat
tiada cara untuk menggunakan "=for formatname text..." untuk menyatakan "teks..." sebagai perenggan verbatim.

"=pengekodan nama pengekodan"
Perintah ini, yang sepatutnya berlaku awal dalam dokumen (sekurang-kurangnya sebelum mana-mana bukan AS-
Data ASCII!), mengisytiharkan bahawa dokumen ini dikodkan dalam pengekodan nama pengekodan,
yang mestilah nama pengekodan yang dikenali oleh Encode. (Senarai Encode yang disokong
pengekodan, dalam Encode::Supported, berguna di sini.) Jika parser Pod tidak boleh menyahkod
pengekodan yang diisytiharkan, ia sepatutnya mengeluarkan amaran dan mungkin membatalkan penghuraian dokumen
sama sekali.

Dokumen yang mempunyai lebih daripada satu baris "=encoding" harus dianggap sebagai ralat. Pod
pemproses boleh bertolak ansur dengan ini secara senyap jika baris "=pengekodan" bukan pertama adalah adil
pendua yang pertama (cth, jika terdapat baris "=encoding utf8", dan kemudiannya
satu lagi baris "=encoding utf8"). Tetapi pemproses Pod harus mengadu jika ada
baris "=encoding" bercanggah dalam dokumen yang sama (cth, jika terdapat "=encoding
utf8" pada awal dokumen dan "=encoding big5" kemudiannya). Pod pemproses itu
mengenali BOM juga mungkin mengadu jika mereka melihat baris "=pengekodan" yang bercanggah dengan
BOM (cth, jika dokumen dengan BOM UTF-16LE mempunyai baris "=encoding shiftjis").

Jika pemproses Pod melihat sebarang arahan selain daripada yang disenaraikan di atas (seperti "=head", atau
"=haed1", atau "=stuff", atau "=sotong", atau "=w123"), pemproses itu mesti secara lalai merawat
ini sebagai kesilapan. Ia tidak boleh memproses perenggan yang bermula dengan arahan itu, mesti dengan
lalai memberi amaran tentang ini sebagai ralat, dan boleh membatalkan penghuraian. Penghurai Pod mungkin membenarkan jalan
untuk aplikasi tertentu untuk menambah senarai arahan yang diketahui di atas, dan untuk menetapkan,
untuk setiap arahan tambahan, sama ada kod pemformatan perlu diproses.

Versi masa depan spesifikasi ini boleh menambah arahan tambahan.

Pod Pemformatan Kod

(Perhatikan bahawa dalam draf terdahulu dokumen ini dan perlpod, kod pemformatan ialah
dirujuk sebagai "urutan dalaman", dan istilah ini masih boleh ditemui dalam dokumentasi
untuk penghurai Pod, dan dalam mesej ralat daripada pemproses Pod.)

Terdapat dua sintaks untuk memformat kod:

· Kod pemformatan bermula dengan huruf besar (hanya US-ASCII [AZ]) diikuti dengan a
"<", sebarang bilangan aksara, dan berakhir dengan padanan pertama ">". Contoh:

Itu yang saya fikir!

Apa itu C untuk?

X dan C Di bawah Sistem Operasi Berbeza>

· Kod pemformatan bermula dengan huruf besar (hanya US-ASCII [AZ]) diikuti dengan dua
atau lebih "<", satu atau lebih aksara ruang putih, sebarang bilangan aksara, satu atau
lebih banyak aksara ruang putih, dan berakhir dengan jujukan padanan pertama dua atau lebih
">", di mana bilangan ">" sama dengan bilangan "<" dalam pembukaan ini
kod pemformatan. Contoh:

Itulah yang saya<< anda >> fikirkan!

C<<< buka(X, ">>thing.dat") || mati $! >>>

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

Dengan sintaks ini, aksara ruang putih selepas "C<<<<" dan sebelum ">>>"
(atau apa sahaja surat). tidak boleh render. Mereka tidak menandakan ruang kosong, adalah semata-mata
sebahagian daripada kod pemformatan itu sendiri. Iaitu, ini semua sinonim:

C
C<< perkara >>
C<< perkara >>
C<<<< perkara >>>
C<<<<
perkara
>>>>

dan sebagainya.

Akhirnya, bentuk kurungan berbilang sudut berfungsi tidak mengubah tafsiran bersarang
kod pemformatan, bermakna empat baris contoh berikut adalah sama dalam
bermaksud:

B =E $b>>

B $b >>>

B =E $b >>>

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

Dalam menghuraikan Pod, bahagian yang sangat rumit ialah penghuraian yang betul bagi (berpotensi bersarang!)
kod pemformatan. Pelaksana harus merujuk kod dalam rutin "parse_text" dalam
Pod::Parser sebagai contoh pelaksanaan yang betul.

"Saya " -- teks condong
Lihat perbincangan ringkas dalam "Kod Pemformatan" dalam perlpod.

"B " -- teks tebal
Lihat perbincangan ringkas dalam "Kod Pemformatan" dalam perlpod.

"C " -- code text
Lihat perbincangan ringkas dalam "Kod Pemformatan" dalam perlpod.

"F " -- gaya untuk nama fail
Lihat perbincangan ringkas dalam "Kod Pemformatan" dalam perlpod.

"X " -- entri indeks
Lihat perbincangan ringkas dalam "Kod Pemformatan" dalam perlpod.

Kod ini adalah luar biasa kerana kebanyakan pemformat membuang sepenuhnya kod ini dan kodnya
kandungan. Pemformat lain akan memaparkannya dengan kod halimunan yang boleh digunakan
membina indeks dokumen semasa.

"Z<>" -- kod pemformatan nol (kesan sifar).
Dibincangkan secara ringkas dalam "Kod Pemformatan" dalam perlpod.

Kod ini adalah luar biasa kerana ia sepatutnya tidak mempunyai kandungan. Iaitu, pemproses boleh
mengeluh jika ia melihat "Z ". Sama ada ia merungut atau tidak, yang kentang teks
patut diabaikan.

"L "-- hiperpautan
Sintaks rumit kod ini dibincangkan dengan panjang lebar dalam "Kod Pemformatan" dalam
perlpod, dan butiran pelaksanaan dibincangkan di bawah, dalam "Perihal L<...> Kod".
Menghuraikan kandungan L adalah rumit. Terutamanya, kandungannya perlu disemak
untuk sama ada ia kelihatan seperti URL atau sama ada ia perlu dipisahkan pada literal "|" dan/atau
"/" (dalam susunan yang betul!), dan seterusnya, sebelum E<...> kod telah diselesaikan.

"E " -- pelarian watak
Lihat "Kod Pemformatan" dalam perlpod dan beberapa perkara dalam "Nota Melaksanakan Pod
Pemproses".

"S " -- teks mengandungi ruang yang tidak pecah
Kod pemformatan ini secara sintaksis mudah, tetapi kompleks dari segi semantik. Apa maksudnya
ialah setiap ruang dalam kandungan boleh cetak kod ini menandakan tidak pecah
ruang.

Pertimbangkan:

C<$x ? $y : $z>

S >

Kedua-duanya menandakan teks monospace (gaya c[ode]) yang terdiri daripada "$x", satu ruang, "?", satu
ruang, ":", satu ruang, "$z". Perbezaannya ialah dalam yang terakhir, dengan kod S,
ruang tersebut bukan ruang "biasa", sebaliknya adalah ruang yang tidak pecah.

Jika pemproses Pod melihat sebarang kod pemformatan selain daripada yang disenaraikan di atas (seperti dalam
"N<...>", atau "Q<...>", dsb.), pemproses itu mesti secara lalai menganggap ini sebagai ralat. A
Penghurai Pod mungkin membenarkan cara untuk aplikasi tertentu ditambahkan pada senarai yang diketahui di atas
kod pemformatan; penghurai Pod mungkin membenarkan cara untuk menetapkan, untuk setiap tambahan
perintah, sama ada ia memerlukan beberapa bentuk pemprosesan khas, seperti yang dilakukan oleh L<...>.

Versi masa depan spesifikasi ini mungkin menambah kod pemformatan tambahan.

Nota sejarah: Beberapa pemproses Pod yang lebih lama tidak akan melihat ">" sebagai menutup kod "C<",
jika ">" segera didahului dengan "-". Ini adalah supaya ini:

C<$foo->bar>

akan menghuraikan sebagai bersamaan dengan ini:

C<$foo-E bar>

bukannya setara dengan kod pemformatan "C" yang mengandungi hanya "$foo-", dan kemudian a
"bar>" di luar kod pemformatan "C". Masalah ini telah diselesaikan oleh
penambahan sintaks seperti ini:

C<< $foo->bar >>

Penghurai yang patuh tidak boleh menganggap "->" sebagai istimewa.

Kod pemformatan sama sekali tidak boleh menjangkau perenggan. Jika kod dibuka dalam satu perenggan,
dan tiada kod penutup ditemui pada penghujung perenggan itu, penghurai Pod mesti menutupnya
kod pemformatan, dan harus mengadu (seperti dalam "Kod Saya Tidak Ditamatkan dalam perenggan bermula
pada baris 123: 'Objek masa bukan...'"). Jadi dua perenggan ini:

saya

Jangan buat saya cakap lagi!>

... mesti tidak dihuraikan sebagai dua perenggan dalam huruf condong (dengan kod I bermula dalam satu
perenggan dan bermula dengan perenggan lain.) Sebaliknya, perenggan pertama harus menjana a
amaran, tetapi selain itu, kod di atas mesti menghuraikan seolah-olah:

saya

Jangan buat saya mengulanginya lagi!E

(Dalam jargon SGMLish, semua arahan Pod adalah seperti elemen peringkat blok, manakala semua Pod
kod pemformatan adalah seperti elemen peringkat sebaris.)

Nota on Melaksanakan Pod Pemproses

Berikut ialah bahagian panjang pelbagai keperluan dan cadangan untuk dilakukan
Pemprosesan pod.

· Pemformat pod harus bertolak ansur dengan baris dalam blok verbatim yang mempunyai sebarang panjang, walaupun
jika itu bermakna perlu memecahkan mereka (mungkin beberapa kali, untuk baris yang sangat panjang) untuk
elakkan teks lari dari sisi halaman. Pemformat pod boleh memberi amaran tentang baris tersebut-
berbuka. Amaran sedemikian amat sesuai untuk talian melebihi 100
aksara panjang, yang biasanya tidak disengajakan.

· Penghurai pod mesti mengenali semua daripada tiga format baris baharu yang terkenal: CR, LF dan
CRLF. Lihat perlport.

· Penghurai pod harus menerima baris input yang mempunyai sebarang panjang.

· Memandangkan Perl mengenali Tanda Pesanan Bait Unicode pada permulaan fail sebagai isyarat
bahawa fail itu dikodkan Unicode seperti dalam UTF-16 (sama ada big-endian atau little-endian) atau
UTF-8, Penghurai Pod harus melakukan perkara yang sama. Jika tidak, pengekodan aksara sepatutnya
difahami sebagai UTF-8 jika jujukan bait tinggi bit pertama dalam fail kelihatan sah
sebagai urutan UTF-8, atau sebaliknya sebagai CP-1252 (versi awal spesifikasi ini
menggunakan Latin-1 dan bukannya CP-1252).

Versi masa depan spesifikasi ini mungkin menentukan cara Pod boleh menerima pengekodan lain.
Mungkin rawatan pengekodan lain dalam penghuraian Pod adalah seperti dalam penghuraian XML:
apa sahaja pengekodan yang diisytiharkan oleh fail Pod tertentu, kandungan perlu disimpan
ingatan sebagai aksara Unicode.

· Tanda Perintah Unicode Byte yang terkenal adalah seperti berikut: jika fail bermula dengan
dua nilai bait literal 0xFE 0xFF, ini ialah BOM untuk big-endian UTF-16. Jika fail
bermula dengan dua nilai bait literal 0xFF 0xFE, ini ialah BOM untuk little-endian
UTF-16. Pada platform ASCII, jika fail bermula dengan tiga nilai bait literal
0xEF 0xBB 0xBF, ini ialah BOM untuk UTF-8. Mekanisme mudah alih ke platform EBCDIC
adalah untuk:

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

· Heuristik yang naif, tetapi selalunya mencukupi pada platform ASCII, untuk menguji yang pertama
jujukan bait tinggi dalam fail tanpa BOM (sama ada dalam kod atau dalam Pod!), untuk melihat sama ada
jujukan itu sah kerana UTF-8 (RFC 2279) adalah untuk menyemak sama ada bait pertama dalam
jujukan adalah dalam julat 0xC2 - 0xFD and sama ada bait seterusnya berada dalam julat
0x80 - 0xBF. Jika ya, penghurai boleh membuat kesimpulan bahawa fail ini berada dalam UTF-8, dan semua
jujukan highbit dalam fail harus diandaikan sebagai UTF-8. Jika tidak penghurai
harus menganggap fail sebagai dalam CP-1252. (Semakan yang lebih baik, dan yang berfungsi pada EBCDIC
platform juga, adalah untuk menghantar salinan urutan kepada utf8::decode() yang membuat persembahan
semakan kesahihan penuh pada jujukan dan mengembalikan BENAR jika ia sah UTF-8, FALSE
sebaliknya. Fungsi ini sentiasa pramuat, pantas kerana ia ditulis dalam C,
dan hanya akan dipanggil paling banyak sekali, jadi anda tidak perlu mengelak daripadanya
kebimbangan prestasi.) Dalam keadaan yang tidak mungkin bahawa jujukan highbit pertama
dalam fail yang benar-benar bukan UTF-8 kebetulan kelihatan seperti UTF-8, seseorang boleh memenuhi keperluan kami
heuristik (serta mana-mana heuristik yang lebih pintar) dengan mendahului baris itu dengan a
baris komen yang mengandungi jujukan highbit yang jelas tidak sah sebagai UTF-8. Satu baris
hanya terdiri daripada "#", e-acute, dan sebarang bait bukan highbit, adalah memadai untuk
wujudkan pengekodan fail ini.

· Pemproses pod mesti menganggap perenggan "=untuk [label] [kandungan...]" sebagai maksud yang sama
perkara sebagai perenggan "=mulakan [label]", kandungan dan perenggan "=akhir [label]". (The
parser boleh menggabungkan kedua-dua binaan ini, atau mungkin meninggalkannya berbeza, dalam
jangkaan bahawa pemformat akan melayan mereka sama.)

· Apabila memaparkan Pod kepada format yang membenarkan komen (iaitu, kepada hampir mana-mana format lain
daripada plaintext), pemformat Pod mesti memasukkan teks ulasan yang mengenal pasti namanya dan
nombor versi, dan nama serta nombor versi mana-mana modul yang mungkin digunakan untuknya
memproses Pod. Contoh minima:

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



{\doccomm dijana oleh Pod::Tree::RTF 3.14159 menggunakan Pod::Tree 1.08}

.\" Pod::Man versi 3.14159, menggunakan POD::Parser versi 1.92

Pemformat juga boleh memasukkan ulasan tambahan, termasuk: tarikh keluaran Pod
program pemformat, alamat hubungan untuk pengarang pemformat, semasa
masa, nama fail input, pilihan pemformatan yang berkuat kuasa, versi Perl yang digunakan,
dan lain-lain.

Pemformat juga boleh memilih untuk mencatat ralat/amaran sebagai ulasan, selain atau sebaliknya
memancarkannya sebaliknya (seperti dalam mesej kepada STDERR, atau "mati").

· Penghurai pod mungkin mengeluarkan amaran atau mesej ralat ("Kod E tidak diketahui E !") kepada STDERR
(sama ada melalui cetakan ke STDERR, atau "amaran"/"carp"ing, atau "die"ing/"croak"ing),
tetapi kemestian membenarkan menyekat semua output STDERR tersebut, dan sebaliknya membenarkan pilihan untuk
melaporkan ralat/amaran dalam beberapa cara lain, sama ada dengan mencetuskan panggilan balik, atau
mencatat ralat dalam beberapa atribut objek dokumen, atau beberapa yang sama tidak mengganggu
mekanisme -- atau pun dengan menambahkan bahagian "Ralat Pod" pada penghujung borang yang dihuraikan
dokumen itu.

· Dalam kes dokumen yang sangat menyimpang, penghurai Pod boleh membatalkan penghuraian. Malah
maka, menggunakan "mati"ing/"croak"ing harus dielakkan; jika boleh, perpustakaan parser
hanya boleh menutup fail input dan menambah teks seperti "*** Memformat Dibatalkan ***" pada
akhir dokumen dalam ingatan (separa).

· Dalam perenggan di mana kod pemformatan (seperti E<...>, B<...>) difahami (iaitu, tidak
perenggan verbatim, tetapi termasuk perenggan biasa, dan perenggan perintah yang
menghasilkan teks boleh render, seperti "=head1"), ruang kosong literal sepatutnya
dianggap "tidak penting", dalam satu ruang literal mempunyai makna yang sama seperti mana-mana
(bukan sifar) bilangan ruang literal, baris baharu literal dan tab literal (selagi
ini tidak menghasilkan baris kosong, kerana ia akan menamatkan perenggan). Penghurai pod
hendaklah padat ruang kosong literal dalam setiap perenggan yang diproses, tetapi mungkin memberikan satu
pilihan untuk mengatasi ini (kerana beberapa tugas pemprosesan tidak memerlukannya), atau mungkin
ikut peraturan khas tambahan (contohnya, merawat khusus ruang-ruang atau
urutan baris-baharu).

· Penghurai pod tidak seharusnya, secara lalai, cuba memaksa apostrof (') dan petikan (") ke dalam
petikan pintar (9 kecil, 66, 99, dsb), dan jangan cuba menukar tanda belakang (`) kepada apa-apa
selain daripada satu watak backtick (berbeza dengan watak petikan terbuka!), mahupun
"--" menjadi apa-apa kecuali dua tanda tolak. mereka kemestian pernah melakukan mana-mana perkara itu untuk
teks dalam kod pemformatan C<...> dan tidak sekali-kali pernah kepada teks dalam perenggan verbatim.

· Apabila memaparkan Pod kepada format yang mempunyai dua jenis sempang (-), satu yang bukan-
sempang pecah, dan satu lagi sempang boleh pecah (seperti dalam "berorientasikan objek", yang
boleh dibahagikan merentasi baris sebagai "objek-", baris baharu, "berorientasikan"), pemformat adalah
digalakkan untuk secara amnya menterjemah "-" kepada tanda sempang tidak putus, tetapi mungkin menggunakan heuristik
untuk menukar sebahagian daripada ini kepada tanda sempang putus.

· Pemformat pod harus membuat usaha yang munasabah untuk mengekalkan perkataan kod Perl daripada wujud
dipecahkan merentasi garisan. Contohnya, "Foo::Bar" dalam beberapa sistem pemformatan dilihat sebagai
layak untuk dipecahkan merentasi baris sebagai "Foo::" baris baharu "Bar" atau pun "Foo::-"
baris baharu "Bar". Ini harus dielakkan jika boleh, sama ada dengan melumpuhkan semua talian-
memecahkan pertengahan perkataan, atau dengan membungkus perkataan tertentu dengan tanda baca dalaman
kod "jangan pecahkan ini merentasi baris" (yang dalam sesetengah format mungkin bukan satu kod,
tetapi mungkin masalah memasukkan ruang lebar sifar yang tidak putus antara setiap pasangan
watak dalam satu perkataan.)

· Penghurai pod harus, secara lalai, mengembangkan tab dalam perenggan verbatim sebagaimana adanya
diproses, sebelum menghantarnya kepada pemformat atau pemproses lain. Penghurai juga boleh
benarkan pilihan untuk mengatasi ini.

· Penghurai pod hendaklah, secara lalai, mengalih keluar baris baharu dari penghujung biasa dan kata demi kata
perenggan sebelum menyerahkannya kepada pemformat. Contohnya, manakala perenggan
yang anda baca sekarang boleh dipertimbangkan, dalam sumber Pod, untuk diakhiri dengan (dan mengandungi)
baris baharu yang mengakhirinya, ia harus diproses sebagai berakhir dengan (dan mengandungi) baris
watak zaman yang mengakhiri ayat ini.

· Penghurai pod, apabila melaporkan ralat, harus berusaha sedikit untuk melaporkan anggaran
nombor baris ("Nested E<>'s dalam Perenggan #52, berhampiran baris 633 Thing/Foo.pm!"), sebaliknya
dengan hanya mencatat nombor perenggan ("Nested E<>'s dalam Perenggan #52 daripada
Thing/Foo.pm!"). Jika ini bermasalah, nombor perenggan hendaklah sekurang-kurangnya
disertakan dengan petikan daripada perenggan ("Nested E<>'s dalam Perenggan #52 daripada
Thing/Foo.pm, yang memulakan 'Baca/tulis aksesori untuk C
atribut...'").

· Penghurai pod, apabila memproses satu siri perenggan verbatim satu demi satu, harus
menganggapnya sebagai satu perenggan verbatim besar yang kebetulan mengandungi baris kosong.
Iaitu, dua baris ini, yang mempunyai garis kosong di antaranya:

gunakan Foo;

cetak Foo->VERSION

hendaklah disatukan menjadi satu perenggan ("\tuse Foo;\n\n\tprint Foo->VERSION") sebelum
dihantar kepada pemformat atau pemproses lain. Penghurai juga boleh membenarkan pilihan
untuk mengatasi ini.

Walaupun ini mungkin terlalu menyusahkan untuk dilaksanakan dalam penghurai Pod berasaskan acara, ia adalah
mudah untuk penghurai yang mengembalikan pokok penghuraian.

· Pemformat pod, jika boleh, dinasihatkan untuk mengelakkan pemisahan kata kerja pendek
perenggan (di bawah dua belas baris, katakan) merentas halaman.

· Penghurai pod mesti menganggap baris dengan hanya ruang dan/atau tab padanya sebagai "garisan kosong"
seperti memisahkan perenggan. (Sesetengah penghurai lama hanya mengenali dua yang bersebelahan
baris baharu sebagai "baris kosong" tetapi tidak akan mengenali baris baharu, ruang dan baris baharu,
sebagai baris kosong. Ini adalah tingkah laku tidak patuh.)

· Pengarang pemformat/pemproses Pod harus berusaha sedaya upaya untuk mengelak daripada menulis mereka
Penghurai Pod sendiri. Sudah terdapat beberapa dalam CPAN, dengan pelbagai antara muka
gaya -- dan salah satu daripadanya, Pod::Parser, disertakan dengan versi moden Perl.

· Aksara dalam dokumen Pod boleh disampaikan sama ada secara literal, atau dengan nombor dalam E
kod, atau dengan mnemonik yang setara, seperti dalam E yang betul-betul setara dengan
E<233>. Nombor tersebut ialah nilai Latin1/Unicode, walaupun pada platform EBCDIC.

Apabila merujuk kepada aksara dengan menggunakan E kod angka, nombor dalam julat 32-126
rujuk kepada aksara AS-ASCII yang terkenal itu (juga ditakrifkan di sana oleh Unicode, dengan
maksud yang sama), yang mesti diberikan oleh semua pemformat Pod dengan betul. Watak yang E<>
nombor berada dalam julat 0-31 dan 127-159 tidak boleh digunakan (bukan sebagai literal,
mahupun sebagai E kod), kecuali untuk jujukan bait literal untuk baris baharu (ASCII 13,
ASCII 13 10, atau ASCII 10), dan tab (ASCII 9).

Nombor dalam julat 160-255 merujuk kepada aksara Latin-1 (juga ditakrifkan di sana oleh
Unicode, dengan maksud yang sama). Nombor di atas 255 harus difahami untuk merujuk
aksara Unikod.

· Beri amaran bahawa sesetengah pemformat tidak boleh menghasilkan aksara di luar 32-126 dengan pasti; dan
ramai yang mampu mengendalikan 32-126 dan 160-255, tetapi tiada yang melebihi 255.

· Selain yang terkenal "E " dan "E " kod untuk kurang daripada dan lebih besar daripada, Pod
penghurai mesti memahami "E " untuk "/" (solidus, slash), dan "E " untuk "|"
(bar menegak, paip). Penghurai pod juga harus memahami "E "dan
"E " sebagai kod warisan untuk aksara 171 dan 187, iaitu, "dua arah kiri
tanda petikan sudut" = "guillemet menghala ke kiri" dan "sudut berganda mengarah ke kanan
tanda petikan" = "guillemet menunjuk ke kanan". (Ini kelihatan seperti "<<" dan ">>" kecil,
dan mereka kini lebih baik dinyatakan dengan kod HTML/XHTML "E "dan
"E ".)

· Penghurai pod harus memahami semua "E " kod seperti yang ditakrifkan dalam entiti
pengisytiharan dalam spesifikasi XHTML terkini di "www.W3.org". Penghurai pod mesti
memahami sekurang-kurangnya entiti yang mentakrifkan aksara dalam julat 160-255
(Latin-1). Penghurai pod, apabila berhadapan dengan beberapa "Epengecam>" kod, tidak sepatutnya
hanya gantikannya dengan nullstring (secara lalai, sekurang-kurangnya), tetapi boleh meneruskannya sebagai a
rentetan yang terdiri daripada aksara literal E, kurang daripada, pengecam, lebih besar daripada.
Atau Penghurai Pod mungkin menawarkan pilihan alternatif untuk memproses yang tidak diketahui tersebut
"Epengecam>" kod dengan melancarkan acara terutamanya untuk kod tersebut, atau dengan menambah a
jenis nod khas kepada pepohon dokumen dalam ingatan. Seperti "Epengecam>" mungkin ada
makna istimewa kepada sesetengah pemproses, atau sesetengah pemproses boleh memilih untuk menambahkannya pada a
laporan ralat khas.

· Penghurai pod juga mesti menyokong kod XHTML "E " untuk watak 34 (petikan berganda,
"), "E " untuk aksara 38 (ampersand, &), dan "E "untuk watak 39
(apostrof, ').

· Ambil perhatian bahawa dalam semua kes "E ", apa sahaja (sama ada nama html, atau nombor dalam
sebarang asas) mestilah hanya terdiri daripada aksara alfanumerik -- iaitu, apa sahaja mesti tengok
"m/\A\w+\z/". Jadi "E< 0 1 2 3 >" adalah tidak sah, kerana ia mengandungi ruang, yang tidak
aksara abjad angka. Ini agaknya tidak perlu layanan istimewa oleh Pod
pemproses; " 0 1 2 3 " tidak kelihatan seperti nombor dalam mana-mana asas, jadi ia mungkin akan berlaku
dicari dalam jadual nama seperti HTML. Oleh kerana tidak ada (dan tidak boleh) an
Entiti seperti HTML yang dipanggil " 0 1 2 3 ", ini akan dianggap sebagai ralat. Walau bagaimanapun, Pod
pemproses boleh merawat "E< 0 1 2 3 >" atau "E "sebagai secara sintaksis tidak sah,
berpotensi memperoleh mesej ralat yang berbeza daripada mesej ralat (atau amaran, atau
acara) yang dijana oleh nama html yang tidak diketahui (tetapi sah secara teorinya), seperti dalam
"E " [sic]. Walau bagaimanapun, penghurai Pod tidak diperlukan untuk membuat perbezaan ini.

· Perhatikan bahawa E kemestian tidak ditafsirkan sebagai "titik kod nombor dalam
set watak semasa/asli". Ia sentiasa bermaksud hanya "watak yang diwakili oleh
titik kod nombor dalam Unicode." (Ini adalah sama dengan semantik &#nombor; dalam
XML.)

Ini mungkin memerlukan banyak pemformat untuk mempunyai pemetaan jadual daripada Unicode yang boleh dirawat
titik kod (seperti "\xE9" untuk aksara e-akut) kepada urutan melarikan diri atau
kod yang diperlukan untuk menyampaikan urutan tersebut dalam format output sasaran. Sebuah penukar
kepada *roff akan, contohnya mengetahui bahawa "\xE9" (sama ada disampaikan secara literal, atau melalui a
E<...> urutan) hendak disampaikan sebagai "e\\*'". Begitu juga, program yang memaparkan Pod in
tetingkap aplikasi Mac OS, mungkin perlu mengetahui bahawa "\xE9" memetakan ke
codepoint 142 dalam pengekodan MacRoman yang (pada masa penulisan) adalah asli untuk Mac OS.
Pemetaan Unicode2whatever tersebut mungkin sudah tersedia secara meluas untuk umum
format output. (Pemetaan sedemikian mungkin tidak lengkap! Pelaksana tidak dijangka
membongkok ke belakang dalam percubaan untuk membuat suku kata Cherokee, rune Etruscan,
Simbol muzik Byzantine, atau mana-mana perkara aneh lain yang Unicode boleh dikodkan.)
Dan jika dokumen Pod menggunakan aksara yang tidak ditemui dalam pemetaan sedemikian, pemformat
harus menganggapnya sebagai watak yang tidak boleh diubah.

· Jika, secara mengejutkan, pelaksana pemformat Pod tidak dapat mencari pra-
pemetaan jadual sedia ada daripada aksara Unicode untuk melarikan diri dalam format sasaran (cth,
jadual aksara Unicode yang sesuai untuk *roff melarikan diri), ia akan menjadi perlu untuk membina
meja sebegitu. Jika anda berada dalam keadaan ini, anda harus bermula dengan watak
dalam julat 0x00A0 - 0x00FF, yang kebanyakannya adalah aksara aksen yang banyak digunakan.
Kemudian teruskan (sebagaimana kesabaran mengizinkan dan ketekunan memaksa) melalui watak-watak
bahawa kumpulan piawaian HTML (X) dinilai cukup penting untuk merit mnemonik.
Ini diisytiharkan dalam spesifikasi HTML (X) di tapak www.W3.org. Pada masa
menulis (September 2001), fail pengisytiharan entiti terkini ialah:

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

Kemudian anda boleh maju melalui mana-mana aksara Unicode yang ketara dalam julat
0x2000-0x204D (rujuk jadual aksara di www.unicode.org), dan apa sahaja lagi
menarik minat anda. Contohnya, dalam xhtml-symbol.ent, terdapat entri:



Walaupun pemetaan "infin" kepada aksara "\x{221E}" akan (mudah-mudahan) telah
sudah dikendalikan oleh penghurai Pod, kehadiran aksara dalam fail ini bermakna
bahawa ia cukup munasabah untuk dimasukkan ke dalam jadual pemformat yang dipetakan
aksara Unicode yang ketara kepada kod yang diperlukan untuk memberikannya. Jadi untuk a
Pemetaan Unicode-to-*roff, sebagai contoh, ini layak untuk masuk:

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

Adalah sangat diharapkan pada masa hadapan, meningkatkan bilangan format (dan pemformat)
akan menyokong aksara Unicode secara langsung (seperti (X)HTML lakukan dengan "∞", "∞",
atau "∞"), mengurangkan keperluan untuk pemetaan idiosinkratik Unicode-to-my_escapes.

· Terpulang kepada pemformat Pod individu untuk memaparkan pertimbangan yang baik apabila berhadapan dengan
watak yang tidak boleh ditukar (yang berbeza daripada E urutan yang
parser tidak dapat menyelesaikan apa-apa, boleh ditukar atau tidak). Ia adalah amalan yang baik untuk memetakan
Huruf Latin dengan diakritik (seperti "E "/"E<233>") kepada yang sepadan
huruf US-ASCII tanpa aksen (seperti aksara ringkas 101, "e"), tetapi jelas ini
selalunya tidak boleh dilaksanakan, dan watak yang tidak boleh diterjemahkan boleh diwakili sebagai "?", atau
suka. Dalam mencuba sandaran yang waras (dari E<233> hingga "e"), pemformat Pod boleh menggunakan
jadual %Latin1Code_to_fallback dalam Pod::Escapes, atau Text::Unidecode, jika tersedia.

Sebagai contoh, teks Pod ini:

sihir didayakan jika anda menetapkan C<$Currency> kepada 'E '.

boleh dijadikan sebagai: "sihir didayakan jika anda menetapkan $Currency kepada '?'" atau sebagai "sihir adalah
didayakan jika anda menetapkan $Currency kepada '[euro]'", atau sebagai "sihir didayakan jika anda menetapkan
$Currency kepada '[x20AC]', dsb.

Pemformat Pod juga boleh mencatat, dalam ulasan atau amaran, senarai perkara yang tidak boleh dipaparkan
watak-watak ditemui.

· E<...> boleh muncul secara bebas dalam mana-mana kod pemformatan (selain dalam E<...> lain atau dalam
Z<>). Iaitu, "X 1,000,000 Penyelesaian>" adalah sah, seperti "L
E 1,000,000 Penyelesaian|Juta::Euros>".

· Sesetengah pemformat Pod mengeluarkan kepada format yang melaksanakan ruang tidak pecah sebagai
watak individu (yang saya akan panggil "NBSP"), dan output lain untuk memformat itu
laksanakan ruang tidak pecah sama seperti ruang yang dibalut dengan huruf "jangan pecahkan ini
baris". Ambil perhatian bahawa pada tahap Pod, kedua-dua jenis kod boleh berlaku: Pod boleh
mengandungi aksara NBSP (sama ada secara literal, atau sebagai "E<160>" atau "E " kod);
dan Pod boleh mengandungi "S baz>", di mana "ruang semata-mata" (aksara 32) masuk
kod tersebut diambil untuk mewakili ruang yang tidak pecah. Penghurai pod harus dipertimbangkan
menyokong penghuraian pilihan "S baz>" seolah-olah
"fooNBSPsayaNBSPbaz", dan, sebaliknya, penghuraian pilihan kumpulan bagi
perkataan yang dicantumkan oleh NBSP seolah-olah setiap kumpulan berada dalam kod S<...>, supaya pemformat boleh
gunakan perwakilan yang paling sesuai dengan apa yang dituntut oleh format output.

· Sesetengah pemproses mungkin mendapati bahawa kod "S<...>" adalah paling mudah untuk dilaksanakan dengan menggantikannya
setiap ruang dalam pokok parse di bawah kandungan S, dengan NBSP. Tetapi perhatikan: yang
penggantian harus digunakan tidak ke ruang dalam semua teks, tetapi hanyalah ke ruang dalam boleh cetak
teks. (Perbezaan ini mungkin atau mungkin tidak nyata dalam model pokok/acara tertentu
dilaksanakan oleh parser Pod.) Sebagai contoh, pertimbangkan kes luar biasa ini:

S >

Ini bermakna ruang di tengah-tengah teks pautan yang boleh dilihat tidak boleh dipecahkan
merentasi garisan. Dalam erti kata lain, ia adalah sama seperti ini:

L<"AutoloadedE<160>Functions"/Autoloaded Functions>

Walau bagaimanapun, penggantian ruang-ke-NBSP yang salah boleh (salah) menghasilkan sesuatu
bersamaan dengan ini:

L<"AutoloadedE<160>Functions"/AutoloadedE<160>Functions>

... yang hampir pasti tidak akan berfungsi sebagai hiperpautan (dengan mengandaikan ini
pemformat mengeluarkan format yang menyokong hiperteks).

Pemformat boleh memilih untuk tidak menyokong kod format S, terutamanya dalam kes di mana
format output hanya tidak mempunyai aksara/kod NBSP dan tiada kod untuk "jangan pecahkan ini
barangan merentas baris".

· Selain watak NBSP yang dibincangkan di atas, pelaksana diingatkan tentang kewujudan
daripada watak "istimewa" lain dalam Latin-1, watak "sempang lembut", juga dikenali
sebagai "sempang budi bicara", iaitu "E<173>" = "E<0xAD>" = "E "). Watak ini
menyatakan titik sempang pilihan. Iaitu, ia biasanya diterjemahkan sebagai tiada, tetapi
boleh dijadikan sebagai "-" jika pemformat memecahkan perkataan pada ketika itu. Pemformat pod
harus, mengikut kesesuaian, melakukan salah satu daripada yang berikut: 1) memberikan ini dengan kod dengan
makna yang sama (cth, "\-" dalam RTF), 2) melaluinya dengan jangkaan bahawa
pemformat memahami aksara ini seperti itu, atau 3) padamkannya.

Sebagai contoh:

sigE tindakan
manuE skrip
JarkE ko HieE taE nieE mi

Ini memberi isyarat kepada pemformat bahawa jika ia adalah untuk menyempang "sigaction" atau "manuskrip",
maka ia perlu dilakukan sebagai "sig-[pecah baris]tindakan" atau "manu-[pecah baris]skrip" (dan jika
ia tidak menandainya, kemudian huruf "E " tidak muncul sama sekali). Dan jika perlu
tanda sempang "Jarkko" dan/atau "Hietaniemi", ia boleh berbuat demikian hanya pada titik yang terdapat
a "E " kod.

Dalam amalan, adalah dijangka bahawa watak ini tidak akan digunakan dengan kerap, tetapi
pemformat harus sama ada menyokongnya, atau memadamnya.

· Jika anda fikir anda ingin menambah arahan baharu pada Pod (seperti, katakan, "=biblio"
perintah), pertimbangkan sama ada anda boleh mendapat kesan yang sama dengan untuk atau mula/akhir
urutan: "=untuk biblio ..." atau "=mulakan biblio" ... "=akhir biblio". Pemproses pod itu
tidak faham "=for biblio", dll, hanya akan mengabaikannya, sedangkan mereka mungkin mengadu
dengan kuat jika mereka melihat "=biblio".

· Sepanjang dokumen ini, "Pod" telah menjadi ejaan pilihan untuk nama
format dokumentasi. Seseorang juga boleh menggunakan "POD" atau "pod". Untuk dokumentasi iaitu
(biasanya) dalam format Pod, anda boleh menggunakan "pod", atau "Pod", atau "POD". Kefahaman
perbezaan ini berguna; tetapi obses tentang cara mengeja mereka, biasanya tidak.

Mengenai Kami L<...> Kod

Seperti yang anda boleh ketahui dari sepintas lalu pada perlpod, kod L<...> ialah yang paling kompleks bagi Pod
kod pemformatan. Perkara di bawah diharapkan dapat menjelaskan maksudnya dan bagaimana
pemproses harus menanganinya.

· Dalam menghuraikan kod L<...>, penghurai Pod mesti membezakan sekurang-kurangnya empat atribut:

Pertama:
Teks pautan. Jika tiada, ini mesti "undef". (Cth, dalam "L
Functions|perlfunc>", teks pautan ialah "Fungsi Perl". Dalam "L "dan
malah "L<|Time::HiRes>", tiada teks pautan. Ambil perhatian bahawa teks pautan mungkin mengandungi
pemformatan.)

Kedua:
Teks pautan yang mungkin disimpulkan; iaitu, jika tiada teks pautan sebenar, maka ini
ialah teks yang akan kita simpulkan sebagai gantinya. (Cth, untuk "L ", yang
teks pautan yang disimpulkan ialah "Getopt::Std".)

Ketiga:
Nama atau URL, atau "undef" jika tiada. (Cth, dalam "L ", yang
nama (juga kadangkala dipanggil halaman) ialah "perlfunc". dalam "L ", nama
ialah "undef".)

Keempat:
Bahagian (AKA "item" dalam perlpods lama), atau "undef" jika tiada. Cth, dalam
"L ", "DESCRIPTION" ialah bahagian. (Perhatikan bahawa ini adalah
tidak sama dengan bahagian halaman manual seperti "5" dalam "man 5 crontab". "Bahagian Foo"
dalam erti kata Pod bermaksud bahagian teks yang diperkenalkan oleh tajuk atau
item yang teksnya ialah "Foo".)

Penghurai pod juga boleh mencatatkan atribut tambahan termasuk:

Kelima:
Bendera untuk sama ada item 3 (jika ada) ialah URL (seperti "http://lists.perl.org"adalah),
dalam kes ini sepatutnya tiada atribut seksyen; nama Pod (seperti "perldoc" dan
"Getopt:: Std" ialah); atau mungkin nama halaman lelaki (seperti "crontab(5)" ialah).

Keenam:
Kandungan L<...> asli mentah, sebelum teks dipecahkan pada "|", "/", dsb, dan sebelum
E<...> kod dikembangkan.

(Di atas diberi nombor hanya untuk rujukan ringkas di bawah. Ia bukan satu keperluan
supaya ini diluluskan sebagai senarai atau tatasusunan sebenar.)

Sebagai contoh:

L
=> undef, # teks pautan
"Foo::Bar", # teks pautan yang mungkin disimpulkan
"Foo::Bar", # nama
undef, # bahagian
'pod', # pautan jenis apa
"Foo::Bar" # kandungan asal

L
=> "Bahagian Perlport pada NL's", # teks pautan
"Bahagian Perlport tentang NL", # teks pautan yang mungkin disimpulkan
"perlport", # nama
"Barisan baharu", # bahagian
'pod', # pautan jenis apa
"Bahagian Perlport pada NL|perlport/Newlines"
# kandungan asal

L
=> undef, # teks pautan
'"Barisan baharu" dalam perlport', # teks pautan berkemungkinan disimpulkan
"perlport", # nama
"Barisan baharu", # bahagian
'pod', # pautan jenis apa
"perlport/Newlines" # kandungan asal

L<crontab(5)/"DESCRIPTION">
=> undef, # teks pautan
'"DESCRIPTION" dalam crontab(5)', # teks pautan yang mungkin disimpulkan
"crontab(5)", # nama
"DESCRIPTION", # bahagian
'lelaki', # pautan jenis apa
'crontab(5)/"DESCRIPTION"' # kandungan asal

L
=> undef, # teks pautan
'"Atribut Objek"', # teks pautan yang mungkin disimpulkan
undef, # nama
"Atribut Objek", # bahagian
'pod', # pautan jenis apa
"/Atribut Objek" # kandungan asal

L<http://www.perl.org/>
=> undef, # teks pautan
"http://www.perl.org/", # teks pautan yang mungkin disimpulkan
"http://www.perl.org/", # nama
undef, # bahagian
'url', # jenis pautan
"http://www.perl.org/" # kandungan asal

Lhttp://www.perl.org/>
=> "Perl.org", # teks pautan
"http://www.perl.org/", # teks pautan yang mungkin disimpulkan
"http://www.perl.org/", # nama
undef, # bahagian
'url', # jenis pautan
"Perl.org|http://www.perl.org/" # kandungan asal

Ambil perhatian bahawa anda boleh membezakan pautan URL daripada yang lain dengan fakta bahawa pautan tersebut sepadan
"m/\A\w+:[^:\s]\S*\z/". Jadi "Lhttp://www.perl.com>" ialah URL, tetapi "L "
tidak.

· Dalam kes kod L<...> tanpa "teks|" sebahagian daripadanya, pemformat lama telah mempamerkan
variasi hebat dalam sebenarnya memaparkan pautan atau rujukan silang. Sebagai contoh,
L<crontab(5)> akan diterjemahkan sebagai "the crontab(5) halaman manual", atau "dalam crontab(5) halaman manual"
atau hanya "crontab(5) ".

Pemproses pod kini mesti merawat pautan "teks|"-kurang seperti berikut:

L => L
L => L<"section"|/section>
L => L<"bahagian" dalam nama|nama/bahagian>

· Ambil perhatian bahawa nama bahagian mungkin mengandungi markup. Iaitu, jika bahagian bermula dengan:

=head2 Mengenai Operator C<-M>

atau dengan:

=item Mengenai Operator C<-M>

maka pautan kepadanya akan kelihatan seperti ini:

L Operator>

Pemformat boleh memilih untuk mengabaikan markup untuk tujuan menyelesaikan pautan dan penggunaan
hanya aksara yang boleh ditukar dalam nama bahagian, seperti dalam:

Mengenai -M
Operator

...

Mengenai -M
Operator" dalam somedoc

· Versi terdahulu perlpod membezakan "L " pautan daripada
"L " pautan (dan sasarannya). Ini telah digabungkan secara sintaksis dan
secara semantik dalam spesifikasi semasa, dan seksyen boleh merujuk sama ada kepada "=headn
Perintah Heading Content" atau kepada arahan "=item Item Content". Spesifikasi ini
tidak menyatakan tingkah laku yang sepatutnya berlaku dalam kes dokumen yang diberikan mempunyai
beberapa perkara semuanya kelihatan menghasilkan yang sama seksyen pengecam (cth, dalam HTML,
beberapa perkara semuanya menghasilkan yang sama nama utama dalamnama utama">...
unsur). Di mana pemproses Pod boleh mengawal tingkah laku ini, mereka harus menggunakan yang pertama
sauh sedemikian. Iaitu, "L " merujuk kepada pertama Bahagian "Bar" dalam Foo.

Tetapi untuk sesetengah pemproses/format ini tidak boleh dikawal dengan mudah; seperti HTML
contoh, tingkah laku berbilang samar-samarnama utama">... paling banyak
mudah sahaja diserahkan kepada pelayar untuk membuat keputusan.

· Dalam "L " kod, teks mungkin mengandungi kod pemformatan untuk pemformatan atau untuk
E<...> melarikan diri, seperti dalam:

L barangan>|...>

Untuk kod "L<...>" tanpa "nama|" bahagian, hanya kod "E<...>" dan "Z<>" mungkin berlaku.
Iaitu, pengarang tidak boleh menggunakan "" L >"".

Walau bagaimanapun, ambil perhatian bahawa kod pemformatan dan Z<>'s boleh berlaku di mana-mana dan semua bahagian an
L<...> (iaitu, dalam nama, seksyen, teks, dan url).

Pengarang tidak boleh meletakkan kod L<...>. Sebagai contoh, "L halaman manusia>" sepatutnya
dianggap sebagai kesilapan.

· Ambil perhatian bahawa pengarang Pod boleh menggunakan kod pemformatan di dalam bahagian "teks".
"L " (dan seterusnya untuk L ).

Dengan kata lain, ini sah:

Pergi baca L |perlvar/"$.">

Sesetengah format output yang membenarkan pemaparan kod "L<...>" sebagai hiperteks, mungkin tidak
benarkan teks pautan diformat; dalam kes itu, pemformat perlu mengabaikan sahaja
pemformatan itu.

· Pada masa penulisan, "L " nilai terdiri daripada dua jenis: sama ada nama halaman Pod
seperti "L " (yang mungkin modul atau program Perl sebenar dalam @INC / PATH
direktori, atau fail .pod di tempat tersebut); atau nama halaman lelaki Unix, seperti
"Lcrontab(5)>". Secara teorinya, "L " dalam samar-samar antara halaman Pod yang dipanggil
"chmod", atau halaman lelaki Unix "chmod" (dalam mana-mana bahagian manusia). Walau bagaimanapun
kehadiran rentetan dalam parens, seperti dalam "crontab(5)", memadai untuk memberi isyarat bahawa apa
sedang dibincangkan bukan halaman Pod, dan begitu juga mungkin halaman manusia Unix. The
perbezaan tidak penting kepada banyak pemproses Pod, tetapi sesetengah pemproses yang
render kepada format hiperteks mungkin perlu membezakannya untuk mengetahui caranya
memberikan "L " kod.

· Versi perlpod sebelumnya dibenarkan untuk "L " sintaks (seperti dalam "L
Atribut>"), yang tidak mudah dibezakan daripada "L " sintaks dan untuk
"L<"section">" yang hanya kurang samar-samar. Sintaks ini tidak ada lagi
spesifikasi, dan telah digantikan dengan "L " sintaks (di mana garis miring
dahulunya pilihan). Penghurai pod harus bertolak ansur dengan sintaks "L<"section">", untuk a
manakala sekurang-kurangnya. Heuristik yang dicadangkan untuk membezakan "L "dari
"L " ialah jika ia mengandungi sebarang ruang putih, ia adalah a seksyen. Pemproses pod
harus memberi amaran tentang sintaks yang ditamatkan ini.

Mengenai Kami =over...=back Kawasan

Kawasan "=over"..."=back" digunakan untuk pelbagai jenis struktur seperti senarai. (Saya menggunakan
istilah "wilayah" di sini hanya sebagai istilah kolektif untuk segala-galanya daripada "=over" kepada
sepadan "=belakang".)

· Angka bukan sifar indentlevel dalam "=over indentlevel" ... "=back" digunakan untuk
memberikan pemformat petunjuk tentang berapa banyak "ruang" (ems, atau unit yang hampir sama)
ia harus tab over, walaupun banyak pemformat perlu menukar ini kepada mutlak
ukuran yang mungkin tidak betul-betul sepadan dengan saiz ruang (atau M) dalam
fon asas dokumen. Pemformat lain mungkin perlu mengabaikan nombor itu sepenuhnya. The
kekurangan apa-apa yang jelas indentlevel parameter adalah bersamaan dengan an indentlevel nilai 4.
Pemproses pod mungkin mengadu jika indentlevel hadir tetapi bukan nombor positif
sepadan dengan "m/\A(\d*\.)?\d+\z/".

· Pengarang pemformat Pod diingatkan bahawa "=over" ... "=back" mungkin dipetakan kepada beberapa
binaan yang berbeza dalam format output anda. Contohnya, dalam menukar Pod kepada
(X)HTML, ia boleh memetakan ke mana-mana ... , ... , ... , atau
... . Begitu juga, "=item" boleh memetakan ke atau .

· Setiap kawasan "=over" ... "=back" hendaklah salah satu daripada yang berikut:

· Rantau "=over" ... "=back" yang mengandungi hanya arahan "=item *", setiap satunya diikuti dengan
beberapa perenggan biasa/verbatim, yang lain bersarang "=over" ... "=back"
wilayah, "=untuk..." perenggan dan "=mula"..."=akhir" wilayah.

(Pemproses pod mesti bertolak ansur dengan "=item" kosong seolah-olah ia adalah "=item *".) Sama ada
"*" diterjemahkan sebagai asterisk literal, "o", atau sebagai sejenis peluru sebenar
aksara, diserahkan kepada pemformat Pod, dan mungkin bergantung pada tahap
bersarang.

· Rantau "=over" ... "=back" yang mengandungi hanya "m/\A=item\s+\d+\.?\s*\z/"
perenggan, setiap satu (atau setiap kumpulan daripada mereka) diikuti dengan beberapa bilangan
perenggan biasa/verbatim, kawasan "=over" bersarang lain ... "=back", "=for..."
perenggan, dan/atau kod "=begin"..."=end". Ambil perhatian bahawa nombor mesti bermula pada 1
dalam setiap bahagian, dan mesti meneruskan dengan tertib dan tanpa melangkau nombor.

(Pemproses pod mesti bertolak ansur dengan baris seperti "=item 1" seolah-olah ia adalah "=item 1.",
dengan tempoh.)

· Rantau "=over" ... "=back" yang mengandungi hanya arahan "=item [teks]", setiap satu
(atau setiap kumpulan daripada mereka) diikuti dengan beberapa perenggan biasa/verbatim,
kawasan "=over" ... "=back" bersarang lain, atau "=for..." perenggan, dan
"=mula"..."=akhir" wilayah.

Perenggan "=item [teks]" tidak sepatutnya sepadan dengan "m/\A=item\s+\d+\.?\s*\z/" atau
"m/\A=item\s+\*\s*\z/", dan tidak sepatutnya sepadan dengan hanya "m/\A=item\s*\z/".

· Rantau "=over" ... "=back" tidak mengandungi perenggan "=item" sama sekali, dan
mengandungi hanya beberapa bilangan perenggan biasa/verbatim, dan mungkin juga
beberapa kawasan "=over" ... "=back" bersarang, "=for..." perenggan, dan
"=mula"..."=akhir" wilayah. Rantau "=over" ... "=back" yang tiada item dalam Pod adalah
setara dengan makna " ... "elemen dalam HTML.

Ambil perhatian bahawa dengan semua kes di atas, anda boleh menentukan jenis "=over" ...
"=kembali" yang anda miliki, dengan memeriksa perenggan Pod pertama (bukan-"=potong", bukan-"=pod") selepas
arahan "=over".

· Pemformat pod kemestian bertolak ansur dengan jumlah teks yang besar secara sewenang-wenangnya dalam "=item teks ..."
perenggan. Dalam amalan, kebanyakan perenggan sedemikian adalah pendek, seperti dalam:

=item Untuk menghentikan perdagangan kami dengan semua bahagian dunia

Tetapi mereka mungkin panjang sewenang-wenangnya:

=item Untuk mengangkut kami ke luar laut untuk dicuba untuk berpura-pura
kesalahan

=item Dia pada masa ini mengangkut tentera asing yang besar
tentera upahan untuk menyelesaikan kerja-kerja kematian, kebinasaan dan
kezaliman, sudah dimulakan dengan keadaan kezaliman dan kezaliman
hampir tidak sejajar pada zaman yang paling biadab, dan sama sekali
tidak layak menjadi ketua negara yang bertamadun.

· Pemproses pod harus bertolak ansur dengan "=item *" / "=item nombor" perintah dengan no
perenggan yang disertakan. Item tengah adalah contoh:

= berakhir

=item 1

Ambil cucian kering.

=item 2

=item 3

Singgah kedai. Dapatkan Abba Zabas, Stoli dan kerusi rumput murah.

= belakang

· Tiada kawasan "=over" ... "=back" boleh mengandungi tajuk. Pemproses boleh merawat a
tajuk sebagai ralat.

· Ambil perhatian bahawa rantau "=over" ... "=back" harus mempunyai beberapa kandungan. Iaitu, pengarang
tidak sepatutnya mempunyai kawasan kosong seperti ini:

= berakhir

= belakang

Pemproses pod melihat kawasan "=over" ... "=back" tanpa kandungan seperti itu, mungkin mengabaikannya, atau
mungkin melaporkannya sebagai ralat.

· Pemproses mesti bertolak ansur dengan senarai "=over" yang keluar di hujung dokumen (iaitu,
yang tidak mempunyai padanan "=back"), tetapi mereka mungkin memberi amaran tentang senarai sedemikian.

· Pengarang pemformat Pod harus ambil perhatian bahawa binaan ini:

=item Neque

=item Porro

=item 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.

=item Ut Enim

adalah samar-samar dari segi semantik, dengan cara yang menjadikan keputusan pemformatan agak sukar.
Di satu pihak, ia boleh menyebut item "Neque", menyebut item lain
"Porro", dan sebutan item lain "Quisquam Est", dengan hanya yang terakhir memerlukannya
perenggan penjelasan "Qui dolorem ipsum quia dolor..."; dan kemudian item "Ut
Enim". Dalam kes itu, anda ingin memformatkannya seperti ini:

Neque

lebih jauh

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

Tetapi ia juga boleh menjadi perbincangan mengenai tiga perkara (berkaitan atau setara),
"Neque", "Porro", dan "Quisquam Est", diikuti dengan perenggan yang menerangkan semuanya, dan
kemudian item baharu "Ut Enim". Dalam kes itu, anda mungkin mahu memformatnya seperti ini:

Neque
lebih jauh
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

Tetapi (untuk masa hadapan yang boleh dijangka), Pod tidak menyediakan sebarang cara untuk pengarang Pod
bezakan kumpulan mana yang dimaksudkan dengan struktur kluster "=item" di atas. Jadi
pemformat harus memformatnya seperti ini:

Neque

lebih jauh

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

Iaitu, perlu ada (sekurang-kurangnya secara kasar) jarak yang sama antara item dengan antara
perenggan (walaupun jarak itu mungkin kurang daripada ketinggian penuh baris
teks). Ini menyerahkan kepada pembaca untuk menggunakan (con) isyarat teks untuk mengetahui sama ada
perenggan "Qui dolorem ipsum..." terpakai pada item "Quisquam Est" atau semua
tiga item "Neque", "Porro", dan "Quisquam Est". Walaupun bukan situasi yang ideal, ini
adalah lebih baik daripada menyediakan isyarat pemformatan yang mungkin sebenarnya bertentangan dengan
niat penulis.

Mengenai Kami Tarikh Perenggan and "=mula/=akhir" Kawasan

Perenggan data biasanya digunakan untuk menyelaraskan data bukan Pod yang akan digunakan (biasanya
dilalui) apabila memberikan dokumen kepada format tertentu:

=mulakan rtf

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

= tamat rtf

Kesan yang sama boleh, secara kebetulan, dicapai dengan satu perenggan "=for":

=untuk rtf \par{\pard\qr\sa4500{\i Printed\~\chdate\~\chtime}\par}

(Walaupun itu bukan perenggan data secara rasmi, ia mempunyai makna yang sama seperti satu, dan Pod
penghurai boleh menghuraikannya sebagai satu.)

Contoh lain perenggan data:

=mulakan html

Saya suka PIE !

Terutamanya pai pecan!

=end html

Jika ini adalah perenggan biasa, penghurai Pod akan cuba mengembangkan "E" (dalam
perenggan pertama) sebagai kod pemformatan, sama seperti "E " atau "E ". Tetapi sejak ini
berada dalam "=mula pengecam"..." = tamat pengecam"wilayah and pengecam "html" tidak
mula mempunyai awalan ":", kandungan rantau ini disimpan sebagai perenggan data,
bukannya diproses sebagai perenggan biasa (atau jika ia bermula dengan ruang dan/atau
tab, sebagai perenggan verbatim).

Sebagai contoh selanjutnya: Pada masa penulisan, tiada pengecam "biblio" disokong, tetapi anggaplah
beberapa pemproses telah ditulis untuk mengiktirafnya sebagai cara (katakan) menandakan bibliografi
rujukan (semestinya mengandungi kod pemformatan dalam perenggan biasa). Hakikat bahawa
Perenggan "biblio" dimaksudkan untuk pemprosesan biasa akan ditunjukkan dengan pendahuluan
setiap pengecam "biblio" dengan titik bertindih:

=mulakan :biblio

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

=akhir :biblio

Ini akan memberi isyarat kepada penghurai bahawa perenggan dalam ini bermula...rantau akhir tertakluk kepada
pengendalian biasa sebagai perenggan biasa/verbatim (sementara masih ditandakan sebagai hanya untuk
pemproses yang memahami pengecam "biblio"). Kesan yang sama boleh berlaku dengan:

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

":" pada pengecam ini bermaksud "proses perkara ini secara normal, walaupun
keputusan adalah untuk beberapa sasaran khas". Saya mencadangkan agar API penghurai melaporkan "biblio" sebagai
pengecam sasaran, tetapi juga melaporkan bahawa ia mempunyai awalan ":". (Dan begitu juga, dengan
di atas "html", laporkan "html" sebagai pengecam sasaran, dan perhatikan kekurangan daripada awalan ":".)

Ambil perhatian bahawa "=begin pengecam"..." = tamat pengecam"wilayah mana pengecam bermula dengan a
kolon, boleh mengandungi arahan. Sebagai contoh:

=mulakan :biblio

Klasik Wirth tersedia dalam beberapa edisi, termasuk:

=untuk komen
hm, semak abebooks.com untuk mengetahui kos salinan terpakai.

= berakhir

=item

Wirth, Niklaus. 1975. I
Teubner, Stuttgart. [Ya, dalam bahasa Jerman.]

=item

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

= belakang

=akhir :biblio

Walau bagaimanapun, perhatikan a "=begin pengecam"..." = tamat pengecam"wilayah mana pengecam tidak tidak
bermula dengan titik bertindih, tidak seharusnya mengandungi perintah "=head1" ... "=head4" secara langsung, mahupun
"=over", atau "=back", atau "=item". Sebagai contoh, ini mungkin dianggap tidak sah:

=mulakan beberapa data

Ini adalah perenggan data.

=head1 Jangan buat begini!

Ini adalah perenggan data juga.

= tamatkan beberapa data

Pemproses Pod mungkin memberi isyarat bahawa perkara di atas (khususnya perenggan "=head1") ialah satu
ralat. Walau bagaimanapun, ambil perhatian bahawa perkara berikut harus tidak dianggap sebagai ralat:

=mulakan beberapa data

Ini adalah perenggan data.

= potong

# Ya, ini bukan Pod lagi.
sub excl { (rand() > .5) ? "hoo!" : "hah!" }

=pod

Ini adalah perenggan data juga.

= tamatkan beberapa data

Dan ini juga sah:

=mulakan beberapa format

Ini adalah perenggan data.

Dan ini adalah perenggan data.

=mulakan format lain

Ini adalah perenggan data juga.

Dan ini juga perenggan data.

=mula :yetanotherformat

=head2 Ini adalah perenggan arahan!

Ini perenggan biasa!

Dan ini adalah perenggan verbatim!

=end :yetanotherformat

= tamatkan format lain

Satu lagi perenggan data!

= tamatkan beberapa format

Kandungan di atas "=begin :yetanotherformat" ... "=end :yetanotherformat" region
tidak perenggan data, kerana pengecam wilayah yang mengandungi serta-merta
(":yetanotherformat") bermula dengan titik bertindih. Dalam amalan, kebanyakan wilayah yang mengandungi data
perenggan akan mengandungi hanyalah perenggan data; namun, sarang di atas adalah secara sintaksis
sah sebagai Pod, walaupun ia jarang berlaku. Walau bagaimanapun, pengendali untuk beberapa format, seperti "html",
hanya akan menerima perenggan data, bukan kawasan bersarang; dan mereka boleh merungut jika mereka melihat
(disasarkan untuk mereka) kawasan bersarang, atau perintah, selain daripada "=end", "=pod", dan "=cut".

Juga pertimbangkan struktur yang sah ini:

=mulakan :biblio

Klasik Wirth tersedia dalam beberapa edisi, termasuk:

= berakhir

=item

Wirth, Niklaus. 1975. I
Teubner, Stuttgart. [Ya, dalam bahasa Jerman.]

=item

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

= belakang

Beli beli beli!

=mulakan html





=end html

Sekarang sekarang sekarang!

=akhir :biblio

Di sana, rantau "=begin html"..."=end html" bersarang di dalam "=begin
:biblio"..."=end :biblio" region. Ambil perhatian bahawa kandungan "=begin html"..."=end
html" ialah perenggan data, kerana pengecam wilayah yang mengandungi serta-merta
("html") tidak mulakan dengan kolon.

Penghurai pod, apabila memproses satu siri perenggan data satu demi satu (dalam a
rantau tunggal), harus menganggapnya sebagai satu perenggan data besar yang berlaku kepada
mengandungi baris kosong. Jadi kandungan di atas "=begin html"..."=end html" mungkin be
disimpan sebagai dua perenggan data (satu terdiri daripada "
src='wirth_spokesmodeling_book.png'>\n" dan satu lagi yang terdiri daripada " \n"), tetapi Sekiranya be
disimpan sebagai satu perenggan data (terdiri daripada "
src='wirth_spokesmodeling_book.png'>\n\n \n").

Pemproses pod harus bertolak ansur dengan "=begin sesuatu"..." = tamat sesuatu" wilayah, kosong
"=mulakan :sesuatu"..."=end :sesuatu" regions, and contentless "=for sesuatu"dan
"=untuk :sesuatu" perenggan. Iaitu, ini harus diterima:

=untuk html

=mulakan html

=end html

=mulakan :biblio

=akhir :biblio

Secara kebetulan, ambil perhatian bahawa tiada cara mudah untuk menyatakan perenggan data bermula dengan
sesuatu yang kelihatan seperti perintah. Pertimbangkan:

=mulakan perkara

=shazbot

= barang tamat

Di sana, "=shazbot" akan dihuraikan sebagai arahan Pod "shazbot", bukan sebagai perenggan data
"=shazbot\n". Walau bagaimanapun, anda boleh menyatakan perenggan data yang terdiri daripada "=shazbot\n" menggunakan
kod ini:

=untuk barangan =shazbot

Keadaan di mana ini perlu, agak jarang berlaku.

Ambil perhatian bahawa perintah =end mesti sepadan dengan perintah =begin yang sedang dibuka. Iaitu, mereka mesti
bersarang dengan betul. Sebagai contoh, ini sah:

=mula luar

X

=mula batin

Y

= hujung batin

Z

= hujung luar

sementara ini tidak sah:

=mula luar

X

=mula batin

Y

= hujung luar

Z

= hujung batin

Yang terakhir ini adalah tidak wajar kerana apabila arahan "=end outer" dilihat, arahan sedang terbuka
rantau mempunyai nama format "dalam", bukan "luar". (Ia hanya berlaku bahawa "luar" adalah
format nama kawasan yang lebih tinggi.) Ini adalah ralat. Pemproses mesti secara lalai melaporkan
ini sebagai ralat, dan mungkin menghentikan pemprosesan dokumen yang mengandungi ralat itu. Akibatnya
daripada ini ialah kawasan tidak boleh "bertindih". Iaitu, blok terakhir di atas tidak
mewakili kawasan yang dipanggil "luar" yang mengandungi X dan Y, bertindih dengan kawasan yang dipanggil
"dalaman" yang mengandungi Y dan Z. Tetapi kerana ia tidak sah (kerana semua nampaknya bertindih
kawasan), ia tidak mewakili itu, atau apa-apa pun.

Begitu juga, ini tidak sah:

=mulakan perkara

=akhir hting

Ini adalah ralat kerana rantau ini dibuka oleh "benda", dan "=end" cuba ditutup
"hting" [sic].

Ini juga tidak sah:

=mulakan perkara

=akhir

Ini tidak sah kerana setiap arahan "=end" mesti mempunyai parameter nama format.

Gunakan perlpodspec dalam talian menggunakan perkhidmatan onworks.net