$OpenBSD: README,v 1.3 2014/01/11 12:56:41 ajacoutot Exp $

+-----------------------------------------------------------------------
| Running tcl-8.6.1p2 on OpenBSD
+-----------------------------------------------------------------------

The OpenBSD port of the Tcl dynamic language was designed to balance
deriving the maximum value from the original software while keeping
any modifications to a minimum.

This document describes these differences and includes a handy guide
and patch for adding Tcl and Tk to /etc/man.conf.

Principally, the original install locations have been altered to enable
installing multiple versions of Tcl and Tk on OpenBSD without conflict.

Tclsh and Wish
==============
Tclsh and wish are installed as tclsh8.6 and wish8.6, respectively.
Many Tcl programs expect to find tclsh or wish.  They will have to be
modified to launch the correct shell or links tclsh and wish may be
created which point to tclsh8.6 and wish8.6, respectively. These links
may have already been created by the system administrator. It is of
course also possible to create one's own links.

Files and Directories
=====================

Library files
-------------
scripts, encoding files, etc.
normally in
/usr/local/lib/tcl8.6, /usr/local/lib/tk8.6
now in
/usr/local/lib/tcl/tcl8.6, /usr/local/lib/tcl/tk8.6

Configuration Files
-------------------
tclConfig.sh, tkConfig.sh
normally in
/usr/local/lib
now in
/usr/local/lib/tcl/tcl8.6, /usr/local/lib/tcl/tk8.6

Header Files
------------
*.h
normally in
/usr/local/include
now in
/usr/local/include/tcl8.6, /usr/local/include/tk8.6

Manual Pages
------------
*.1, *.3, *.n
normally in
/usr/local/man
now in
/usr/local/lib/tcl8.6/man, /usr/local/lib/tk8.6/man

Demos
-----
*.tcl, *
normally in
/usr/local/lib/tk8.6/demos
now in
/usr/local/share/examples/tk8.6

Bundled Tcl Modules
-------------------
*.tm
normally in
/usr/local/lib/tcl8/...
now in
/usr/local/lib/tcl/tcl8.6/modules/...

Tcl Module Paths
----------------
normally
/usr/local/lib/tcl8/...
now
/usr/local/lib/tcl/modules/...

Additional Header Files
-----------------------
Additional ('private') header files are installed
in /usr/local/include/tcl8.6 and /usr/local/include/tk8.6.

Libraries
=========
On architectures that support shared libraries, additional static
libraries (libtcl86.a, libtk86.a) are built from the -fPIC compiled
object (.o) files.  A symbolic link from any lib.a to lib_pic.a
is created in order to satisfy libtool.

Manual Page Configuration
=========================
Changes to /etc/man.conf are required so that OpenBSD's man(1) and
related commands can find the Tcl and Tk manual pages.

Additional _whatdb entries are needed which point to the Tcl and Tk
whatis.db files. The Tcl and Tk manual page directories need to be
added to the _default and n sections. Additional sections tcl and tk
point to the Tcl and Tk manual page directories.

Following this text is a patch (with instructions) that will perform
the aforementioned changes on an unmodified /etc/man.conf.
If not used directly it can serve as a guide.

Tcl/Tk Resources
================
Newsgroup: nntp://comp.lang.tcl
Wiki:      http://wiki.tcl.tk
Tutorial:  http://www.tcl.tk/man/tcl8.5/tutorial/tcltutorial.html
Wikibook:  http://en.wikibooks.org/wiki/Programming:Tcl
Book:      Practical Programming in Tcl and Tk, 4th Edition
           ISBN: 0-13-038560-3

Patch to add Tcl and Tk to /etc/man.conf
========================================
Run:
$ patch -o man.conf.new /etc/man.conf /usr/local/share/doc/pkg-readmes/tcl-8.6.1p2
Examine and install as /etc/man.conf if it appeases you.

@@ -7,6 +7,8 @@
 _whatdb		/usr/share/man/whatis.db
 _whatdb		/usr/local/man/whatis.db
 _whatdb		/usr/X11R6/man/whatis.db
+_whatdb		/usr/local/lib/tcl/tcl8.6/man/whatis.db
+_whatdb		/usr/local/lib/tcl/tk8.6/man/whatis.db
 
 # Subdirectories for paths ending in '/', IN SEARCH ORDER.
 _subdir		{cat,man}1 {cat,man}8 {cat,man}6 {cat,man}2 {cat,man}3 {cat,man}5 {cat,man}7 {cat,man}4 {cat,man}9 {cat,man}3p {cat,man}3f {cat,man}n
@@ -31,17 +33,19 @@
 # directory with all of the subdirectories listed for the keyword _subdir.
 
 # default
-_default	/usr/{share,X11R6,local,ports/infrastructure}/man/
+_default	/usr/{share,X11R6,local,local/lib/tcl/{tcl,tk}8.6,ports/infrastructure}/man/
 
 # Other sections that represent complete man subdirectories.
 X11		/usr/X11R6/man/
 X11R6		/usr/X11R6/man/
 local		/usr/local/man/
+tcl		/usr/local/lib/tcl/tcl8.6/man/
+tk		/usr/local/lib/tcl/tk8.6/man/
 
 # Specific section/directory combinations.
-1		/usr/{share,X11R6,local}/man/{cat,man}1
+1		/usr/{share,X11R6,local,local/lib/tcl/{tcl,tk}8.6}/man/{cat,man}1
 2		/usr/{share,X11R6,local}/man/{cat,man}2
-3		/usr/{share,X11R6,local}/man/{cat,man}3
+3		/usr/{share,X11R6,local,local/lib/tcl/{tcl,tk}8.6}/man/{cat,man}3
 3F		/usr/local/man/{cat,man}3f
 3f		/usr/local/man/{cat,man}3f
 3P		/usr/{share,local}/man/{cat,man}3p
@@ -52,4 +56,4 @@
 7		/usr/{share,X11R6,local}/man/{cat,man}7
 8		/usr/{share,X11R6,local}/man/{cat,man}8
 9		/usr/share/man/{cat,man}9
-n		/usr/local/man/{cat,man}n
+n		/usr/{local,local/lib/tcl/{tcl,tk}8.6}/man/{cat,man}n
