container man page on Ubuntu

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

doctools::toc(3tcl)	      Documentation tools	   doctools::toc(3tcl)

______________________________________________________________________________

NAME
       doctools::toc - Holding tables of contents

SYNOPSIS
       package require doctools::toc  ?2?

       package require Tcl  8.4

       package require doctools::toc::structure

       package require struct::tree

       package require snit

       ::doctools::toc objectName

       objectName method ?arg arg ...?

       objectName destroy

       objectName + reference id label docid desc

       objectName + division id label ?docid?

       objectName remove id

       objectName up id

       objectName next id

       objectName prev id

       objectName child id label ?...?

       objectName element ?...?

       objectName children id

       objectName type id

       objectName full-label id

       objectName elabel id ?newlabel?

       objectName description id ?newdesc?

       objectName document id ?newdocid?

       objectName title

       objectName title text

       objectName label

       objectName label text

       objectName importer

       objectName importer object

       objectName exporter

       objectName exporter object

       objectName deserialize = data ?format?

       objectName deserialize += data ?format?

       objectName serialize ?format?

_________________________________________________________________

DESCRIPTION
       This  package  provides a class to contain and programmatically manipu‐
       late tables of contents.

       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]    Importing 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 used to encode tables of contents as values see the
       section ToC serialization format.  This is  the	only  format  directly
       known  to this class. Conversions from and to any other format are han‐
       dled by export and import manager objects. These may be attached	 to  a
       container, but do not have to be, it is merely a convenience.

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 objectName
	      This  command  creates a new container object with an associated
	      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 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 + reference id label docid desc
	      This  method  adds  a new reference element to the table of con‐
	      tents, under the element specified via its handle id. This  par‐
	      ent  element has to be a division element, or the root. An error
	      is thrown otherwise.  The new element will be externally identi‐
	      fied  by	its label, which has to be be unique within the parent
	      element. An error is thrown otherwise.

	      As a reference element it will refer to a document identified by
	      the symbolic docid. This reference must not be the empty string,
	      an error is thrown otherwise.  Beyond the label the element also
	      has a longer descriptive string, supplied via desc.

	      The result of the method is the handle (id) of the new element.

       objectName + division id label ?docid?
	      This  method  adds  a  new division element to the table of con‐
	      tents, under the element specified via its handle id. This  par‐
	      ent  element has to be a division element, or the root. An error
	      is thrown otherwise.  The new element will be externally identi‐
	      fied  by	its label, which has to be be unique within the parent
	      element. An error is thrown otherwise.

	      As a division element it is can refer to a document,  identified
	      by the symbolic docid, but may choose not to.

	      The result of the method is the handle (id) of the new element.

       objectName remove id
	      This method removes the element identified by the handle id from
	      the table of contents.  If the element is a division all of  its
	      children, if any, are removed as well. The root element/division
	      of the table of contents cannot be  removed  however,  only  its
	      children.

	      The result of the method is the empty string.

       objectName up id
	      This  method  returns  the  handle of the parent for the element
	      identified by its handle id, or the empty string if  id  refered
	      to the root element.

       objectName next id
	      This method returns the handle of the right sibling for the ele‐
	      ment identified by its handle id, or the handle of the parent if
	      the element has no right sibling, or the empty string if id ref‐
	      ered to the root element.

       objectName prev id
	      This method returns the handle of the left sibling for the  ele‐
	      ment identified by its handle id, or the handle of the parent if
	      the element has no left sibling, or the empty string if id  ref‐
	      ered to the root element.

       objectName child id label ?...?
	      This method returns the handle of a child of the element identi‐
	      fied by its handle id. The  child	 itself	 is  identified	 by  a
	      series of labels.

       objectName element ?...?
	      This  method  returns  the handle of the element identified by a
	      series of labels, starting from the root of the  table  of  con‐
	      tents.  The  series  of  labels is allowed to be empty, in which
	      case the handle of the root element is returned.

       objectName children id
	      This method returns a list containing the handles of  all	 chil‐
	      dren  of	the element identified by the handle id, from first to
	      last, in that order.

       objectName type id
	      This method returns the type of the element,  either  reference,
	      or division.

       objectName full-label id
	      This  method is the complement of the method element, converting
	      the handle id of an element into a list of labels full identify‐
	      ing the element within the whole table of contents.

       objectName elabel id ?newlabel?
	      This  method  queries  and/or  changes  the label of the element
	      identified by the handle id. If the argument newlabel is present
	      then the label is changed to that value. Regardless of this, the
	      result of the method is the current value of the label.

	      If the label is changed the new label has to  be	unique	within
	      the containing division, or an error is thrown.

	      Further,	of  the	 id refers to the root element of the table of
	      contents, then using this method	is  equivalent	to  using  the
	      method  label,  i.e.  it	is  accessing the global label for the
	      whole table.

       objectName description id ?newdesc?
	      This method queries and/or changes the description of  the  ele‐
	      ment  identified	by  the	 handle id. If the argument newdesc is
	      present then the description is changed to that  value.  Regard‐
	      less  of	this, the result of the method is the current value of
	      the description.

	      The element this method operates on has to be a  reference  ele‐
	      ment, or an error will be thrown.

       objectName document id ?newdocid?
	      This method queries and/or changes the document reference of the
	      element identified by the handle id.  If the  argument  newdocid
	      is  present  then	 the  description  is  changed	to that value.
	      Regardless of this, the result of	 the  method  is  the  current
	      value of the document reference.

	      Setting  the  reference  to the empty string means unsetting it,
	      and is allowed only for division elements.  Conversely,  if  the
	      result is the empty string then the element has no document ref‐
	      erence, and this can happen only for division elements.

       objectName title
	      Returns the currently defined title of the table of contents.

       objectName title text
	      Sets the title of the table of contents to text, and returns  it
	      as the result of the command.

       objectName label
	      Returns the currently defined label of the table of contents.

       objectName label text
	      Sets  the label of the table of contents to text, and returns it
	      as the result of the command.

       objectName importer
	      Returns the import manager object currently attached to the con‐
	      tainer, if any.

       objectName importer object
	      Attaches	the  object  as	 import	 manager to the container, and
	      returns it as the result of the command.	Note that  the	object
	      is not put into ownership of the container. I.e., destruction of
	      the container will not destroy the object.

	      It is expected that object provides a method named  import  text
	      which  takes a text and a format name, and returns the canonical
	      serialization of the table of contents contained	in  the	 text,
	      assuming the given format.

       objectName exporter
	      Returns the export manager object currently attached to the con‐
	      tainer, if any.

       objectName exporter object
	      Attaches the object as export  manager  to  the  container,  and
	      returns  it  as the result of the command.  Note that the object
	      is not put into ownership of the container. I.e., destruction of
	      the container will not destroy the object.

	      It is expected that object provides a method named export object
	      which takes the container and a format name, and returns a  text
	      encoding table of contents stored in the container, in the given
	      format. It is further expected that the object will use the con‐
	      tainer's method serialize to obtain the serialization of the ta‐
	      ble of contents from which to generate the text.

       objectName deserialize = data ?format?
	      This method replaces the contents of the table object  with  the
	      table  contained	in  the data. If no format was specified it is
	      assumed to be the regular serialization of a table of contents.

	      Otherwise the object will use the	 attached  import  manager  to
	      convert the data from the specified format to a serialization it
	      can handle.  In that case an error will be thrown	 if  the  con‐
	      tainer has no import manager attached to it.

	      The result of the method is the empty string.

       objectName deserialize += data ?format?
	      This method behaves like deserialize = in its essentials, except
	      that it merges the table of contents in the data to its contents
	      instead  of  replacing  it.   The	 method will throw an error if
	      merging is not possible, i.e. would produce  an  invalid	table.
	      The existing content is left unchanged in that case.

	      The result of the method is the empty string.

       objectName serialize ?format?
	      This  method  returns  the  table	 of  contents contained in the
	      object. If no format is not specified the returned result is the
	      canonical serialization of its contents.

	      Otherwise	 the  object  will  use the attached export manager to
	      convert the data to the specified format.	 In that case an error
	      will  be	thrown if the container has no export manager attached
	      to it.

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
       HTML, TMML, conversion, doctoc markup, documentation, formatting,  gen‐
       eration, json, latex, markup, nroff, parsing, plugin, reference, table,
       table of contents, tcler's wiki, text, wiki

CATEGORY
       Documentation tools

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

doctools2toc			       2		   doctools::toc(3tcl)
[top]

List of man pages available for Ubuntu

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