Рабочая среда К

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

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

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

9.3.1. Объявления DTD

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

&<;!doctype linuxdoc system&>;

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

9.3.1.1. Структура документа

При использовании 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&>;.

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

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

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

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

9.3.3. Индексы

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

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

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

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

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

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

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

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