'the following line is here to please nroff, in case you use this as manpage
.nf
#
# README for tkPostit 1.4
#
# Copyright 1993 - A Rubini - DIS - Universita` di Pavia - Italy
#
####

1. tkPostit
-----------

	This  is an  enhanced  replacement  for the package   xpostit.
Current version is 1.4.
	TkPostit is a for-fun project, and won't take much of my time;
Nonetheless, I will  be happy to apply sensible  patches to this code,
wherever they come from. I don't plan  to make new releases, since the
code  is just as  configurable as it  ought to be;  maybe I'll provide
extensions, and/or patches on  harbor.ecn.purdue.edu, if sth  relevant
comes out. Since I am  an heavy  user  of this program, however,  I'll
provide tk-4.0 compatibility as soon as possible.
	TkPostit 1.4 does not provide a Makefile,  nor does it provide
a manual page (though I promised them both). However, this README file
can be    used   as a      manual  page by    copying  it   to   ,say,
/usr/man/manl/tkpostit.l.
	I can't  provide  tags, either,  since my  allowable  time did
collapse. Anyway, when tags will be present  they'll be optional and a
new release will surely appear on harbor.


2. Copying and warranty
----------

	No licence  or fee.  You can  do   anything with these  files
provided some  pointer to the    original author or  organizazion   is
included somewhere in the credits. No warranty whatsoever.


3. System Requirements
----------------------

	Tk 3.3 or greater, tcl 7.0 or greater.


4. Features of tkPostit
-----------------------

-> Backup copies of your notes
-> Backup on destroying
-> Delayed backup, to ease your computer
-> Optional autosave on Mouse-leave
-> Optionally mantains geometry between sessions
-> It provides optional emacs key-bindings
-> It provides optional mac-like bindings
-> User-level overriding of defaults
-> Basic file-editing capabilities
-> On the fly evaluation of tcl commands
-> Alarm/reminder built-in facility

====> It is written in the tcl language

4.1 Enhancements over version 1.2
---------------------------------

- the alarm facility now works reliably
- keyboard grab on menus is instantaneously released
- file editing is now available, and backups are keeped a la emacs
- menus now feature a standard behaviour
- mac bindings for Text are available
- the keyboard arrows are correctly configured
- button 3 on text now works reliably (emacs bindings)
- constrained scroll for text is available
- menus remain inside real screen
- "-geometry" now takes precedence over remebered position
- complete command bar configurability
- capability to print notes
- a global "note manager" window to map/unmap individual notes


4.2 Known Bugs
--------------

- notes can be lost outside the screen, due to strange interactions
	with the window manager, in this case you should edit the note
	file.
- tkpostit has problems placing windows if it is run before the wm -
	all windows fall at top left, thus fixing bug 1 :-(


5. Future of tkPostit
---------------------

	TkPostit  can go on refining  and expanding forever.  However,
since users of  slow  machines (such as  myself)  won't enjoy this,  I
don't plan   to make new releases,   unless tags will  work  and prove
useful.  Upgrades,if  any,  will be silent  uploads  to harbor without
announce on  usenet.  Bug fixes  are nonetheless  welcome,  as well as
simple bug  reports  are.  If  you  want  to be on  the  hot  line for
upgrades just tell me.


6. Compiling and installing
---------------------------

	No compiling, just edit one or two lines in the script
	and copy it iside your $PATH

- Optionally, remove the first four lines of tkpostit and replace the
	pathname of your wish for '/usr/local/bin/wish'. If wish
	is in your path, you can simply skip this pass.
- Then, the first two 'Set' lines (lines 26-27) should be modified to
	retain your actual pathnames (though perhaps they're already right).
- Compulsory: copy and/or rename the bitmap where it needs to be.
	Modify tkpostit source at line 39 to enable finding the bitmap.
- Any other value can be overriden by system or user cfg files,
	however, nobody denies to edit tkpostit itself, though this
	practice can prevent you from easy upgrading to new releases.	

- Finally, you should copy tkpostit in his final directory (/usr/local/bin
	or $HOME/bin or such). The bitmap should go where tkpostit will look
	for it, while this README can be directly used as a man page,
	by copying and renaming it, like "cp README /usr/man/manl/tkpostit.l"

- If something in tkpostit doesn't please your taste, you're encouraged to
	fix it in your personal configuration file. You can even add
	new functionality without touching the main source file.
	If you happen to write something interesting to distribute along with
	the script, feel free to send me your code.

6.1 Other goodies
-----------------

The executable file tknote  is a *short* shell  script that allows you
to open an editor on one of  your notes (I use  it at home, where I've
no graphic access).
	Usage: "tknote <substring_of_notename>"


7. Configuration of tkpostit-1.4 (optional)
-------------------------------------------

	This   sections explains  the   options you  can  set, and the
procedures you can  invoke. This is  only needed to tailor tkpostit to
your personal taste.


7.1 Settings (and default values)
---------------------------------

Set system_config      /usr/local/etc/tkpostitrc
Set user_config        $env(HOME)/.tkpostit
	These are the pathnames for system-wide and user-wide configuration
	files. The cfg files are tcl sources, and can override any of the
	following settings, as well as define new procedures and so on.

Set my_name		<nothing>
	This is the name by which tkpostit is invoked, and is used
	to re-read configuration at run time, when asked by the user.
	This variable can be unset, in which case $env(PATH) is searched.

Set canvas_width     66
Set canvas_height    66
Set canvas_bitmap    /usr/local/tools/lib/tkpostit.bm
Set canvas_x_pos     "11 33 55"
Set canvas_y_pos     "11 33 55"
	The main window is tiled with bitmaps and these 5 settings detail
	how to place the tiles. The bitmap supplyed is 22x22 pixels big
	and is replicated on a 3x3 grid

Set button_font      "fixed"
	The font used for buttons is defined here. Other fonts can be
	specified during command-bar configuration.

Set data_dir           $env(HOME)/.tkNotes
	This is the directory where tkpostit will load and save your notes,
	their backups, its own geometry and, maybe, other data.
 
Set data_file_mode    640
	The notes undergo a chmod command, and this is the chosen mode

Set remember_geometry   1
	This is a boolean value, telling whether tkpostit should place itself
	in the same position as it was at the previous invocation.
	Anyway, a -geometry command line switch will take precedence.

Set grab_type        local
	Grab on menus can be either local or global. 

Set backups_allowed         2
Set initial_delay       20000
Set incremental_delay    2000
	You can choose between 0 and 3 backup copies for your notes.
	The backups are created some seconds after tkpostit is run,
	and the two delay values are expressed in milliseconds.

Set save_on_modified    1
	This boolean value tells wether to save the note anytime you
	modify it (it saves as soon as the pointer leaves the note).
	However, a few percent of changes are lost due to "bind"
	behaviour.

Set save_regularly     30
	The number is the delay in minutes between two auto-saving events.
	Zero means 'no auto-save'.

Set keep_destroyed      0
	You can choose to keep a backup of a note when you destroy it,
	or even two backups (at two successive destructions). Zero
	means that when destroyed it is lost forever.

Set note_init_width     20
Set note_init_height    10
Set file_init_width     80
Set file_init_height    25
Set text_wrap_mode      word
Set text_font           fixed
Set scrollbar_side      left
        This set of options configures the text widget. The initial
	size is different for notes and file editing.

Set constrained_scroll   1
	You can force a text widget not to scroll past end-of-file.

Set text_editor_background   bisque3
Set text_editor_foreground   black
	In order to differentiate between notes and file editors, 
	you should specify a non-default color for text editors.

Set file_backup_suff ~
	File editors provide one baclup copy, built using this suffix.

Set emacs_bindings	1
Set mac_bindings	0
	A boolean value telling if you want emacs-like keybindings
	and another to tell if macintosh bindings are your best choice.
	If both are zero tk bindings will remain. (Emacs bindings are
	quite poor, and contributions are welcome).

Set verbose_mode    0
	Verbose mode is a debugging facility, and enables messages as files
	are saved to disk.

Set menu_bg     black
Set menu_border 1
	Menus are actually toplevels, and a bounding frame is needed.

Set reposition_menu             1
	If menus are repositioned they're always inside the screen, but
	they flash while being posted.

Set pipeout_print   {a2ps -H$name | lp}
	The "pipeout_" settings are filters for note contents. You can
	specify as many of them as you want.

Set manager_withdrawn ""
Set manager_iconified ""
Set manager_normal ""
Set manager_check_relief flat
Set manager_frame_relief ridge
Set manager_frame_border 2
	The note manager is the thing you use to withdraw, iconify
	or map on screen individual notes. You can choose some features

Set cmdbar_border               4
Set cmdbar_relief               groove
Set cmdbar_background_note      default
Set cmdbar_background_file      default
 	The command-bar is completely configurable. This configures the
	bounding frame, while the following table configures its contents.

Set cmdbar_cfg_note {
        {button .s "Save" Save
                {-font $cfg(button_font) -relief raised}
                {-side left}}
        {label .l "Title"
                {-font fixed}
                {-side left}}
        {button .d "Close" Destroy
                {-font $cfg(button_font) -relief raised}
                {-side right}}
        {name_entry
                {-width 16 -relief groove -font fixed}
                {-side left}}
}
	cmdbar_cfg_note is a list used to build the command bar.
	cmdbar_cfg_file is their sister used for file editors.
	Each item in the list is a list itself. Each item has one of
	the following forms:
    {button <win-name> <text> <command> <widget-options> <packer options>}
    {label <win-name> <text> <widget-options> <packer options>}
    {menu <win-name> <text> <menu-name> <widget-options> <packer options>}
    {name_entry <widget-options> <packer options>}
	"name_entry" is mandatory, while the other can appear
	zero, one or more times.
	Button commands are invoked with the name of the invoking window
	appended.


Bind main:<1>	"MkNewWin new"
Bind main:<2>	"MkMenu main %X %Y"
Bind main:<3>	"ChangeState iconify"
Bind main:<Control-1> "MkMenu eval %X %Y"
Bind main:<Control-3> "MkMenu eval %X %Y"
Bind main:<q>   "SaveAllNotes; exit"
Bind main:<m>	"MkMenu main %X %Y"
Bind main:<Control-c> "exit"
	These are the bindings associated to the main window of tkpostit.
	You can add any binding you like, or change these, provided
	you follow the same syntax.

Bind note:<Control-1> "MkMenu window %X %Y"
Bind note:<Control-2> "MkMenu sleep %X %Y"
Bind note:<Control-3> "MkMenu eval %X %Y"
	As before, these are the bindings on the text widget. You can
	add or change.

Menu main {
	{ label "tkPostit-1.4" }
	{ button "save all"  SaveAllNotes }
	{ button "withdraw all" "ChangeState withdraw" }
	{ button "iconify all" "ChangeState iconify"}
	{ button "show all" "ChangeState deiconify" }
	{ button "manage them" NoteManager}
	{ button "restart"  Restart }
	{ button "quit"      "SaveAllNotes; exit" }
}
	This is the main menu. You can add new menus and change or override
	proposed menus. The menu is a list of lists. Each item in the list
	has one of the following forms:
    {button <text> <command>}
    {label <text>}
	Other menus are not copied here, just look at the source code.



7.2 Builtin Procedures
----------------------

The following is a description of builtin  procedures, but you can add
your  own by  writing  tcl  code  in your  cfg  file. The  description
provided here is  quite terse, since  the best source  of info is code
itself.

MkNewWin <name> [<detail>]
	Creates a new note. If name is 'new' a new note is created.
	If $name is "-file" the file $detail is edited.
	Otherwise, the note $name is loaded.

BaseName <widget_name>
	Returns the name of the toplevel embedding widget_name.

MkNewName <widget> <name>
	Changes the name of the toplevel embedding widget.

CatchScroll <win> <a> <b> <c> <d>
ConstrainedScroll <win> <start>
	These are used to implement constrained scrolling of text

Save <name>
	Save the note on file. name must be the same form as "note3" and
	the note must already exist.

SaveAllNotes
	This takes no arguments, and saves all the notes.

ChangeState <action> <args>
	Used to 'iconify', 'deiconify' or 'withdraw'.
	If $args=="me" it acts on the current note.
	If $args=="-note $name" it acts on $name
	If $args=="" all notes are acted upon.

PipeOut <mode> <win>
	Pipes the contents of $win through the filter $cfg(pipeout_$mode)

Destroy <name>
	Destroy a note, but ask the user first. name must be the same form as
	"note0".

RemoveFile <fname>
	Removes a note file and, if chosen, keeps backups. Refer to code.

MkMenu <name> <x_pos> <y_pos> [<exact>]
	This posts a menu. name must be the name of a menu configured
	into tkpostit, as explained in section 7.1. x_pos and y_pos
	are the position where to put it, and usually are %X and %Y from
	an event binding.
	If exact is not specified menus a re repositioned on screen

MkBackup <fname>
	Makes backups, if you have chosen to.

MkSleeper <time_in_minutes>
	Forces the current note to be withdrawn, and to pop up
	after the specified time.

MkEval <program>
	This executes the told tcl program, and places its output at the
	insertion cursor in the current note.

NoteManager <args>
	This creates a note manager window.
	If $args=="reconfig" it doesn't destroy an existing window

Restart
	Causes tkpostit to reread its source file and configuration,
	like you killed and restarted it.


7.3. Toplevel classes
---------------------

The toplevel tkpostit creates belong to the following classes:

tkpostit     the main window is named according to the executable file
tkNote       the note windows belong to this class
tkNoteEdit   file editing windows belong to a different class, so
		you can give them a different color in the icon-manager


8. Suggested modifications to your .vtwmrc
------------------------------------------


 NailedDown
   {
   "tkpostit"
   "tkNote"
   }

 IconifyByUnMapping { "tkNote"}

 NoTitle
   {
   "tkpostit"
   }

9. Bug reports and suggestions
------------------------------

rubini@ipvvis.unipv.it

10. Acnowledgements
-------------------

All the relevant coding has been made by John Ousterhout and the UCB.
I have only played with the toy they let me steal.

Gregor Schmid (schmid@fb3-s7.math.tu-berlin.de) provided constrained-scroll
Hoshi Takanori (hoshi@sras31.sra.co.jp) provided mac-bindings
Normal Walsh (norm@ora.com) wrote the first font configuring code


'what follows is here to please nroff
.fi
