DocBook. Коротко.

Пример кода

<book id="simple_book">
<title>Very simple book</title>

<chapter id="simplechapter">
<title>Chapter 1</title>
<para>Hello world!</para>
</chapter>
</book>

Подробнее

Текущая версия:

Официальный сайт DocBook: DocBook.org

Официальный сайт DocBook XSL:

Основная официальная документация: книга Norman Walsh "DocBook: The Definitive Guide".

Первоначально DocBook использовался в основном Open Source сообществом: в том числе the Linux Documentation Project, the GNOME и GTK+ API справочник, документация ядра Linux. В последнее время все больше организаций используют систему DocBook для всей программной документации, в том числе и для документирования коммерческих продуктов.

Возможности DocBook

• Формат DocBook условно делится на Book и Article по функциональному назначению. Book используется для подготовки большой технической документации, книг и т.д., тогда как вид Article удобно использовать для статей.

  Заготовка для Article DocBook Автоматически сгененрированная Altova XML Spy *

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
  <?xmlspysps http://www.altova.com/sps/Template/Publishing/docbook.sps?>
  <article>
  <title>Article Title</title>
  <sect1>
  
  <title>Section1 Title</title>
  <para>Text</para>
  </sect1>
  </article>
  

  Заготовка для Book DocBook

  <?xml version="1.0" encoding="UTF-8"?>
  
  <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
  <?xmlspysps http://www.altova.com/sps/Template/Publishing/docbook.sps?>
  <book>
  <bookinfo>
  <title>Book Title</title>
  <author>
  <firstname>Author First Name</firstname>
  
  <surname>Author Last Name</surname>
  </author>
  <publisher>
  <publishername>Publisher Name</publishername>
  </publisher>
  <isbn>ISBN#</isbn>
  
  <copyright>
  <year>Copyright Year</year>
  </copyright>
  </bookinfo>
  <part>
  <title>Part Title</title>
  <chapter>
  
  <title>Chapter Title</title>
  <sect1>
  <title>Section1 Title</title>
  <para>Text</para>
  </sect1>
  </chapter>
  
  </part>
  </book>			
  

• Существуют специализированные XML-редакторы, и большинство из них умеет работать с DocBook. Теоретически они предоставляют больший сервис по сравнению с обычными текстовыми редакторами: например, автоматически проверяют правильность вводимых тэгов, предлагают выбор тэгов в зависимости от контекста.

• Благодаря открытому проекту DocBook XSLs, представляющему собой набор прекрасно настраиваемых DSSSL и XSL stylesheets, и существованию ряда как бесплатных, так и коммерческих инструментов для преобразования XML, вы легко (одной кнопкой) получаете свою документацию в различных форматах, в том числе и подготовленной для печати (в формате PDF).

  Norman Walsh разработал модель публикации DocBook.

  

• Внешний вид выходных форматов (HTML, CHM, PDF) легко настраивается с помощью CSS, а также через специальную XSL - Driver XSL.

• DocBook определяет большое количество тегов, что может быть не очень удобно, но так как это XML формат, можно его упростить. Существует также модификация DocBook - Simple DocBook (упрощенный вариант)

• Возможность модульной подготовки документации. Конечный выходнной файл легко собирается из нескольких отдельных XML файлов. Также возможна вставка текстов, листингов программ и всего чего захотите из внеших файлов. DocBook удобно использовать совместно с любой системой контроля версий.

• И наоборот, DocBook позволяет из одного исходного документа создавать выходные документы не только в разных выходных форматах , но и с разным содержимым.

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

Как создавать и редактировать DocBook

Основной инструмент редактирования DocBook - обычный текстовый редактор, например, замечательный UltraEdit, так как DocBook является подмножеством XML и представляет собой обыкновенный текстовый документ с разметкой, аналогично документу HTML.

Подойдет также любой XML редактор, например Altova XML Spy (коммерческий).

В редакторе создается DocBook текст, затем с помощью XSLT процессора получаем данный текст в выходном формате HTML, CHM... Для получения PDF используем еще и XSL-FO процессор.

Преимущества DocBook

Система DocBook:

• встроенные возможности для работы с различным содржанием;

• сопровождается системой DocBookStylesheets, позволяющей используя различные инструменты преобразовывать DocBook контент в различные выходные форматы - HTML pages, PDF files, Microsoft HTMLHelp, UNIX man pages, JavaHelp, TeX, Texinfo, и RTF;

  существует набор инструментов (free), которые также позволяют конвертировать различные форматы (man pages, HTML documents, Javadoc, plain text, Texinfo files, and OpenOffice Writer documents) в DocBook

• хорошо документирована (DocBookThe Definitive Guide и DocBookTutorials, к сожалению, не на русском языке)

• широко внедрена и протестирована такими коммерческими организациями как Sun, Microsoft, Hewlett-Packard, Novell, SCO, Caldera, и Red Hat, open-source группами - the KDE и GNOME, FreeBSD, Debian, и Linux documentation projects и the Darwin Documentation Project (Apple).

• полностью открытый (open-source) стандарт

• прекрасно настраиваемая и расширяемая система