perlpodstyle - Online sa Cloud

PROGRAMA:

NAME

perlpodstyle - Gabay sa istilo ng Perl POD

DESCRIPTION

Ito ang mga pangkalahatang patnubay para sa kung paano magsulat ng dokumentasyon ng POD para sa mga Perl script at
modules, batay sa pangkalahatang mga alituntunin para sa pagsusulat ng magandang UNIX man page. Lahat ng ito
Ang mga alituntunin ay, siyempre, opsyonal, ngunit ang pagsunod sa mga ito ay gagawing higit ang iyong dokumentasyon
pare-pareho sa iba pang dokumentasyon sa system.

Ang pangalan ng program na nakadokumento ay karaniwang nakasulat sa bold (gamit ang B<>)
saanman ito mangyari, tulad ng lahat ng mga opsyon sa programa. Ang mga argumento ay dapat na nakasulat sa italics
(ako<>). Ang mga pangalan ng function ay tradisyonal na nakasulat sa italics; kung sumulat ka ng isang function bilang
function(), Pod::Lalaki na ang bahala dito para sa iyo. Ang literal na code o mga utos ay dapat
sa C<>. Ang mga sanggunian sa ibang mga man page ay dapat nasa anyong "manpage(seksyon)" o
"L ", at Pod::Man ay awtomatikong i-format ang mga iyon nang naaangkop. Ang
Ang pangalawang anyo, na may L<>, ay ginagamit upang humiling na ang isang POD formatter ay gumawa ng isang link sa man page
kung maaari. Bilang isang pagbubukod, karaniwang inaalis ng isa ang seksyon kapag tinutukoy ang module
dokumentasyon dahil hindi malinaw kung saang seksyon ang babasahin ng module; gamitin
"L " para sa mga sanggunian ng module sa halip.

Ang mga sanggunian sa iba pang mga programa o function ay karaniwang nasa anyo ng mga sanggunian sa man page
upang ang mga cross-referencing tool ay makapagbigay sa user ng mga link at mga katulad nito. ito ay
posibleng lumampas ito, gayunpaman, kaya mag-ingat na huwag kalat din ang iyong dokumentasyon
maraming markup. Mga sanggunian sa iba pang mga programa na hindi ibinigay bilang mga sanggunian sa man page
dapat na nakapaloob sa B<>.

Ang mga pangunahing header ay dapat itakda gamit ang isang "=head1" na direktiba, at ayon sa kasaysayan
nakasulat sa medyo nakakagulat na ALL UPPER CASE na format; ito ay hindi sapilitan, ngunit ito ay
mahigpit na inirerekomenda upang ang mga seksyon ay may pare-parehong pagpapangalan sa iba't ibang software
mga pakete. Maaaring isama ang mga menor de edad na header gamit ang "=head2", at karaniwang nasa magkahalong kaso.

Ang mga karaniwang seksyon ng isang manu-manong pahina ay:

NAME
Mandatoryong seksyon; dapat ay isang listahan ng mga programa o function na pinaghihiwalay ng kuwit
dokumentado ng pahina ng POD na ito, tulad ng:

foo, bar - mga programa para gumawa ng isang bagay

Ang mga manual page indexer ay kadalasang napakapili tungkol sa format ng seksyong ito, kaya
huwag maglagay ng anuman dito maliban sa linyang ito. Bawat programa o function na dokumentado ng
dapat nakalista ang POD page na ito, na pinaghihiwalay ng kuwit at puwang. Para sa isang Perl module,
ibigay lang ang pangalan ng module. Isang solong gitling, at isang solong gitling lang, ang dapat maghiwalay sa
listahan ng mga programa o function mula sa paglalarawan. Huwag gumamit ng anumang markup tulad ng C<>
o B<> saanman sa linyang ito. Ang mga function ay hindi dapat maging kwalipikado sa "()" o sa
gaya ng. Ang paglalarawan ay dapat na perpektong magkasya sa isang linya, kahit na isang programa ng tao
pinapalitan ang gitling ng ilang tab.

SINOPSIS
Isang maikling buod ng paggamit para sa mga programa at function. Ang seksyong ito ay sapilitan para sa
seksyon 3 mga pahina. Para sa dokumentasyon ng Perl module, kadalasang maginhawang magkaroon ng
ang mga nilalaman ng seksyong ito ay isang verbatim block na nagpapakita ng ilang (maikling) halimbawa ng tipikal
paraan ng paggamit ng modyul.

DESCRIPTION
Pinalawak na paglalarawan at talakayan ng programa o mga function, o ang katawan ng
dokumentasyon para sa mga man page na nagdodokumento ng ibang bagay. Kung partikular na mahaba, ito ay
isang magandang ideya na hatiin ito sa mga subsection na "=head2" na mga direktiba tulad ng:

=head2 Normal na Paggamit

=head2 Mga Advanced na Tampok

=head2 Pagsusulat ng Mga File ng Configuration

o anuman ang naaangkop sa iyong dokumentasyon.

Para sa isang module, ito ay karaniwang kung saan ang dokumentasyon ng mga interface na ibinigay ng
napupunta ang module, kadalasan sa anyo ng isang listahan na may "=item" para sa bawat interface.
Depende sa kung gaano karaming mga interface ang mayroon, maaaring gusto mong ilagay ang dokumentasyong iyon
hiwalay na mga seksyon ng METHODS, FUNCTIONS, CLASS METHODS, o INSTANCE METHODS at
i-save ang seksyong DESCRIPTION para sa isang pangkalahatang-ideya.

Opsyon
Detalyadong paglalarawan ng bawat isa sa mga opsyon sa command-line na kinuha ng programa. Ito
dapat na hiwalay sa paglalarawan para sa paggamit ng mga parser tulad ng Pod::Usage. Ito
ay karaniwang ipinapakita bilang isang listahan, na ang bawat opsyon ay hiwalay na "=item". Ang tiyak
ang pagpipiliang string ay dapat na nakapaloob sa B<>. Anumang mga halaga na kinuha ng opsyon ay dapat na
nakapaloob sa I<>. Halimbawa, ang seksyon para sa opsyon --seksyon=manext ay magiging
ipinakilala sa:

=item B<--section>=I

Pinaghihiwalay ng kuwit at a
space sa parehong linyang "=item", o opsyonal na nakalista bilang sarili nilang item na may a
pagtukoy sa canonical na pangalan. Halimbawa, mula noong --seksyon maaari ding isulat bilang
-s, ang nasa itaas ay magiging:

=item B<-s> I , B<--section>=I

Inirerekomenda na isulat muna ang maikling opsyon dahil mas madaling basahin. Ang mahaba
ang opsyon ay sapat na ang haba upang maakit ang mata dito at ang maikling opsyon ay maaaring kung hindi man
mawala sa biswal na ingay.

IBABALIK ANG HALAGA
Ano ang ibinabalik ng programa o function, kung matagumpay. Maaaring tanggalin ang seksyong ito para sa
mga program na ang mga tiyak na exit code ay hindi mahalaga, basta't magbabalik sila ng 0 sa tagumpay
at non-zero sa kabiguan bilang pamantayan. Dapat itong palaging naroroon para sa mga function.
Para sa mga module, maaaring maging kapaki-pakinabang ang pagbubuod ng mga return value mula sa interface ng module
dito, o maaaring mas kapaki-pakinabang na talakayin ang mga halaga ng pagbabalik nang hiwalay sa
dokumentasyon ng bawat function o paraan na ibinibigay ng module.

MGA KAMALI
Mga pagbubukod, error return code, exit status, at errno setting. Karaniwang ginagamit para sa
function o module na dokumentasyon; Ang dokumentasyon ng programa ay gumagamit ng DIAGNOSTICS sa halip. Ang
pangkalahatang tuntunin ng thumb ay ang mga error na naka-print sa "STDOUT" o "STDERR" at nilayon para sa
ang end user ay nakadokumento sa DIAGNOSTICS habang ang mga error ay pumasa sa panloob sa pagtawag
program at inilaan para sa iba pang mga programmer ay nakadokumento sa MGA MALI. Kapag nagdodokumento
isang function na nagtatakda ng errno, isang buong listahan ng mga posibleng errno value ang dapat ibigay
dito.

DIAGNOSTICS
Lahat ng posibleng mensahe ay maaaring i-print ng programa at kung ano ang ibig sabihin ng mga ito. Baka gusto mo
sundin ang parehong istilo ng dokumentasyon gaya ng dokumentasyon ng Perl; tingnan mo perldiag(1) para sa
higit pang mga detalye (at tingnan din ang pinagmulan ng POD).

Kung naaangkop, mangyaring isama ang mga detalye sa kung ano ang dapat gawin ng user upang itama ang error;
pagdodokumento ng isang error bilang nagpapahiwatig na "ang input buffer ay masyadong maliit" nang hindi sinasabi ang
user kung paano dagdagan ang laki ng input buffer (o hindi bababa sa pagsasabi sa kanila na ito
ay hindi posible) ay hindi masyadong kapaki-pakinabang.

HALIMBAWA
Magbigay ng ilang halimbawa ng paggamit ng program o function. Huwag magtipid; madalas itong mahanap ng mga user
ang pinakakapaki-pakinabang na bahagi ng dokumentasyon. Ang mga halimbawa ay karaniwang ibinibigay bilang
verbatim na mga talata.

Huwag lamang magpakita ng isang halimbawa nang hindi ipinapaliwanag kung ano ang ginagawa nito. Pagdaragdag ng maikling
talata na nagsasabi kung ano ang gagawin ng halimbawa ay maaaring tumaas ang halaga ng halimbawa
napakalaki.

Kapaligiran
Ang mga variable ng kapaligiran na pinapahalagahan ng programa, na karaniwang ipinapakita bilang isang listahan na ginagamit
"=over", "=item", at "=back". Halimbawa:

=higit sa 6

=item HOME

Ginagamit upang matukoy ang home directory ng user. F<.foorc> dito
binabasa ang direktoryo para sa mga detalye ng pagsasaayos, kung mayroon ito.

= likod

Dahil ang mga variable ng kapaligiran ay karaniwang nasa lahat ng malalaking titik, walang karagdagang espesyal
karaniwang kailangan ang pag-format; sila ay nakasisilaw sapat na ito ay.

MGA FILE
Lahat ng mga file na ginagamit ng program o function, na karaniwang ipinapakita bilang isang listahan, at kung ano ito
ginagamit ang mga ito para sa. Ang mga pangalan ng file ay dapat na nakapaloob sa F<>. Ito ay partikular na mahalaga sa
mga file ng dokumento na posibleng mabago.

MGA CAVEATS
Mga bagay na dapat bigyan ng espesyal na pangangalaga, kung minsan ay tinatawag na MGA BABALA.

TUMBOK
Mga bagay na sira o sadyang hindi gumagana nang tama.

RESTRICTIONS
Mga bug na hindi mo planong ayusin. :-)

NOTA
Sari-saring komentaryo.

AUTHOR
Sino ang nagsulat nito (gumamit ng AUTHORS para sa maraming tao). Magandang ideya na isama ang iyong
kasalukuyang e-mail address (o ilang e-mail address kung saan dapat ipadala ang mga ulat ng bug) o
ilang iba pang impormasyon sa pakikipag-ugnayan upang ang mga user ay magkaroon ng paraan ng pakikipag-ugnayan sa iyo. Tandaan
na ang dokumentasyon ng programa ay may posibilidad na gumala sa ligaw nang mas matagal kaysa sa iyong inaasahan at
pumili ng paraan ng pakikipag-ugnayan na malamang na magtatagal.

KASAYSAYAN
Ang mga program na nagmula sa ibang mga mapagkukunan kung minsan ay mayroon nito. Ang ilang mga tao ay nagpapanatili ng a
log ng pagbabago dito, ngunit karaniwan itong humahaba at karaniwang mas pinapanatili sa
isang hiwalay na file.

COPYRIGHT AT LISENSYA
Para sa copyright

Copyright YEAR(s) YOUR NAME(s)

(Hindi, (C) ay hindi kailangan. Hindi, "all rights reserved" ay hindi kailangan.)

Para sa paglilisensya ang pinakamadaling paraan ay ang paggamit ng parehong paglilisensya gaya ng mismong Perl:

Ang library na ito ay libreng software; maaari mo itong muling ipamahagi at/o
baguhin ito sa ilalim ng parehong mga termino bilang Perl mismo.

Ginagawa nitong madali para sa mga tao na gamitin ang iyong module sa Perl. Tandaan na ang paglilisensyang ito
halimbawa ay hindi isang pag-endorso o isang kinakailangan, siyempre libre kang pumili
anumang paglilisensya.

TINGNAN DIN
Iba pang mga man page upang tingnan, i-like lalakiNa (1), lalakiNa (7), makewhatis(8), o taong pusaNa (8).
Karaniwang isang simpleng listahan ng mga man page na pinaghihiwalay ng mga kuwit, o isang talata na nagbibigay ng
pangalan ng isang sangguniang gawain. Mga sanggunian sa man page, kung ginagamit nila ang pamantayan
"pangalan(seksyon)" na form, hindi kailangang ilakip sa L<> (bagama't inirerekomenda),
ngunit ang ibang mga bagay sa seksyong ito ay malamang na dapat kung naaangkop.

Kung may mailing list ang package, magsama ng URL o mga tagubilin sa subscription dito.

Kung may web site ang package, magsama ng URL dito.

Maaaring naisin ng dokumentasyon ng mga object-oriented na library o module na gumamit ng CONSTRUCTORS at
Mga seksyon ng METHODS, o mga seksyon ng CLASS METHODS at INSTANCE METHODS, para sa detalyadong
dokumentasyon ng mga bahagi ng aklatan at i-save ang seksyong DESCRIPTION para sa isang
pangkalahatang-ideya. Maaaring gusto ng malalaking module na may interface ng function na gumamit ng FUNCTIONS para sa katulad
mga dahilan. Ang ilang mga tao ay gumagamit ng PANGKALAHATANG-IDEYA upang ibuod ang paglalarawan kung ito ay medyo mahaba.

Nag-iiba-iba ang pag-order ng seksyon, bagama't ang NAME ay dapat palaging ang unang seksyon (masisira mo ang ilan
man page system kung hindi man), at NAME, SYNOPSIS, DESCRIPTION, at OPTIONS sa pangkalahatan ay palaging
mangyari muna at sa ganoong pagkakasunud-sunod kung naroroon. Sa pangkalahatan, TINGNAN DIN, AUTHOR, at katulad nito
materyal ay dapat na iwan para sa huling. Ang ilang mga system ay naglilipat din ng MGA BABALA at TALA upang tumagal. Ang
Ang pagkakasunud-sunod na ibinigay sa itaas ay dapat na makatwiran para sa karamihan ng mga layunin.

Gumagamit ang ilang system ng CONFORMING TO para tandaan ang pagsunod sa mga nauugnay na pamantayan at MT-LEVEL sa
tandaan ang kaligtasan para sa paggamit sa mga sinulid na programa o mga humahawak ng signal. Ang mga heading na ito ay
pangunahing kapaki-pakinabang kapag nagdodokumento ng mga bahagi ng isang C library.

Panghuli, bilang pangkalahatang tala, subukang huwag gumamit ng labis na halaga ng markup. Tulad ng dokumentado
dito at sa Pod::Man, maaari mong ligtas na iwanan ang mga variable ng Perl, mga pangalan ng function, pahina ng tao
mga sanggunian, at mga katulad na hindi pinalamutian ng markup at malalaman ito ng mga tagasalin ng POD
para sa iyo. Ginagawa nitong mas madaling i-edit ang dokumentasyon sa ibang pagkakataon. Tandaan na marami
ang mga kasalukuyang tagasalin ay gagawa ng maling bagay sa mga e-mail address kapag nakabalot sa L<>, kaya
wag mong gawin yan.

Gumamit ng perlpodstyle online gamit ang mga serbisyo ng onworks.net