tepam::doc_gen
ИМЯ
tepam::doc_gen — генерация документации TEPAM, справочное руководство
Содержание
КРАТКОЕ ОПИСАНИЕ
package require Tcl 8.5 9
package require tepam 0.5
package require tepam::doc_gen ?0.1.3?
tepam::doc_gen::generate ?-format format? ?-style style? ?-header_footer? ?-dest_file dest_file? name
tepam::doc_gen::patch ?-format format? ?-style style? ?-search_pattern search_pattern? ?-src_string src_string | -src_file src_file? ?-dest_file dest_file? ?name?
ОПИСАНИЕ
Этот пакет генерирует документацию для процедур TEPAM (процедур, объявленных с помощью tepam::procedure). Документация создаётся в классическом стиле документации UNIX и включает следующие разделы: имя, краткое описание, описание, аргументы и примеры. TEPAM Doc Gen поддерживает различные форматы документов. При необходимости можно добавить поддержку дополнительных форматов.
Пакет TEPAM Doc Gen предоставляет следующие команды:
-
tepam::doc_gen::generate ?-format format? ?-style style? ?-header_footer? ?-dest_file dest_file? name
Эта команда генерирует документацию для указанной процедуры (name) в одном из поддерживаемых форматов (TXT, HTML, POD (Perl Doc), DT (TclLib DocTool) или в пользовательском формате). Формат указывается с помощью ?format?. Флаг ?-header_footer? добавляет в файл документации заголовок и нижний колонтитул. Если указан ?dest_file?, документация сохраняется в файл (в этом случае заголовок и нижний колонтитул добавляются автоматически), а имя файла возвращается. В противном случае команда generate возвращает строку документации.
-
tepam::doc_gen::patch ?-format format? ?-style style? ?-search_pattern search_pattern? ?-src_string src_string | -src_file src_file? ?-dest_file dest_file? ?name?
Эта команда вставляет документацию процедур в существующий основной документ в местах, обозначенных маркерами вставки, соответствующими шаблону ?search_pattern?. Существующий основной документ передаётся либо как данные аргумента (?src_string?), либо через файл (?src_file?). Если файл назначения не задан (?dest_file?), команда patch возвращает итоговый документ. В противном случае документ сохраняется в указанный файл, а команда возвращает количество маркеров вставки, обработанных успешно.
По умолчанию обрабатываются все маркеры вставки основного документа. Если задан аргумент ?name?, вставка документации будет ограничена указанной процедурой.
АРГУМЕНТЫ
-
?-format format?
Задаёт формат документации. TEPAM Doc Gen поддерживает следующие форматы:
- TXT — текстовый формат (по умолчанию)
- HTML
- POD — формат Perl Plain Old Documentation (PerlPOD)
- DT — формат TclLib DocTool
В разделе ДОБАВЛЕНИЕ ПОДДЕРЖКИ НОВЫХ ФОРМАТОВ ДОКУМЕНТОВ описано, как добавить поддержку дополнительных форматов.
-
?-style style?
По умолчанию документация создаётся в стиле Tcl (например, command arg1 arg2 ...). Документацию в стиле C можно создать, задав для этого аргумента значение 'C' (например, command(arg1,arg2,...)).
-
?-dest_file dest_file?
Если задан ?dest_file?, документация записывается в указанный файл назначения. В противном случае команды generate и patch возвращают строку документации.
-
name / ?name?
Это имя процедуры, для которой необходимо создать документацию. Для команды generate этот аргумент обязателен, а для patch — необязателен.
-
?-header_footer?
Команда generate добавляет заголовок и нижний колонтитул файла к документации процедуры только при создании файла. При выборе флага ?-header_footer? заголовок и нижний колонтитул также добавляются, если команда generate возвращает документацию в виде строки.
-
?-src_string src_string | -src_file src_file?
Команда Patch вставляет документацию процедур в существующий документ, переданный либо в виде строки аргументу (?src_string?), либо в виде файла (?src_file?). Необходимо указать один из этих двух аргументов.
-
?-search_pattern search_pattern?
Аргумент ?search_pattern? задаёт маркер вставки документации, используемый в документе. Это регулярное выражение, принимаемое командой regexp; оно должно содержать подвыражение в скобках с именем процедуры, для которой нужно вставить документацию.
По умолчанию используется следующий шаблон маркера вставки: \{!(.*?)!\}. Это означает, что имя процедуры помещается между {! и !}. В разделе ПРИМЕРЫ приведён пример пользовательского шаблона маркера вставки.
ПРЕДОПРЕДЕЛЁННЫЕ ФОРМАТЫ ДОКУМЕНТОВ
TEPAM Doc Gen предварительно определяет следующие форматы документов:
TXT — текстовый формат
Если выбран этот формат, документация будет создана в простом текстовом формате. Формат можно настроить с помощью следующей переменной:
-
tepam::doc_gen::Option(TXT,MaxLineLength)
По умолчанию: 80
Эта переменная задаёт ограничение на длину строки (позицию символа).
HTML — формат HTML
TEPAM Doc Gen создаёт HTML-файлы, оформленные с помощью CSS. HTML-документацию можно настроить с помощью следующей переменной:
-
tepam::doc_gen::Option(HTML,CssFile)
По умолчанию: "tepam_doc_stylesheet.css"
Эта переменная задаёт файл таблицы стилей CSS, на который ссылаются созданные HTML-файлы.
Таблицу стилей CSS можно настроить, чтобы изменить форматирование документации. В качестве отправной точки для создания пользовательской таблицы стилей CSS удобно использовать файл CSS из примера/демонстрации TEPAM Doc Gen. В HTML-документации используются следующие стили классов CSS:
h1.tepam_page_title — заголовок страницы документа. Используется командой generate только при создании файла или при формировании заголовка и нижнего колонтитула (выбран флаг ?-header_footer?).
div.tepam_command_help — контейнер документации. Весь текст документации процедуры размещается внутри этого контейнера.
p.tepam_section_title — заголовок раздела (например, Имя, Краткое описание, Описание и т. д.)
p.tepam_sub_section_title — заголовок подраздела (используется для разделения документации нескольких подпрограмм)
p.tepam_name — раздел с именем
p.tepam_synopsis — раздел с кратким описанием
p.tepam_description — абзац описания
ul.tepam_description_list — элемент маркированного/неупорядоченного HTML-списка в разделе описания
dt.tepam_argument — элемент HTML-списка описаний, используемый для перечисления аргументов процедуры
p.tepam_argument_description — абзац с описанием аргумента
p.tepam_argument_attribute — строка атрибута аргумента
pre.tepam_example — раздел с примерами
POD — формат документов Perl
Если выбран этот формат, документация создаётся в формате Perl Plain Old Documentation (PerlPOD).
DT — формат TclLib DocTools
Если выбран этот формат, документация создаётся в формате Tcllib DocTools.
ДОБАВЛЕНИЕ ПОДДЕРЖКИ НОВЫХ ФОРМАТОВ ДОКУМЕНТОВ
Поддержку нового формата документов можно добавить, определив в пространстве имён tepam::doc_gen набор процедур для генерации различных компонентов документа.
В следующем фрагменте документации содержатся токены, соответствующие различным процедурам генерации документов:
<01>
<03> <20s> ИМЯ*<20e>*
<30s> message_box — Отображает текст в окне сообщения*<30e>*
<20s> КРАТКОЕ ОПИСАНИЕ*<20e>*
<40s> message_box [-mtype] <40e>
<20s> ОПИСАНИЕ*<20e>*
<21s> message_box<21e>
<54s> message_box [-mtype] <54e>
<50s> Эта процедура позволяет отображать текст в окне сообщения. Поддерживаются следующие
** типы сообщений:<50e>
<51> <53s> * Информация*<53e>*
<53s> * Предупреждение*<53e>*
<53s> * Ошибка*<53e>* <52>
<50s> Если параметр text используется несколько раз, различные тексты
** объединяются в текст сообщения.<50e>
<20s> АРГУМЕНТЫ*<20e>*
<60> <62s> [-mtype]<62e>
<63> <65s> Тип сообщения*<65e>*
<66s> По умолчанию: "Warning"<66e>
<66s> Несколько значений: да*<66e>*
<66s> Допустимые значения: Info, Warning, Error*<66e>* <64>
<62s><62e>
<63> <65s> Одна или несколько строк текста для отображения*<65e>*
<66s> Тип: string*<66e>*
<66s> Несколько значений: да*<66e>* <64><61>
<20s> ПРИМЕР*<20e>*
<70> <72s> message_box "Please save first the document"<72e>
<73s> -> 1*<73e>* <71><04>
<02>
Существует 2 типа процедур генерации документов:
-
Процедуры генерации содержимого (например, <40s>...<40e>)
Эти процедуры создают содержимое документа на основе текста, переданного в качестве аргумента процедуры. В приведённом выше фрагменте для этих процедур показаны два токена, обозначающие начало и конец создаваемого содержимого.
-
Процедуры генерации управляющих элементов (например, <03>)
Эти процедуры создают управляющие конструкции, например для генерации пролога и эпилога списков, разделов и т. д. У этих процедур нет аргументов.
Чтобы добавить поддержку нового формата документов, необходимо определить следующий набор процедур:
-
01 - gen($Format,Header) {Text}
Вызывается только в том случае, если doc_gen генерирует файл или вызывается с флагом ?-header_footer?. Процедура создаёт заголовок файла. В качестве параметра передаётся имя процедуры, для которой необходимо сгенерировать документацию.
-
02 - gen($Format,Footer) {Text}
Вызывается только в том случае, если doc_gen генерирует файл или вызывается с флагом ?-header_footer?. Процедура создаёт нижний колонтитул файла.
-
03 - gen($Format,Begin) {}
Генерирует пролог (вводную часть) документации
-
04 - gen($Format,End) {}
Генерирует эпилог документации
-
20 - gen($Format,SectionTitle) {Text}
Генерирует заголовок раздела (например, Имя, Синопсис, Описание, ...). Исходный текст заголовка передаётся в качестве параметра
-
21 - gen($Format,SubSectionTitle) {Text}
Генерирует заголовок подраздела. Подразделы используются, если одна документация создаётся для нескольких подкоманд, чтобы разделить их. Исходный текст заголовка передаётся в качестве параметра
-
30 - gen($Format,Name) {Text}
Генерирует раздел с именем (без заголовка). Исходный текст раздела передаётся в качестве параметра.
-
40 - gen($Format,Synopsis) {Text}
Генерирует раздел синопсиса (без заголовка). Текст раздела, переданный в качестве параметра, предварительно отформатирован (строки аргументов генерируются с помощью gen($Format,ArgumentString)).
-
50 - gen($Format,Description) {Text}
Генерирует абзац описания. Исходный текст абзаца передаётся в качестве параметра.
-
51 - gen($Format,DescriptionListBegin) {}
Генерирует пролог маркированного/неупорядоченного списка в разделе описания. Обычно этот пролог представляет собой начальный код структуры списка.
-
52 - gen($Format,DescriptionListEnd) {}
Генерирует эпилог маркированного/неупорядоченного списка в разделе описания. Обычно этот эпилог представляет собой завершающий код структуры списка.
-
53 - gen($Format,DescriptionListItem) {Text}
Генерирует текстовый элемент маркированного/неупорядоченного списка описания. Исходный текст элемента передаётся в качестве параметра.
-
54 - gen($Format,DescriptionSynopsis) {Text}
Генерирует строку синопсиса в начале раздела описания. Команда может возвращать пустую строку, если в этом месте строка синопсиса не требуется.
Некоторые форматы (например, Tcl DocTools) требуют, чтобы строка синопсиса задавалась в разделе описания, чтобы затем автоматически сформировать раздел синопсиса. Текст раздела, переданный в качестве параметра, предварительно отформатирован (строки аргументов генерируются с помощью gen($Format,ArgumentString)).
-
60 - gen($Format,ArgumentListBegin) {}
Генерирует пролог списка аргументов (списка определений/немаркированного списка). Обычно этот пролог представляет собой начальный код списка определений.
-
61 - gen($Format,ArgumentListEnd) {}
Генерирует эпилог списка аргументов. Обычно этот эпилог представляет собой завершающую строку структуры списка.
-
62 - gen($Format,ArgumentListItem) {Name IsOptional IsNamed Type}
Генерирует строку элемента аргумента в списке аргументов. Эта команда может использовать gen($Format,ArgumentDetailBegin), поскольку параметры у них одинаковы.
-
63 - gen($Format,ArgumentDetailBegin) {}
Генерирует пролог сведений об аргументе (вводную часть).
-
64 - gen($Format,ArgumentDetailEnd) {}
Генерирует эпилог сведений об аргументе
-
65 - gen($Format,ArgumentDescription) {Text}
Генерирует описание аргумента (один абзац).
-
66 - gen($Format,ArgumentAttribute) {Text}
Генерирует строку отдельного атрибута аргумента. Команда вызывается отдельно для каждого атрибута.
-
70 - gen($Format,ExampleBegin) {}
Генерирует пролог раздела примеров (вводную часть)
-
71 - gen($Format,ExampleEnd) {}
Генерирует эпилог раздела примеров
-
72 - gen($Format,ExampleCommandLine) {Text}
Генерирует отдельную командную строку в разделе примеров. Команда вызывается для каждой отдельной командной строки.
-
73 - gen($Format,ExampleResultLine) {Text}
Генерирует строку результата команды
-
80 - gen($Format,ArgumentString) {Name IsOptional IsNamed Type}
Генерирует часть командной строки или синопсиса, относящуюся к аргументу. В сгенерированной строке необходимо указать, является ли аргумент необязательным, именованным и флагом.
Этой процедуре передаются следующие параметры:
-
Name
Имя аргумента
-
IsOptional
Если значение истинно (=1), аргумент является необязательным; это должно быть указано в сгенерированной строке (например, заключением аргумента в скобки {[]} или вопросительные знаки '?'):
-
gen(TXT,ArgumentString) mtype 1 0 string -> "[mtype]"
* *IsNamed*
If true \(=__1__\) an argument is a named argument \(option\)\. The
generated string should in this case contain the argument/option name,
followed by the argument itself:
gen(TXT,ArgumentString) mtype 0 1 string -> "-mtype
"
Named arguments can also be optional:
gen(TXT,ArgumentString) mtype 1 1 string -> "[-mtype
]"
* *Type*
Indicates the type of the argument\. If the type is set to __none__
the argument is a flag, which needs to be indicated by the generated
string\. Example:
gen(TXT,ArgumentString) close 1 1 none -> "[-close]"
ПРИМЕРЫ
tepam::doc_gen::generate
Пакет TEPAM Doc Gen можно изучить, сгенерировав документацию для команды tepam::doc_gen::generate. В следующем примере документ создаётся в текстовом формате (формат по умолчанию):
tepam::doc_gen::generate tepam::doc_gen::generate
В следующем примере документация создаётся в формате HTML:
tepam::doc_gen::generate -format HTML tepam::doc_gen::generate
Флаг ?header_footer? также добавляет заголовок и нижний колонтитул файла:
tepam::doc_gen::generate -format HTML -header_footer tepam::doc_gen::generate
Документацию можно сразу сохранить в файл. В этом случае заголовок и нижний колонтитул файла создаются автоматически:
tepam::doc_gen::generate -format HTML -dest_file doc_gen.html tepam::doc_gen::generate
В созданном HTML-файле указывается файл таблицы стилей CSS (по умолчанию: tepam_doc_stylesheet.css). Чтобы HTML-файл отображался корректно, этот файл таблицы стилей CSS необходимо скопировать в каталог с созданным HTML-файлом.
Формат Tcl DOC Tools можно использовать как промежуточный для создания других форматов, например HTML:
# Generate the documentation in Tcl Doc Tool format
set dt [tepam::doc_gen::generate -format DT -header_footer tepam::doc_gen::generate]
**
# Create a new doc tools object (HTML format)
package require doctools
::doctools::new myDoc -format html
**
# Open the HTML file, and write the HTML formatted documentation
set fHtml [open doc_gen.dt.html w]
puts $fHtml [myDoc format $dt]
close $fHtml
tepam::doc_gen::patch
В то время как команда generate предоставляет ограниченное число возможностей для изменения структуры документа, команда patch обеспечивает большую гибкость. Например, можно добавить документацию для нескольких процедур и метаинформацию.
В следующем примере показано, как работает команда patch. Сначала задаётся строка главного HTML-документа, содержащая два заполнителя для документации процедур ({*
# Define the HTML master document
set HtmlMasterDoc {\
tepam::doc_gen
tepam::doc_gen
Generate
{*tepam::doc_gen::generate*}
Patch
{*tepam::doc_gen::patch*}
\
}
**
# Patch the master document: This will replace the placeholders by the *
*# procedure documentation divisions:tepam::doc_gen::patch -format HTML -search_pattern {\{\*(.*?)\*\}} \
-src_string $HtmlMasterDoc -dest_file tepam_doc_gen.html
СМ. ТАКЖЕ
КАТЕГОРИЯ
Средства документирования
АВТОРСКИЕ ПРАВА
Авторское право © 2013, Andreas Drollinger
