tpad

help

Configuration

You can configure tpad by editing the file tpad.conf. This file uses the Tcl(n) syntax. Tcl provides a good reconfigurability but when editing tpad.conf you must be care not to make any syntax error otherwise tpad won't start. It is advisable to make a backup copy of tpad.conf before modifying it or to make changes to a copy of tpad.conf and check the syntax by running it with the Tcl interpreter before overwriting the real tpad.conf with it. To do those things you should use commands similar to the following:

$ cp tpad.conf tpad.conf.default
$ cp tpad.conf tpad.conf.copy
... editing tpad.conf.copy
$ tclsh8.4 tpad.conf.copy
$ mv tpad.conf.copy tpad.conf

If you want to make changes only for a single user, instead of modifying the global configuration file, you can copy it as a hidden per user configuration file named ~/.tpadrc and make changes only there. If something goes wrong and tpad doesn't start anymore, you can simply delete ~/.tpadrc and start again.

When you run tpad it will first search for ~/.tpadrc; if it can't find this, it will try to load the global configuration file tpad.conf, so ~/.tpadrc completely overrides tpad.conf. This means all the options are required. You should not comment out any of the options below otherwise tpad won't start.

This is the default global configuration file shipped with this version (default values are those of the FreeBSD package; there are minor differences under Linux).

## Configuration file for tpad version 1.3
# WinXP (TM) enhanced Notepad clone written in Tcl/Tk.
# Copyright (C) 2004  Antonio Bonifati
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details:
#	<http://www.fsf.org/copyleft/gpl.html>
#
# Requires at least Tcl/Tk 8.4.
# Please report any bug found to the author:
#
#       Antonio Bonifati <ant@venus.deis.unical.it>
#       http://monitor.deis.unical.it/ant
#       Snail mail:
#               Via Ernesto Moneta, 11
#               87012 Castrovillari (CS)
#               Italy
#
## last revised on: $Date: 2004/08/30 $

#
# You can safely change constants and default values
# of variables below as long as you make no syntax errors.
# See Tcl(n) for a summary of Tcl language syntax.
#

## initialize tpad static vars or constants
variable version 1.3  ;# don't change this

# file types listbox entries
variable types {
  {{All Files}      *                         }
  {{Text Files}     {.txt .text}              }
  {{HTML Files}     {.html .htm .shtml .xhtml}}
  {{XML Files}      .xml                      }
  {{TCL Files}      {.tcl .tk}                }
  {{C Source Files} {.c .h}                   }
}

variable tearoff no  ;# include tearoff in pulldown menus (no, yes)

variable palette gray85  ;# color scheme (see tk_setPalette(n))
variable fg black        ;# text and entry foreground color
variable bg white        ;# text and entry background color
variable selfg white     ;# selection foreground color
variable selbg navy      ;# selection background color

# font to use for the editor (a fixed size font is recommended)
variable editfont Courier
variable statusfont Helvetica  ;# font to use for the status bar

# lpr(1) like command and options to use for off line printing
variable lpr {lpr}

variable logfac yes  ;# turn on log creation facility (no, yes)

variable timefmt %c  ;# date and time format
variable titlefmt {%1$s:%2$s}  ;# title bar format

variable insertofftime 300  ;# cursor off time (milliseconds)
variable insertontime 600   ;# cursor on time (milliseconds)

# Warning: there seems to be a bug with the undo implementation
# in Tk 8.4.6 or previous, which causes segmentation faults when
# this parameter is set to more than one.
# This is not tpad's fault and I hope will be fixed soon.
variable maxundo 1  ;# maximum number of compound undo actions

# command to run an external browser to read the HTML help
variable browsercmd mozilla

# path to where the HTML documentation lives
variable helpath {/usr/local/share/doc/tpad}

# initial placing of non-modal dialogs ({},pointer,widget,none)
variable placing widget

# max entries of the "open recent" list (0 for no list)
variable maxopenrec 10

# file where the "open recent" list is saved ({} for non-permanent list)
variable openrecfile {~/.tpad_history}

variable fmtkind BSD  ;# kind of fmt(1) (GNU, BSD, none)
variable fmt {fmt}    ;# fmt(1) path (ignored if fmtkind is none)

variable xmlwf {xmlwf}  ;# xmlwf(1) path (empty if you don't have it)

# note that you will also need to install Tcllib for this plugin to work
variable tidy {}  ;# tidy(1) path (empty if you don't have it)

# fortune(1) path; make it empty if you don't have a BSD-like
# fortune command; note that Linux fortune is ok
variable fortune {fortune}

# display fortune tip at startup (no, yes); ignored if fortune is empty
variable tip yes

# you will need to change this only if you move or rename the fortune
# database file and its index (which has the added extension .dat)
# ignored if fortune is empty
variable fortunefile {/usr/local/share/tpad/tpad-tips}

set tk_strictMotif 0  ;# strict Motif compliance (0, 1)
## end of static vars or constants initialization

## initialize tpad instance vars to default values
variable wrap none   ;# wrap mode (none, word)
variable pattern {}  ;# search pattern
variable substr {}   ;# substitution string
variable dir down    ;# search direction (up, down)
variable case no     ;# case sensitive search (no, yes)
variable regexp no   ;# match using Regular Expressions (no, yes)
variable status yes  ;# display status bar (no, yes)

variable ascii no   ;# display ascii table (no, yes)
variable format no  ;# display text formatter window (no, yes)
variable wf no      ;# display xmlwf window (no, yes)
variable ht no      ;# display HTML Tidy window (no, yes)

variable inputEnc system   ;# default encoding to use when reading files
variable outputEnc system  ;# default encoding to use when writing files
## end of tpad instance vars initialization

# initialize ascii plugin static vars or constants
namespace eval ascii {
  variable font Courier  ;# font to use for table characters
}
# end of ascii plugin static vars or constants initialization

# initialize BSD fmt(1) plugin vars to default values
namespace eval BSDfmt {
  variable width 65      ;# line width alias goal length
  variable excess 10     ;# excess chars so that maximum=width+excess
  variable center no     ;# center the text (no, yes)
  variable nonroff no    ;# don't ignore nroff command lines (no, yes)
  variable mail no       ;# try to format mail headers (no, yes)
  variable spaces no     ;# collapse whitespaces inside lines (no, yes)
  variable ending {.?!}  ;# sentence ending chars
  variable replace no    ;# replace spaces with tabs at the start (no, yes)
  variable para no       ;# allow indented paragraphs (no, yes)
}
# end of BSD fmt(1) plugin vars initialization

# initialize GNU fmt(1) plugin vars to default values
namespace eval GNUfmt {
  variable width 75    ;# maximum line length
  variable uniform no  ;# uniform spacing (no, yes)
  variable prefix {}   ;# format only lines beginning with this prefix
  variable crown no    ;# crown margin mode (no, yes)
  variable tagged no   ;# tagged paragraph (no, yes)
  variable split no    ;# split long lines, but do not refill (no, yes)
}
# end of GNU fmt(1) plugin vars initialization

# initialize xmlwf(1) plugin vars to default values
namespace eval xmlwf {
  variable font Helvetica  ;# font to use for error messages

  variable external no    ;# parse external entities (no, yes)
  variable parameter no   ;# process parameter entities (no, yes)
  variable standalone no  ;# error if not standalone (no, yes)
  variable namespace no   ;# process (describe) namespaces (no, yes)
}
# end of xmlwf(1) plugin vars initialization

# initialize tidy(1) plugin vars to default values
namespace eval tidy {
  variable errorFg white
  variable errorBg #b03060
  variable warningFg white
  variable warningBg #303080
  variable smallFont {Helvetica -9}  ;# used for the show/hide options button

  variable showopts yes  ;# whether or not display options at startup (no, yes)

  # if not empty this value overrides the environment variable HTML_TIDY;
  # if empty and HTML_TIDY is defined, the value of HTML_TIDY
  # will be assigned to it; please always use an absolute path
  variable config {}     ;# additional config file, {} if none or default

  variable indent no     ;# indent contents of elements (no, yes)
  variable wrap yes      ;# wrap output (no, yes)
  # default right margin for line wrapping
  variable column 68
  variable preserve no   ;# preserve source file entities as is (no, yes)
  variable xml no        ;# input is wellformed xml (no, yes)
  variable omit no       ;# omit optional endtags (no, yes)
  variable upper no      ;# force tags to upper case (no, yes)
  variable clean no      ;# replace font, nobr & center tags by CSS (no, yes)
  variable asxml no      ;# convert html to wellformed xml (no, yes)
  variable numeric no    ;# output numeric rather than named entities (no, yes)
}
# end of tidy(1) plugin vars initialization

Even though you don't know Tcl, you should not have too much trouble to change the configuration file to suit your needs. Here are some notes about every constant or variable to help you a bit. The possible values a variable may assume are bracketed. If you get stuck at something contact me, but first please read this page and the Tcl documentation referenced here, and try to fix things yourself :-)

When speaking of boolean values, no is the same as 0 and yes is the same as 1. If you need to set a variable to a string which has more than one word in it, remember to use the open braces around (e.g. {word1 word2}) otherwise Tcl will complain.

version [version number]

This states what version tpad is. Unless you are a developer, you shouldn't change this.

types [nested Tcl lists]

This option defines the list of types in the file types listbox of a file dialog. You should not have too much problems editing this following the example. For details, see tk_getOpenFile(n) or tk_getSaveFile(n), especially the section titled SPECIFYING FILE PATTERNS.

tearoff [no,yes]

Specifies whether or not the menu should include a tear-off entry at the top. A tear-off appears as a dashed line at the top of the menu. Invoking the tear-off entry causes a torn-off copy to be made of the menu and all of its submenus. Even the popup menu can be torn-off.

palette [palette spec]

Defines the color scheme. The most simple way to do this is by specifying the name of a color to use as the normal background color (see colors(n)); a complete color palette will be computed from this background color. If you need more tuning, see tk_setPalette(n). Note that the following options fg, bg, selfg and selbg override some of the colors defined by this scheme and they are required also.

fg [color name]

Text foreground color. See colors(n). I prefer black on white as on paper. Just make sure there is enough contrast.

bg [color name]

Text background color. Ditto.

selfg [color name]

Selection foreground color. Ditto.

selbg [color name]

Selection background color. Ditto.

editfont [font desc]

Choose the font and size to use for the textarea. If you want to change this you should read the font(n) manual page (skip at section FONT DESCRIPTION if you are in a hurry). Also, for best results and better performance, choose a font that is capable of displaying all the glyphs you expect to display, depending on your I/O encodings.

statusfont [font desc]

Font to use for the status bar. Ditto.

lpr [shell command]

This command will be invoked by the Print option in the File menu to send tpad's buffer to a printer. It must be a filter program. Under Unix you can use lpr(1). See this manpage for a description of the option you can add. For example under FreeBSD if you want to use pr(1) to paginate the output you can make this variabile value as {lpr -p}. You can also change this variable at runtime using the File/Print Setup menu option.

logfac [no,yes]

Turn log creation facility on/off. Log creation facility is on by default, which is useful to people who need to write log or diary files. If for some reasons you don't want it, set this to no.

timefmt [time description]

A string that describes how the date and time inserted by the Edit/Date/Time menu option are to be formatted. Please refer to the clock(n) manual page (see the help about the clock format subcommand). The default value is %c which stands for a locale specific date and time format.

titlefmt [format string]

This controls the title bar string using a format(n)-like string. %1$s, if present, will be substituted for the name of the executable (tpad or tview) and %2$s for the current edited filename.

insertofftime [milliseconds]

Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain off in each blink cycle. If this option is zero then the cursor doesn't blink: it is on all the time. The display line with the insert cursor is redrawn each time the cursor blinks, which causes a steady stream of graphics traffic. Set this attribute to 0 avoid this.

insertontime [milliseconds]

Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain on in each blink cycle.

maxundo [integer number]

Specifies the maximum number of compound undo actions on the undo stack. A zero or a negative value imply an unlimited undo stack. Please note that the greater the undo stack becomes, the more memory is required. For default this is 1 that means you can only undo/redo the last edit action.

browsercmd [command line]

This command will be used to run an external browser when the Help option under the Help menu is selected. You can also use command line options understood by the browser of your choice here.

helpath [directory path]

This must be set to the path to the directory where are located these HTML help files. The index page file name (index.html) will be concatenated with this path and the resulting argument will be the last argument passed to the command specified by the previous constant browsercmd.

placing [{},pointer,widget,none]

This controls how some tpad subwindows are placed on the screen when they are displayed. Possible values are:

value	meaning
{}	place subwindows in the middle of the screen
pointer	place subwindows centered on the pointer
widget	place subwindows centered over tpad main window
none	no placement, leave it to the window manager

The none option is only useful if the window manager is smart enough :) Note that this setting only applies to non-modal dialogs; most modal dialogs are centered over tpad main window regardless of this setting.

maxopenrec [integer number]

Maximum number of entries to keep into the "open recent" list; default is 10 which should be enough for normal usage; use 0 if you don't want any "open recent" list.

openrecfile [file path]

File where to save the "open recent" list; defaults to a per-user file named ~/.tpad_history, but could also be a global file writable by every user; if empty the list will be non-permanent; ignored if maxopenrec is 0.

fmtkind [GNU,BSD,none]

fmt(1) is a simple text formatter which is accessible from tpad as a plugin. Usually, by default, Linux has the GNU variant, while FreeBSD uses a different version. Make sure to specify the right type you have, otherwise you will not be able to invoke it correctly from tpad. If you installed tpad from a package specific to your platform, the default value should be ok.

fmt [command path]

Because under Linux and FreeBSD fmt(1) is part of the standard utilities, you don't need to specify the full path to it. This can only be useful if you want to use a different kind of fmt(1) that can't be invoked simply by name using the current value of PATH or has a different name. For example under FreeBSD, if you install the Free Software Foundation's core utilities (ports/sysutils/coreutils) you will get, among many others, the GNU version of fmt renamed as gfmt. If you want to use this instead of the default fmt shipped with FreeBSD, set this variable to gfmt and fmtkind to GNU.

tk_strictMotif [0,1]

If set to 1 requires strict Motif compliance. It is better to leave it to 0 because it may affect some key bindings. You can find more information by reading the manpage Tk_StrictMotif(3).

wrap [none,word]

Specifies how to handle lines in the text that are too long to be displayed in a single line of the text's window. The value must be none or word. A wrap mode of none means that each line of text appears as exactly one line on the screen; extra characters that don't fit on the screen are not displayed. In the word mode each line of text will be broken up into several screen lines if necessary to keep all the characters visible and a line break will only be made at word boundaries.

pattern [string]

What search pattern do you want for default? If none use the empty string here.

substr [string]

Substitution string used by the Edit/Replace function. Defaults to the empty string.

dir [up,down]

What search direction do you prefer for default? You will be alerted when a search gets to the beginning or the end of the file.

case [no,yes]

Do you prefer case sensitive or insensitive search for default? What kind do you need most of the time?

regexp [no, yes]

If you use regular expression very often, setting this to yes allows you to make the regexp mode for the Find and Replace functions the default.

status [no,yes]

Whether or not you want the status bar for default.

ascii [no, yes]

Set to to yes to display the ASCII table plugin at startup.

format [no, yes]

Set to to yes to display the Text Formatter plugin at startup.

wf [no, yes]

Set to to yes to display the Expat xmlwf plugin at startup.

inputEnc [system,encoding name]

Default encoding to use when reading files. Here the special value "system" stands for the current system encoding; most of the times you will want the system encoding to be the default encoding for tpad I/O, so don't change this option, unless your system encoding is not what you want by default with tpad. Be careful when setting this option to a value other than "system"; in fact if you don't use the right encoding for the language that the document you are editing belongs to, you can lose some characters when you read or save files (these will be displayed or written as a ?). If you sometimes need to edit or view files using a different encoding from what your system uses, you can always change the encodings at runtime inside tpad, using the Format/IO Encodings menu option; when finished, using the same option or exiting and re-entering tpad, you can switch back to the system encoding.

outputEnc [system,encoding name]

Default encoding to use when writing files. Ditto.

As you can see there are also some options related to plugins. They are grouped under a unique "namespace" named after the plugin name. I will not describe the meaning of these options here in detail, to avoid repetitions with the respective tool documentation. For example, you can find a more detailed description of the text formatter by running one of these commands, depending on your flavor of Unix:

$ fmt -h
$ man fmt
$ info fmt

Upgrading

A common problem after having upgraded tpad is that the old configuration files are left in place and must be upgraded manually. tpad will fail on startup if one of these conditions is true:

it can't find a config file
it found a config file, but an error occurred when sourcing it
it found a config file, but the file version doesn't match the program version

Case 3 is commonly encountered after a tpad upgrade and requires a configuration upgrade.

Since the config file may change from version to version, the following configuration upgrading procedure is recommended, for both global and user level config files:

backup your old config file, if you made any changes to it you don't want to lose, or alternatively take note of the changes you made.
copy the new version default configuration file *over* the old one. Administrators should make sure the global config file can be read by any users interested in using tpad with the default system configuration.
edit the new version configuration file copied in step 2 to redo the changes you made to the old config file.

[ Return to Contents ]

Last modified: Sunday, 18-Apr-2010 09:36:13 UTC