Кіріспе
Perl құжаттамасының таңбалау тілі (Plain Old Documentation) — Perl бағдарламалау тілін, сондай-ақ Perl модульдері мен бағдарламаларын құжаттау үшін қолданылатын жеңіл таңбалау тілі.
Plain Old Documentation (pod) is a lightweight markup language used to document the Perl programming language as well as Perl modules and programs.
Қолдану
Pod – Perl әлеміндегі көптеген құжаттамалар үшін қолданылатын тіл. Бұл Perl-дің өзіне, дерлік барлық ашыққа шығарылған модульдерге, көптеген скрипттерге, көпшілік дизайн құжаттарына, Perl туралы көптеген мақалаларға, .com және басқа Perl-ге қатысты веб-сайттарға, сондай-ақ Parrot виртуалды машинасына қатысты. Pod көбінесе өңдеу құралының көмегінсіз оқылмайды, бірақ ол пішімдеу құралынсыз оқуға ыңғайлы. Оның орнына, ол perldoc құралымен оқылады немесе Unix man беттеріне немесе Web стандартты HTML беттеріне түрлендіріледі. Pod-ты Perl-ден басқа жағдайларда да қолдануға болады. Мысалы, bash скрипттеріне қарапайым құжаттама қосу үшін, оларды кейіннен man беттеріне оңай түрлендіруге болады. Мұндай қолданыстар POD бөлігін жасыру үшін тілге тән тәсілдерге сүйенеді, мысалы (bash-та) POD бөлімін :<<=cut жолымен алдын ала қою, бұл bash-тың операциясыз : командасын шақыру арқылы жұмыс істейді, Pod-тың толық блогы оған кіріс дерегі ретінде беріледі. Таза pod файлдары әдетте .pod кеңейтімімен сақталады, бірақ pod көбінесе тікелей Perl кодында қолданылады, ол әдетте .pl және .pm кеңейтімдерін пайдаланады. (Perl интерпретаторының анализаторы Perl кодындағы pod-ты назарға алмайды.) Бастапқы код файлдарында құжаттама әдетте END белгісінен кейін орналастырылады (бұл кейбір редакторларда оны түсініктеме ретінде көрсету үшін синтаксистің ерекшеленуіне көмектеседі). Pod-ты басқа форматтарға оңай түрлендіруге болады, мысалы, WikiWikiWeb, Kwiki, TWiki, UseModWiki, TiddlyWiki, Textile, MediaWiki, MoinMoin немесе Confluence сияқты әртүрлі Wiki форматтарына Pod::Simple::Wiki арқылы.
and the Parrot virtual machine. Pod is rarely read in the raw, although it is designed to be readable without the assistance of a formatting tool. Instead, it is read with the perldoc tool, or converted into Unix man pages or Web standard HTML pages. It is also possible to use pod in other contexts than Perl. For example, to add simple documentation to bash scripts, which can then be easily converted to man pages. Such uses rely on language specific hacks to hide the pod part(s), such as (in bash) prefixing the POD section with the line :<<=cut which works by calling bash's no op : command, with the whole block of Pod as a here document as input to it. Pure pod files usually have the extension pod, but pod is mostly used directly in Perl
code, which typically uses the pl and pm extensions. (The Perl
interpreter's parser is designed to ignore pod in Perl code.) In source code files, the documentation is generally placed after the END marker (which also helps syntax highlighting in some editors to display it as comments). Pod can easily be converted to other formats, for example some of the various Wiki formats like: WikiWikiWeb, Kwiki, TWiki, UseModWiki, TiddlyWiki, Textile, MediaWiki, MoinMoin or Confluence using Pod::Simple::Wiki.
Мысал
Бұл құжат синтаксистік тұрғыдан дұрыс, сонымен қатар бөлімдерді атаудың қалыпты талаптарын сақтауға тырысады.
Пішімдеу егжей-тегжейі
Pod файлдары ASCII-ға үйлесімді кодтауларда, мысалы, Latin 1 немесе UTF 8 форматында жазылады. Pod талдағышы (parser) әрқашан өңделіп жатқан файлдың pod сөзімен басталмайтынын болжайды; ол pod директивасын кездестіргенге дейін барлық жолдарды назардан тыс қалдырады. Pod директивалары жолдың басында орналасуы керек және барлығы тең белгімен (=) басталады. Pod талдағышы содан кейін барлық келесі жолдарды pod ретінде қарастырады, "=cut" директивасынан тұратын жолға дейін. Осыдан кейінгі кез келген мазмұн, талдағыш тағы бір pod директивасын кездестіргенге дейін елемей қалады. Осылайша, pod тілдің талдағышы pod-ты қалай тану керектігін және назардан тыс қалдыру керектігін білсе, орындалатын кодпен араластырылуы мүмкін. Pod мазмұны бос жолдар арқылы абзастарға бөлінеді. Бос орын (пробел) немесе табуляция таңбаларымен басталатын абзастар "әдеби абзастар" деп есептеледі және толығымен өзгеріссіз қалдырылады; олар мысал кодтары, ASCII графикасы және т.б. үшін қолданылады. Тең белгісімен басталатын абзастар "команда абзастары" болып табылады; тең белгісінен кейін тікелей келетін әріптік-сандық символдар тізбегі pod директивасы ретінде қарастырылады, ал абзастың қалған бөлігі осы директиваға сәйкес пішімделеді. Кейбір директивалар келесі абзастарға да әсер етеді. Егер абзац тең белгісінен немесе бос орыннан басқа нәрсемен басталса, ол "қалыпты абзац" деп саналады. Қалыпты абзастар мен команда абзастарының мазмұны пішімдеу кодтарын табу үшін талданады. Pod-тағы пішімдеу өте қарапайым; ол негізінен қалың, көлбеу, сызылған, моноширінді және басқа да бірнеше пішімдермен шектеледі. Сондай-ақ, pod құжаттары арасында немесе бір құжаттың ішіндегі басқа бөлімге сілтеме жасауға мүмкіндік беретін код бар. Пішімдеу кодтары мынадай болып келеді:
until it sees a pod directive. pod directives must come at the beginning of a line, and all begin with an equal sign. The pod parser will then assume that all following lines are pod, until it encounters a line consisting of the "=cut" directive. Any content following that is ignored until the parser encounters another pod directive. Thus, pod can be intermixed with executable source code if the language's parser knows how to recognize and ignore pod. Pod content is divided into paragraphs by empty lines. Paragraphs that begin with whitespace characters—tabs or spaces—are considered to be "verbatim paragraphs", and are left completely unformatted; these are used for sample code, ASCII art, etc. Paragraphs that begin with an equal sign are "command paragraphs"; the sequence of alphanumeric characters immediately following the equal sign is treated as a pod directive, and the rest of the paragraph is formatted according to that directive. Some directives also affect the following paragraphs. If a paragraph starts with something besides an equal sign or whitespace, it's considered an "ordinary paragraph". Both ordinary paragraphs and the contents of command paragraphs are parsed for formatting codes. Formatting in pod is very plain; it's mainly limited to bold, italic, underlined, monospaced, and a few other formats. There is also a code for linking between pod documents or to another section within the same document. Formatting codes consist of either:
* Бір үлкен әріп, одан кейін кіші белгі (<), пішімделуі керек мазмұн және үлкен белгі (>), мысалы, B<қалың мәтін>, немесе
* Бір үлкен әріп, екі немесе одан көп кіші белгілер (<<), бос орын, пішімделуі керек мазмұн, тағы бір бос орын және бұрын қолданылған кіші белгілердің санымен тең үлкен белгілер, мысалы, B<<қалың мәтін>>. Бұл форма көбінесе үлкен белгіні қамтитын код фрагменттері үшін қолданылады, әйтпесе пішімдеу коды осы белгімен аяқталар еді. Pod-тағы командалар төрт деңгейлі тақырыптарды, тізімдерді (маркерленген және нөмірленген) және бөлімдерді басқа тілде деп белгілеуге арналған командаларды қамтиды. Соңғы мүмкіндік оны қолдайтын талдағыштарға арнайы пішімдеуді беруге мүмкіндік береді.
A single uppercase letter, two or more less than signs (<<), a space, the content to be formatted, another space, and the same number of greater than signs as were used before, e. g. B<< bolded text >>. This form is often used for code snippets containing a greater than sign, which would otherwise end the formatting code. Commands in pod include four levels of headings, bulleted and numbered lists, and commands to mark sections as being in another language. The latter feature allows for special formatting to be given to parsers that support it.