[Pkg-tcltk-commits] r345 - policy/trunk
sgolovan-guest at alioth.debian.org
sgolovan-guest at alioth.debian.org
Sat Oct 20 19:49:11 UTC 2007
Author: sgolovan-guest
Date: 2007-10-20 19:49:11 +0000 (Sat, 20 Oct 2007)
New Revision: 345
Modified:
policy/trunk/tcltk-policy.sgml
Log:
[policy]
1) Replaced future tense by present tense in chapter 1.
2) Removed phrases about deprecating wish and tclsh packages from chapter 1
(they are useful for modules and extensions which work with all Tcl/Tk
versions, so I don't think they should be dropped).
3) Added several useful SGML entities.
Modified: policy/trunk/tcltk-policy.sgml
===================================================================
--- policy/trunk/tcltk-policy.sgml 2007-10-20 17:15:07 UTC (rev 344)
+++ policy/trunk/tcltk-policy.sgml 2007-10-20 19:49:11 UTC (rev 345)
@@ -1,10 +1,26 @@
-<!doctype debiandoc system>
+<!DOCTYPE debiandoc system [
+<!ENTITY XY "<var>X</var>.<var>Y</var>">
+<!ENTITY tclsh "<package>tclsh</package>">
+<!ENTITY wish "<package>wish</package>">
+<!ENTITY tcl "<package>tcl</package>">
+<!ENTITY tcl-dev "<package>tcl-dev</package>">
+<!ENTITY tcl-doc "<package>tcl-doc</package>">
+<!ENTITY tclXY "<package>tcl&XY;</package>">
+<!ENTITY tclXY-dev "<package>tcl&XY;-dev</package>">
+<!ENTITY tclXY-doc "<package>tcl&XY;-doc</package>">
+<!ENTITY tk "<package>tk</package>">
+<!ENTITY tk-dev "<package>tk-dev</package>">
+<!ENTITY tk-doc "<package>tk-doc</package>">
+<!ENTITY tkXY "<package>tk&XY;</package>">
+<!ENTITY tkXY-dev "<package>tk&XY;-dev</package>">
+<!ENTITY tkXY-doc "<package>tk&XY;-doc</package>">
+]>
<debiandoc>
<book>
<titlepag>
<title>Debian Tcl/Tk Policy</title>
<author>
- <name>Fracesco Paolo Lovergine</name>
+ <name>Francesco Paolo Lovergine</name>
</author>
<author>
<name>Sergei Golovan</name>
@@ -57,34 +73,32 @@
<sect id="versions">
<heading>Versions</heading>
<p>
- At any given time, the virtual packages <package>tclsh</package> and
- <package>wish</package> are provided by different source package versions
+ At any given time, the virtual packages &tclsh; and
+ &wish; are provided by all source package versions
of Tcl and Tk. So pseudo-default Tcl and Tk exist, but they are generally a choice
of the administrator by means of <tt>update-alternatives</tt> use.
Starting from Lenny release, proper default packages are also provided,
- in order to manage better modules and extensions packaging.
+ in order to manage modules and extensions packaging better.
Modules should preferably use those packages when appropriate
(i.e. they are either version independent
or properly versioned to inhibit the use of a non compatible versions), but it is
not mandatory. This is consistent with the use of alternatives.
The default packages are
<example>
- tcl
- tk
- tcl-dev
- tk-dev
- tcl-doc
- tk-doc
+ tcl
+ tk
+ tcl-dev
+ tk-dev
+ tcl-doc
+ tk-doc
</example>
</p>
<p>
The default Debian Tcl/Tk version should alway be the latest stable
upstream release that can be integrated in the distribution. Starting
from 8.0, Tcl and Tk share the same version numbering. The default packages
- must depend on the right versioned packages and provide useful additional
- symlinks and alternatives. At some point in the development cycle
- after Lenny release, virtual packages could be dropped and all packages
- have to only depend on default packages or versioned ones.
+ depend on the appropriate versioned packages and provide useful additional
+ symlinks and alternatives.
</p>
<p>
Apart from the default version, legacy versions of Tcl/Tk
@@ -96,61 +110,56 @@
the same Tcl/Tk version 8.4, but Tcl 8.5 and 8.3 are
indeed different versions. The patchlevel intends the result of
the 'info patchlevel' command, i.e. Tcl/Tk 8.4.16 and 8.4.15 have the
- same version but different patchlevels)
+ same version but different patchlevels).
</p>
<p>In addition, unstable/development version of Tcl/Tk
may be included in the unstable/experimental distribution.
</p>
<p>
- For any version, the main Tcl and Tk packages must be called
- <package>tcl<var>X</var>.<var>Y</var></package> and
- <package>tk<var>X</var>.<var>Y</var></package> respectively.
+ For any version, the main Tcl and Tk packages are called
+ &tclXY; and &tkXY; respectively.
They are always packaged as separate sources, as for upstream.
Names of related packages or extensions must follow the same
- convention, if the inclusion of multiple versions make sense
- and/or it they work only with specific versions of Tcl or Tk.
+ convention if the inclusion of multiple versions make sense
+ or if they work only with specific versions of Tcl or Tk.
</p>
<p>
To avoid definition clashes with Debian terminology, we will call
- <var>modules</var> any Tcl/Tk packages which consist uniquely of
- Tcl/Tk sources, and <var>extension</var> any program which
+ <em>modules</em> any Tcl/Tk packages which consist uniquely of
+ Tcl/Tk sources, and <em>extension</em> any program which
extends consistently Tcl/Tk using TEA and shared libraries.
Note that this is not completely consistent with Tcl terminology,
- which recently also introduced <em>.tm modules</em> and traditionally
- deals with <em>packages</em> and <em>script libraries</em>.
+ which started from version 8.5 also introduces <em>.tm modules</em>
+ and traditionally deals with <em>packages</em> and <em>script
+ libraries</em>.
</p>
-
</sect>
<sect id="base">
<heading>Main packages</heading>
<p>
For every Tcl/Tk versions provided in the distribution, the
- packages <package>tcl<var>X</var>.<var>Y</var></package>
- and <package>tk<var>X</var>.<var>Y</var></package>
- shall comprise a complete distribution for
+ packages &tclXY;
+ and &tkXY;
+ comprise a complete distribution for
<em>deployment</em> of Tcl/Tk scripts and applications. The
packages include the binaries
- <file>/usr/bin/tclsh<var>X</var>.<var>Y</var></file>,
- <file>/usr/bin/wish<var>X</var>.<var>Y</var></file> and
+ <file>/usr/bin/tclsh&XY;</file>,
+ <file>/usr/bin/wish&XY;</file> and
core modules and extensions of the upstream Tcl/Tk distribution.
- Any Tcl packages will include a <var>Provides:</var> item of the virtual package
- <package>tclsh</package> and any Tk packages will include a <var>Provides:</var>
- item for the <package>wish</package> virtual package. Those virtual packages
- could be dropped any time after Lenny release.
- They will also provide alternatives for the following files:
- <package>/usr/bin/tclsh</package>
- <package>/usr/bin/wish</package>
- <package>/usr/share/aclocal/tcl.m4</package>
+ Any Tcl package includes a <var>Provides:</var> item of the virtual package
+ &tclsh; and any Tk package includes a <var>Provides:</var>
+ item for the &wish; virtual package.
+ They also provide alternatives for files
+ <file>/usr/bin/tclsh</file> and
+ <file>/usr/bin/wish</file>.
</p>
<p>
- Any modules or extensions that depend on non-<em>required</em> packages
- are excluded and will be provided in separate packages. Tools and files
+ All modules and extensions that depend on non-<em>required</em> packages
+ are excluded and will be provided in separate packages. Tools and files
for the <em>development</em> of Tcl/Tk packages are split off in two
- separate packages
- <package>tcl<var>X</var>.<var>Y</var>-dev</package> and
- <package>tk<var>X</var>.<var>Y</var>-dev</package>.
- Documentation will be provided separately as well.
+ separate packages &tclXY-dev; and &tkXY-dev;.
+ Documentation is provided separately in packages &tclXY-doc; and &tkXY-doc;.
</p>
</sect>
@@ -167,9 +176,8 @@
<p>
Tcl/Tk scripts that only work with a specific Tcl/Tk version must
explicitely use the versioned interpreter name
- (<file>tclsh<var>X</var>.<var>Y</var></file> and/or <file>wish<var>X</var>.<var>Y</var></file>)
- and either depend on the specific Tcl/Tk versioned package or add versioning to their
- dependencies on the default Tcl/Tk packages.
+ (<file>tclsh&XY;</file> and/or <file>wish&XY;</file>)
+ and must depend on the specific Tcl/Tk versioned package.
</p>
</sect1>
<sect1 id="interpreter_loc">
@@ -177,19 +185,19 @@
<p>
The path name for the Tcl interpreter is
<file>/usr/bin/tclsh</file> or
- <file>/usr/bin/tclsh<var>X</var>.<var>Y</var></file>.
+ <file>/usr/bin/tclsh&XY;</file>.
</p>
<p>
The path name for the Tk interpreter is
<file>/usr/bin/wish</file> or
- <file>/usr/bin/wish<var>X</var>.<var>Y</var></file>.
+ <file>/usr/bin/wish&XY;</file>.
</p>
<p>
- If a maintainer would like to provide the user with the
+ If a maintainer would like to provide the user a
possibility to override the Debian Tcl interpreter, he
may want to use <file>/usr/bin/env tclsh</file> or
- <file>/usr/bin/env tclshX.Y</file>. The same consideration
- applies for Tk and the wish interpreter. Administrators could also
+ <file>/usr/bin/env tclsh&XY;</file>. The same consideration
+ applies for Tk and the <file>wish</file> interpreter. Administrators could also
override default versions of the interpreters
using <tt>update-alternatives</tt>,
so maintainers must always consider that the default Tcl/Tk
@@ -203,14 +211,13 @@
<sect id="libtcltk">
<heading>Tcl/Tk libraries</heading>
<p>
- The Tcl/Tk libraries are provided by
- <package>tcl<var>X</var>.<var>Y</var></package> and
- <package>tk<var>X</var>.<var>Y</var></package>.
+ The Tcl and Tk libraries are provided by
+ &tclXY; and &tkXY; respectively.
These packages install
- <file>/usr/lib/libtcl<var>X</var>.<var>Y</var>.so.<var>Z.</var></file>
- (soname is <tt>libtcl<var>X</var>.<var>Y</var>.so.<var>Z</var></tt>)
- and <file>/usr/lib/libtk<var>X</var>.<var>Y</var>.so.<var>Z</var></file>
- (soname is <tt>libtk<var>X</var>.<var>Y</var>.so.<var>Z</var></tt>).
+ <file>/usr/lib/libtcl&XY;.so.<var>Z</var></file>
+ (soname is <tt>libtcl&XY;.so.<var>Z</var></tt>)
+ and <file>/usr/lib/libtk&XY;.so.<var>Z</var></file>
+ (soname is <tt>libtk&XY;.so.<var>Z</var></tt>).
</p>
</sect>
@@ -218,16 +225,15 @@
<heading>Tools/files for Development of Tcl/Tk modules and extensions</heading>
<p>
Some tools and files for development of Tcl/Tk modules and extensions are
- packaged as <package>tcl<var>X</var>.<var>Y</var>-dev</package>
- and <package>tk<var>X</var>.<var>Y</var>-dev</package>.
+ packaged as &tclXY-dev; and &tkXY-dev;.
These packages provide header files as well as static and stub libraries.
- Header files are installed in <file>/usr/include/tcl<var>X</var>.<var>Y</var>/</file>
- and <file>/usr/include/tk<var>X</var>.<var>Y</var>/</file> directories.
- Default packages <tt>tcl-dev</tt> and <tt>tk-dev</tt> must provide also
- symlink for the right versioned header files directory
+ Header files are installed in <file>/usr/include/tcl&XY;</file>
+ directory (for both Tcl and Tk).
+ Default packages <tt>tcl-dev</tt> and <tt>tk-dev</tt> provide
+ symlinks to the right versioned header files directory
<example>
- /usr/include/tcl -> /usr/include/tclX.Y
- /usr/include/tk -> /usr/include/tclX.Y
+ /usr/include/tcl -> /usr/include/tcl&XY;
+ /usr/include/tk -> /usr/include/tcl&XY;
</example>
See net section and <ref id="debian_oddities"> for more information about
possible issues with extension building due to Debian customizations.
@@ -237,49 +243,53 @@
<sect id="paths">
<heading>Auto_load Path</heading>
<p>
- The package search path (<tt>$auto_path</tt>) for both Tcl and Tk
+ The package search path (<var>auto_path</var>) for both Tcl and Tk
is a list searched in the following order:
<taglist>
<tag>Site modules and extensions:</tag>
<item>
<example>
- /usr/local/lib/tcltk (architecture dependent files)
- /usr/local/share/tcltk (architecture independent files)
+ /usr/local/lib/tcltk (architecture dependent files)
+ /usr/local/share/tcltk (architecture independent files)
</example>
</item>
<tag>Packaged modules and extensions:</tag>
<item>
<example>
- /usr/lib/tcltk (architecture dependent files)
- /usr/share/tcltk (architecture independent files)
+ /usr/lib/tcltk (architecture dependent files)
+ /usr/share/tcltk (architecture independent files)
</example>
</item>
<tag>Version specific core modules and extensions:</tag>
<item>
<example>
- /usr/share/tcltk/tcl<var>X.Y</var>
- /usr/share/tcltk/tk<var>X.Y</var>
+ /usr/share/tcltk/tcl&XY;
+ /usr/share/tcltk/tk&XY; (for Tk only)
</example>
</item>
</taglist>
</p>
<p>
Maintainers must ensure that modules and extensions are correctly installed in subdirs of
- the paths above consistently. See <ref id="modules_loading"> also for more information
+ the paths above consistently. See <ref id="modules_loading"> for more information
about Tcl/Tk specific ways of dealing with modules and extensions loading.
Developers must consider that these defaults impact TEA-based modules and use
preferably system-wide <file>tcl.m4</file> instead
of private one (see <ref id="debian_oddities">).
</p>
-
</sect>
<sect id="docs">
<heading>Documentation</heading>
<p>
- Default packages <file>tcl-doc</file> and <file>tk-doc</file> are provided which depend
- on default versioned <file>tclX.Y-doc</file> and <file>tkX.Y-doc</file>. They both
- include also a copy of the most up-to-date version of this policy and suitable symlinks.
+ Default packages &tcl-doc; and &tk-doc; which depend
+ on default versioned &tclXY-doc; and &tkXY-doc; are provided.
+ Since different &tclXY-doc; and &tkXY-doc; conflict in files and cannot be installed
+ simultaneously, &tcl-doc; and &tk-doc; only recommend
+ &tclXY-doc; and &tkXY-doc; to allow administrators to install
+ any desirable package with Tcl/Tk manual pages.
+ The package
+ &tcl-doc; also includes a copy of the up-to-date version of this policy.
</p>
</sect>
</chapt>
@@ -423,7 +433,7 @@
Tcl/Tk supports a few alternative ways for modules loading.
Modules can be implemented as shared libraries, Tcl/Tk scripts or a combination
of them. Generally, specific index scripts are used for that and they
- need to be placed in a directory included in the <tt>$auto_path</tt> list along
+ need to be placed in a directory included in the <tt>auto_path</tt> list along
with scripts and libraries.
Old non-package script libraries require a <tt>tclIndex</tt> generated with
the <tt>auto_mkindex</tt> Tcl instruction.
@@ -475,7 +485,7 @@
shared library extensions) along with the needed index file (see <ref id="modules_loading">).
</item>
<item>
- This policy customizes <file>$auto_path</file> differently with respect to
+ This policy customizes <file>auto_path</file> differently with respect to
generic upstream <file>UNIX</file> platforms, so that you should use preferably
system provided <file>tcl.m4</file> or <file>tclConfig.sh</file>. Occasionally
that could either require custom hacks for non TEA-based building systems, or
More information about the Pkg-tcltk-commits
mailing list