Yaleks: категория

2009-01-07T09:21:50Z

категория

Crazy Rebel: /* Оформление страницы */

2008-12-09T13:10:34Z

‎Оформление страницы

Crazy Rebel: викификация, оформление

2008-12-09T13:09:25Z

викификация, оформление

Внесённые изменения

Crazy Rebel: викификация, оформление

2008-12-09T12:52:58Z

викификация, оформление

Внесённые изменения

Crazy Rebel: викификация, оформление

2008-12-09T09:58:10Z

викификация, оформление

Новая страница

[[Категория:Учебники]]
: '''Hardcore Linux''' Проверьте себя, участвуя в сложных проектах для продвинутых пользователей.

=DocBook: Пишем документацию=

: Что общего у ядра, FreeBSD, KDE и Gnome? Документация! '''Пол Хадсон''' рассказывает о новой технологии для ее написания.

Создание документации к программам всегда было пробле мой для программистов: ведь это же тупость – объяснять,
как все работает, когда оно ослепительно-очевидно. Наши
программы, естественно, всегда понятны нам, потому что мы сами их
написали; но есть люди, до сих пор думающие, что компьютеры и программы – это какое-то колдовство. Поэтому необходимо кратко объяснить им, какие кнопки нажимать для выполнения нужных операций. На
этом уроке мы изучим ''DocBook'' – формат написания документации. Он
основан на ''XML'', и с ним можно работать в любом текстовом редакторе. Он используется во многих крупных проектах, включая ядро Linux, FreeBSD и KDE, поэтому рано или поздно вы с ним столкнетесь.

В процессе урока мы будем документировать выдуманную игру
'''Ловля мух'''. Если у вас еще нет открытого проекта, который вы могли
бы задокументировать, то присоединяйтесь к уже существующему, или
начните новый!

==Ныряем в DocBook==

''DocBook'' (как ''XML'') имеет строгую структуру, которой необходимо
следовать, но она довольно понятна. Помните, что ''DocBook'' – это разновидность ''XML'', разработанная специально для создания документации, поэтому его структурными элементами являются главы, разделы,
заголовки, абзацы и так далее. Вот и все, что необходимо знать для
создания нашей первой части документации: книги, состоящей из
одной главы. Начнем:

<source lang=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>
</source>

['''Необходимо использовать кодировку 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>'''. Вот как все может выглядеть:

<source lang=xml>
<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>
</source>

Необходимо строго соблюдать иерархию структуры – вы не можете создать '''<chapter>''', затем сразу '''<sect3>''', или же '''<sect3>''', а затем
'''<sect2>''', как показано ниже:

<source lang=xml>
<chapter id=”ch01”>
<sect3>
<sect2>
<title>Введение</title>
</sect2>
</sect3>
</chapter>
</source>

И книга, и глава, и раздел могут иметь свой собственный '''<title>''', то
есть заголовок. После этого начинается основная работа: множество
элементов '''<para>''', каждый из которых представляет один текстовый
абзац.

Как вы понимаете, разобраться с ''XML'' здесь не самое сложное –
куда сложнее написать качественную документацию!

← Предыдущая		Версия 09:21, 7 января 2009
Строка 418:		Строка 418:

	То, что внутри '''CDATA''', не игнорируется (в смысле, идет на вывод), но и не обрабатывается как ''XML''.		То, что внутри '''CDATA''', не игнорируется (в смысле, идет на вывод), но и не обрабатывается как ''XML''.
		+
		+	[[Категория:Hardcore Linux]]
		+	[[Категория:Пол Хадсон]]

@@ Строка 303: / Строка 303: @@
 </source>
-В терминах ''HTML'', '''<informaltable>''' – это '''<nowiki><table></nowiki>''', <row> – '''<nowiki><tr></nowiki>''', а
+В терминах ''HTML'', '''<informaltable>''' – это '''<nowiki><table></nowiki>''', '''<row>''' – '''<nowiki><tr></nowiki>''', а
-<entry> – '''<nowiki><td></nowiki>'''. Мы можем превратить нашу '''<informaltable>''' в обычную
+'''<entry>''' – '''<nowiki><td></nowiki>'''. Мы можем превратить нашу '''<informaltable>''' в обычную
 таблицу '''<nowiki><table></nowiki>''' с добавлением заголовка:

LXF87-88:DocBook - История изменений

Yaleks: категория

Crazy Rebel: /* Оформление страницы */

Crazy Rebel: викификация, оформление

Crazy Rebel: викификация, оформление

Crazy Rebel: викификация, оформление