doctools::idx::import::docidx

ИМЯ

doctools::idx::import::docidx - плагин импорта docidx

Содержание

• Содержание

• Краткое описание

• Описание

• API

• Нотация [docidx] для предметных указателей ключевых слов

• Формат сериализации предметного указателя ключевых слов

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

• Категория

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

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

package require Tcl 8.5 9
package require doctools::idx::import::docidx ?0.2.1?
package require doctools::idx::parse
package require doctools::idx::structure
package require doctools::msgcat
package require doctools::tcl::parse
package require fileutil
package require logger
package require snit
package require struct::list
package require struct::set
package require struct::stack
package require struct::tree
package require treeql

import string configuration

ОПИСАНИЕ

Этот пакет реализует плагин импорта предметных указателей ключевых слов doctools для разбора разметки docidx.

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

Использовать его из обычного интерпретатора возможно, однако это требует обходных решений и не рекомендуется. Правильный способ использовать эту функциональность — пакет doctools::idx::import и предоставляемые им объекты диспетчера импорта.

API

API, предоставляемый этим пакетом, соответствует спецификации API плагина импорта docidx версии 2.

• import string configuration

  Эта команда принимает string и разбирает его как разметку docidx, кодирующую предметный указатель ключевых слов, в контексте указанной configuration (словаря). Результатом команды является каноническая сериализация этого предметного указателя в формате, указанном в разделе Формат сериализации предметного указателя ключевых слов.

Нотация [docidx] для предметных указателей ключевых слов

Формат docidx для предметных указателей ключевых слов, также называемый языком разметки docidx, слишком обширен, чтобы рассмотреть его в одном разделе. Заинтересованному читателю следует начать с документа

1. введение в язык docidx

а затем перейти к формальным спецификациям, то есть к документам

1. синтаксис языка docidx и

2. справочник по командам языка docidx.

чтобы получить полное представление о языке.

Формат сериализации предметного указателя ключевых слов

Здесь мы определяем формат, используемый пакетами doctools v2 для сериализации предметных указателей ключевых слов в виде неизменяемых значений для передачи, сравнения и т. д.

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

• обычная сериализация

  1. Сериализация предметного указателя представляет собой вложенный словарь Tcl.
  2. Этот словарь содержит один ключ — doctools::idx — и его значение. Это значение содержит содержимое предметного указателя.

  3. Содержимое предметного указателя представляет собой словарь Tcl, содержащий заголовок предметного указателя, метку, ключевые слова и ссылки. Используются следующие ключи и значения:

     • title

       Значение — строка, содержащая заголовок предметного указателя.

     • label

       Значение — строка, содержащая метку предметного указателя.

     • keywords

       Значение — словарь Tcl, в котором в качестве ключей используются известные предметному указателю ключевые слова. Связанные значения — списки, содержащие идентификаторы ссылок, относящихся к соответствующему ключевому слову.

       Каждый идентификатор ссылки, используемый в этих списках, должен существовать в качестве ключа в словаре references; его определение приведено в следующем пункте.

     • references

       Значение — словарь Tcl, в котором в качестве ключей используются идентификаторы известных предметному указателю ссылок. Связанные значения — списки из двух элементов, содержащие тип и метку ссылки именно в таком порядке.

       Каждый ключ здесь должен быть связан хотя бы с одним ключевым словом, то есть встречаться хотя бы в одном из списков ссылок, являющихся значениями словаря keywords; его определение приведено в предыдущем пункте.

  4. тип ссылки может принимать одно из двух значений:

     • manpage

       Идентификатор ссылки интерпретируется как символическое имя файла, указывающее на один из документов, для которых создан предметный указатель.

     • url

       Идентификатор ссылки интерпретируется как URL-адрес, указывающий на некоторое внешнее местоположение, например веб-сайт и т. д.

• каноническая сериализация

  Каноническая сериализация предметного указателя ключевых слов имеет формат, описанный в предыдущем пункте, и дополнительно удовлетворяет приведённым ниже ограничениям, которые делают её единственной среди всех возможных сериализаций этого предметного указателя.

  1. Ключи во всех вложенных словарях Tcl отсортированы по возрастанию в словарном порядке, как при выполнении встроенной команды Tcl lsort -increasing -dict.
  2. Ссылки, перечисленные для каждого ключевого слова предметного указателя (если они есть), отсортированы по возрастанию в словарном порядке их меток, как при выполнении встроенной команды Tcl lsort -increasing -dict.

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

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

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

Обратите также внимание: настоятельно рекомендуется прикладывать вложения, а не вставлять исправления непосредственно в текст. Вложения можно добавить, открыв форму Edit соответствующей заявки сразу после её создания, а затем нажав самую левую кнопку на дополнительной панели навигации.

КАТЕГОРИЯ

Плагин форматирования текста

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

Авторское право © 2009–2019 Andreas Kupries