 |
|
|
|
Система создания документации POD. Часть 1
Система создания документации POD Часть 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, не затронутые ни в одном из указанных руководств. Принцип работы POD Читатели, знакомые с HTML или системой вёрстки TeX/LaTeX, уже встречались с подходом, практикуемым и в POD. Это не WYSIWYG-система. Она предполагает, что вы разрабатываете документ в определённом формате, а потом конвертируете его в любой другой, который необходим вам для печати или просмотра. Это позволяет поддерживать одну «мастер-версию» в формате POD, из которой по мере необходимости вы сможете получать документы в различных форматах и по-разному оформленные, например, отличающиеся базовым размером шрифта или свёрстанные в одну или две колонки. Таким образом, для освоения POD нам придётся рассмотреть сам формат и средства конвертирования. Статья и примеры В статье я буду рассказывать о возможностях POD от простого к сложному. При накоплении критической массы знаний мы будем отвлекаться и рассматривать вопросы конвертирования POD-документов в соответствующий формат. Естественно, при таком изложении и форматы будут идти от простых к сложным. Для того чтобы не быть голословным, я написал крошечную программку на Perl и снабдил её инструкцией. Подавляющее большинство примеров в этой статье взяты из неё. Вы можете получить полную версию программы и документации на сайте журнала в разделе «Исходный код». Далее я буду называть этот файл для краткости просто архивом. В него входят документированная программа и все средства преобразования документации в форматы – от простых текстовых до PostScript, PDF и HTML. Конвертирование в PostScript и PDF будет описано в следующем номере. Перейдём к рассмотрению возможностей POD. Начнём с базовых принципов формата POD. Абзацы в POD Формат POD предполагает, что весь документ разбит на абзацы, которые отделены друг от друга одной (или более) пустой строкой. Очень желательно, чтобы это была действительно пустая строка, не содержащая даже пробелов. Старые версии обработчиков POD могут некорректно реагировать на подобные неточности соблюдения формата. Абзацы бывают всего трёх типов:
Тип параграфа задаётся очень просто:
Вот простой пример форматированного и неформатированного параграфов: Конвертировать EPS-файл в любой другой формат можно программой C, имеющей неисчислимое множество опций и возможностей. Пример: gs -sDEVICE=png16 -sOutputFile=drag.png -dBATCH -dNOPAUSE -r72x72 -sPAPERSIZE=a5 drag.eps Обратите внимание, второй параграф («gs...») начинается с пробела, это неформатированный параграф. После обработки, в формате PDF этот фрагмент будет выглядеть примерно так:
Конечно, внешний вид будет слегка варьироваться в зависимости от того, какой вы выберете размер шрифта при создании PDF, каков будет размер бумаги и поля, во сколько колонок будет свёрстан документ, будет ли использоваться система автоматической расстановки переносов. Основные команды Управляющих команд совсем немного, и в этом разделе мы рассмотрим почти все из них. Оформление команд, команды начала и конца документа Сперва скажу о командах =pod и =cut. Они задают начало и конец POD-документа соответственно. Использование =сut не обязательно. Эта команда полезна в тех случаях, когда файл содержит не только POD-документ. При документировании Perl-программ и модулей общепринятой практикой является включение в один файл и Perl-кода программы или модуля, и POD-документа к нему. Обратите внимание! Чтобы эти команды получили должную интерпретацию, их следует оформить как отдельные командные параграфы. То есть они должны иметь по одной (или более) пустых строк до и после; а знак «=» должен быть первым в строке. В следующем примере я создал простой POD-документ, содержащий три слова: =pod Привет от POD. =cut Если вы оформите его так: =pod Привет от POD. =cut то «=cut» будет считаться просто четвёртым словом в единственном форматированном параграфе документа. Об этой специфике надо помнить и при использовании других команд. Я для краткости буду говорить о «командах», но подразумевать буду управляющие параграфы, начинающиеся с этих команд. Заголовки Команды =head1, =head2, =head3, =head4 позволяют задавать заголовки разных уровней. Весь текст абзаца после этих команд интерпретируется как текст заголовка. Вот фрагмент POD-документа, содержащего различные заголовки: =head1 Алгоритмы построения Приведу здесь два алгоритма, отличающихся принципиально. =head2 Итерационный алгоритм построения дракона Настоящая программа использует именно этот алгоритм. А вот PDF-результат:
Как видите, номера расставляются автоматически. Скоро мы увидим, что автоматически могут создаваться и оглавления. Списки Для форматирования списков в POD предусмотрено три команды:
Спецификация POD настаивает на том, чтобы разработчики не использовали смешанных списков. То есть в одном списке не должны сочетаться и нумерованные и ненумерованные элементы (вряд ли кому-то понадобится такой список-химера). POD-процессоры оставляют за собой право заменять маркеры-звёздочки на более подходящие символы, если это возможно (например, в формате HTML). В нумерованных списках рекомендуется начинать нумерацию с единицы. Сам элемент списка, отмеченный маркером, содержится в следующем абзаце или абзацах. Список может вообще не содержать элементов, а только маркеры. Вот пример списка (не обращайте пока внимания на управляющие последовательности C<...> и E<...>, мы к ним ещё вернёмся): Всё построение ведёт подпрограмма C<next_step>. Она получает следующие параметры: =over =item $x, $y Первый и второй E<mdash> координаты начала вектора. =item $dx, $dy Третий и четвёртый E<mdash> координаты самого вектора. =item $d Текущая глубина рекурсии. =back В формате PDF этот фрагмент кода будет давать примерно такой результат.
Маркеры можно не указывать, тогда их не будет и в результирующем документе. Отступ же сохранится. Списки можно использовать и не совсем по назначению. Например, вот так:
Это просто список из одного элемента. Первый опыт конвертирования Мы уже знаем достаточно, чтобы разметить простенький POD-документ. Готовый POD-файл можно сконвертировать в текстовый документ. Делается это командой pod2text, например, так: pod2text input.pod >output.txt Вот как будет выглядеть результат конвертирования фрагмента документа, который я привёл в разделе про заголовки:
Команда pod2text допускает множество ключей. Перечислять их все нет смысла, тем более что многие предоставляют весьма экзотические возможности (например, сохранение в результирующем документе не только обработанного POD-кода, но и всего остального содержимого файла), которые могут быть полезны только Perl-программистам. Я лишь упомяну о весьма полезной опции -w, позволяющей указать ширину документа. Опция -m позволяет задать поля. Я ещё вернусь к вопросам конвертирования в текстовый формат, когда мы продвинемся чуть дальше в освоении POD, а исчерпывающую информацию по pod2text можно найти в руководстве perldoc pod2text. Форматирование Давайте теперь рассмотрим, какую разметку допускают форматированные абзацы. В форматированных абзацах можно задавать определённое оформление текста. Доступны три классические возможности: жирный шрифт (bold), курсивный шрифт (italic) и моноширинный шрифт (code). Управляющие последовательности просты и компактны: Часть текста можно выделить I<курсивом>, некоторые фрагменты - B<полужирным шрифтом> или C<моноширинным шрифтом>. Здесь, как вы уже догадались, слова «курсивом», «полужирным шрифтом» и «моноширинным шрифтом» будут оформлены соответствующим образом. Если формат, в который вы конвертируете документ, не допускает подобных вариаций шрифта (например, рассмотренный выше обычный текст), то управляющие последовательности будут корректно проигнорированы. POD предлагает и средства логической разметки. Конструкция F<...> предназначена для выделения имён файлов (обычно эквивалентна курсиву I<...>). Конструкция X<...> игнорируется большинством конвертеров, но может использоваться для создания предметных указателей. Конструкция S<...> указывает на то, что текст, заключённый в ней, не должен разбиваться на строки. Например: S<Ситникова О.В.> или S<5 кг.> Инициалы всегда будут находиться на одной строке с фамилией, а единицы измерения не «оторвутся» от величины. Для полноты скажу о довольно редко используемой последовательности Z<>. Это «символ нулевой ширины». Он не отображается на печати и поэтому может показаться абсолютно бесполезным. Пример его использования я приведу чуть ниже. Как только вы начнёте создавать свои собственные POD-документы, вы столкнётесь с одной проблемой. Как выделить курсивом фразу «Alex » или выделить жирным «I>10A»? Очевидно, конструкция вида: B10A> не даст требуемого результата. Жирным будет выделена только буква I, а необходимый нам знак «больше» вообще исчезнет, будучи проинтерпретирован как часть управляющей последовательности. В ранних версиях POD эта проблема решалась только путём использования escape-последовательностей (о них разговор ниже). Этот метод работает и по сей день, но он не очень удобен. Начиная с версии POD, поставляемой с Perl 5.5.660, был предложен гораздо более изящный путь обойти эти затруднения. Теперь фрагмент текста, подлежащий выделению, можно ограничивать любым количеством символов «<« и «>». «Открывающая» и «закрывающая» последовательности должны быть одинаковой длины, а заключённый в них текст должен быть дополнен пробелами в начале и в конце. Эти пробелы также являются частью управляющей конструкции и не будут отображаться на печати. То есть в нашем примере требуемого результата можно добиться, написав в POD-файле: B<< I>10A >> Более «тяжеловесные» ограничители тоже могут пригодиться. Например: C<<< cat part >> file2append >>> Здесь вся фраза «cat part >> file2append» будет оформляться моноширинным шрифтом. Как раз здесь уместно вспомнить о последовательности Z<>. Её можно внедрить между двумя символами «больше». Она никак не повлияет на внешний вид документа, но разобьёт последовательность «>>», которая в противном случае могла бы быть интерпретирована как управляющая. Одним словом, код: C<< cat part >> file2append >> будет понят POD-конвертерами не так, как мы хотели, а код: << cat part >Z<>> file2append >> даст как раз требуемый результат. Честно говоря, я не сталкивался с ситуациями, когда использование последовательности Z<> было бы действительно оправданно (мой пример – не исключение), но, возможно, вы встретитесь с такими ситуациями, и вам она сослужит хорошую службу. Такая же разметка допустима и в управляющих параграфах, например, в тексте заголовков, но там её использование не вполне оправданно. Текст управляющих параграфов и так форматируется соответствующим образом; причём в разных форматах по-разному. Имеет ли смысл выделять жирным шрифтом слово в заголовке, которое и без того будет отформатирован жирным? Кроме того, могут возникнуть недоразумения: в заголовке форматирования не видно, а в оглавлении – видно. Специальные символы (escape-последовательности) Набор символов, доступных в форматированных абзацах, гораздо шире стандартного ASCII-набора. Символы можно задавать с помощью последовательности E<...>. Её «аргументом» может быть имя символа или код. Имена символов совпадают с именами, используемыми в HTML, коды могут быть и ASCII, и Unicode-кодами символов (никогда не пробовал использовать Unicode, но согласно документации – должно работать). Согласно документации, если код предварён конструкцией «0x», он интерпретируется как шестнадцатеричный, если начинается с нуля – как восьмеричный. Например, E обозначает знак «больше». Этот же символ можно получить, задав его код в любой системе счисления: E<62> или E<0x3e>, или E<076>. Однако мой опыт показывает, что надёжнее использовать десятеричные коды. От использования Unicode я бы советовал воздержаться. POD-процессоры, преобразующие документы в текстовые форматы, «не любят» Unicode. А в HTML-документах Unicode-символы (&#NNNN;) могут вызвать неожиданные смены семейств шрифтов и прочие недоразумения, причины которых бывает трудно установить. Используя как раз такую запись, можно обойти проблемы, описанные выше: B10A> Как видите, способ не самый удачный, но зато он работает и в старых версиях POD. Здесь же уместно привести ещё один пример использования Z<>. Если вам потребуется получить последовательность символов «E<60>» в форматированном параграфе, то в POD-файле её можно записать так: EZ<><60> Тогда она не будет обработана как escape-последовательность. Конвертирование в «цветной» текст и man Теперь мы знаем о POD почти всё и можем посмотреть, как с этим работать. Для начала рассмотрим текстовые форматы. Не секрет, что в текстовом формате доступен весьма скромный набор символов (максимум 256), а шрифт варьировать нельзя. Поэтому ни pod2text, ни pod2man не обрабатывают «сложные» escape-последовательности. То есть последовательность E так и попадёт в текст документа необработанной потому, что символ «длинное тире» недопустим в текстовом документе. Вы получите предупреждающее сообщение «Unknown escape». Корректно обрабатываются только «простые» символы. Например, последовательность E (или E<62>) будет, как и положено, преобразована в знак «больше». В разделе «Списки» вы уже видели, как получить длинное тире с помощью последовательности E. В моём примере встречается ещё один «неординарный» символ – градус. По аналогии с HTML он именуется deg. После конвертирования в такие форматы, как HTML эти символы выглядят абсолютно корректно и только украшают текст, но текстовые конвертеры не в состоянии их обработать: Я использовал вот такой скрипт: #!/usr/bin/sed -f s/E<mdash>/--/g s/E<deg>/ градусов/g Как видите, это sed-фильтр, который заменяет «E» на «—», «E» на слово «градусов». Все текстовые документы я получал, предварительно пропустив исходный документ через этот фильтр: ./antiescape file.pod | pod2text >file.text Это, пожалуй, единственная неприятная особенность конвертеров в текстовые форматы. Теперь о приятном: об их возможностях, пусть скромных, но всё-таки заслуживающих пары слов. Начнём с самого простого pod2text. Опция -c позволяет ему разметить текст цветом при помощи ANSI escape-последовательностей. Вот как будет выглядеть на экране терминала фрагмент документа, полученного с помощью pod2text -c (мы, конечно, предварительно обработали POD-файл фильтром antie-scape):
Вы видите, что заголовки отформатированы жирным шрифтом, а курсив – синим. Конкретные цвета зависят от настроек терминала. Рассмотренное форматирование примерно в той же мере сохраняется и на man-страницах, полученных из POD-источников. Вот тот же фрагмент документа, после конвертирования его утилитой pod2man (в просмотрщике от mc):
Конвертер pod2man ещё более гибок, чем pod2text. Приводить здесь все его опции я не буду, они во многом сходны с опциями pod2text и прекрасно описаны в perldoc pod2man. Остановлюсь лишь на специфических, именно для формата man. Man-страница, как вы знаете, имеет колонтитулы. В верхнем колонтитуле, справа и слева, традиционно, указывается имя команды. Оно задаётся ключом -n. В центре верхнего колонтитула обычно указывается что-то вроде «FreeBSD General Commands Manual». Эту строку вы можете задать, используя ключ -c. В нижнем колонтитуле, справа и слева, обычно указывается версия ОС. Эта информация может быть задана ключом -r. В центре нижнего колонтитула по традиции указывается дата создания документа. Её можно изменить с помощью ключа -d. Оба конвертера pod2man и pod2text поддерживают опцию -q, не сказать о которой нельзя. Вот как будет выглядеть результат обработки POD-фрагмента, который я приводил в качестве примера в разделе «списки»:
Здесь я применил pod2text без каких-либо параметров. Обратите внимание, что название подпрограммы взято в кавычки, которых в POD-документе мы не писали. Это произошло потому, что мы указали, что «next_step» – код программы – C<...>. По умолчанию конвертер pod2text заключает фрагменты кода в кавычки. Это поведение можно скорректировать. Опция -q none подавляет кавычки, опция -q с иным аргументом задаёт альтернативные символы кавычек. За подробностями обращайтесь к man-странице pod2text или pod2man или perldoc-страницам, посвящённым этим командам. Конвертирование в HTML В полную силу возможности форматирования начинают работать при конвертировании в более «серьёзные форматы», например, в HTML. Преобразование осуществляет программа pod2html. Уже знакомый нам фрагмент в формате HTML будет выглядеть так:
Как видите, всё форматирование отражено в полной мере, но один неприятный сюрприз нам всё-таки уготован. Утилита pod2html создаёт оглавление в начале документа. Это очень удобно (а если не удобно, то можно отменить ключом --noindex), но оно создаётся явно без учёта русской специфики. В качестве якорей и ссылок используется непосредственно текст соответствующих заголовков. То есть в нашем случае якоря и ссылки будут содержать русские буквы. Не все браузеры лояльны к таким вольностям. Чтобы обойти эту неприятность, я использую следующий несложный скрипт на Perl: #!/usr/bin/perl undef $/; $_=<>; %h=(); $c=0; s/href="#(.+?)"/$c++; $h{$1}=$c; qq|href="#$c"|/ge; s/name="(.+?)"/"name="".($h{$1}?$h{$1}:$1)."""/ge; print; Как видите, это фильтр. Он считывает стандартный ввод, создаёт хэш якорей и производит надлежащие замены. Затем результат отправляется на стандартный вывод. Я назвал этот скрипт antirus.pl (он входит в архив к этой статье). Команда: pod2html file.pod | antirus.pl > file.html создаст «безопасный» HTML-файл. Гиперссылки Гиперссылки формируются только при конвертировании в HTML-формат. Во всех остальных форматах конструкции, описывающие ссылку, обрабатываются корректно: текст ссылки попадает в документ, но ссылкой он, конечно, не становится. Тем не менее гиперссылки заслуживают краткого описания. В наиболее общем случае ссылка создаётся последовательностью L<текст|документ/раздел>. «Текст» будет виден читателю документа и будет являться ссылкой. «Документ» – имя документа. «Раздел» – раздел в документе. При необходимости любое из полей можно взять в кавычки. Раздел можно не указывать. Если не указан документ, то предполагается, что это ссылка на один из разделов текущего документа. Ссылки используются довольно редко и имеют много ограничений. Как вы уже поняли, ни одно из полей не может содержать символы «|» и «/». Это ограничение можно обойти, используя escape-последовательности. Наличие документа, указанного между «|» и «/», проверяется. Если он не найден, то ссылка не создаётся. По умолчанию поиск ведётся среди модулей Perl, но пути можно задать и свои. В поле «раздел» следует указывать полное название раздела. Это не только громоздко, но и приводит к созданию «русских» якорей и ссылок в русскоязычных документах, что весьма нежелательно. Ограничусь одним примером: =pod =head1 Глава I L<это ссылка на Главу I|/"Глава I"> Если вам понадобится более подробная информация о ссылках, обращайтесь к документации на POD, но я бы не назвал возможность создания ссылок доведённой до совершенства. А в русскоязычных документах работа со ссылками ещё более затруднена, чем в англоязычных. Предложенная мною программа, корректирующая ссылки, должна быть значительно доработана, прежде чем она сможет работать с группами файлов и обрабатывать ссылки не только внутри документа, но и между документами. Я полагаю, что если вам действительно понадобится система взаимосвязанных HTML-документов, то POD – не лучшее средство разработки. Поэтому я не предлагаю никаких средств корректировки гиперссылок. Вставки, специфичные для разных форматов Мы не рассмотрели ещё три команды. Начав параграф с команды =for, вы сообщаете обработчику POD-документа, что этот параграф предназначен для определённого формата. Например: =for html <hr> Этот параграф предназначен только для формата HTML. Он будет исключён из документа всеми обработчиками, кроме pod2html. А этот единственный включит содержимое параграфа в HTML-документ без изменений, и в HTML-документе появится горизонтальная черта.Если вам необходимо вставить большой формат-ориентированный фрагмент документа, то можно использовать пару команд =begin/=end. Наш пример можно переписать так: =begin html <hr> =end html Обратите внимание, что, как и любые другие команды, =begin и =end должны находиться в отдельных абзацах. Таким образом, вы можете писать документ в формате POD, но использовать и средства разметки других форматов, когда это необходимо. Чаще всего эти возможности используются для вставки графики. К сожалению, нельзя вставлять специфичные для формата фрагменты внутри абзаца (in-line). То есть вам вряд ли удастся успешно использовать теги <font>, <small>, <sup> и подобные.
Вставка рисунков в HTML Теперь становится ясно, как включить изображение в HTML-документ. Для этого в POD-исходнике можно написать что-то подобное: =for html <center><img src="examp.png" hspace="3"></center> В результате в HTML-код будет помещена указанная строка, а значит, и картинка со всеми HTML-специфичными атрибутами. «Причёсываем» HTML Теперь, когда мы знаем большинство тонкостей конвертирования в HTML-формат, уместно будет сказать о возможных «косметических» улучшениях. Как мы видели раньше, документ получается максимально простой: шрифт – по умолчанию, цвета – белый и чёрный. Такая строгость не всегда уместна. Ситуацию можно исправить практически одним движением, включив в состав HTML-документа CSS-таблицу (или ссылку на отдельный файл, содержащий CSS-таблицу). Для этого можно использовать несколько путей. Можно вставить CSS-таблицу непосредственно в POD-документ. =begin html <style type="text/css"><!-- тело таблицы // --></style> =end html Такой подход не очень хорош по двум причинам. Во-первых, он не удобен, если вы создаёте несколько документов (или часто готовите инструкции и руководства), потому что вам придётся вставлять эту громоздкую конструкцию в каждый POD-файл. Во-вторых, CSS-таблица окажется не в заголовке документа (между тегами <head> и </head>), как это принято. Тем же методом можно вставить и HTML-элемент link, обеспечивающий связь с CSS-таблицей, находящейся во внешнем файле. =for html <link rel="stylesheet" href="file.css" type="text/css"> В этом случае указанный HTML-тег тоже окажется в теле документа (между <body> и </body>), что не очень желательно. Чтобы включить тег link в заголовок документа (где ему и положено быть), можно использовать ключ --css: pod2html --css file.css file.pod >file.html Но мне представляется более уместным включать в HTML-документы не элемент link, а полную CSS-таблицу. Это не намного «утяжелит» результат (что вообще не критично для off-line-ориентированных документов), но сделает его более «монолитным». Зачастую документация адресуется не очень квалифицированному пользователю, который может достаточно своевольно с ней обращаться (например пересылать отдельные файлы по e-mail коллегам в другой офис). Мой опыт подсказывает, что лучше создавать максимально самодостаточные файлы. Чтобы автоматизировать процесс вставки полноценной CSS-таблицы в HTML-код, могу предложить элементарный скрипт: #!/usr/bin/perl undef $/; $_=<>; s|</head>|<style type="text/css"><!-- a { font-family: sans-serif; weight: bold; text-decoration: none; color: #090; } h1 a, h2 a{ color: #C00; font-family: sans-serif; } dt strong a{ color: #900; } code { background: #ccc; font-weight: bold; } p { text-align: justify; } pre { background: #ffe; border-width: 3px; border-style: solid; border-color: #ddc #443 #443 #ddc; } // --></style> </head>|; print; Как видите, вся его работа заключается в том, что он вставляет CSS-таблицу перед тегом </head>. Практически всё его тело тоже составляет CSS-таблица. Кстати, использование такого скрипта полностью освобождает вас от необходимости указывать в POD-файле какие-либо дополнительные конструкции (типа =for html). После пропускания HTML-документа через этот фильтр, вид его кардинально изменится. Вот фрагмент:
Предполагая, что читатель знаком с CSS, остановлюсь только на особенностях моей CSS-таблицы. Первый элемент просто оговаривает вид ссылок. На рисунке их нет, но поверьте, они становятся зелёными. Второй элемент таблицы определяет вид заголовков. Обратите внимание, что мы задаём не просто стиль заголовков, а заголовков-ссылок. Это делается не случайно. При формировании HTML-документа система POD делает многие части документа (в том числе и заголовки) якорями гиперссылок на случай, если на них потребуется сослаться из другого документа. Поэтому в формате HTML заголовки оформляются следующим образом: <h1><a name="якорь">текст заголовка</a></h1> Теперь становится ясно, что если мы опишем только действие тега h1, то заголовок будет оформлен всё равно по правилам оформления ссылок (тег a). То есть в нашем случае заголовок унаследовал бы от ссылок зелёный цвет. Чтобы добиться желаемого результата – задать форматирование заголовков – нам следует описать действие пары тегов h1 и a, что мы и делаем. По той же причине мы описываем не тег dt, а всю связку dt-strong-a. Это стиль для маркеров списков. Тегом code снабжаются фрагменты кода (C<...>). Я задал для этих элементов сероватый фон. Для абзацев оговорено выравнивание по обоим сторонам колонки. Тегом pre оформляются неформатированные абзацы. Я, как можно видеть из картинки и как описано в CSS-таблице, задал для этих частей документа рамку и жёлтый фон. Конечно, вы можете задать любые стили, шрифты, выравнивания, отступы, цвета; главное при этом учитывать структуру документа, формируемого pod2html, чтобы стиль ссылок не конфликтовал с другими стилями. Продолжение следует В следующем номере я опишу процедуру конвертирования POD-документов в форматы PostScript и PDF. Коснусь конвертирования в такие форматы, как Microsoft Word Document и RTF. Расскажу о средствах автоматической проверки правильности POD-синтаксиса. И поделюсь своими мыслями о перспективах развития POD и о том, каких усовершенствований можно ждать от будущих версий. |
АЛЕКСЕЙ МИЧУРИН
Комментарии отсутствуют
| Добавить комментарий |
|
Комментарии могут оставлять только зарегистрированные пользователи |
|
