Часть 1

Алексей Мичурин

Разрабатываете ли вы утилиту или обширный пакет программ, строите ли аппаратный комплекс или создаёте программно-аппаратную среду, вы неминуемо столкнётесь с необходимостью составления качественной документации. Зачастую требуется или желательно, чтобы документация была доступна в нескольких форматах: для печати и для ознакомления on-line. Система POD предлагает простой язык разметки документов и средства конвертирования, позволяющие получить документы в наиболее «ходовых» форматах: не размеченный текст, man-страница, HTML-страница, PostScript и PDF.

Что такое POD?

Постараюсь угадать первые вопросы читателей и коротко ответить на них, но прежде не могу не процитировать perldoc perlpod: «The Pod format is not necessarily sufficient for writing a book. Pod is just meant to be an idiot-proof common source for nroff, HTML, TeX, and other markup languages, as used for online documentation».

Аббревиатура POD означает Plain Old Documentation.

POD разрабатывалась для документирования программ и модулей, разработанных на языке Perl. Но, во-первых, эта система достаточно универсальна и может использоваться для документирования не только Perl-программ. А во-вторых, она разработана так, что не требует для написания документации знания языка Perl. Это делает её универсальным, мощным и простым в освоении средством создания электронных документов.

Слово «old» в аббревиатуре не должно вводить читателя в заблуждение. Система не является устаревшей. Напротив, она постоянно совершенствуется. В последней версии Perl (5.8) впервые появилась подробная спецификация POD.

Я не могу претендовать на исчерпывающее описание. Если оно вам нужно, обратитесь к perldoc perlpodspec. Там подробно обсуждаются все детали формата.

Например, что будет, если в список вставить заголовок или повторно выделить жирным текст, уже являющийся таковым. Для решения большинства задач документирования этих тонкостей знать не надо. Они нужны, скорее, разработчикам новых конвертеров POD-документов в другие форматы. Для пользователя существует описание формата POD perldoc perlpod. В этой статье я практически не буду выходить за его рамки, но отдельно рассмотрю вопросы кириллизации POD, не затронутые ни в одном из указанных руководств.