# 9. Создание документации с использованием SGML

Учитывая тот факт, что зачастую проекты не содержат полного набора пользовательской документации, все проекты KDevelop включают в себя шаблон документации, который может быть легко приспособлен к проекту; этим достигается одна из целей KDE: предоставить достаточное количество online-помощи для поддержки пользователей, еще не овладевших приложением. Эта глава посвящена тому, как расширить предлагаемый шаблон документации и что необходимо сделать, чтобы он стал доступен пользователю.

# 9.1. Почему SGML ?

SGML (Standard Generalized Markup Language) - язык, с помощью которого можно написать спецификацию другого языка разметки (markup language), но он не является языком разметки сам по себе. Спецификация для языка разметки называется DTD (Document Type Definition, Определение типа документа), и содержит структуры документа и доступные таги. Кроме того, SGML-система предоставляет набор файлов замены, которые переводят таги DTD в требуемый формат - вот так это работает. Наиболее часто используемый формат вывода - HTML для создания online-помощи, просматриваемой через браузер, учитывая, что стандарты Internet доступны даже на отдельно стоящих компьютерах. KDE широко использует HTML документацию в KDEHelp , в котором приведены все приложения KDE , и предоставляет доступ к их руководствам пользователя. Эти руководства доступны также через меню Help непосредственно из приложения.

Сейчас KDE и, следовательно, KDevelop, используют пакет SGML-Tools 1.x (см. \|\|), ранее известный как пакет LinuxDoc. Он содержит DTD, называемый `LinuxDoc`, набор map-файлов для генерации выходных файлов в различных форматах и необходимые инструменты, которые в действительности производят замену тагов `LinuxDoc`. LinuxDoc DTD базируется на Qwertz DTD, который, в свою очередь, был написан для обеспечения хорошего картирования (mapping, то есть замена тагов) в основном для текстовой системы LaTeX, поэтому с ним очень легко генерировать готовые к печати документы. Пакет получил свое название в связи с его использованием для написания документации LDP (Linux Documentation Project, Проект документирования Linux), и его имя было изменено только из-за того, что это была sgml-система, которая вовсе не должна быть связана с Linux-проектом, а может использоваться на любой из Unix-систем; вы можете даже написать свой собственный DTD и map-файлы для него.

Тем временем был разработан для определенных целей другой DTD - "DocBook DTD". DocBook имеет почти те же возможности, что и LinuxDoc DTD, но предоставляет лучшие таги и map-файлы для таблиц и включаемой графики, но все это возможно и в LinuxDoc. SGML-инструмент, таким образом, получил необходимость поддержки DocBook DTD в серии версий 2.x, которые также предоставляли конвертер для получения DocBook sgml из исходников LinuxDoc.

В своем текущем состоянии KDE все еще использует LinuxDoc DTD по нескольким причинам:

- написание LinuxDoc документации проще,

- инсталляция SGML-Tools 1.x для использования LinuxDoc еще проще,

- KDE предоставляет дополнительный инструмент, называемый `ksgml2html`, который придает стиль KDE выходным файлам HTML, генерируемым конвертером SGML-Tools 1.x `sgml2html`.

Я сам обнаружил, пока писал книги о KDevelop, что использовать LinuxDoc DTD очень просто, и он предоставляет все необходимое для написания документации. Скорость изучения очень высокая, поэтому вы сможете стать гуру в области sgml-tools/LinuxDoc DTD за несколько дней, и это сохранит вам очень много времени при работе с такими системами форматирования, как TeX для распечатки документации или языком разметки для создания HTML.

Основная причина продолжать использовать sgml-tools 1.x - большинство дистрибутивов содержат пакет и дополнительные средства, необходимые вам для производства других выходных форматов. Это делает инсталляцию максимально простой, да и написание sgml-документа само по себе не сложное, как вы увидите. Вы можете получить документы в следующих форматах, генерируя их из sgml:

- HTML, который приобретает вид KDE документа, если дополнительно используется `ksgml2html`,

- текст,

- GNU info,

- Lyx формат,

- TeX, DVI, PostScript и PDF формат,

- Rich Text Format (RTF).