1 files changed, 308 insertions, 0 deletions
diff --git a/tcllib/modules/doctools2idx/idx_export.man b/tcllib/modules/doctools2idx/idx_export.man
new file mode 100644
index 0000000..f16b73e
--- /dev/null
+++ b/tcllib/modules/doctools2idx/idx_export.man
@@ -0,0 +1,308 @@
+[comment {-*- tcl -*- doctools manpage}]
+[manpage_begin doctools::idx::export n 0.1]
+[keywords conversion]
+[keywords docidx]
+[keywords documentation]
+[keywords export]
+[keywords formatting]
+[keywords generation]
+[keywords HTML]
+[keywords index]
+[keywords json]
+[keywords {keyword index}]
+[keywords manpage]
+[keywords markup]
+[keywords nroff]
+[keywords plugin]
+[keywords reference]
+[keywords {tcler's wiki}]
+[keywords text]
+[keywords url]
+[keywords wiki]
+[copyright {2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
+[moddesc   {Documentation tools}]
+[titledesc {Exporting keyword indices}]
+[category  {Documentation tools}]
+[require doctools::idx::export [opt 0.1]]
+[require Tcl 8.4]
+[require doctools::config]
+[require doctools::idx::structure]
+[require snit]
+[require pluginmgr]
+[description]
+
+This package provides a class to manage the plugins for the export of
+keyword indices to other formats, i.e. their conversion to, for
+example [term docidx], [term HTML], etc.
+
+[para]
+
+This is one of the three public pillars the management of keyword
+indices resides on. The other two pillars are
+
+[list_begin enum]
+[enum] [manpage {Importing keyword indices}], and
+[enum] [manpage {Holding keyword indices}]
+[list_end]
+
+[para]
+
+For information about the [sectref Concepts] of keyword indices, and
+their parts, see the same-named section.
+
+For information about the data structure which is the major input to
+the manager objects provided by this package see the section
+[sectref {Keyword index serialization format}].
+
+[para]
+
+The plugin system of our class is based on the package
+[package pluginmgr], and configured to look for plugins using
+
+[list_begin enum]
+[enum] the environment variable [var DOCTOOLS_IDX_EXPORT_PLUGINS],
+[enum] the environment variable [var DOCTOOLS_IDX_PLUGINS],
+[enum] the environment variable [var DOCTOOLS_PLUGINS],
+[enum] the path [file {~/.doctools/idx/export/plugin}]
+[enum] the path [file {~/.doctools/idx/plugin}]
+[enum] the path [file {~/.doctools/plugin}]
+[enum] the path [file {~/.doctools/idx/export/plugins}]
+[enum] the path [file {~/.doctools/idx/plugins}]
+[enum] the path [file {~/.doctools/plugins}]
+[enum] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\EXPORT\PLUGINS"
+[enum] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\IDX\PLUGINS"
+[enum] the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"
+[list_end]
+
+The last three are used only when the package is run on a machine
+using Windows(tm) operating system.
+
+[para]
+
+The whole system is delivered with six predefined export plugins,
+namely
+
+[list_begin definitions]
+[def docidx]  See [manpage {docidx export plugin}] for details.
+[def html]    See [manpage {html export plugin}] for details.
+[def json]    See [manpage {json export plugin}] for details.
+[def nroff]   See [manpage {nroff export plugin}] for details.
+[def text]    See [manpage {text export plugin}] for details.
+[def wiki]    See [manpage {wiki export plugin}] for details.
+[list_end]
+
+[para]
+
+Readers wishing to write their own export plugin for some format, i.e.
+[term {plugin writer}]s reading and understanding the section
+containing the [sectref {Export plugin API v2 reference}] is an
+absolute necessity, as it specifies the interaction between this
+package and its plugins in detail.
+
+[section Concepts] [include include/concept.inc]
+
+[section API]
+[subsection {Package commands}]
+
+[list_begin definitions]
+
+[call [cmd ::doctools::idx::export] [arg objectName]]
+
+This command creates a new export manager object with an associated
+Tcl command whose name is [arg objectName]. This [term object] command
+is explained in full detail in the sections [sectref {Object command}]
+and [sectref {Object methods}]. The object command will be created
+under the current namespace if the [arg objectName] is not fully
+qualified, and in the specified namespace otherwise.
+
+[list_end]
+
+[subsection {Object command}]
+
+All objects created by the [cmd ::doctools::idx::export] command have
+the following general form:
+
+[list_begin definitions]
+
+[call [cmd objectName] [method method] [opt [arg "arg arg ..."]]]
+
+The method [method method] and its [arg arg]'uments determine the
+exact behavior of the command.
+
+See section [sectref {Object methods}] for the detailed
+specifications.
+
+[list_end]
+
+[subsection {Object methods}]
+
+[list_begin definitions]
+
+[call [arg objectName] [method destroy]]
+
+This method destroys the object it is invoked for.
+
+[call [arg objectName] [method {export serial}] [arg serial] [opt [arg format]]]
+
+This method takes the canonical serialization of a keyword index
+stored in [arg serial] and converts it to the specified [arg format],
+using the export plugin for the format. An error is thrown if no
+plugin could be found for the format.
+
+The string generated by the conversion process is returned as
+the result of this method.
+
+[para]
+
+If no format is specified the method defaults to [const docidx].
+
+[para]
+
+The specification of what a [term canonical] serialization is can be
+found in the section [sectref {Keyword index serialization format}].
+
+[para]
+
+The plugin has to conform to the interface specified in section
+[sectref {Export plugin API v2 reference}].
+
+[call [arg objectName] [method {export object}] [arg object] [opt [arg format]]]
+
+This method is a convenient wrapper around the [method {export serial}]
+method described by the previous item.
+
+It expects that [arg object] is an object command supporting a
+[method serialize] method returning the canonical serialization of a
+keyword index. It invokes that method, feeds the result into
+[method {export serial}] and returns the resulting string as its own
+result.
+
+[call [arg objectName] [method {config names}]]
+
+This method returns a list containing the names of all configuration
+variables currently known to the object.
+
+[call [arg objectName] [method {config get}]]
+
+This method returns a dictionary containing the names and values of
+all configuration variables currently known to the object.
+
+[call [arg objectName] [method {config set}] [arg name] [opt [arg value]]]
+
+This method sets the configuration variable [arg name] to the
+specified [arg value] and returns the new value of the variable.
+
+[para]
+
+If no value is specified it simply returns the current value, without
+changing it.
+
+[para]
+
+Note that while the user can set the predefined configuration
+variables [const user] and [const format] doing so will have no
+effect, these values will be internally overriden when invoking an
+import plugin.
+
+[call [arg objectName] [method {config unset}] [arg pattern]...]
+
+This method unsets all configuration variables matching the specified
+glob [arg pattern]s. If no pattern is specified it will unset all
+currently defined configuration variables.
+
+[list_end]
+
+[section {Export plugin API v2 reference}]
+
+Plugins are what this package uses to manage the support for any
+output format beyond the
+[sectref {Keyword index serialization format}]. Here we specify the
+API the objects created by this package use to interact with their
+plugins.
+
+[para]
+
+A plugin for this package has to follow the rules listed below:
+
+[list_begin enumerated]
+
+[enum] A plugin is a package.
+
+[enum] The name of a plugin package has the form
+
+		doctools::idx::export::[var FOO],
+
+       where [var FOO] is the name of the format the plugin will
+       generate output for. This name is also the argument to provide
+       to the various [method export] methods of export manager
+       objects to get a string encoding a keyword index in that
+       format.
+
+[enum] The plugin can expect that the package
+       [package doctools::idx::export::plugin] is present, as
+       indicator that it was invoked from a genuine plugin manager.
+
+[enum] A plugin has to provide one command, with the signature shown
+       below.
+
+[list_begin definitions]
+[call [cmd export] [arg serial] [arg configuration]]
+
+Whenever an export manager of [package doctools::idx] has to generate
+output for an index it will invoke this command.
+
+[list_begin arguments]
+
+[arg_def string serial]
+
+This argument will contain the [term canonical] serialization of the
+index for which to generate the output.
+
+The specification of what a [term canonical] serialization is can be
+found in the section [sectref {Keyword index serialization format}].
+
+[arg_def dictionary configuration]
+
+This argument will contain the current configuration to apply to the
+generation, as a dictionary mapping from variable names to values.
+
+[para]
+
+The following configuration variables have a predefined meaning all
+plugins have to obey, although they can ignore this information at
+their discretion. Any other other configuration variables recognized
+by a plugin will be described in the manpage for that plugin.
+
+[list_begin definitions]
+
+[def user] This variable is expected to contain the name of the user
+           owning the process invoking the plugin.
+
+[def format] This variable is expected to contain the name of the
+             format whose plugin is invoked.
+
+[def file] This variable, if defined by the user of the index object
+           is expected to contain the name of the input file for which
+           the plugin is generating its output for.
+
+[def map] This variable, if defined by the user of the index object is
+          expected to contain a dictionary mapping from symbolic file
+          names used in the references of type [const manpage] to
+          actual paths (or urls). A plugin has to be able to handle
+          the possibility that a symbolic name is without entry in
+          this mapping.
+
+[list_end][comment {-- predefined configuration variables --}]
+[list_end][comment {-- arguments --}]
+[list_end][comment {-- api command signatures --}]
+
+[enum] A single usage cycle of a plugin consists of the invokations of
+       the command [cmd export]. This call has to leave the plugin in
+       a state where another usage cycle can be run without problems.
+
+[list_end]
+
+[include include/serialization.inc]
+[vset CATEGORY doctools]
+[include ../doctools2base/include/feedback.inc]
+[manpage_end]