Next Previous Table of Contents

### 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 (см. http://www.sgmltools.org), ранее известный как пакет 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).

### 9.2 Что уже содержит шаблон документации

При создании проекта KDevelop подкаталог `docs/en` уже содержит файл `index.sgml` с документацией на английском языке и уже сгенерированные файлы HTML формата. Они уже включены в проект, и путь для их инсталляции указывает на KDE HTML каталог. Документация уже адаптирована к вашему наименованию проекта, номеру версии и содержит информацию о программисте. Далее, файл index.html включает содержание руководства по использованию программы. Этот файл открывается системой помощи KDE, когда пользователь запрашивает помощь по работе с вашим приложением; в файл включены инструкция по установке, лицензия GPL и информация о copyright.

При разработке документации вы должны только добавить информацию, специфичную для вашего приложения. Помните, что проект KDE требует запуска "Make Doc-Handbook" из меню "Project" после окончания разработки проекта. Файл index.sgml при этом вновь обрабатывается `ksgml2html` и генерируется выполненная в KDE-стиле HTML документация. Откройте каталог `docs/en` в RFV и добавьте `logotp3.gif` в проект через контекстное меню; затем правильно задайте его свойства для инсталляции логотипа в тот же каталог, где будут расположены HTML файлы - `$(kde_htmldir)/en/<ваш_проект>/logotp3.gif`.

### 9.3 Написание SGML документации

Этот раздел добавлен, потому что SGML (или, более точно, LinuxDoc DTD), все еще кажется сложным для начинающих писать документацию. Когда я посмотрел на некоторые приложения KDE, то увидел, что некоторые из них содержат файл sgml в виде исходного шаблона - а автор редактировал HTML файлы вместо sgml. Это приводит к проблемам при переводе - если необходимо перевести документацию на родной язык, приходится редактировать каждый файл в HTML формате, и это делает невозможным повторное использование документов в других форматах, причем не только в английской версии, а и во всех локализованных версиях проекта. Как видно, это не продуманное решение, приводящее к весьма тяжким последствиям; я считаю, что это происходит, поскольку автор знает HTML, но не знает SGML. Поскольку большинство старается избежать изучения нового языка форматирования, они используют HTML файлы как шаблон для редактирования. Если вы однажды посмотрите на то, как легко и просто использовать SGML с LinuxDoc, вы решите, что лучше выучить несколько лишних тагов и создавать SGML формат.

Следующие разделы дают начальную информацию о наиболее важных частях файла sgml в LinuxDoc, и объясняют, как расширить вашу документацию.

#### Объявления DTD

Для того, чтобы показать, какой вариант DTD используется, каждый sgml файл начинается с объявления DTD. Первый таг (взятое в скобки выражение, например <ваш_таг> содержимое </ваш_таг>) всегда DOCTYPE:

    <!doctype linuxdoc system>

Это сообщает вашему форматировщику sgml, что он должен использовать LinuxDoc DTD.

#### Структура документа

При использовании LinuxDoc следующий таг - стартовый таг документа, определяющий его стиль. LinuxDoc DTD предлагает целый набор типов документов, из который вы можете выбрать нужный в зависимости от назначения документа и его длины. Доступны следующие типы:

- `<notes>` для короткого пояснения,
- `<article>` для написания статьи длиной 10-20 страниц (примерно). Этот тип используется в качестве шаблона в KDevelop и большинстве KDE приложений,
- `<report>` для статей длиннее <article>,
- `<book>` для написания большой книги - руководство по KDevelop использует этот тип,
- `<slides>` для слайд-шоу. Это полезно для презентаций. Предполагается использование LaTeX в качестве конечного формата в большинстве случаев,
- `<letter>` для обычных писем,
- `<telefax>` для факсов,
- `<manpage>` для статьи man.

Имейте в виду, что эти типы описывают только общую организацию структуры документа, а не конкретный вид выходных документов. Как упоминалось, KDevelop по умолчанию генерирует шаблон, используя структуру <article>. Это используется большинством приложений, исключая сам KDevelop, который использует тип <book>. В HTML формате это не имеет серьезного значения - но для LaTeX, например, это важно. Руководство - это настоящая "книга" с отдельными страницами для каждой главы (главное отличие).

Конец sgml файла должен содержать завершающий таг для структуры документа - для <article> это будет </article>.

#### Титульная страница

После тага структуры документа идет секция, описывающая основные пункты, располагаемые на титульной странице. Шаблон не использует их все, но заполняет информацию для тагов `<title>`, `<author>` и `<date>`, чего обычно достаточно. При использовании структуры `<book>` вы, вероятно, захотите определить все таги титульной страницы. Следующий пример показывает использование этих тагов, он взят из sgml исходника этой книги:

    <!doctype linuxdoc system>
    <book>
    <titlepag>
    <title>The KDevelop Programming Handbook
    <subtitle>The User Guide to C++ Application Design for the K Desktop Environment (KDE) with the KDevelop IDE, Version 1.0
    <author>
    <name>Ralf Nolden <htmlurl url="mailto:Ralf.Nolden@post.rwth-aachen.de"
                                       name = "<Ralf.Nolden@post.rwth-aachen.de>">
    <inst>The KDevelop Team
    <date>Version 2.1 , July 7, 1999
    <abstract>
    This handbook itself is part of the KDevelop Integrated Development Environment
    and is therefore also licensed under the GNU General Public License;
    see <ref id="Copyright" name="Copyright"> for more information.
    </abstract>

Это включает в себя все, что обычно содержит титульная страница. Таг `<author>` включает таг `<thanks>`, вставляющий некоторые благодарности соавторам и т.п. `<inst>` представляет институт или компанию, для которой автор писал документацию; вы также можете использовать имя вашей команды, как сделал я. `<abstract>` содержит краткое описание, расположенное на титульной странице. Это несколько неприятно в печатной версии, поэтому там данная секция будет напечатана на обратной стороне титульной страницы вместе с copyright; это может быть изменено в LaTeX редактированием файла TeX.

#### Индексы

LinuxDoc DTD определяет набор тагов для построения различных индексов, как это обычно делается в документах. Это:

- <toc> для содержания
- <lof> для списка рисунков
- <lot> для списка таблиц

Завершающий таг не требуется в конце; индексы вставляются непосредственно после титульной страницы перед началом документа с соответствующими разделами или главами.

Для индексации ключевых слов, список которых располагается в конце документа, вам предоставляются 4 различных тага; два из них оставляют индексированную фразу видимой на странице, а два других не отображают индексные входы:

- <idx> для элемента обычного индекса,
- <cdx> для true-type элемента индекса,
- <nidx> для индексного входа, не отображаемого на странице,
- <ncdx> аналогично для tt-индекса

Эти таги игнорируются всеми конечными форматами, кроме `sgml2latex`, который генерирует индексный файл `index.idx`, который преобразуется в TeX-индекс командой `makeindex index.idx`. Сам индекс может быть вставлен в TeX файл с помощью `\printindex`. Я написал скрипт, автоматизирующий вставку индекса в LaTeX (но до сих пор не знаю, как включить индекс в содержание...).

#### Содержание документа

Сейчас, после объяснения большинства деталей основной структуры, мы переходим к рассмотрению текста документа. В зависимости от типа структуры документа, он начинается либо с тага `<sect>`, либо, при использовании `<book>`, с тага `<chapt>` для глав.

После стартового тага, вы можете структурировать каждую главу с помощью `<sect1>`, `<sect2>` и т.п. до максимального уровня вложенности (4).

После стартового тага главы следует ее заголовок. Здесь вы можете использовать `<title>` и `<`title>/ для заголовков глав (при необходимости). После заголовка главы вы должны добавить таг <p>, чтобы обозначить начало текста главы. В тексте вы имеете возможность использовать списки, перечисления, списки определений (description lists) и т.п. Далее, цитаты и фрагменты кода также могут быть вставлены с помощью тагов, см. документацию по `sgmltools` для получения полного перечня тагов. Также в ней посмотрите раздел о добавлении специальных символов. В нем перечислены все доступные неалфавитные символ, например, знак торговой марки. С помощью этих тагов вы сможете структурировать документацию так, как это требуется для вашего приложения.

### 9.4 Как вызывать помощь в диалоговых окнах

Вызов помощи в диалогах часто реализуется с помощью кнопки Помощь (Help); после этого вы добавляете слот, выполняемый по нажатию этой кнопки. В коде этого слота вы должны вызвать:

> `

>     kapp->invokeHTMLHelp( QString aFilename, QString aTopic );

> `

где `aFilename` - имя файла в каталоге с HTML-документацией вашего приложения; например, index-3.html. `aTopic` - заголовок, который должен быть вызван. Хеш-префикс "#" добавляется автоматически; введите главу, к которой вы хотите обратиться, хотя это может быть и заголовок более низкого уровня.

Next Previous Table of Contents