[csw-devel] SF.net SVN: gar:[15036] csw/mgar/pkg
Dagobert Michelsen
dam at opencsw.org
Mon Jul 11 12:55:39 CEST 2011
Hi Kester,
some comments inline.
Best regards
-- Dago
Am 11.07.2011 um 11:48 schrieb khabermann at users.sourceforge.net:
> Revision: 15036
> http://gar.svn.sourceforge.net/gar/?rev=15036&view=rev
> Author: khabermann
> Date: 2011-07-11 09:48:15 +0000 (Mon, 11 Jul 2011)
>
> Log Message:
> -----------
> tcllib: created package
>
> Added Paths:
> -----------
> csw/mgar/pkg/tcllib/
> csw/mgar/pkg/tcllib/Makefile
> csw/mgar/pkg/tcllib/branches/
> csw/mgar/pkg/tcllib/tags/
> csw/mgar/pkg/tcllib/trunk/
> csw/mgar/pkg/tcllib/trunk/Makefile
> csw/mgar/pkg/tcllib/trunk/checksums
> csw/mgar/pkg/tcllib/trunk/files/
> csw/mgar/pkg/tcllib/trunk/files/0001-csw-path-changes.patch
> csw/mgar/pkg/tcllib/trunk/files/0002-renamed-conflicting-man-pages.patch
>
> Copied: csw/mgar/pkg/tcllib/Makefile (from rev 15008, csw/mgar/pkg/template/Makefile)
> ===================================================================
> --- csw/mgar/pkg/tcllib/Makefile (rev 0)
> +++ csw/mgar/pkg/tcllib/Makefile 2011-07-11 09:48:15 UTC (rev 15036)
> @@ -0,0 +1,15 @@
> +# vim: ft=make ts=4 sw=4 noet
> +
> +default:
> + @echo "You are in the pkg/ directory."
> +
> +%:
> + $(MAKE) -C trunk $*
> +
> +paranoid-%:
> + $(MAKE) -C trunk $* || exit 2
> +
> +export BUILDLOG ?= $(shell pwd)/buildlog.txt
> +
> +report-%:
> + $(MAKE) -C trunk $* || echo " *** make $* in $$i failed ***" >> $(BUILDLOG)
>
>
> Property changes on: csw/mgar/pkg/tcllib/trunk
> ___________________________________________________________________
> Added: svn:ignore
> + cookies
> download
> work
>
>
> Added: svn:externals
> + gar https://gar.svn.sourceforge.net/svnroot/gar/csw/mgar/gar/v2
>
>
> Added: csw/mgar/pkg/tcllib/trunk/Makefile
> ===================================================================
> --- csw/mgar/pkg/tcllib/trunk/Makefile (rev 0)
> +++ csw/mgar/pkg/tcllib/trunk/Makefile 2011-07-11 09:48:15 UTC (rev 15036)
> @@ -0,0 +1,43 @@
> +# $Id$
> +# TODO (release-critical prefixed with !, non release-critical with *)
> +#
> +NAME = tcllib
> +VERSION = 1.13
> +GARTYPE = v2
> +CATEGORIES = lang
> +ARCHALL_CSWtcllib = 1
> +LICENSE = license.terms
> +
> +DESCRIPTION = Standard Tcl library, collection of common utility functions and modules
> +define BLURB
> +endef
> +
> +MASTER_SITES = $(SF_MIRRORS)
> +DISTFILES = $(DISTNAME).tar.gz
> +PATCHFILES = 0001-csw-path-changes.patch 0002-renamed-conflicting-man-pages.patch
> +
> +# comment contains "/usr/share/misc/magic.mime"
> +CHECKPKG_OVERRIDES_CSWtcllib += file-with-bad-content|/usr/share|root/opt/csw/lib/tcllib1.13/fumagic/filetypes.tcl
> +CHECKPKG_OVERRIDES_CSWtcllib += file-with-bad-content|/usr/share|root/opt/csw/lib/tcllib1.13/fumagic/mimetypes.tcl
> +
> +# list of shells containing "/usr/local/bin/bash" and others
> +CHECKPKG_OVERRIDES_CSWtcllib += file-with-bad-content|/usr/local|root/opt/csw/lib/tcllib1.13/fumagic/filetypes.tcl
> +CHECKPKG_OVERRIDES_CSWtcllib += file-with-bad-content|/usr/local|root/opt/csw/lib/tcllib1.13/fumagic/mimetypes.tcl
Probably this should be adjusted to /opt/csw/bin/bash ?
> +
> +# comment contains "/usr/share/misc/file/magic"
> +CHECKPKG_OVERRIDES_CSWtcllib += file-with-bad-content|/usr/share|root/opt/csw/lib/tcllib1.13/fumagic/cfront.tcl
> +
> +# File name regex to get notifications about upstream software releases
> +# NOTE: Use this only if the automatic regex creation
> +# does not work for your package
> +# UFILES_REGEX = $(NAME)-(\d+(?:\.\d+)*).tar.gz
> +
> +# If the url used to check for software update is different of MASTER_SITES, then
> +# uncomment the next line. Otherwise it is set by default to the value of MASTER_SITES
> +# UPSTREAM_MASTER_SITES =
> +
> +# CONFIGURE_ARGS = $(DIRPATHS)
> +CONFIGURE=./configure --prefix=/opt/csw
This has no effect. Probably you meant this?
CONFIGURE_ARGS = --prefix=$(prefix)
> +
> +include gar/category.mk
> +
>
>
> Property changes on: csw/mgar/pkg/tcllib/trunk/Makefile
> ___________________________________________________________________
> Added: svn:keywords
> + Id
>
> Added: csw/mgar/pkg/tcllib/trunk/checksums
> ===================================================================
> --- csw/mgar/pkg/tcllib/trunk/checksums (rev 0)
> +++ csw/mgar/pkg/tcllib/trunk/checksums 2011-07-11 09:48:15 UTC (rev 15036)
> @@ -0,0 +1 @@
> +5bc9567b3a61884716a908d5295d7105 tcllib-1.13.tar.gz
>
> Added: csw/mgar/pkg/tcllib/trunk/files/0001-csw-path-changes.patch
> ===================================================================
> --- csw/mgar/pkg/tcllib/trunk/files/0001-csw-path-changes.patch (rev 0)
> +++ csw/mgar/pkg/tcllib/trunk/files/0001-csw-path-changes.patch 2011-07-11 09:48:15 UTC (rev 15036)
> @@ -0,0 +1,75 @@
> +From 9cc0fd54cf707a756de8606c08eb315e465659da Mon Sep 17 00:00:00 2001
> +From: Kester Habermann <kester at opencsw.org>
> +Date: Mon, 11 Jul 2011 11:15:59 +0200
> +Subject: [PATCH] csw path changes
> +
> +---
> + modules/doctools/docidx.man | 4 ++--
> + modules/doctools/doctoc.man | 4 ++--
> + modules/doctools/doctools.man | 4 ++--
> + modules/ncgi/ncgi.man | 2 +-
> + 4 files changed, 7 insertions(+), 7 deletions(-)
> +
> +diff --git a/modules/doctools/docidx.man b/modules/doctools/docidx.man
> +index f6b19b8..aa7571a 100644
> +--- a/modules/doctools/docidx.man
> ++++ b/modules/doctools/docidx.man
> +@@ -301,8 +301,8 @@ through the command [cmd ::doctools::idx::search].
> + It contains initially one path, the subdirectory [file mpformats] of
> + the directory the package itself is located in. In other words, if the
> + package implementation [file docidx.tcl] is installed in the directory
> +-[file /usr/local/lib/tcllib/doctools] then it will by default search
> +-the directory [file /usr/local/lib/tcllib/doctools/mpformats] for
> ++[file /opt/csw/lib/tcllib1.13/doctools] then it will by default search
> ++the directory [file /opt/csw/lib/tcllib1.13/doctools/mpformats] for
> + format implementations.
> +
> + [enum]
> +diff --git a/modules/doctools/doctoc.man b/modules/doctools/doctoc.man
> +index d09a5ef..9e5a0a8 100644
> +--- a/modules/doctools/doctoc.man
> ++++ b/modules/doctools/doctoc.man
> +@@ -301,8 +301,8 @@ through the command [cmd ::doctools::toc::search].
> + It contains initially one path, the subdirectory [file mpformats] of
> + the directory the package itself is located in. In other words, if the
> + package implementation [file doctoc.tcl] is installed in the directory
> +-[file /usr/local/lib/tcllib/doctools] then it will by default search
> +-the directory [file /usr/local/lib/tcllib/doctools/mpformats] for
> ++[file /opt/csw/lib/tcllib1.13/doctools] then it will by default search
> ++the directory [file /opt/csw/lib/tcllib1.13/doctools/mpformats] for
> + format implementations.
> +
> + [enum]
> +diff --git a/modules/doctools/doctools.man b/modules/doctools/doctools.man
> +index 9c2c139..aeb4370 100644
> +--- a/modules/doctools/doctools.man
> ++++ b/modules/doctools/doctools.man
> +@@ -381,10 +381,10 @@ It contains initially one path, the subdirectory [file mpformats] of
> + the directory the package itself is located in.
> +
> + In other words, if the package implementation [file doctools.tcl] is
> +-installed in the directory [file /usr/local/lib/tcllib/doctools] then
> ++installed in the directory [file /opt/csw/lib/tcllib1.13/doctools] then
> + it will by default search the
> +
> +-directory [file /usr/local/lib/tcllib/doctools/mpformats] for format
> ++directory [file /opt/csw/lib/tcllib1.13/doctools/mpformats] for format
> + implementations.
> +
> + [enum]
> +diff --git a/modules/ncgi/ncgi.man b/modules/ncgi/ncgi.man
> +index 4b24de7..155b861 100644
> +--- a/modules/ncgi/ncgi.man
> ++++ b/modules/ncgi/ncgi.man
> +@@ -311,7 +311,7 @@ Name: <input type="text" name="filedesc"><br>
> + </html>
> +
> + TCL: upload.cgi
> +-#!/usr/local/bin/tclsh
> ++#!/opt/csw/bin/tclsh
> +
> + ::ncgi::parse
> + set filedata [::ncgi::value filedata]
> +--
> +1.7.6
> +
>
> Added: csw/mgar/pkg/tcllib/trunk/files/0002-renamed-conflicting-man-pages.patch
> ===================================================================
> --- csw/mgar/pkg/tcllib/trunk/files/0002-renamed-conflicting-man-pages.patch (rev 0)
> +++ csw/mgar/pkg/tcllib/trunk/files/0002-renamed-conflicting-man-pages.patch 2011-07-11 09:48:15 UTC (rev 15036)
> @@ -0,0 +1,1733 @@
> +From 999efdbce1f9d494841786e94cf0674b420e485f Mon Sep 17 00:00:00 2001
> +From: Kester Habermann <kester at opencsw.org>
> +Date: Mon, 11 Jul 2011 11:19:19 +0200
> +Subject: [PATCH 3/3] renamed conflicting man pages
> +
> +---
> + modules/doctools2idx/container.man | 305 -----------
> + modules/doctools2toc/container.man | 386 --------------
> + modules/struct/graph.man | 1007 ------------------------------------
> + 3 files changed, 0 insertions(+), 1698 deletions(-)
> + delete mode 100644 modules/doctools2idx/container.man
> + delete mode 100644 modules/doctools2toc/container.man
> + delete mode 100644 modules/struct/graph.man
> +
> +diff --git a/modules/doctools2idx/container.man b/modules/doctools2idx/container.man
> +deleted file mode 100644
> +index 09dae66..0000000
> +--- a/modules/doctools2idx/container.man
> ++++ /dev/null
> +@@ -1,305 +0,0 @@
> +-[comment {-*- tcl -*- doctools manpage}]
> +-[manpage_begin doctools::idx n 2]
> +-[copyright {2009 Andreas Kupries <andreas_kupries at users.sourceforge.net>}]
> +-[moddesc {Documentation tools}]
> +-[titledesc {Holding keyword indices}]
> +-[category {Documentation tools}]
> +-[require doctools::idx [opt 2]]
> +-[require Tcl 8.4]
> +-[require doctools::idx::structure]
> +-[require snit]
> +-[keywords {keyword index} index reference documentation manpage url]
> +-[keywords {docidx markup} markup conversion formatting generation plugin]
> +-[keywords json text nroff wiki {tcler's wiki} latex TMML HTML]
> +-[keywords parsing]
> +-[description]
> +-
> +-This package provides a class to contain and programmatically
> +-manipulate keyword indices
> +-
> +-[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 {Exporting keyword indices}], and
> +-[enum] [manpage {Importing 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 used to encode
> +-keyword indices as values see the section
> +-[sectref {Keyword index serialization format}].
> +-
> +-This is the only format directly known to this class. Conversions from
> +-and to any other format are handled by export and import manager
> +-objects. These may be attached to a container, but do not have to be,
> +-it is merely a convenience.
> +-
> +-
> +-[section Concepts] [include include/concept.inc]
> +-
> +-
> +-[section API]
> +-[subsection {Package commands}]
> +-
> +-[list_begin definitions]
> +-
> +-[call [cmd ::doctools::idx] [arg objectName]]
> +-
> +-This command creates a new container 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] 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 {key add}] [arg name]]
> +-
> +-This method adds the keyword [arg name] to the index. If the keyword
> +-is already known nothing is done. The result of the method is the
> +-empty string.
> +-
> +-
> +-[call [arg objectName] [method {key remove}] [arg name]]
> +-
> +-This method removes the keyword [arg name] from the index. If the
> +-keyword is already gone nothing is done. Any references for whom this
> +-keyword was the last association are removed as well. The result of
> +-the method is the empty string.
> +-
> +-
> +-[call [arg objectName] [method {key references}] [arg name]]
> +-
> +-This method returns a list containing the names of all references
> +-associated with the keyword [arg name]. An error is thrown in the
> +-keyword is not known to the index. The order of the references in the
> +-list is undefined.
> +-
> +-
> +-[call [arg objectName] [method keys]]
> +-
> +-This method returns a list containing the names of all keywords known
> +-to the index. The order of the keywords in the list is undefined.
> +-
> +-
> +-[call [arg objectName] [method {reference add}] [arg type] [arg key] [arg name] [arg label]]
> +-
> +-This method adds the reference [arg name] to the index and associates
> +-it with the keyword [arg key].
> +-
> +-The other two arguments hold the [arg type] and [arg label] of the
> +-reference, respectively.
> +-
> +-The type has to match the stored information, should the reference
> +-exist already, i.e. this information is immutable after the reference
> +-is known. The only way to change it is delete and recreate the
> +-reference.
> +-
> +-The label on the other hand is automatically updated to the value of
> +-the argument, overwriting any previously stored information.
> +-
> +-Should the reference exists already it is simply associated with the
> +-[arg key]. If that is true already as well nothing is done, but the
> +-[arg label] updated to the new value. The result of the method is the
> +-empty string.
> +-
> +-[para]
> +-
> +-The [arg type] argument has be to one of [const manpage] or [const url].
> +-
> +-
> +-[call [arg objectName] [method {reference remove}] [arg name]]
> +-
> +-The reference [arg name] is removed from the index. All associations
> +-with keywords are released and the relevant reference labels removed.
> +-The result of the method is the empty string.
> +-
> +-
> +-[call [arg objectName] [method {reference label}] [arg name]]
> +-
> +-This method returns the label associated with the reference
> +-[arg name]. An error is thrown if the reference is not known.
> +-
> +-
> +-[call [arg objectName] [method {reference keys}] [arg name]]
> +-
> +-This method returns a list containing the names of all keywords
> +-associated with the reference [arg name]. An error is thrown in the
> +-reference is not known to the index. The order of the keywords in the
> +-list is undefined.
> +-
> +-
> +-[call [arg objectName] [method {reference type}] [arg name]]
> +-
> +-This method returns the type of the reference [arg name]. An error is
> +-thrown in the reference is not known to the index.
> +-
> +-
> +-[call [arg objectName] [method references]]
> +-
> +-This method returns a list containing the names of all references
> +-known to the index. The order of the references in the list is
> +-undefined.
> +-
> +-
> +-[call [arg objectName] [method title]]
> +-
> +-Returns the currently defined title of the keyword index.
> +-
> +-
> +-[call [arg objectName] [method title] [arg text]]
> +-
> +-Sets the title of the keyword index to [arg text], and returns it as
> +-the result of the command.
> +-
> +-
> +-[call [arg objectName] [method label]]
> +-
> +-Returns the currently defined label of the keyword index.
> +-
> +-
> +-[call [arg objectName] [method label] [arg text]]
> +-
> +-Sets the label of the keyword index to [arg text], and returns it as
> +-the result of the command.
> +-
> +-
> +-[call [arg objectName] [method importer]]
> +-
> +-Returns the import manager object currently attached to the container,
> +-if any.
> +-
> +-
> +-[call [arg objectName] [method importer] [arg object]]
> +-
> +-Attaches the [arg object] as import manager to the container, and
> +-returns it as the result of the command.
> +-
> +-Note that the [arg object] is [emph not] put into ownership of the
> +-container. I.e., destruction of the container will [emph not] destroy
> +-the [arg object].
> +-
> +-[para]
> +-
> +-It is expected that [arg object] provides a method named
> +-[method {import text}] which takes a text and a format name, and
> +-returns the canonical serialization of the keyword index contained in
> +-the text, assuming the given format.
> +-
> +-
> +-[call [arg objectName] [method exporter]]
> +-
> +-Returns the export manager object currently attached to the container,
> +-if any.
> +-
> +-
> +-[call [arg objectName] [method exporter] [arg object]]
> +-
> +-Attaches the [arg object] as export manager to the container, and
> +-returns it as the result of the command.
> +-
> +-Note that the [arg object] is [emph not] put into ownership of the
> +-container. I.e., destruction of the container will [emph not] destroy
> +-the [arg object].
> +-
> +-[para]
> +-
> +-It is expected that [arg object] provides a method named
> +-[method {export object}] which takes the container and a format name,
> +-and returns a text encoding keyword index stored in the container, in
> +-the given format. It is further expected that the [arg object] will
> +-use the container's method [method serialize] to obtain the
> +-serialization of the keyword index from which to generate the text.
> +-
> +-
> +-[call [arg objectName] [method {deserialize =}] [arg data] [opt [arg format]]]
> +-
> +-This method replaces the contents of the index object with the index
> +-contained in the [arg data]. If no [arg format] was specified it is
> +-assumed to be the regular serialization of a keyword index.
> +-
> +-[para]
> +-
> +-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 container has no import
> +-manager attached to it.
> +-
> +-[para]
> +-
> +-The result of the method is the empty string.
> +-
> +-
> +-[call [arg objectName] [method {deserialize +=}] [arg data] [opt [arg format]]]
> +-
> +-This method behaves like [method {deserialize =}] in its essentials,
> +-except that it merges the keyword index in the [arg 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 index. The existing content is left unchanged in
> +-that case.
> +-
> +-[para]
> +-
> +-The result of the method is the empty string.
> +-
> +-
> +-[call [arg objectName] [method serialize] [opt [arg format]]]
> +-
> +-This method returns the keyword index contained in the object. If no
> +-[arg format] is not specified the returned result is the canonical
> +-serialization of its contents.
> +-
> +-[para]
> +-
> +-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.
> +-
> +-
> +-[list_end]
> +-
> +-
> +-[include include/serialization.inc]
> +-[vset CATEGORY doctools]
> +-[include ../doctools2base/include/feedback.inc]
> +-[manpage_end]
> +diff --git a/modules/doctools2toc/container.man b/modules/doctools2toc/container.man
> +deleted file mode 100644
> +index e28eee6..0000000
> +--- a/modules/doctools2toc/container.man
> ++++ /dev/null
> +@@ -1,386 +0,0 @@
> +-[comment {-*- tcl -*- doctools manpage}]
> +-[manpage_begin doctools::toc n 2]
> +-[copyright {2009 Andreas Kupries <andreas_kupries at users.sourceforge.net>}]
> +-[moddesc {Documentation tools}]
> +-[titledesc {Holding tables of contents}]
> +-[category {Documentation tools}]
> +-[require doctools::toc [opt 2]]
> +-[require Tcl 8.4]
> +-[require doctools::toc::structure]
> +-[require struct::tree]
> +-[require snit]
> +-[keywords {table of contents} table reference documentation]
> +-[keywords {doctoc markup} markup conversion formatting generation plugin]
> +-[keywords json text nroff wiki {tcler's wiki} latex TMML HTML]
> +-[keywords parsing]
> +-[description]
> +-
> +-This package provides a class to contain and programmatically
> +-manipulate tables of contents.
> +-
> +-[para]
> +-
> +-This is one of the three public pillars the management of tables of
> +-contents resides on. The other two pillars are
> +-
> +-[list_begin enum]
> +-[enum] [manpage {Exporting tables of contents}], and
> +-[enum] [manpage {Importing tables of contents}]
> +-[list_end]
> +-
> +-[para]
> +-
> +-For information about the [sectref 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
> +-[sectref {ToC serialization format}].
> +-
> +-This is the only format directly known to this class. Conversions from
> +-and to any other format are handled by export and import manager
> +-objects. These may be attached to a container, but do not have to be,
> +-it is merely a convenience.
> +-
> +-
> +-[section Concepts] [include include/concept.inc]
> +-
> +-
> +-[section API]
> +-[subsection {Package commands}]
> +-
> +-[list_begin definitions]
> +-
> +-[call [cmd ::doctools::toc] [arg objectName]]
> +-
> +-This command creates a new container 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::toc] 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 {+ reference}] [arg id] [arg label] [arg docid] [arg desc]]
> +-
> +-This method adds a new reference element to the table of contents,
> +-under the element specified via its handle [arg id]. This parent
> +-element has to be a division element, or the root. An error is thrown
> +-otherwise.
> +-
> +-The new element will be externally identified by its [arg label],
> +-which has to be be unique within the parent element. An error is
> +-thrown otherwise.
> +-
> +-[para]
> +-
> +-As a reference element it will refer to a document identified by the
> +-symbolic [arg 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 [arg desc].
> +-
> +-[para]
> +-
> +-The result of the method is the handle (id) of the new element.
> +-
> +-
> +-[call [arg objectName] [method {+ division}] [arg id] [arg label] [opt [arg docid]]]
> +-
> +-This method adds a new division element to the table of contents,
> +-under the element specified via its handle [arg id]. This parent
> +-element has to be a division element, or the root. An error is thrown
> +-otherwise.
> +-
> +-The new element will be externally identified by its [arg label],
> +-which has to be be unique within the parent element. An error is
> +-thrown otherwise.
> +-
> +-[para]
> +-
> +-As a division element it is can refer to a document, identified by the
> +-symbolic [arg docid], but may choose not to.
> +-
> +-[para]
> +-
> +-The result of the method is the handle (id) of the new element.
> +-
> +-
> +-[call [arg objectName] [method remove] [arg id]]
> +-
> +-This method removes the element identified by the handle [arg 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.
> +-
> +-[para]
> +-
> +-The result of the method is the empty string.
> +-
> +-
> +-[call [arg objectName] [method up] [arg id]]
> +-
> +-This method returns the handle of the parent for the element
> +-identified by its handle [arg id], or the empty string if [arg id]
> +-refered to the root element.
> +-
> +-
> +-[call [arg objectName] [method next] [arg id]]
> +-
> +-This method returns the handle of the right sibling for the element
> +-identified by its handle [arg id], or the handle of the parent if the
> +-element has no right sibling, or the empty string if [arg id] refered
> +-to the root element.
> +-
> +-
> +-
> +-[call [arg objectName] [method prev] [arg id]]
> +-
> +-This method returns the handle of the left sibling for the element
> +-identified by its handle [arg id], or the handle of the parent if the
> +-element has no left sibling, or the empty string if [arg id] refered
> +-to the root element.
> +-
> +-
> +-[call [arg objectName] [method child] [arg id] [arg label] [opt [arg ...]]]
> +-
> +-This method returns the handle of a child of the element identified by
> +-its handle [arg id]. The child itself is identified by a series of
> +-labels.
> +-
> +-
> +-[call [arg objectName] [method element] [opt [arg ...]]]
> +-
> +-This method returns the handle of the element identified by a series
> +-of labels, starting from the root of the table of contents. The series
> +-of labels is allowed to be empty, in which case the handle of the root
> +-element is returned.
> +-
> +-
> +-[call [arg objectName] [method children] [arg id]]
> +-
> +-This method returns a list containing the handles of all children of
> +-the element identified by the handle [arg id], from first to last, in
> +-that order.
> +-
> +-
> +-[call [arg objectName] [method type] [arg id]]
> +-
> +-This method returns the type of the element, either [const reference],
> +-or [const division].
> +-
> +-
> +-[call [arg objectName] [method full-label] [arg id]]
> +-
> +-This method is the complement of the method [method element],
> +-converting the handle [arg id] of an element into a list of labels
> +-full identifying the element within the whole table of contents.
> +-
> +-
> +-[call [arg objectName] [method elabel] [arg id] [opt [arg newlabel]]]
> +-
> +-This method queries and/or changes the label of the element identified
> +-by the handle [arg id]. If the argument [arg 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.
> +-
> +-[para]
> +-
> +-If the label is changed the new label has to be unique within the
> +-containing division, or an error is thrown.
> +-
> +-[para]
> +-
> +-Further, of the [arg id] refers to the root element of the table of
> +-contents, then using this method is equivalent to using the method
> +-[arg label], i.e. it is accessing the global label for the whole
> +-table.
> +-
> +-
> +-[call [arg objectName] [method description] [arg id] [opt [arg newdesc]]]
> +-
> +-This method queries and/or changes the description of the element
> +-identified by the handle [arg id]. If the argument [arg newdesc] is
> +-present then the description is changed to that value. Regardless of
> +-this, the result of the method is the current value of the description.
> +-
> +-[para]
> +-
> +-The element this method operates on has to be a reference element, or
> +-an error will be thrown.
> +-
> +-
> +-[call [arg objectName] [method document] [arg id] [opt [arg newdocid]]]
> +-
> +-This method queries and/or changes the document reference of the
> +-element identified by the handle [arg id].
> +-
> +-If the argument [arg 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.
> +-
> +-[para]
> +-
> +-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 reference, and this can
> +-happen only for division elements.
> +-
> +-
> +-[call [arg objectName] [method title]]
> +-
> +-Returns the currently defined title of the table of contents.
> +-
> +-
> +-[call [arg objectName] [method title] [arg text]]
> +-
> +-Sets the title of the table of contents to [arg text], and returns it as
> +-the result of the command.
> +-
> +-
> +-[call [arg objectName] [method label]]
> +-
> +-Returns the currently defined label of the table of contents.
> +-
> +-
> +-[call [arg objectName] [method label] [arg text]]
> +-
> +-Sets the label of the table of contents to [arg text], and returns it as
> +-the result of the command.
> +-
> +-
> +-[call [arg objectName] [method importer]]
> +-
> +-Returns the import manager object currently attached to the container,
> +-if any.
> +-
> +-
> +-[call [arg objectName] [method importer] [arg object]]
> +-
> +-Attaches the [arg object] as import manager to the container, and
> +-returns it as the result of the command.
> +-
> +-Note that the [arg object] is [emph not] put into ownership of the
> +-container. I.e., destruction of the container will [emph not] destroy
> +-the [arg object].
> +-
> +-[para]
> +-
> +-It is expected that [arg object] provides a method named
> +-[method {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.
> +-
> +-
> +-[call [arg objectName] [method exporter]]
> +-
> +-Returns the export manager object currently attached to the container,
> +-if any.
> +-
> +-
> +-[call [arg objectName] [method exporter] [arg object]]
> +-
> +-Attaches the [arg object] as export manager to the container, and
> +-returns it as the result of the command.
> +-
> +-Note that the [arg object] is [emph not] put into ownership of the
> +-container. I.e., destruction of the container will [emph not] destroy
> +-the [arg object].
> +-
> +-[para]
> +-
> +-It is expected that [arg object] provides a method named
> +-[method {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 [arg object] will
> +-use the container's method [method serialize] to obtain the
> +-serialization of the table of contents from which to generate the text.
> +-
> +-
> +-[call [arg objectName] [method {deserialize =}] [arg data] [opt [arg format]]]
> +-
> +-This method replaces the contents of the table object with the table
> +-contained in the [arg data]. If no [arg format] was specified it is
> +-assumed to be the regular serialization of a table of contents.
> +-
> +-[para]
> +-
> +-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 container has no import
> +-manager attached to it.
> +-
> +-[para]
> +-
> +-The result of the method is the empty string.
> +-
> +-
> +-[call [arg objectName] [method {deserialize +=}] [arg data] [opt [arg format]]]
> +-
> +-This method behaves like [method {deserialize =}] in its essentials,
> +-except that it merges the table of contents in the [arg 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.
> +-
> +-[para]
> +-
> +-The result of the method is the empty string.
> +-
> +-
> +-[call [arg objectName] [method serialize] [opt [arg format]]]
> +-
> +-This method returns the table of contents contained in the object. If no
> +-[arg format] is not specified the returned result is the canonical
> +-serialization of its contents.
> +-
> +-[para]
> +-
> +-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.
> +-
> +-
> +-[list_end]
> +-
> +-
> +-[include include/serialization.inc]
> +-[vset CATEGORY doctools]
> +-[include ../doctools2base/include/feedback.inc]
> +-[manpage_end]
> +diff --git a/modules/struct/graph.man b/modules/struct/graph.man
> +deleted file mode 100644
> +index 5cf99a6..0000000
> +--- a/modules/struct/graph.man
> ++++ /dev/null
> +@@ -1,1007 +0,0 @@
> +-[comment {-*- tcl -*-}]
> +-[manpage_begin struct::graph n 2.4]
> +-[copyright {2002-2009 Andreas Kupries <andreas_kupries at users.sourceforge.net>}]
> +-[moddesc {Tcl Data Structures}]
> +-[titledesc {Create and manipulate directed graph objects}]
> +-[category {Data structures}]
> +-[require Tcl 8.4]
> +-[require struct::graph [opt 2.4]]
> +-[require struct::list [opt 1.5]]
> +-[require struct::set [opt 2.2.3]]
> +-[description]
> +-[para]
> +-
> +-
> +-A directed graph is a structure containing two collections of
> +-elements, called [term nodes] and [term arcs] respectively, together
> +-with a relation ("connectivity") that places a general structure upon
> +-the nodes and arcs.
> +-
> +-[para]
> +-
> +-Each arc is connected to two nodes, one of which is called the
> +-
> +-[term source] and the other the [term target]. This imposes a
> +-direction upon the arc, which is said to go from the source to the
> +-target. It is allowed that source and target of an arc are the same
> +-node. Such an arc is called a [term loop].
> +-
> +-Whenever a node is either the source or target of an arc both are said
> +-to be [term adjacent]. This extends into a relation between nodes,
> +-i.e. if two nodes are connected through at least one arc they are said
> +-to be [term adjacent] too.
> +-
> +-[para]
> +-
> +-Each node can be the source and target for any number of arcs. The
> +-former are called the [term {outgoing arcs}] of the node, the latter
> +-the [term {incoming arcs}] of the node. The number of arcs in either
> +-set is called the [term in-degree] resp. the [term out-degree] of the
> +-node.
> +-
> +-[para]
> +-
> +-In addition to maintaining the node and arc relationships, this graph
> +-implementation allows any number of named [term attributes] to be
> +-associated with the graph itself, and each node or arc.
> +-
> +-[para]
> +-
> +-[emph Note:] The major version of the package [package struct] has
> +-been changed to version 2.0, due to backward incompatible changes in
> +-the API of this module. Please read the section
> +-
> +-[sectref {Changes for 2.0}] for a full list of all changes,
> +-incompatible and otherwise.
> +-
> +-[para]
> +-
> +-[emph Note:] A C-implementation of the command can be had from the
> +-location [uri http://www.purl.org/NET/schlenker/tcl/cgraph]. See also
> +-[uri http://wiki.tcl.tk/cgraph]. This implementation uses a bit less
> +-memory than the tcl version provided here directly, and is faster. Its
> +-support is limited to versions of the package before 2.0.
> +-
> +-[para]
> +-
> +-As of version 2.2 of this package a critcl based C implementation is
> +-available from here as well. This implementation however requires Tcl
> +-8.4 to run.
> +-
> +-[para]
> +-
> +-The main command of the package is:
> +-
> +-[list_begin definitions]
> +-
> +-[call [cmd ::struct::graph] [opt [arg graphName]] \
> +- [opt "[const =]|[const :=]|[const as]|[const deserialize] [arg source]"]]
> +-
> +-The command creates a new graph object with an associated global Tcl
> +-command whose name is [arg graphName]. This command may be used to
> +-invoke various operations on the graph. It has the following general
> +-form:
> +-
> +-[list_begin definitions]
> +-[call [cmd graphName] [arg option] [opt [arg "arg arg ..."]]]
> +-
> +-[arg Option] and the [arg arg]s determine the exact behavior of the
> +-command.
> +-
> +-[list_end]
> +-[para]
> +-
> +-If [arg graphName] is not specified a unique name will be generated by
> +-the package itself. If a [arg source] is specified the new graph will
> +-be initialized to it. For the operators [const =], [const :=], and
> +-[const as] the [arg source] argument is interpreted as the name of
> +-another graph object, and the assignment operator [method =] will be
> +-executed. For the operator [const deserialize] the [arg source] is a
> +-serialized graph object and [method deserialize] will be executed.
> +-
> +-[para]
> +-
> +-In other words
> +-[para]
> +-[example {
> +- ::struct::graph mygraph = b
> +-}]
> +-[para]
> +-is equivalent to
> +-[para]
> +-[example {
> +- ::struct::graph mygraph
> +- mygraph = b
> +-}]
> +-[para]
> +-and
> +-[para]
> +-[example {
> +- ::struct::graph mygraph deserialize $b
> +-}]
> +-[para]
> +-is equivalent to
> +-[para]
> +-[example {
> +- ::struct::graph mygraph
> +- mygraph deserialize $b
> +-}]
> +-
> +-[list_end]
> +-
> +-[para]
> +-
> +-The following commands are possible for graph objects:
> +-
> +-[list_begin definitions]
> +-
> +-[call [arg graphName] [method =] [arg sourcegraph]]
> +-
> +-This is the [term assignment] operator for graph objects. It copies
> +-the graph contained in the graph object [arg sourcegraph] over the
> +-graph data in [arg graphName]. The old contents of [arg graphName] are
> +-deleted by this operation.
> +-
> +-[para]
> +-
> +-This operation is in effect equivalent to
> +-[para]
> +-[example_begin]
> +- [arg graphName] [method deserialize] [lb][arg sourcegraph] [method serialize][rb]
> +-[example_end]
> +-
> +-[para]
> +-
> +-The operation assumes that the [arg sourcegraph] provides the method
> +-[method serialize] and that this method returns a valid graph
> +-serialization.
> +-
> +-
> +-[call [arg graphName] [method -->] [arg destgraph]]
> +-
> +-This is the [term {reverse assignment}] operator for graph objects. It
> +-copies the graph contained in the graph object [arg graphName] over
> +-the graph data in the object [arg destgraph].
> +-
> +-The old contents of [arg destgraph] are deleted by this operation.
> +-
> +-[para]
> +-
> +-This operation is in effect equivalent to
> +-[para]
> +-[example_begin]
> +- [arg destgraph] [method deserialize] [lb][arg graphName] [method serialize][rb]
> +-[example_end]
> +-
> +-[para]
> +-
> +-The operation assumes that the [arg destgraph] provides the method
> +-[method deserialize] and that this method takes a graph serialization.
> +-
> +-
> +-[call [arg graphName] [method append] [arg key] [arg value]]
> +-
> +-Appends a [arg value] to one of the keyed values associated with the graph.
> +-Returns the new value given to the attribute [arg key].
> +-
> +-
> +-[call [arg graphName] [method deserialize] [arg serialization]]
> +-
> +-This is the complement to [method serialize]. It replaces the graph
> +-data in [arg graphName] with the graph described by the
> +-[arg serialization] value. The old contents of [arg graphName] are
> +-deleted by this operation.
> +-
> +-
> +-[call [arg graphName] [method destroy]]
> +-
> +-Destroys the graph, including its storage space and associated command.
> +-
> +-
> +-[call [arg graphName] [method {arc append}] [arg arc] [arg key] [arg value]]
> +-
> +-Appends a [arg value] to one of the keyed values associated with an
> +-[arg arc]. Returns the new value given to the attribute [arg key].
> +-
> +-
> +-[call [arg graphName] [method {arc attr}] [arg key]]
> +-[call [arg graphName] [method {arc attr}] [arg key] [option -arcs] [arg list]]
> +-[call [arg graphName] [method {arc attr}] [arg key] [option -glob] [arg globpattern]]
> +-[call [arg graphName] [method {arc attr}] [arg key] [option -regexp] [arg repattern]]
> +-
> +-This method retrieves the value of the attribute named [arg key], for
> +-all arcs in the graph (matching the restriction specified via one of
> +-the possible options) and having the specified attribute.
> +-
> +-[para]
> +-
> +-The result is a dictionary mapping from arc names to the value of
> +-attribute [arg key] at that arc.
> +-
> +-Arcs not having the attribute [arg key], or not passing a
> +-specified restriction, are not listed in the result.
> +-
> +-[para]
> +-
> +-The possible restrictions are:
> +-
> +-[list_begin options]
> +-[opt_def -arcs]
> +-
> +-The value is a list of arcs. Only the arcs mentioned in this list
> +-are searched for the attribute.
> +-
> +-[opt_def -glob]
> +-
> +-The value is a glob pattern. Only the arcs in the graph whose names
> +-match this pattern are searched for the attribute.
> +-
> +-[opt_def -regexp]
> +-
> +-The value is a regular expression. Only the arcs in the graph whose
> +-names match this pattern are searched for the attribute.
> +-
> +-[list_end]
> +-[para]
> +-
> +-
> +-[call [arg graphName] [method {arc delete}] [arg arc] [opt "[arg arc] ..."]]
> +-
> +-Remove the specified arcs from the graph.
> +-
> +-
> +-[call [arg graphName] [method {arc exists}] [arg arc]]
> +-
> +-Return true if the specified [arg arc] exists in the graph.
> +-
> +-
> +-[call [arg graphName] [method {arc flip}] [arg arc]]
> +-
> +-Reverses the direction of the named [arg arc], i.e. the source and
> +-target nodes of the arc are exchanged with each other.
> +-
> +-
> +-[call [arg graphName] [method {arc get}] [arg arc] [arg key]]
> +-
> +-Returns the value associated with the key [arg key] for the [arg arc].
> +-
> +-
> +-[call [arg graphName] [method {arc getall}] [arg arc] [opt [arg pattern]]]
> +-
> +-Returns a dictionary (suitable for use with [lb][cmd {array set}][rb])
> +-for the [arg arc].
> +-
> +-If the [arg pattern] is specified only the attributes whose names
> +-match the pattern will be part of the returned dictionary. The pattern
> +-is a [cmd glob] pattern.
> +-
> +-
> +-[call [arg graphName] [method {arc getunweighted}]]
> +-
> +-Returns a list containing the names of all arcs in the graph which
> +-have no weight associated with them.
> +-
> +-
> +-[call [arg graphName] [method {arc getweight}] [arg arc]]
> +-
> +-Returns the weight associated with the [arg arc]. Throws an error if
> +-the arc has no weight associated with it.
> +-
> +-
> +-[call [arg graphName] [method {arc keys}] [arg arc] [opt [arg pattern]]]
> +-
> +-Returns a list of keys for the [arg arc].
> +-
> +-If the [arg pattern] is specified only the attributes whose names
> +-match the pattern will be part of the returned list. The pattern is a
> +-[cmd glob] pattern.
> +-
> +-
> +-[call [arg graphName] [method {arc keyexists}] [arg arc] [arg key]]
> +-
> +-Return true if the specified [arg key] exists for the [arg arc].
> +-
> +-
> +-[call [arg graphName] [method {arc insert}] [arg start] [arg end] [opt [arg child]]]
> +-
> +-Insert an arc named [arg child] into the graph beginning at the node
> +-[arg start] and ending at the node [arg end]. If the name of the new
> +-arc is not specified the system will generate a unique name of the
> +-form [emph arc][arg x].
> +-
> +-
> +-[call [arg graphName] [method {arc lappend}] [arg arc] [arg key] [arg value]]
> +-
> +-Appends a [arg value] (as a list) to one of the keyed values
> +-associated with an [arg arc]. Returns the new value given to the
> +-attribute [arg key].
> +-
> +-
> +-[call [arg graphName] [method {arc rename}] [arg arc] [arg newname]]
> +-
> +-Renames the arc [arg arc] to [arg newname]. An error is thrown if
> +-either the arc does not exist, or a arc with name [arg newname] does
> +-exist. The result of the command is the new name of the arc.
> +-
> +-
> +-[call [arg graphName] [method {arc set}] [arg arc] [arg key] [opt [arg value]]]
> +-
> +-Set or get one of the keyed values associated with an arc.
> +-
> +-An arc may have any number of keyed values associated with it.
> +-If [arg value] is not specified, this command returns the current value assigned to the key;
> +-if [arg value] is specified, this command assigns that value to the key, and returns
> +-that value.
> +-
> +-
> +-[call [arg graphName] [method {arc setunweighted}] [opt [arg weight]]]
> +-
> +-Sets the weight of all arcs without a weight to [arg weight]. Returns
> +-the empty string as its result. If not present [arg weight] defaults
> +-to [const 0].
> +-
> +-
> +-[call [arg graphName] [method {arc setweight}] [arg arc] [arg weight]]
> +-
> +-Sets the weight of the [arg arc] to [arg weight]. Returns [arg weight].
> +-
> +-
> +-[call [arg graphName] [method {arc unsetweight}] [arg arc]]
> +-
> +-Removes the weight of the [arg arc], if present. Does nothing
> +-otherwise. Returns the empty string.
> +-
> +-
> +-[call [arg graphName] [method {arc hasweight}] [arg arc]]
> +-
> +-Determines if the [arg arc] has a weight associated with it. The
> +-result is a boolean value, [const True] if a weight is defined, and
> +-[const False] otherwise.
> +-
> +-
> +-[call [arg graphName] [method {arc source}] [arg arc]]
> +-
> +-Return the node the given [arg arc] begins at.
> +-
> +-
> +-[call [arg graphName] [method {arc target}] [arg arc]]
> +-
> +-Return the node the given [arg arc] ends at.
> +-
> +-
> +-[call [arg graphName] [method {arc nodes}] [arg arc]]
> +-
> +-Return the nodes the given [arg arc] begins and ends at,
> +-as a two-element list.
> +-
> +-
> +-[call [arg graphName] [method {arc move-source}] [arg arc] [arg newsource]]
> +-
> +-Changes the source node of the arc to [arg newsource]. It can be said
> +-that the arc rotates around its target node.
> +-
> +-
> +-[call [arg graphName] [method {arc move-target}] [arg arc] [arg newtarget]]
> +-
> +-Changes the target node of the arc to [arg newtarget]. It can be said
> +-that the arc rotates around its source node.
> +-
> +-
> +-[call [arg graphName] [method {arc move}] [arg arc] [arg newsource] [arg newtarget]]
> +-
> +-Changes both source and target nodes of the arc to [arg newsource],
> +-and [arg newtarget] resp.
> +-
> +-
> +-[call [arg graphName] [method {arc unset}] [arg arc] [arg key]]
> +-
> +-Remove a keyed value from the arc [arg arc]. The method will do
> +-nothing if the [arg key] does not exist.
> +-
> +-
> +-[call [arg graphName] [method {arc weights}]]
> +-
> +-Returns a dictionary whose keys are the names of all arcs which have a
> +-weight associated with them, and the values are these weights.
> +-
> +-
> +-[call [arg graphName] [method arcs] [opt "-key [arg key]"] [opt "-value [arg value]"] [opt "-filter [arg cmdprefix]"] [opt "-in|-out|-adj|-inner|-embedding [arg {node node...}]"]]
> +-
> +-Returns a list of arcs in the graph. If no restriction is specified a
> +-list containing all arcs is returned. Restrictions can limit the list
> +-of returned arcs based on the nodes that are connected by the arc, on
> +-the keyed values associated with the arc, or both. A general filter
> +-command can be used as well. The restrictions that involve connected
> +-nodes take a variable number of nodes as argument, specified after the
> +-name of the restriction itself.
> +-
> +-[para]
> +-
> +-The restrictions imposed by either [option -in], [option -out],
> +-[option -adj], [option -inner], or [option -embedded] are applied
> +-first. Specifying more than one of them is illegal.
> +-
> +-[para]
> +-
> +-After that the restrictions set via [option -key] (and
> +-[option -value]) are applied. Specifying more than one [option -key]
> +-(and [option -value]) is illegal. Specifying [option -value] alone,
> +-without [option -key] is illegal as well.
> +-
> +-[para]
> +-
> +-Any restriction set through [option -filter] is applied
> +-last. Specifying more than one [option -filter] is illegal.
> +-
> +-[para]
> +-
> +-Coming back to the restrictions based on a set of nodes, the command
> +-recognizes the following switches:
> +-
> +-[list_begin definitions]
> +-[def [option -in]]
> +-
> +-Return a list of all arcs whose target is one of the nodes in the set
> +-of nodes. I.e. it computes the union of all incoming arcs of the nodes
> +-in the set.
> +-
> +-[def [option -out]]
> +-
> +-Return a list of all arcs whose source is one of the nodes in the set
> +-of nodes. I.e. it computes the union of all outgoing arcs of the nodes
> +-in the set.
> +-
> +-[def [option -adj]]
> +-
> +-Return a list of all arcs adjacent to at least one of the nodes in the
> +-set. This is the union of the nodes returned by [option -in] and
> +-[option -out].
> +-
> +-[def [option -inner]]
> +-
> +-Return a list of all arcs which are adjacent to two of the nodes in
> +-the set. This is the set of arcs in the subgraph spawned by the
> +-specified nodes.
> +-
> +-[def [option -embedding]]
> +-
> +-Return a list of all arcs adjacent to exactly one of the nodes in the
> +-set. This is the set of arcs connecting the subgraph spawned by the
> +-specified nodes to the rest of the graph.
> +-
> +-[def "[option -key] [arg key]"]
> +-
> +-Limit the list of arcs that are returned to those arcs that have an
> +-associated key [arg key].
> +-
> +-[def "[option -value] [arg value]"]
> +-
> +-This restriction can only be used in combination with
> +-
> +-[option -key]. It limits the list of arcs that are returned to those
> +-arcs whose associated key [arg key] has the value [arg value].
> +-
> +-
> +-[def "[option -filter] [arg cmdrefix]"]
> +-
> +-Limit the list of arcs that are returned to those arcs that pass the
> +-test. The command in [arg cmdprefix] is called with two arguments, the
> +-name of the graph object, and the name of the arc in question. It is
> +-executed in the context of the caller and has to return a boolean
> +-value. Arcs for which the command returns [const false] are removed
> +-from the result list before it is returned to the caller.
> +-
> +-[list_end]
> +-
> +-
> +-[call [arg graphName] [method lappend] [arg key] [arg value]]
> +-
> +-Appends a [arg value] (as a list) to one of the keyed values
> +-associated with the graph. Returns the new value given to the
> +-attribute [arg key].
> +-
> +-
> +-[call [arg graphName] [method {node append}] [arg node] [arg key] [arg value]]
> +-
> +-Appends a [arg value] to one of the keyed values associated with an
> +-[arg node]. Returns the new value given to the attribute [arg key].
> +-
> +-
> +-[call [arg graphName] [method {node attr}] [arg key]]
> +-[call [arg graphName] [method {node attr}] [arg key] [option -nodes] [arg list]]
> +-[call [arg graphName] [method {node attr}] [arg key] [option -glob] [arg globpattern]]
> +-[call [arg graphName] [method {node attr}] [arg key] [option -regexp] [arg repattern]]
> +-
> +-This method retrieves the value of the attribute named [arg key], for
> +-all nodes in the graph (matching the restriction specified via one of
> +-the possible options) and having the specified attribute.
> +-
> +-[para]
> +-
> +-The result is a dictionary mapping from node names to the value of
> +-attribute [arg key] at that node.
> +-
> +-Nodes not having the attribute [arg key], or not passing a
> +-specified restriction, are not listed in the result.
> +-
> +-[para]
> +-
> +-The possible restrictions are:
> +-
> +-[list_begin options]
> +-[opt_def -nodes]
> +-
> +-The value is a list of nodes. Only the nodes mentioned in this list
> +-are searched for the attribute.
> +-
> +-[opt_def -glob]
> +-
> +-The value is a glob pattern. Only the nodes in the graph whose names
> +-match this pattern are searched for the attribute.
> +-
> +-[opt_def -regexp]
> +-
> +-The value is a regular expression. Only the nodes in the graph whose
> +-names match this pattern are searched for the attribute.
> +-
> +-[list_end]
> +-[para]
> +-
> +-
> +-[call [arg graphName] [method {node degree}] [opt -in|-out] [arg node]]
> +-
> +-Return the number of arcs adjacent to the specified [arg node]. If one
> +-of the restrictions [option -in] or [option -out] is given only the
> +-incoming resp. outgoing arcs are counted.
> +-
> +-
> +-[call [arg graphName] [method {node delete}] [arg node] [opt "[arg node]..."]]
> +-
> +-Remove the specified nodes from the graph. All of the nodes' arcs
> +-will be removed as well to prevent unconnected arcs.
> +-
> +-
> +-[call [arg graphName] [method {node exists}] [arg node]]
> +-
> +-Return true if the specified [arg node] exists in the graph.
> +-
> +-
> +-[call [arg graphName] [method {node get}] [arg node] [arg key]]
> +-
> +-Return the value associated with the key [arg key] for the [arg node].
> +-
> +-
> +-[call [arg graphName] [method {node getall}] [arg node] [opt [arg pattern]]]
> +-
> +-Returns a dictionary (suitable for use with [lb][cmd {array set}][rb])
> +-for the [arg node].
> +-
> +-If the [arg pattern] is specified only the attributes whose names
> +-match the pattern will be part of the returned dictionary. The pattern
> +-is a [cmd glob] pattern.
> +-
> +-
> +-[call [arg graphName] [method {node keys}] [arg node] [opt [arg pattern]]]
> +-
> +-Returns a list of keys for the [arg node].
> +-
> +-If the [arg pattern] is specified only the attributes whose names
> +-match the pattern will be part of the returned list. The pattern is a
> +-[cmd glob] pattern.
> +-
> +-
> +-[call [arg graphName] [method {node keyexists}] [arg node] [arg key]]
> +-
> +-Return true if the specified [arg key] exists for the [arg node].
> +-
> +-
> +-[call [arg graphName] [method {node insert}] [opt [arg node]...]]
> +-
> +-Insert one or more nodes into the graph. The new nodes have no arcs
> +-connected to them. If no node is specified one node will be inserted,
> +-and the system will generate a unique name of the form
> +-[emph node][arg x] for it.
> +-
> +-
> +-[call [arg graphName] [method {node lappend}] [arg node] [arg key] [arg value]]
> +-
> +-Appends a [arg value] (as a list) to one of the keyed values
> +-associated with an [arg node]. Returns the new value given to the
> +-attribute [arg key].
> +-
> +-
> +-[call [arg graphName] [method {node opposite}] [arg node] [arg arc]]
> +-
> +-Return the node at the other end of the specified [arg arc], which has
> +-to be adjacent to the given [arg node].
> +-
> +-
> +-[call [arg graphName] [method {node rename}] [arg node] [arg newname]]
> +-
> +-Renames the node [arg node] to [arg newname]. An error is thrown if
> +-either the node does not exist, or a node with name [arg newname] does
> +-exist. The result of the command is the new name of the node.
> +-
> +-
> +-[call [arg graphName] [method {node set}] [arg node] [arg key] [opt [arg value]]]
> +-
> +-Set or get one of the keyed values associated with a node. A node may have any
> +-number of keyed values associated with it. If [arg value] is not
> +-specified, this command returns the current value assigned to the key;
> +-if [arg value] is specified, this command assigns that value to the
> +-key.
> +-
> +-
> +-[call [arg graphName] [method {node unset}] [arg node] [arg key]]
> +-
> +-Remove a keyed value from the node [arg node]. The method will do
> +-nothing if the [arg key] does not exist.
> +-
> +-
> +-[call [arg graphName] [method nodes] [opt "-key [arg key]"] [opt "-value [arg value]"] [opt "-filter [arg cmdprefix]"] [opt "-in|-out|-adj|-inner|-embedding [arg node] [arg node]..."]]
> +-
> +-Return a list of nodes in the graph. Restrictions can limit the list
> +-of returned nodes based on neighboring nodes, or based on the keyed
> +-values associated with the node. The restrictions that involve
> +-neighboring nodes have a list of nodes as argument, specified after
> +-the name of the restriction itself.
> +-
> +-[para]
> +-
> +-The possible restrictions are the same as for method
> +-[method arcs]. The exact meanings change slightly, as they operate on
> +-nodes instead of arcs. The command recognizes:
> +-
> +-[list_begin definitions]
> +-[def [option -in]]
> +-
> +-Return a list of all nodes with at least one outgoing arc ending in a
> +-node found in the specified set of nodes. Alternatively specified as
> +-the set of source nodes for the [option -in] arcs of the node set. The
> +-[term {incoming neighbours}].
> +-
> +-[def [option -out]]
> +-
> +-Return a list of all nodes with at least one incoming arc starting in
> +-a node found in the specified set of nodes. Alternatively specified as
> +-the set of target nodes for the [option -out] arcs of the node
> +-set. The [term {outgoing neighbours}].
> +-
> +-[def [option -adj]]
> +-
> +-This is the union of the nodes returned by [option -in] and
> +-[option -out]. The [term neighbours].
> +-
> +-[def [option -inner]]
> +-
> +-The set of neighbours (see [option -adj] above) which are also in the
> +-set of nodes. I.e. the intersection between the set of nodes and the
> +-neighbours per [option -adj].
> +-
> +-[def [option -embedding]]
> +-
> +-The set of neighbours (see [option -adj] above) which are not in the
> +-set of nodes. I.e. the difference between the neighbours as per
> +-[option -adj], and the set of nodes.
> +-
> +-[def "[option -key] [arg key]"]
> +-
> +-Limit the list of nodes that are returned to those nodes that have an
> +-associated key [arg key].
> +-
> +-[def "[option -value] [arg value]"]
> +-
> +-This restriction can only be used in combination with
> +-[option -key]. It limits the list of nodes that are returned to those
> +-nodes whose associated key [arg key] has the value [arg value].
> +-
> +-[def "[option -filter] [arg cmdrefix]"]
> +-
> +-Limit the list of nodes that are returned to those nodes that pass the
> +-test. The command in [arg cmdprefix] is called with two arguments, the
> +-name of the graph object, and the name of the node in question. It is
> +-executed in the context of the caller and has to return a boolean
> +-value. Nodes for which the command returns [const false] are removed
> +-from the result list before it is returned to the caller.
> +-
> +-[list_end]
> +-
> +-
> +-[call [arg graphName] [method get] [arg key]]
> +-
> +-Return the value associated with the key [arg key] for the graph.
> +-
> +-
> +-[call [arg graphName] [method getall] [opt [arg pattern]]]
> +-
> +-Returns a dictionary (suitable for use with [lb][cmd {array set}][rb])
> +-for the whole graph.
> +-
> +-If the [arg pattern] is specified only the attributes whose names
> +-match the pattern will be part of the returned dictionary. The pattern
> +-is a [cmd glob] pattern.
> +-
> +-
> +-[call [arg graphName] [method keys] [opt [arg pattern]]]
> +-
> +-Returns a list of keys for the whole graph.
> +-
> +-If the [arg pattern] is specified only the attributes whose names
> +-match the pattern will be part of the returned list. The pattern is a
> +-[cmd glob] pattern.
> +-
> +-
> +-[call [arg graphName] [method keyexists] [arg key]]
> +-
> +-Return true if the specified [arg key] exists for the whole graph.
> +-
> +-
> +-[call [arg graphName] [method serialize] [opt [arg node]...]]
> +-
> +-This method serializes the sub-graph spanned up by the [arg node]s. In
> +-other words it returns a tcl value completely describing that
> +-graph. If no nodes are specified the whole graph will be serialized.
> +-
> +-This allows, for example, the transfer of graph objects (or parts
> +-thereof) over arbitrary channels, persistence, etc.
> +-
> +-This method is also the basis for both the copy constructor and
> +-the assignment operator.
> +-
> +-[para]
> +-
> +-The result of this method has to be semantically identical over all
> +-implementations of the graph interface. This is what will enable us to
> +-copy graph data between different implementations of the same
> +-interface.
> +-
> +-[para]
> +-
> +-The result is a list containing a multiple of three items, plus one!
> +-In other words, '[lb]llength $serial[rb] % 3 == 1'. Valid values
> +-include 1, 4, 7, ...
> +-
> +-[para]
> +-
> +-The last element of the list is a dictionary containing the attributes
> +-associated with the whole graph.
> +-
> +-Regarding the other elements; each triple consists of
> +-
> +-[list_begin enumerated]
> +-[enum]
> +-The name of the node to be described,
> +-
> +-[enum]
> +-A dictionary containing the attributes associated with the node,
> +-
> +-[enum]
> +-And a list describing all the arcs starting at that node.
> +-[list_end]
> +-[para]
> +-
> +-The elements of the arc list are lists containing three or four
> +-elements each, i.e.
> +-
> +-[list_begin enumerated]
> +-[enum]
> +-The name of the arc described by the element,
> +-
> +-[enum]
> +-
> +-A reference to the destination node of the arc. This reference is an
> +-integer number given the index of that node in the main serialization
> +-list. As that it is greater than or equal to zero, less than the
> +-length of the serialization, and a multiple of three.
> +-
> +-[emph Note:] For internal consistency no arc name may be used twice,
> +-whether in the same node, or at some other node. This is a global
> +-consistency requirement for the serialization.
> +-
> +-[enum]
> +-And a dictionary containing the attributes associated with the arc.
> +-
> +-[enum]
> +-The weight associated with the arc. This value is optional. Its
> +-non-presence means that the arc in question has no weight associated
> +-with it.
> +-
> +-[para][emph Note:] This information is new, compared to the
> +-serialization of [package graph] 2.3 and earlier. By making it an
> +-optional element the new format is maximally compatible with the
> +-old. This means that any graph not using weights will generate a
> +-serialization which is still understood by the older graph package. A
> +-serialization will not be understood any longer by the older packages
> +-if, and only if the graph it was generated from actually has arcs with
> +-weights.
> +-
> +-[list_end]
> +-[para]
> +-
> +-For all attribute dictionaries they keys are the names of the
> +-attributes, and the values are the values for each name.
> +-
> +-[para]
> +-
> +-[emph Note:] The order of the nodes in the serialization has no
> +-relevance, nor has the order of the arcs per node.
> +-
> +-[example {
> +- # A possible serialization for the graph structure
> +- #
> +- # d -----> %2
> +- # / ^ \\
> +- # / / \\
> +- # / b \\
> +- # / / \\
> +- # %1 <- a - %0 e
> +- # ^ \\ /
> +- # \\ c /
> +- # \\ \\ /
> +- # \\ v v
> +- # f ------ %3
> +- # is
> +- #
> +- # %3 {} {{f 6 {}}} %0 {} {{a 6 {}} {b 9 {}} {c 0 {}}} %1 {} {{d 9 {}}} %2 {} {{e 0 {}}} {}
> +- #
> +- # This assumes that the graph has neither attribute data nor weighted arcs.
> +-}]
> +-[para]
> +-
> +-
> +-[call [arg graphName] [method set] [arg key] [opt [arg value]]]
> +-
> +-Set or get one of the keyed values associated with a graph. A graph
> +-may have any number of keyed values associated with it. If [arg value]
> +-is not specified, this command returns the current value assigned to
> +-the key; if [arg value] is specified, this command assigns that value
> +-to the key.
> +-
> +-
> +-[call [arg graphName] [method swap] [arg node1] [arg node2]]
> +-
> +-Swap the position of [arg node1] and [arg node2] in the graph.
> +-
> +-
> +-[call [arg graphName] [method unset] [arg key]]
> +-
> +-Remove a keyed value from the graph. The method will do nothing if the
> +-[arg key] does not exist.
> +-
> +-
> +-[call [arg graphName] [method walk] [arg node] \
> +- [opt "-order [arg order]"] \
> +- [opt "-type [arg type]"] \
> +- [opt "-dir [arg direction]"] \
> +- -command [arg cmd]]
> +-
> +-Perform a breadth-first or depth-first walk of the graph starting at
> +-the node [arg node] going in either the direction of outgoing or
> +-opposite to the incoming arcs.
> +-
> +-[para]
> +-
> +-The type of walk, breadth-first or depth-first, is determined by the
> +-value of [arg type]; [const bfs] indicates breadth-first,
> +-
> +-[const dfs] indicates depth-first. Depth-first is the default.
> +-
> +-[para]
> +-
> +-The order of the walk, pre-order, post-order or both-order is
> +-determined by the value of [arg order]; [const pre] indicates
> +-pre-order, [const post] indicates post-order, [const both] indicates
> +-both-order. Pre-order is the default. Pre-order walking means that a
> +-node is visited before any of its neighbors (as defined by the
> +-
> +-[arg direction], see below). Post-order walking means that a parent is
> +-visited after any of its neighbors. Both-order walking means that a
> +-node is visited before [emph and] after any of its neighbors. The
> +-combination of a breadth-first walk with post- or both-order is illegal.
> +-
> +-[para]
> +-
> +-The direction of the walk is determined by the value of [arg dir];
> +-[const backward] indicates the direction opposite to the incoming
> +-arcs, [const forward] indicates the direction of the outgoing arcs.
> +-
> +-[para]
> +-
> +-As the walk progresses, the command [arg cmd] will be evaluated at
> +-each node, with the mode of the call ([const enter] or
> +-[const leave]) and values [arg graphName] and the name of the current
> +-node appended. For a pre-order walk, all nodes are [const enter]ed, for a
> +-post-order all nodes are left. In a both-order walk the first visit of
> +-a node [const enter]s it, the second visit [const leave]s it.
> +-
> +-[list_end]
> +-
> +-
> +-[section {Changes for 2.0}]
> +-The following noteworthy changes have occurred:
> +-
> +-[list_begin enumerated]
> +-[enum]
> +-
> +-The API for accessing attributes and their values has been
> +-simplified.
> +-
> +-[para]
> +-
> +-All functionality regarding the default attribute "data" has been
> +-removed. This default attribute does not exist anymore. All accesses
> +-to attributes have to specify the name of the attribute in
> +-question. This backward [emph incompatible] change allowed us to
> +-simplify the signature of all methods handling attributes.
> +-
> +-[para]
> +-
> +-Especially the flag [option -key] is not required anymore, even more,
> +-its use is now forbidden. Please read the documentation for the arc
> +-and node methods [method set], [method get], [method getall],
> +-
> +-[method unset], [method append], [method lappend], [method keyexists]
> +-and [method keys] for a description of the new API's.
> +-
> +-[enum]
> +-
> +-The methods [method keys] and [method getall] now take an optional
> +-pattern argument and will return only attribute data for keys matching
> +-this pattern.
> +-
> +-[enum]
> +-
> +-Arcs and nodes can now be renamed. See the documentation for the
> +-methods [method {arc rename}] and [method {node rename}].
> +-
> +-[enum]
> +-
> +-The structure has been extended with API's for the serialization and
> +-deserialization of graph objects, and a number of operations based on
> +-them (graph assignment, copy construction).
> +-
> +-[para]
> +-
> +-Please read the documentation for the methods [method serialize],
> +-[method deserialize], [method =], and [method -->], and the
> +-documentation on the construction of graph objects.
> +-
> +-[para]
> +-
> +-Beyond the copying of whole graph objects these new API's also enable
> +-the transfer of graph objects over arbitrary channels and for easy
> +-persistence.
> +-
> +-
> +-[enum]
> +-
> +-A new method, [method attr], was added to both [method arc] and
> +-[method node] allowing the query and retrieval of attribute data
> +-without regard to arc and node relationships.
> +-
> +-[enum]
> +-
> +-Both methods [method arcs] and [method nodes] have been extended with
> +-the ability to select arcs and nodes based on an arbitrary filtering
> +-criterium.
> +-
> +-
> +-[list_end]
> +-
> +-
> +-[section {BUGS, IDEAS, FEEDBACK}]
> +-
> +-This document, and the package it describes, will undoubtedly contain
> +-bugs and other problems.
> +-
> +-Please report such in the category [emph {struct :: graph}] of the
> +-[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].
> +-
> +-Please also report any ideas for enhancements you may have for either
> +-package and/or documentation.
> +-
> +-
> +-[keywords graph cgraph serialization]
> +-[keywords edge arc node vertex subgraph neighbour]
> +-[keywords adjacent loop degree]
> +-[manpage_end]
> +--
> +1.7.6
> +
>
>
> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
> _______________________________________________
> devel mailing list
> devel at lists.opencsw.org
> https://lists.opencsw.org/mailman/listinfo/devel
--
"You don't become great by trying to be great, you become great by wanting to do something,
and then doing it so hard that you become great in the process." - xkcd #896
More information about the devel
mailing list