doctools_intro

ИМЯ

doctools_intro — введение в doctools

Содержание

• Содержание

• Описание

• СВЯЗАННЫЕ ФОРМАТЫ

• Ошибки, идеи, отзывы

• См. также

• Категория

• Авторские права

ОПИСАНИЕ

doctools (сокращение от documentation tools, инструменты документирования) — это набор связанных, но различных сущностей, которые совместно упрощают создание и преобразование документации. К ним относятся

1. Язык на основе Tcl для семантической разметки текста. Разметка представлена командами Tcl, перемежающимися с собственно текстом.

2. Пакет, предоставляющий возможность читать и преобразовывать тексты, написанные на этом языке разметки. Важно отметить, что фактическое преобразование входного текста выполняют плагины.

3. API, описывающий интерфейс между указанным выше пакетом и плагином.

Выбор более подробных документов, которые могут быть полезны читателю этого введения, зависит от его роли в процессе документирования.

1. Автору документации необходимо понимать сам язык разметки. Начинающим пользователям doctools сначала следует прочитать менее формальное введение в язык doctools. После этого им должна стать понятна формальная спецификация синтаксиса языка doctools. Опытному пользователю doctools может время от времени понадобиться справочник по командам языка doctools, чтобы освежить знания.

   Во время написания документа для его проверки можно использовать приложение dtplite, а после завершения оно также преобразует документ в выбранный формат визуальной разметки, будь то *roff, HTML, обычный текст, wiki и т. д.

2. Обработчику документации, написанной на языке разметки doctools, необходимо знать, какие инструменты доступны для использования.

   Основной инструмент — упомянутое выше приложение dtplite, входящее в Tcllib. Более мощное приложение (с точки зрения набора параметров и возможностей настройки) — dtp, входящее в Tclapps. Однако на нижнем уровне, общем для обоих приложений, находится пакет doctools, предоставляющий основные средства для чтения и обработки файлов с текстом в формате doctools.

3. И наконец, разработчикам плагинов необходимо понимать взаимодействие пакета doctools с его плагинами, описанное в справочнике по API плагинов doctools.

СВЯЗАННЫЕ ФОРМАТЫ

doctools не является самостоятельным форматом: у него есть два сопутствующих формата. Они называются docidx и doctoc и предназначены соответственно для разметки указателей ключевых слов и оглавлений. Они описаны в отдельных наборах документов, которые начинаются с введения в docidx и введения в doctoc.

Ошибки, идеи, отзывы

В этом документе и описываемом в нём пакете, несомненно, могут быть ошибки и другие проблемы. Просим сообщать о них в категории doctools в системе отслеживания ошибок Tcllib. Также просим сообщать о любых идеях по улучшению пакета и/или документации.

Предлагая изменения кода, приводите унифицированные diff-файлы, то есть результат выполнения diff -u.

Обратите также внимание, что вложения предпочтительнее встроенных патчей. Чтобы добавить вложение, сразу после создания заявки откройте форму Изменить и нажмите самую левую кнопку на дополнительной панели навигации.

СМ. ТАКЖЕ

docidx_intro, doctoc_intro, doctools, doctools_lang_cmdref, doctools_lang_faq, doctools_lang_intro, doctools_lang_syntax, doctools_plugin_apiref

КАТЕГОРИЯ

Инструменты документирования

АВТОРСКИЕ ПРАВА

Авторское право © 2007 Andreas Kupries