LXF87-88:DocBook
|
|
|
- Hardcore Linux Проверьте себя, участвуя в сложных проектах для продвинутых пользователей.
Содержание |
DocBook: Пишем документацию
- Что общего у ядра, FreeBSD, KDE и Gnome? Документация! Пол Хадсон рассказывает о новой технологии для ее написания.
Создание документации к программам всегда было пробле мой для программистов: ведь это же тупость – объяснять, как все работает, когда оно ослепительно-очевидно. Наши программы, естественно, всегда понятны нам, потому что мы сами их написали; но есть люди, до сих пор думающие, что компьютеры и программы – это какое-то колдовство. Поэтому необходимо кратко объяснить им, какие кнопки нажимать для выполнения нужных операций. На этом уроке мы изучим DocBook – формат написания документации. Он основан на XML, и с ним можно работать в любом текстовом редакторе. Он используется во многих крупных проектах, включая ядро Linux, FreeBSD и KDE, поэтому рано или поздно вы с ним столкнетесь.
В процессе урока мы будем документировать выдуманную игру Ловля мух. Если у вас еще нет открытого проекта, который вы могли бы задокументировать, то присоединяйтесь к уже существующему, или начните новый!
Ныряем в DocBook
DocBook (как XML) имеет строгую структуру, которой необходимо следовать, но она довольно понятна. Помните, что DocBook – это разновидность XML, разработанная специально для создания документации, поэтому его структурными элементами являются главы, разделы, заголовки, абзацы и так далее. Вот и все, что необходимо знать для создания нашей первой части документации: книги, состоящей из одной главы. Начнем:
<?xml version=”1.0” ?> <!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook XML V4.4//EN” “http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd”> <book> <title>Ловля мух!</title> <chapter id=”ch01”> <title>Введение</title> <sect1> <title> Добро пожаловать в лучшую в мире игру!</title> <para>Да, она действительно так хороша.</para> </sect1> </chapter> </book>
[Необходимо использовать кодировку UTF-8 или указать ее явно в тэге <?xml?> при помощи атрибута ‘encoding’, – прим. ред.] Тип DTD, который мы собираемся использовать – стандарт DocBook 4.4, доступный из сотворившей его организации Oasis. Если хотите, можете скопировать файл .dtd на свою машину – это немного ускорит вашу работу, потому что в противном случае вашему компьютеру для валидации документа придется копировать DTD из сети.
Разберем написанное: наша полностью законченная документация называется книгой (book). Как и большинство книг, она состоит из отдельных глав, разбитых на разделы. В нашем примере с Ловлей мух у нас могут быть следующие главы: Введение, Описание игрового процесса, Многопользовательская игра, Разрешение проблем и Контактная информация.
Каждая глава состоит из разделов и подразделов, это упрощает чтение материала. Например, раздел Многопользовательская игра' может состоять из секций ‘Запускаем сервер’, ‘Подсоединяемся к серверу’ и ‘Настраиваем брандмауэр’. ‘Запускаем сервер’ можно затем подразделить на ‘Выделенный сервер’, ‘Невыделенный сервер’, ‘Обнаружение вашего IP-адреса’ и так далее. В терминологии DocBook эти разделы называются ‘sections’ и вы можете выбирать из <sect1> (раздел верхнего уровня), <sect2>, <sect3> или <sect4>. Обычно в оглавление попадают только первые три уровня – четвертый чуть больше размером, чем жирный текст, и если вы поймаете себя на том, что вовсю используете <sect4>, то придется признать: ваша документация чересчур многословна!
Итак, книга <book> содержит главы <chapter>, которые содержат разделы <sect1>, содержащие подразделы <sect2>, в свою очередь, содержащие <sect3>, а те <sect4>. Вот как все может выглядеть:
<chapter id=”ch01”> <title>Введение</title> <sect1> <title> Добро пожаловать в лучшую в мире игру!</title> <para>Да, она действительно так хороша.</para> <sect2> <title>Почему же она так хороша?</title> <para>На это есть множество причин!</para> <sect3> <title>Взрослым...</title> <para>Много крови, убийств и жутких моментов!</para> </sect3> <sect3> <title>Детям...</title> <para>Еще больше крови, убийств и жутких моментов!</para> </sect3> </sect2> </sect1> </chapter>
Необходимо строго соблюдать иерархию структуры – вы не можете создать <chapter>, затем сразу <sect3>, или же <sect3>, а затем <sect2>, как показано ниже:
<chapter id=”ch01”> <sect3> <sect2> <title>Введение</title> </sect2> </sect3> </chapter>
И книга, и глава, и раздел могут иметь свой собственный <title>, то есть заголовок. После этого начинается основная работа: множество элементов <para>, каждый из которых представляет один текстовый абзац.
Как вы понимаете, разобраться с XML здесь не самое сложное – куда сложнее написать качественную документацию!
Структура абзаца
- Метамодернизм в позднем творчестве В.Г. Сорокина
- ЛитРПГ - последняя отрыжка постмодерна
- "Ричард III и семиотика"
- 3D-визуализация обложки Ridero создаем обложку книги при работе над самиздатом.
- Архитектура метамодерна - говоря о современном искусстве, невозможно не поговорить об архитектуре. В данной статье будет отмечено несколько интересных принципов, характерных для построек "новой волны", столь притягательных и скандальных.
- Литература
- Метамодерн
- Рокер-Прометей против изначального зла в «Песне про советскую милицию» Вени Дркина, Автор: Нина Ищенко, к.ф.н, член Союза Писателей ЛНР - перепубликация из журнала "Топос".
- Как избавиться от комаров? Лучшие типы ловушек.
- Что делать если роблокс вылетает на windows
- Что делать, если ребенок смотрит порно?
- Почему собака прыгает на людей при встрече?
- Какое масло лить в Задний дифференциал (мост) Visco diff 38434AA050
- О чем может рассказать хвост вашей кошки?
- Верветки
- Отчетность бюджетных учреждений при закупках по Закону № 223-ФЗ
- Срок исковой давности как правильно рассчитать
- Дмитрий Патрушев минсельхоз будет ли преемником Путина
- Кто такой Владислав Поздняков? Что такое "Мужское Государство" и почему его признали экстремистским в России?
- Как правильно выбрать машинное масло в Димитровграде?
- Как стать богатым и знаменитым в России?
- Почему фильм "Пипец" (Kick-Ass) стал популярен по всему миру?
- Как стать мудрецом?
- Как правильно установить FreeBSD
- Как стать таким как Путин?
- Где лучше жить - в Димитровграде или в Ульяновске?
- Почему город Димитровград так называется?
- Что такое метамодерн?
- ВАЖНО! Временное ограничение движения автотранспортных средств в Димитровграде
- Тарифы на электроэнергию для майнеров предложено повысить
Набор бесформенных абзацев – занятие нудное, но это легко исправляется тем, что DocBook предоставляет специальные тэги для форматирования. Кроме базовых элементов, типа нумерованных списков и выделения жирным шрифтом или курсивом, вы можете особо выделить листинги программ, цитаты других людей, экранные снимки и многое другое. У DocBook есть тэги для всего, что как-то связано с программами или компьютерами, так что он далеко не прост!
На наше счастье, достаточно знать только о тех элементах, которые будут вами использоваться. Основные элементы можно разделить на две катэгории: встраиваемые и блочные. Блочные элементы образуют естественные части текста, которые в результирующем документе отделяются пустой строкой. Встраиваемые элементы изменяют отдельные слова внутри блочных, не влияя на организацию текста. Начнем с основных элементов:
<para>Чтобы организовать собственный сервер Ловли, вы <emphasis>должны</emphasis> открыть <acronym>TCP</acronym> порт 556 в брандмауэре. <emphasis role=”bold”>Внимание:</ emphasis> мы не отвечаем за возможные последствия.</para> <para>Вы можете найти предустановленные настройки брандмауэра в файле <filename>firewall.config</filename> в каталоге с игрой.</para> <para>Если проблемы все еще есть, попытайтесь подключиться к нашему сайту для проверки брандмауэра <systemitem role=”url”>http://www.qaziqargs.com/firewall</ systemitem>.</para>
Тэг <emphasis> задает либо жирный шрифт, либо курсив: если вы уточните его словом ‘bold’, то текст будет выделен жирным; в противном случае – курсивом. Элемент <systemitem> – довольно хитрый зверь: в зависимости от роли, он может хранить IP-адреса, доменные имена, имена пользователей и, как в моем примере, URL-ы. Кому интересно, знайте, что нет никаких способов указать «текст» ссылки (то есть фразу, которой она будет представлена в документе), потому что DocBook спроектирован для работы с любыми носителями, включая печатные (где, понятное дело, щелкать по URL бессмысленно!).
Мы уже рассмотрели тэги <para> и <title>, однако интерес представляют еще пять тэгов: <orderlist>, <itemizedlist>, <listitem>, <programlisting> и <screen>. Первые три связаны между собой, поэтому начнем с них: покажем, как сделать упорядоченный (нумерованный) и неупорядоченный список (где порядок элементов не важен):
<para>Существует три способа погибнуть в игре Ловля мух:</para> <orderedlist> <listitem><para>Быть съеденным лягушкой</para></listitem> <listitem><para>Быть съеденным птицей</para></listitem> <listitem><para>Быть прихлопнутым мухобойкой</para></listitem> </orderedlist> <para>Если у вас в наличии один из следующих предметов, вы можете избежать смерти:</para> <itemizedlist> <listitem><para>Ружье</para></listitem> <listitem><para>Кустарник</para></listitem> <listitem><para>Слабительное</para></listitem> </itemizedlist>
Будь это HTML, то <orderlist> был бы <ol>, <listitem> стал бы <li> и так далее – невелика разница, только что тэги DocBook длиннее! Текст внутри <listitem> должен обрамляться тэгами <para>.
Элементы <programminglisting> и <screen> используются подобным образом, но они являются отдельными сущностями и могут быть поразному отформатированы при выводе, если потребуется. Например:
<para>Для включения режима бессмертия в игре, войдите в консоь Ловли и наберите следующие коды:</para> <programlisting> idkfa iddqd idspispopd </programlisting> <para>Вы узнаете, что режим бессмертия активирован, когда увидите следующее сообщение на экране:</para> <screen> Сообщаем: режим бессмертия активирован! </screen>
Все символы-разделители сохраняются в элементах <programminglist> и <screen>, так что набранный вами текст будет отображен на экран в таком же виде.
Работа с несколькими главами
- Метамодернизм в позднем творчестве В.Г. Сорокина
- ЛитРПГ - последняя отрыжка постмодерна
- "Ричард III и семиотика"
- 3D-визуализация обложки Ridero создаем обложку книги при работе над самиздатом.
- Архитектура метамодерна - говоря о современном искусстве, невозможно не поговорить об архитектуре. В данной статье будет отмечено несколько интересных принципов, характерных для построек "новой волны", столь притягательных и скандальных.
- Литература
- Метамодерн
- Рокер-Прометей против изначального зла в «Песне про советскую милицию» Вени Дркина, Автор: Нина Ищенко, к.ф.н, член Союза Писателей ЛНР - перепубликация из журнала "Топос".
- Как избавиться от комаров? Лучшие типы ловушек.
- Что делать если роблокс вылетает на windows
- Что делать, если ребенок смотрит порно?
- Почему собака прыгает на людей при встрече?
- Какое масло лить в Задний дифференциал (мост) Visco diff 38434AA050
- О чем может рассказать хвост вашей кошки?
- Верветки
- Отчетность бюджетных учреждений при закупках по Закону № 223-ФЗ
- Срок исковой давности как правильно рассчитать
- Дмитрий Патрушев минсельхоз будет ли преемником Путина
- Кто такой Владислав Поздняков? Что такое "Мужское Государство" и почему его признали экстремистским в России?
- Как правильно выбрать машинное масло в Димитровграде?
- Как стать богатым и знаменитым в России?
- Почему фильм "Пипец" (Kick-Ass) стал популярен по всему миру?
- Как стать мудрецом?
- Как правильно установить FreeBSD
- Как стать таким как Путин?
- Где лучше жить - в Димитровграде или в Ульяновске?
- Почему город Димитровград так называется?
- Что такое метамодерн?
- ВАЖНО! Временное ограничение движения автотранспортных средств в Димитровграде
- Тарифы на электроэнергию для майнеров предложено повысить
Прежде чем начать печатать, подумайте об организации работы. Прекрасно, что вы можете разбить вашу книгу на главы, разделы и абзацы, но важно разделить на части и работу, создав предпосылки для привлечения команды. То есть – использовать несколько файлов, разделенных согласно вашим нуждам – например, можно выделить по файлу для каждой документируемой функции.
Файл, в который включают другие файлы, использует стандарт XInclude, в котором вы можете определить URL, загружаемый при обработке файла. Это позволит вам переложить часть работы на коллег, а затем собрать все документы вместе. Чтобы распределить главы по отдельным файлам, ваша XML-книга должна выглядеть примерно так:
<?xml version=”1.0”?> <!DOCTYPE book PUBLIC “-//OASIS//DTD DocBook XML V4.4//EN” “http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd”> <book> <title> Ловля мух!</title> <include xmlns=”http://www.w3.org/2001/XInclude” href=”chapter01.xml”/> <include xmlns=”http://www.w3.org/2001/XInclude” href=”chapter02.xml”/> <include xmlns=”http://www.w3.org/2001/XInclude” href=”chapter03.xml”/> <include xmlns=”http://www.w3.org/2001/XInclude” href=”chapter04.xml”/> </book>
Начало положено, но это не облегчит людям чтение: если вы скажете «смотри раздел 3 главы 4», то им придется искать, где находится это место. Обычно DocBook-конверторы создают оглавление, содержащее номера страниц (или HTML-ссылки), но такой подход требует, чтобы пользователи поднимались к оглавлению, находили ссылку, переходили по ней, а затем нажимали кнопку Назад два раза, чтобы вернуться туда, откуда пришли.
Мы можем облегчить им задачу, используя тэг <xref>, позволяющий делать ссылки на главы, разделы и некоторые другие блоки. Взглянув на наш первый пример с книгой, вы заметите строку:
<chapter id=”ch01”>
Именно атрибут “id” позволяет нам устанавливать ссылки. Например, если мы хотим сделать ссылку на главу 1, то можем написать следующее:
<para>Если ваша игра не устанавливается, вернитесь и прочтите инструкции в <xref linkend=”ch01” />.</para>
Нам не требуется писать «прочтите инструкции в главе 1» – такой текст будет получен после преобразования документа в требуемый формат. Например, если документ преобразуется в HTML, <xref> станет гиперссылкой с текстом типа «главе Руководство по установке», указывающей на начало этой самой главы.
Можно применить атрибуты id и к разделам, но когда вы делаете ссылки на отдельные блоки <para>, ссылки обычно создаются на начало раздела, содержащего требуемый блок.
