perlpod - Online di Cloud

PROGRAM:

NAMA

perlpod - format Dokumentasi Lama Biasa

DESKRIPSI

Pod adalah bahasa markup yang mudah digunakan yang digunakan untuk menulis dokumentasi untuk Perl, Perl
program, dan modul Perl.

Penerjemah tersedia untuk mengonversi Pod ke berbagai format seperti teks biasa, HTML, man
halaman, dan lainnya.

Markup pod terdiri dari tiga jenis paragraf dasar: biasa, kata demi kata, dan perintah.

Biasa Ayat
Sebagian besar paragraf dalam dokumentasi Anda akan berupa blok teks biasa, seperti ini. Anda
cukup mengetik teks Anda tanpa markup apa pun, dan hanya dengan baris kosong
sebelum dan sesudah. Ketika diformat, itu akan menjalani pemformatan minimal, seperti menjadi
dibungkus ulang, mungkin dimasukkan ke dalam font dengan spasi proporsional, dan bahkan mungkin dibenarkan.

Anda dapat menggunakan kode pemformatan dalam paragraf biasa, untuk pin, italic, "gaya kode",
hyperlink, dan lainnya. Kode tersebut dijelaskan di bagian "Kode Pemformatan", di bawah ini.

Kata demi kata Ayat
Paragraf verbatim biasanya digunakan untuk menyajikan codeblock atau teks lain yang tidak
tidak memerlukan penguraian atau pemformatan khusus, dan yang tidak boleh dibungkus.

Paragraf verbatim dibedakan dengan karakter pertamanya berupa spasi atau tab.
(Dan umumnya, semua barisnya dimulai dengan spasi dan/atau tab.) Itu harus direproduksi
tepatnya, dengan tab yang diasumsikan berada pada batas 8 kolom. Tidak ada format khusus
kode, jadi Anda tidak bisa mencetak miring atau semacamnya. A \ berarti \, dan tidak ada yang lain.

perintah Ayat
Paragraf perintah digunakan untuk perlakuan khusus terhadap seluruh potongan teks, biasanya sebagai
judul atau bagian dari daftar.

Semua paragraf perintah (yang biasanya hanya satu baris panjangnya) dimulai dengan "=", diikuti
oleh pengenal, diikuti oleh teks arbitrer yang dapat digunakan perintah sesuka hati.
Perintah yang diakui saat ini adalah

= polong
=head1 Teks Judul
=head2 Teks Judul
=head3 Teks Judul
=head4 Teks Judul
=melebihi tingkat indentasi
= barang barang
= kembali
=mulai format
= format akhir
= untuk format teks...
= jenis pengkodean
= potong

Untuk menjelaskan masing-masing secara rinci:

"=kepala1 Kepala Teks"
"=kepala2 Kepala Teks"
"=kepala3 Kepala Teks"
"=kepala4 Kepala Teks"
Head1 sampai head4 menghasilkan heading, head1 menjadi level tertinggi. Teks dalam
sisa paragraf ini adalah isi dari heading. Sebagai contoh:

=head2 Obyek Atribut

Teks "Atribut Objek" terdiri dari judul di sana. Teks dalam judul ini
perintah dapat menggunakan kode pemformatan, seperti yang terlihat di sini:

=head2 Kemungkinan Nilai untuk C<$/>

Perintah tersebut dijelaskan di bagian "Memformat Kode", di bawah ini.

"= lebih tingkat indent"
"=barang hal-hal..."
"= kembali"
Item, over, dan back memerlukan sedikit penjelasan lagi: "= over" memulai suatu wilayah
khusus untuk pembuatan daftar menggunakan perintah "= item", atau untuk indentasi
(kelompok) paragraf normal. Di akhir daftar Anda, gunakan "= kembali" untuk mengakhirinya. Itu
tingkat indent opsi untuk "= over" menunjukkan seberapa jauh indentasi, umumnya dalam ems
(di mana satu em adalah lebar "M" di font dasar dokumen) atau kira-kira
unit sebanding; jika tidak ada tingkat indent pilihan, defaultnya adalah empat. (Dan beberapa
pemformat mungkin mengabaikan apa pun tingkat indent Anda berikan.) Dalam barang dalam "=item
hal-hal...", Anda dapat menggunakan kode pemformatan, seperti yang terlihat di sini:

=item Menggunakan C<$|> untuk Mengontrol Buffering

Perintah tersebut dijelaskan di bagian "Memformat Kode", di bawah ini.

Perhatikan juga bahwa ada beberapa aturan dasar untuk menggunakan region "=over" ... "=back":

· Jangan gunakan "=item" di luar wilayah "=over" ... "=back".

· Hal pertama setelah perintah "=over" harus berupa "=item", kecuali ada
tidak akan ada item sama sekali di wilayah "=over" ... "=back" ini.

· Jangan letakkan "=headn" perintah di dalam wilayah "=over" ... "=back".

· Dan mungkin yang paling penting, jaga agar item tetap konsisten: gunakan "=item *" untuk
semuanya, untuk menghasilkan peluru; atau gunakan "=item 1.", "=item 2.", dll., untuk menghasilkan
daftar bernomor; atau gunakan "=item foo", "=item bar", dll.--yaitu, hal-hal yang terlihat
tidak seperti peluru atau angka.

Jika Anda memulai dengan poin atau angka, tetaplah menggunakannya, karena pemformat menggunakan yang pertama
Jenis "=item" untuk memutuskan cara memformat daftar.

"= potong"
Untuk mengakhiri blok Pod, gunakan baris kosong, lalu baris yang diawali dengan "=cut", dan baris kosong
baris setelahnya. Ini membuat Perl (dan pemformat Pod) tahu bahwa di sinilah Perl
kode dilanjutkan. (Baris kosong sebelum "= cut" secara teknis tidak diperlukan, tapi
banyak prosesor Pod yang lebih tua membutuhkannya.)

"= polong"
Perintah "= pod" dengan sendirinya tidak melakukan banyak hal, tetapi memberi sinyal ke Perl (dan
Pemformat Pod) bahwa blok Pod dimulai di sini. Blok Pod dimulai dengan Apa pun Command
paragraf, jadi perintah "=pod" biasanya digunakan saat Anda ingin memulai blok Pod
dengan paragraf biasa atau paragraf verbatim. Sebagai contoh:

= barang barang()

Fungsi ini melakukan hal-hal.

= potong

sub barang {
...
}

= polong

Ingatlah untuk memeriksa nilai pengembaliannya, seperti pada:

barang() || die "Tidak bisa melakukan sesuatu!";

= potong

"=mulai nama format"
"= akhir nama format"
"= untuk nama format teks..."
Untuk, awal, dan akhir akan membiarkan Anda memiliki wilayah teks/kode/data yang tidak umumnya
diinterpretasikan sebagai teks Pod biasa, tetapi diteruskan langsung ke formatter tertentu, atau
sebaliknya khusus. Pemformat yang dapat menggunakan format tersebut akan menggunakan wilayah,
jika tidak maka akan diabaikan sama sekali.

Perintah "=mulai nama format", beberapa paragraf, dan perintah "=end nama format", berarti
bahwa teks/data di antaranya dimaksudkan untuk pemformat yang memahami khusus
format yang disebut nama format. Sebagai contoh,

=mulai html


Ini adalah paragraf HTML mentah

=akhiri html

Perintah "=untuk nama format teks..." menentukan bahwa sisa hanya ini
paragraf (dimulai tepat setelah nama format) dalam format khusus itu.

= untuk html
Ini adalah paragraf HTML mentah

Ini berarti hal yang sama seperti di atas "=mulai html" ... "=akhiri html" wilayah.

Artinya, dengan "= untuk", Anda hanya dapat memiliki teks senilai satu paragraf (yaitu, teks
di "=foo teks targetname..."), tetapi dengan "=begin targetname" ... "=end targetname", Anda
dapat memiliki jumlah barang di antaranya. (Perhatikan bahwa masih harus ada baris kosong
setelah perintah "=begin" dan baris kosong sebelum perintah "=end".)

Berikut adalah beberapa contoh cara menggunakannya:

=mulai html

Gambar 1.

=akhiri html

= mulai teks

---------------
| foo |
| bilah |
---------------

^^^^ Gambar 1. ^^^^

= teks akhir

Beberapa nama format yang diketahui diterima oleh pemformat saat ini termasuk "roff", "man",
"lateks", "tex", "teks", dan "html". (Beberapa pemformat akan memperlakukan beberapa di antaranya sebagai
sinonim.)

Nama format "komentar" biasa digunakan hanya untuk membuat catatan (mungkin untuk diri sendiri)
yang tidak akan muncul dalam versi format dokumen Pod apa pun:

= untuk komentar
Pastikan bahwa semua opsi yang tersedia didokumentasikan!

Beberapa nama format akan membutuhkan titik dua di depan (seperti pada "=for :formatname", atau "=begin
:formatname" ... "=end :formatname"), untuk menandakan bahwa teks bukan data mentah, tetapi
sebagai gantinya is Teks pod (yaitu, mungkin berisi kode pemformatan) yang bukan untuk
pemformatan normal (misalnya, mungkin bukan paragraf penggunaan normal, tetapi mungkin untuk
pemformatan sebagai catatan kaki).

"= pengkodean nama penyandian"
Perintah ini digunakan untuk mendeklarasikan pengkodean dokumen. Sebagian besar pengguna tidak perlu
ini; tetapi jika penyandian Anda bukan US-ASCII, maka beri tanda "= penyandian nama penyandian" Command
sangat awal dalam dokumen sehingga pemformat pod akan mengetahui cara memecahkan kode
dokumen. Untuk nama pengkodean, gunakan nama yang dikenali oleh modul Encode::Supported.
Beberapa pemformat pod mungkin mencoba menebak antara Latin-1 atau CP-1252 versus UTF-8
encoding, tetapi mereka mungkin salah menebak. Yang terbaik adalah eksplisit jika Anda menggunakan apa pun
selain ASCII yang ketat. Contoh:

= pengkodean latin1

= pengkodean utf8

= pengkodean koi8-r

= pengkodean ShiftJIS

= pengkodean besar5

"=encoding" mempengaruhi seluruh dokumen, dan harus muncul hanya sekali.

Dan jangan lupa, semua perintah kecuali "=encoding" bertahan sampai akhir nya ayat, tidak
garisnya. Jadi dalam contoh di bawah ini, Anda dapat melihat bahwa setiap perintah membutuhkan baris kosong
setelah itu, untuk mengakhiri paragrafnya. (Dan beberapa penerjemah Pod yang lebih tua mungkin memerlukan
baris "= encoding" untuk memiliki baris kosong berikut juga, meskipun seharusnya legal untuk
menghilangkan.)

Beberapa contoh daftar meliputi:

= lebih

= barang *

Barang pertama

= barang *

Item kedua

= kembali

= lebih

= item Foo()

Deskripsi fungsi Foo

=Batang barang()

Deskripsi fungsi Bar

= kembali

format Kode
Dalam paragraf biasa dan dalam beberapa paragraf perintah, berbagai kode pemformatan (alias
"urutan interior") dapat digunakan:

"SAYA " -- teks miring
Digunakan untuk penekanan (""be I "") dan parameter (""ulangi saya "")

"B " -- teks tebal
Digunakan untuk sakelar (""perl's B<-n> switch""), program (""beberapa sistem menyediakan
B untuk itu""), penekanan (""menjadi B ""), dan seterusnya (""dan fitur itu adalah
dikenal sebagai B "").

"C " -- code text
Merender kode dalam font mesin tik, atau memberikan indikasi lain bahwa ini mewakili
teks program (""C "") atau bentuk lain dari komputer
(""C "").

"L " -- sebuah hyperlink
Ada berbagai sintaks, tercantum di bawah ini. Dalam sintaks yang diberikan, "teks", "nama", dan
"bagian" tidak boleh berisi karakter '/' dan '|'; dan '<' atau '>' apa pun harus
cocok.

· "L "

Tautan ke halaman manual Perl (mis., "L "). Perhatikan bahwa "nama" tidak boleh
mengandung spasi. Sintaks ini juga kadang-kadang digunakan untuk referensi ke Unix man
halaman, seperti dalam "Lcrontab(5)>".

· "L " atau "L "

Tautan ke bagian di halaman manual lainnya. Misalnya, "L "

· "L " atau "L "

Tautan ke bagian di halaman manual ini. Misalnya, "L "

Bagian dimulai dengan judul atau item bernama. Misalnya, "L " atau
"L " kedua tautan ke bagian dimulai dengan ""=item $."" di perlvar. Dan
"L " atau "L " kedua tautan ke bagian dimulai oleh
""=head2 Untuk Perulangan"" di perlsyn.

Untuk mengontrol teks apa yang digunakan untuk tampilan, Anda menggunakan ""L "", seperti dalam:

· "L "

Tautkan teks ini ke halaman manual itu. Misalnya, "L "

· "L " atau "L "

Tautkan teks ini ke bagian itu di halaman manual itu. Misalnya, "L
"jika"|perlsyn/"Pengubah Pernyataan">"

· "L " atau "L " atau "L "

Tautkan teks ini ke bagian itu di halaman manual ini. Misalnya, "L
atribut|/"Data Anggota">"

Atau Anda dapat menautkan ke halaman web:

· "L "

"L "

Tautan ke URL absolut. Misalnya, "Lhttp://www.perl.org/>" atau "L
Halaman Beranda|http://www.perl.org/>".

"E " -- karakter melarikan diri
Sangat mirip dengan HTML/XML "&halo;" "referensi entitas":

· "E " -- literal < (kurang dari)

· "E " -- sebuah literal > (lebih besar dari)

· "E " -- harfiah | (vertikal bar)

· "E " -- secara harfiah / (solidus)

Empat di atas adalah opsional kecuali dalam kode pemformatan lain, terutama "L<...>",
dan jika didahului dengan huruf kapital.

· "E "

Beberapa nama entitas HTML non-numerik, seperti "E ", artinya sama dengan
"é" dalam HTML -- yaitu, huruf kecil e dengan aksen akut (/-berbentuk).

· "E "

Karakter ASCII/Latin-1/Unicode dengan nomor tersebut. Awalan "0x" berarti bahwa
jumlah adalah hex, seperti pada "E<0x201E>". Awalan "0" berarti bahwa jumlah adalah oktal, seperti pada
"B<075>". Jika tidak jumlah ditafsirkan sebagai desimal, seperti dalam "E<181>".

Perhatikan bahwa pemformat Pod yang lebih lama mungkin tidak mengenali escape numerik oktal atau hex,
dan bahwa banyak pemformat tidak dapat merender karakter di atas 255 dengan andal. (Beberapa
pemformat bahkan mungkin harus menggunakan rendering yang dikompromikan dari Latin-1/CP-1252
karakter, seperti rendering "E " hanya sebagai "e".)

"F " -- digunakan untuk nama file
Biasanya ditampilkan dalam huruf miring. Contoh: ""F<.cshrc>""

"S " -- teks berisi spasi yang tidak boleh putus
Ini berarti bahwa kata-kata di teks tidak boleh dipatahkan melintasi garis. Contoh:
"S<$x ? $y : $z>".

"X " -- entri indeks
Ini diabaikan oleh sebagian besar formatter, tetapi beberapa mungkin menggunakannya untuk membangun indeks. Dia
selalu dirender sebagai string kosong. Contoh: "X "

"Z<>" -- kode pemformatan nol (nol-efek)
Ini jarang digunakan. Ini adalah salah satu cara untuk menyiasati penggunaan kode E<...> kadang-kadang. Untuk
contoh, alih-alih ""NE 3"" (untuk "N<3") Anda bisa menulis ""NZ<><3"" ("Z<>"
memecah "N" dan "<" sehingga mereka tidak dapat dianggap sebagai bagian dari (fiktif)
kode "N<...>").

Sebagian besar waktu, Anda hanya perlu satu set kurung sudut untuk membatasi
awal dan akhir kode pemformatan. Namun, terkadang Anda ingin menempatkan yang nyata
kurung sudut kanan (tanda lebih besar dari, '>') di dalam kode pemformatan. Ini
sangat umum ketika menggunakan kode pemformatan untuk menyediakan jenis font yang berbeda untuk a
potongan kode. Seperti semua hal di Perl, ada lebih dari satu cara untuk melakukannya. Satu
caranya adalah dengan melepaskan diri dari kurung tutup menggunakan kode "E":

C<$a E =E $b>

Ini akan menghasilkan: ""$a <=> $b""

Cara yang lebih mudah dibaca, dan mungkin lebih "polos" adalah dengan menggunakan serangkaian pembatas alternatif
yang tidak memerlukan satu ">" untuk diloloskan. Tanda kurung siku ganda ("<<" dan ">>")
dapat digunakan if dan hanya if sana is ruang putih benar setelah itu pembukaan pembatas dan
ruang putih benar sebelum itu penutupan pembatas! Misalnya, berikut ini akan melakukan
menipu:

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

Sebenarnya, Anda dapat menggunakan kurung sudut berulang sebanyak yang Anda suka selama Anda memilikinya
jumlah yang sama di pembatas pembukaan dan penutupan, dan pastikan spasi itu
segera mengikuti '<' terakhir dari pembatas pembukaan, dan segera mendahului
'>' pertama dari pembatas penutup. (Spasi putih diabaikan.) Jadi berikut ini akan
juga bekerja:

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

Dan mereka semua berarti persis sama seperti ini:

C<$a E =E $b>

Bentuk tanda kurung ganda tidak mempengaruhi interpretasi isi dari
memformat kode, hanya bagaimana itu harus berakhir. Itu berarti contoh di atas juga
sama persis seperti ini:

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

Sebagai contoh lebih lanjut, ini berarti bahwa jika Anda ingin meletakkan bit kode ini di "C"
(kode) gaya:

buka(X, ">>thing.dat") || mati $!
$foo->bar();

Anda bisa melakukannya seperti ini:

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

yang mungkin lebih mudah dibaca daripada cara lama:

C E hal.dat") || mati $!>
C<$foo-E bar();>

Saat ini didukung oleh pod2text (Pod::Text), pod2man (Pod::Man), dan lainnya
pod2xxx atau penerjemah Pod::Xxxx yang menggunakan Pod::Parser 1.093 atau lebih baru, atau Pod::Tree 1.02 atau
nanti.

The Maksud
Tujuannya adalah kesederhanaan penggunaan, bukan kekuatan ekspresi. Paragraf terlihat seperti paragraf
(format blok), sehingga terlihat menonjol secara visual, dan agar saya dapat menjalankannya
"fmt" dengan mudah untuk memformat ulang mereka (itu F7 di versi saya vi, atau Esc Q di versi saya
emacs). Saya ingin penerjemah selalu meninggalkan tanda kutip "'" dan "`" dan """ saja, di
mode verbatim, jadi saya bisa menyeruput program kerja, menggesernya ke empat spasi, dan memiliki
itu dicetak, eh, kata demi kata. Dan mungkin dalam font monospace.

Format Pod belum tentu cukup untuk menulis buku. Pod hanya dimaksudkan untuk menjadi
sumber umum anti-idiot untuk nroff, HTML, TeX, dan bahasa markup lainnya, seperti yang digunakan untuk
dokumentasi daring. Penerjemah ada untuk pod2teks, pod2html, pod2man (itu untuk
tidak(1) dan troff(1)), pod2latex, dan pod2fm. Berbagai lainnya tersedia di CPAN.

Menanamkan polong in Perl Modul
Anda dapat menyematkan dokumentasi Pod di modul dan skrip Perl Anda. Mulai Anda
dokumentasi dengan baris kosong, perintah "=head1" di awal, dan akhiri dengan a
perintah "=cut" dan baris kosong. NS perl executable akan mengabaikan teks Pod. Kamu bisa
menempatkan pernyataan Pod di mana perl mengharapkan awal dari pernyataan baru, tetapi tidak di dalam
pernyataan, karena itu akan menghasilkan kesalahan. Lihat salah satu modul perpustakaan yang disediakan
untuk contoh.

Jika Anda akan meletakkan Pod Anda di akhir file, dan Anda menggunakan "__END__" atau
Tanda potong "__DATA__", pastikan untuk meletakkan baris kosong di sana sebelum perintah Pod pertama.

__AKHIR__

=kepala1 NAMA

Waktu::Lokal - menghitung waktu secara efisien dari waktu lokal dan GMT

Tanpa baris kosong sebelum "=head1", banyak penerjemah tidak akan mengenali
"=head1" sebagai memulai blok Pod.

Petunjuk untuk Writing Polong
·

The pemeriksa pod perintah disediakan untuk memeriksa sintaks Pod untuk kesalahan dan peringatan.
Misalnya, memeriksa baris yang benar-benar kosong di blok Pod dan untuk yang tidak diketahui
perintah dan kode pemformatan. Anda masih harus melewati dokumen Anda melalui satu
atau lebih penerjemah dan mengoreksi hasilnya, atau mencetak hasilnya dan mengoreksinya
itu. Beberapa masalah yang ditemukan mungkin merupakan bug pada penerjemah, yang mungkin atau mungkin Anda alami
tidak ingin bekerja di sekitar.

· Jika Anda lebih terbiasa menulis dalam HTML daripada menulis di Pod, Anda dapat mencoba
tangan Anda dalam menulis dokumentasi dalam HTML sederhana, dan mengubahnya menjadi Pod dengan
modul Pod::HTML2Pod eksperimental, (tersedia di CPAN), dan lihat hasilnya
kode. Modul eksperimental Pod::PXML di CPAN mungkin juga berguna.

· Banyak penerjemah Pod yang lebih tua membutuhkan baris sebelum setiap perintah Pod dan setelah setiap
Perintah Pod (termasuk "=cut"!) menjadi baris kosong. Memiliki sesuatu seperti ini:

# - - - - - - - - - - - -
=item $petasan->boom()

Ini meledakkan objek petasan dengan berisik.
= potong
sub booming {
...

...akan membuat para penerjemah Pod tersebut benar-benar gagal melihat blok Pod sama sekali.

Sebagai gantinya, buat seperti ini:

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

=item $petasan->boom()

Ini meledakkan objek petasan dengan berisik.

= potong

sub booming {
...

· Beberapa penerjemah Pod yang lebih lama memerlukan paragraf (termasuk paragraf perintah seperti
"=head2 Fungsi") untuk dipisahkan oleh sama sekali baris kosong. Jika Anda memiliki
tampaknya baris kosong dengan beberapa spasi di atasnya, ini mungkin tidak dihitung sebagai pemisah untuk
penerjemah tersebut, dan itu dapat menyebabkan pemformatan yang aneh.

· Penerjemah yang lebih tua mungkin menambahkan kata-kata di sekitar tautan L<>, sehingga "L " boleh
menjadi "halaman manual Foo::Bar", misalnya. Jadi Anda tidak boleh menulis hal-hal seperti "the
L dokumentasi", jika Anda ingin dokumen yang diterjemahkan dibaca dengan bijaksana.
tulis "L dokumentasi" atau "L
dokumentasi|Foo::Bar>", untuk mengontrol bagaimana tautan keluar.

· Melewati kolom ke-70 dalam blok kata demi kata mungkin tidak sopan dibungkus oleh beberapa
pemformat.

Gunakan perlpod online menggunakan layanan onworks.net