Flash mechanism for Alpha

Download for xdvi
Download for TeXniscope

# Flash mode prototype for Alpha (with xdvi or TeXniscope)
# ========================================================
# 
# 
# Overview
# --------
# Flash mode is the feature peculiar to Textures, by which a preview window
# continuously reflects the changes in the source document.  Recently Claus
# Gerhardt has implemented a version of this as a compiled AppleScript
# application controlling an editor and a previewer.
# 
# The present Alpha 'plugin' is a short Tcl script to achieve a flash
# effect between Alpha and xdvi (or TeXniscope).
# 
# It's approach is different from Claus Gerhardt's in two main respects:
# 
# 1) it doesn't modify the source file itself, and uses instead a temporary
# file, together with a dynamically precompiled custom tex format.
# 
# 2) it works by notification instead of by polling.  Instead of having the
# various components check every fraction of a second if there is anything
# to do, the components here communicate via a two-way pipe and via event
# hooks, notifying each other when an action is required.  This means there
# is no unnecessary waiting time -- the updating occurs as soon as
# possible.  (It also means that when idle (nothing is typed in the tex
# source window), the workload is zero.)
# 
# 
# Speed and usability
# -------------------
# I am testing this on my good-old 500MHz G3 iBook (without Quartz
# Extreme).  The mechanism typesets a 2-page document about 90 times per
# minute (which I think is comparable to what Textures achieves on
# documents of this length (?)), hence the maximum amount of time elapsing
# from a character is typed until it appears in the preview window is about
# 0.66 seconds.  (These measurements are for xdvi.  TeXniscope takes a 
# little longer.)  However when the document is in an unstable state
# (unmatched dollar sign or such), the gap can be somewhat longer.  For
# long documents, there is an option to preview and flash only the
# surroundings of the cursor, i.e. only current paragraph.  This works at
# about the same speed, independently of the size of the document.
# 
# 
# Shortcomings
# ------------ 
# This is only a prototype.  To keep the flash script as simple as possible
# in this phase of development (and because of general laziness), I have
# refrained from several obvious refinements.  The current shortcomings
# include:
# 
# The window geometries are currently hardcoded to fit on a 1024x768 
# display -- squeezed!  It would not be too difficult to automatically
# adjust to the screen size, or provide these settings as preference flags
# where the user can write his own idiosynchrasies.
# 
# Because the pdf is produced from a temporary file, right now standard
# synchronisation doesn't work optimally together with flash mode: all
# line indications are shifted by the number of lines in the preamble!
# Fixing this will require a few tweaks to Alpha's synchronisation code,
# but there is no technically difficulty in this project.
# 
# The partial flash mode is certainly not very well polished, and fails
# if you are typing near the top of the document!  It is just a very quick
# hack...
# 
# I don't think it works in AlphaTk, since I have been a bit sloppy with
# file positions...
# 
# 
# Instructions for installation and usage
# ---------------------------------------
# Place this file /anyhwere/you/want and write the following line in
# your prefs.tcl file:
# 
#     source /anywhere/you/want/flash.tcl
# 
# Then restart Alpha.
# 
# To try out the mechanism, open a tex document (a self-contained latex
# document) and press F2.  Then start typing.  To stop the mechanism, press
# shift-F2.  (The mechanism also stops automatically when the source window
# is closed.)  (If these keyboard shortcuts are in conflict with others,
# you can change them using Alpha's usual syntax for key bindings, e.g.
# 
#     Bind 'a'  TeX::flash::startFlash TeX
#     
# to use Shift-cmd-opt-ctrl-A.)
# 
# You can save the document when you want, it has no direct influence on
# the flash behaviour, except that changes to the preamble only take effect
# when the document is saved.
# 
# To try out the partial flash mode (typesetting only current paragraph),
# you have to write the following command in the AlphaTcl shell (Cmd-Y):
# 
#    set TeX::flash::partialFlash 1
#    
# If you want this as a permanent setting, write it in your alpha.tcl file.
# 
# 
# Technical remarks
# -----------------
# A flash cycle consist in the following actions: write the temp file, tex
# the temp file, move the pdf file to replace the original, refresh pdf.
# The flash mechanism is busy when any of these actions takes place,
# otherwise it is IDLE.  The flash mechanism can be triggered by two sorts
# of events:
# 
# -- when a character is typed in the source window (and if the mechanism
# is IDLE).  This is detected by the characterInsertedHook [detectTyping].
# 
# -- when the cycle terminates (and if the window is DIRTY).  This is
# detected by the pipe-readable eventhandler [detectSignal].  The window
# is considered DIRTY if a character has been typed after the flash cycle
# has been initiated.
# 
# The flash cycle is initiated by [writeTempFileAndContinue], who then
# sets IDLE = 1 and DIRTY = 0.  Setting these variables in the other 
# direction is done by the two triggers just mentioned.
# 
# A custom tex format file is maintained, corresponding to the content of
# the preamble of the source file.  Whenever flash mode is turned on and
# also whenever the source file is saved, there is a saveHook that checks
# if the preamble has changed (comparing a checksum with one recorded when
# the format was built).  In that case the format file is rebuilt.
# 
# Note: the hooks are written for old-style pre-8.0 AlphaTcl.  They can 
# be simplified in AlphaTcl 8.1.