import man page on MacOSX

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
MacOSX logo
[printable version]

doctools::toc::import(n)      Documentation tools     doctools::toc::import(n)

______________________________________________________________________________

NAME
       doctools::toc::import - Importing keyword indices

SYNOPSIS
       package require doctools::toc::import  ?0.1?

       package require Tcl  8.4

       package require doctools::config

       package require doctools::toc::structure

       package require snit

       package require pluginmgr

       ::doctools::toc::import objectName

       objectName method ?arg arg ...?

       objectName destroy

       objectName import text text ?format?

       objectName import file path ?format?

       objectName import object text object text ?format?

       objectName import object file object path ?format?

       objectName config names

       objectName config get

       objectName config set name ?value?

       objectName config unset pattern...

       objectName includes

       objectName include add path

       objectName include remove path

       objectName include clear

       IncludeFile currentfile path

       import text configuration

_________________________________________________________________

DESCRIPTION
       This  package  provides a class to manage the plugins for the import of
       tables of contents from other formats, i.e. their conversion from,  for
       example doctoc, json, etc.

       This  is	 one  of  the three public pillars the management of tables of
       contents resides on. The other two pillars are

       [1]    Exporting tables of contents, and

       [2]    Holding tables of contents

       For information about the Concepts of tables  of	 contents,  and	 their
       parts,  see  the	 same-named  section.	For information about the data
       structure which is the major output of the manager objects provided  by
       this package see the section ToC serialization format.

       The  plugin  system of our class is based on the package pluginmgr, and
       configured to look for plugins using

       [1]    the environment variable DOCTOOLS_TOC_IMPORT_PLUGINS,

       [2]    the environment variable DOCTOOLS_TOC_PLUGINS,

       [3]    the environment variable DOCTOOLS_PLUGINS,

       [4]    the path "~/.doctools/toc/import/plugin"

       [5]    the path "~/.doctools/toc/plugin"

       [6]    the path "~/.doctools/plugin"

       [7]    the path "~/.doctools/toc/import/plugins"

       [8]    the path "~/.doctools/toc/plugins"

       [9]    the path "~/.doctools/plugins"

       [10]   the     registry	   entry      "HKEY_CURRENT_USER\SOFTWARE\DOC‐
	      TOOLS\TOC\IMPORT\PLUGINS"

       [11]   the      registry	    entry     "HKEY_CURRENT_USER\SOFTWARE\DOC‐
	      TOOLS\TOC\PLUGINS"

       [12]   the registry entry "HKEY_CURRENT_USER\SOFTWARE\DOCTOOLS\PLUGINS"

       The last three are used only when the package is run on a machine using
       Windows(tm) operating system.

       The  whole  system  is  delivered  with	two predefined import plugins,
       namely

       doctoc See doctoc import plugin for details.

       json   See json import plugin for details.

       Readers wishing to write their own import plugin for some format,  i.e.
       plugin  writers	reading	 and  understanding the section containing the
       Import plugin API v2 reference is an absolute necessity, as  it	speci‐
       fies the interaction between this package and its plugins in detail.

CONCEPTS
       [1]    A	 table of contents consists of a (possibly empty) list of ele‐
	      ments.

       [2]    Each element in the list is identified by its label.

       [3]    Each element is either a reference, or a division.

       [4]    Each reference has an associated document, identified by a  sym‐
	      bolic id, and a textual description.

       [5]    Each  division  may have an associated document, identified by a
	      symbolic id.

       [6]    Each division consists consists of a (possibly  empty)  list  of
	      elements,	 with each element following the rules as specified in
	      item 2 and above.

       A few notes

       [1]    The above rules span up a tree of elements, with	references  as
	      the  leaf nodes, and divisions as the inner nodes, and each ele‐
	      ment representing an entry in the whole table of contents.

       [2]    The identifying labels of any element E are unique within	 their
	      division	(or  toc),  and the full label of any element E is the
	      list of labels for all nodes on the unique path from the root of
	      the tree to E, including E.

API
   PACKAGE COMMANDS
       ::doctools::toc::import objectName
	      This command creates a new import manager object with an associ‐
	      ated Tcl command whose name is objectName. This  object  command
	      is  explained  in full detail in the sections Object command and
	      Object methods. The object command will  be  created  under  the
	      current  namespace if the objectName is not fully qualified, and
	      in the specified namespace otherwise.

   OBJECT COMMAND
       All objects created by the  ::doctools::toc::import  command  have  the
       following general form:

       objectName method ?arg arg ...?
	      The  method method and its arg'uments determine the exact behav‐
	      ior of the command.  See section Object methods for the detailed
	      specifications.

   OBJECT METHODS
       objectName destroy
	      This method destroys the object it is invoked for.

       objectName import text text ?format?
	      This  method  takes  the text and converts it from the specified
	      format to the canonical serialization of	a  table  of  contents
	      using the import plugin for the format. An error is thrown if no
	      plugin could be found for the format.  The serialization	gener‐
	      ated by the conversion process is returned as the result of this
	      method.

	      If no format is specified the method defaults to doctoc.

	      The specification of what a canonical serialization  is  can  be
	      found in the section ToC serialization format.

	      The  plugin has to conform to the interface specified in section
	      Import plugin API v2 reference.

       objectName import file path ?format?
	      This method is a	convenient  wrapper  around  the  import  text
	      method described by the previous item.  It reads the contents of
	      the specified file into memory, feeds  the  result  into	import
	      text and returns the resulting serialization as its own result.

       objectName import object text object text ?format?
	      This  method  is	a  convenient  wrapper	around the import text
	      method described by the previous item.  It expects  that	object
	      is  an  object command supporting a deserialize method expecting
	      the canonical serialization of a table of contents.  It  imports
	      the  text using import text and then feeds the resulting serial‐
	      ization into the object via deserialize.	 This  method  returns
	      the empty string as it result.

       objectName import object file object path ?format?
	      This  method  behaves  like  import  object text, except that it
	      reads the text to convert from the  specified  file  instead  of
	      being given it as argument.

       objectName config names
	      This  method returns a list containing the names of all configu‐
	      ration variables currently known to the object.

       objectName config get
	      This method returns a dictionary containing the names and values
	      of all configuration variables currently known to the object.

       objectName config set name ?value?
	      This  method  sets the configuration variable name to the speci‐
	      fied value and returns the new value of the variable.

	      If no value is specified it simply returns  the  current	value,
	      without changing it.

	      Note  that  while	 the user can set the predefined configuration
	      variables user and format doing so will have  no	effect,	 these
	      values  will  be	internally  overriden  when invoking an import
	      plugin.

       objectName config unset pattern...
	      This method unsets  all  configuration  variables	 matching  the
	      specified	 glob  patterns.  If  no  pattern is specified it will
	      unset all currently defined configuration variables.

       objectName includes
	      This method returns a list containing  the  currently  specified
	      paths  to use to search for include files when processing input.
	      The order of paths in the list corresponds to the order in which
	      they  are	 used, from first to last, and also corresponds to the
	      order in which they were added to the object.

       objectName include add path
	      This methods adds the specified path to the list of paths to use
	      to  search  for include files when processing input. The path is
	      added to the end of the list, causing it to  be  searched	 after
	      all  previously  added  paths.  The result of the command is the
	      empty string.

	      The method does nothing if the path is already known.

       objectName include remove path
	      This methods removes the specified path from the list  of	 paths
	      to  use  to  search for include files when processing input. The
	      result of the command is the empty string.

	      The method does nothing if the path is not known.

       objectName include clear
	      This method clears the list  of  paths  to  use  to  search  for
	      include  files  when processing input. The result of the command
	      is the empty string.

IMPORT PLUGIN API V2 REFERENCE
       Plugins are what this package uses to manage the support for any	 input
       format beyond the ToC serialization format. Here we specify the API the
       objects created by this package use to interact with their plugins.

       A plugin for this package has to follow the rules listed below:

       [1]    A plugin is a package.

       [2]    The   name   of	a   plugin   package   has   the   form	  doc‐
	      tools::toc::import::FOO, where FOO is the name of the format the
	      plugin will generate output for. This name is also the  argument
	      to  provide  to  the  various  import  methods of import manager
	      objects to get a string encoding a table	of  contents  in  that
	      format.

       [3]    The    plugin    can    expect	that	the    package	  doc‐
	      tools::toc::export::plugin is present, as indicator that it  was
	      invoked from a genuine plugin manager.

       [4]    The  plugin  can	expect	that  a	 command  named IncludeFile is
	      present, with the signature

	      IncludeFile currentfile path
		     This command has to be invoked by the plugin when it  has
		     to	 process  an included file, if the format has the con‐
		     cept of such. An example of such a format would  be  doc‐
		     toc.

		     The plugin has to supply the following arguments

		     string currentfile
			    The	 path  of the file it is currently processing.
			    This may be the empty string if no such is known.

		     string path
			    The path of the include file as specified  in  the
			    include directive being processed.
	      The result of the command will be a 5-element list containing

		     [1]    A  boolean	flag  indicating the success (True) or
			    failure (False) of the operation.

		     [2]    In case of success the contents  of	 the  included
			    file, and the empty string otherwise.

		     [3]    The	 resolved,  i.e. absolute path of the included
			    file, if possible, or the unchanged path argument.
			    This is for display in an error message, or as the
			    currentfile argument of another call  to  Include‐
			    File should this file contain more files.

		     [4]    In	case of success an empty string, and for fail‐
			    ure a code indicating the reason for it, one of

			    notfound
				   The specified file could not be found.

			    notread
				   The specified file was found,  but  not  be
				   read into memory.

		     [5]    An	empty  string in case of success of a notfound
			    failure, and an additional error message  describ‐
			    ing the reason for a notread error in more detail.

       [5]    A	 plugin	 has  to provide one command, with the signature shown
	      below.

	      import text configuration
		     Whenever an import manager of doctools::toc has to	 parse
		     input  for	 a  table of contents it will invoke this com‐
		     mand.

		     string text
			    This argument will contain the text	 encoding  the
			    table  of  contents	 per  the format the plugin is
			    for.

		     dictionary configuration
			    This argument will contain the current  configura‐
			    tion to apply to the parsing, as a dictionary map‐
			    ping from variable names to values.

			    The following configuration variables have a  pre‐
			    defined meaning all plugins have to obey, although
			    they can ignore this information at their  discre‐
			    tion. Any other other configuration variables rec‐
			    ognized by a plugin will be described in the  man‐
			    page for that plugin.

			    user   This	 variable  is  expected to contain the
				   name of the user owning the process	invok‐
				   ing the plugin.

			    format This	 variable  is  expected to contain the
				   name of the format whose plugin is invoked.

       [6]    A single usage cycle of a plugin consists of the invokations  of
	      the command import. This call has to leave the plugin in a state
	      where another usage cycle can be run without problems.

TOC SERIALIZATION FORMAT
       Here we specify the format used by the doctools v2 packages to  serial‐
       ize  tables  of contents as immutable values for transport, comparison,
       etc.

       We distinguish between regular and canonical serializations.   While  a
       table  of  contents  may	 have more than one regular serialization only
       exactly one of them will be canonical.

       regular serialization

	      [1]    The serialization of any table of contents	 is  a	nested
		     Tcl dictionary.

	      [2]    This  dictionary  holds  a single key, doctools::toc, and
		     its value. This value holds the contents of the table  of
		     contents.

	      [3]    The  contents  of the table of contents are a Tcl dictio‐
		     nary holding the title of the table of contents, a label,
		     and its elements. The relevant keys and their values are

		     title  The	 value is a string containing the title of the
			    table of contents.

		     label  The value is a string containing a label  for  the
			    table of contents.

		     items  The	 value	is  a Tcl list holding the elements of
			    the table, in the order they are to be shown.

			    Each element is a Tcl list holding the type of the
			    item,  and	its  description,  in  this  order. An
			    alternative description would be that it is a  Tcl
			    dictionary	holding	 a  single key, the item type,
			    mapped to the item description.

			    The two legal item types  and  their  descriptions
			    are

			    reference
				   This	 item  describes a single entry in the
				   table of  contents,	referencing  a	single
				   document.   To  this end its value is a Tcl
				   dictionary containing an id for the	refer‐
				   enced  document, a label, and a longer tex‐
				   tual description which  can	be  associated
				   with	 the  entry.   The  relevant  keys and
				   their values are

				   id	  The value is a string containing the
					  id  of  the document associated with
					  the entry.

				   label  The value is a string	 containing  a
					  label	 for  this  entry. This string
					  also identifies the  entry,  and  no
					  two  entries	(references  and divi‐
					  sions) in the	 containing  list  are
					  allowed to have the same label.

				   desc	  The  value  is a string containing a
					  longer description for this entry.

			    division
				   This item describes a group of  entries  in
				   the table of contents, inducing a hierarchy
				   of entries.	To this end its value is a Tcl
				   dictionary	containing  a  label  for  the
				   group, an optional id to a document for the
				   whole group, and the list of entries in the
				   group.  The relevant keys and their	values
				   are

				   id	  The value is a string containing the
					  id of the document  associated  with
					  the	whole	group.	 This  key  is
					  optional.

				   label  The value is a string	 containing  a
					  label	 for  the  group.  This string
					  also identifies the  entry,  and  no
					  two  entries	(references  and divi‐
					  sions) in the	 containing  list  are
					  allowed to have the same label.

				   items  The  value is a Tcl list holding the
					  elements of the group, in the	 order
					  they are to be shown.	 This list has
					  the same structure as the value  for
					  the  keyword	items used to describe
					  the whole  table  of	contents,  see
					  above.  This	closes	the  recusrive
					  definition of	 the  structure,  with
					  divisions  holding  the same type of
					  elements as the whole table of  con‐
					  tents, including other divisions.

       canonical serialization
	      The  canonical serialization of a table of contents has the for‐
	      mat as specified in the previous	item,  and  then  additionally
	      satisfies	 the constraints below, which make it unique among all
	      the possible serializations of this table of contents.

	      [1]    The keys found in all the	nested	Tcl  dictionaries  are
		     sorted  in	 ascending  dictionary	order, as generated by
		     Tcl's builtin command lsort -increasing -dict.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs  and  other problems.  Please report such in the category doctools
       of	the	  Tcllib       SF	Trackers       [http://source‐
       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
       enhancements you may have for either package and/or documentation.

KEYWORDS
       conversion, doctoc, documentation, import, json, manpage, markup, pars‐
       ing, plugin, reference, table, table of contents, url

CATEGORY
       Documentation tools

COPYRIGHT
       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>

doctools2toc			      0.1	      doctools::toc::import(n)
[top]

List of man pages available for MacOSX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net