Better Templates Help

Name:	Better Templates
Version:	9.5
Last update:	2019-10-17 13:28:28

The Better Templates package enhances the default electric template behavior, by creating electric template rings that can be navigated using Special Keys keyboard shortcuts, and also adds several options for how templates and template hints are inserted into the window. Template rings make it easier to navigate to previous template stops even if the Elec Stop Marker has been deleted, and helps ensure that we don't delete valid occurrences of this marker.
Activate this feature via the Features Preferences dialog using the Alpha ↣ Global Setup ↣ Features menu item. While this is generally a global feature, individual modes can also turn it off if desired. This package does not insert any new menu command, it just introduces new preferences in the Completions Preferences panel, providing extra behavior as described below.
Note that this package will do very little for you if you already make use of the package Elec Completions and have defined (via the Special Keys Preferences panel) a keyboard shortcut that creates Electric Completion templates.
For more information about basic electric behavior that is supplied by default, see the Electrics Help file.
Note: some of the features described here will only make sense in modes that have defined sophisticated electric completions. Bib, HTML, Perl, Tcl, TeX, and most of the Statistical Modes do so. See the help file Electrics Help for more information on how to add more completions for any given mode. Throughout this file, '•' refers to your current setting for the Elec Stop Marker preference.
The additional preferences provided by this package can be accessed via the Alpha ↣ Preferences ↣ Global Preferences ↣ Completions menu item.
See the Testing section below for more information about temporarily activating this feature and opening this prefs dialog to change them. Click here to display the Completions Preferences panel.

Template Prompts

When this package is NOT activated, electric completions will simply insert '•' into your window, looking something like

    if {|} {
    	•
    } •

where '|' indicates the current cursor position and '•' indicates a template stop. You can jump to a bullet using one of the navigation keys: by default, you jump to the next bullet (if any) by pressing Tab or to the previous one (if any) by pressing ⇧-Tab. This default behavior of Alpha may not always be what you desire: not all bullets in a file are necessarily intended to represent a stop.
This is where the Better Template package comes in handy. When this package IS activated, any electric completion containing stops defines a ring and navigation occurs only within the ring. You jump circularly from one stop to the other within the ring and pressing Tab or ⇧-Tab will never jump to a stop which is outside the ring.

Better Templates Preferences

The preferences supplied by the Better Templates package are found in the Completions panel of the Global Preferences (see Alpha ↣ Preferences ↣ Global Preferences ↣ Completions).
By default, this package will also insert an electric template message in the status bar window giving you a hint as to what should be included in the template, something that might look like

    Fill in 'test',  press user-defined keys to move from stop to stop.

    Fill in 'true body', press ctrl-j (shift-ctrl-j) to move to the next (previous) stop.

TIP: you can turn off the tail end of this message by setting the Completions preference for Turn Navigation Msg Off, so that the message will instead just include something like

    Fill in 'test'

    Fill in 'true body'

The Max Template Nesting preference specifies the maximum number of nested electric templates. If the level of nesting of template stops exceeds this value, we clear all the template stops.
The great thing with Template Prompts is that the hints can also be included in the template that is inserted into the window. The Template Prompts preference specifies the way the package displays hints about the stops. It offers five different methods:

Just use 'Electric Stop Marker'
Use marker and status window prompt
Put prompts in the text
Highlight prompts in the text
Highlight, but delete when moving

If the Template Prompts preference is Put prompts in the text then the template will look like

    if {|} {
    	<true body>
    }

Navigating to the next hint (see Ring Navigation below) will delete it, but insert the message into the status bar to help jog your memory. If the preference is set to Highlight prompts in the text then ring navigation will NOT delete the hint, but highlight it instead -- you can just begin to type to remove it.
To only insert '•' without any additional hints in either the status bar or the window, set your Electric Template Prompts preference to Just use 'Electric Stop Marker'.

Ring Navigation

Each time you insert a block of text by electric completion, the set of stops contained in this block constitute a ring. Using the navigation keys (described below), you can navigate from one stop to the other within the ring.
Alpha defines the following actions to enable ring navigation and supplies key bindings for some of them as shown in the next table:

Action	Default Binding	Description
Next Stop		go to the next stop
Next Stop or Indent	`Tab`	go to the next stop, or indent if none is found
Previous Stop	`⇧-Tab`	go to the previous stop
Clear All Stops	`⌃⇧-Tab`	clear the ring stops
Nth Stop		go to a stop chosen from a pick list

The key bindings that trigger the actions can be set or modified in the Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Special Keys dialog (click here to display this Special Keys Preferences panel).
If this package is turned off, the first four actions refer to the presence of '•' within the entire text, and allow you to navigate to the next/previous marker, or delete all of them. The item Nth Stop is undefined unless this package is activated.
With this package turned on, electric insertions create a ring of template stops, and all of these items perform actions relative to this ring. The first benefit of this feature is that Next Stop will never inadvertently jump to and delete any '•' string that appears outside of the current ring.
The second benefit is that if you are currently within a ring and create another electric insertion, this is included within the current ring so that you can still navigate previous stops. This will continue to occur so long as (1) you remain within the current ring, and (2) the number of insertions does NOT exceed the Max Template Nesting preference -- when this number is exceeded, all previous template stops are first cleared.
The third benefit provided by this package is that the Nth Stop item and key binding is now enabled, allowing you to jump to any template stop via a listpick dialog -- stops are identified by their hints.
If, however, you create an electric insertion that is OUTSIDE the current ring, all template markers/prompts are first deleted before the new ring is created. This is also the action performed by Clear All Stops, which again means that any '•' appearing outside the ring will be preserved rather than deleted (a fourth major benefit !!).
Note that the action performed by the binding for Next Stop Or Indent is identical to that for Next Stop SO LONG AS you are still within the limits of the current ring. Otherwise, the current ring is cleared and the current line/selection is indented.

How to exit a ring

The circular navigation among the stops contained in a ring is cancelled under different circumstances:

if you press the key binding corresponding to the Clear All Stops action (by default, this is ⌃⇧-Tab).
if you perform an electric completion outside the limits of the current ring.
if you press a navigation key (like Tab or ⇧-Tab outside the limits of the current ring.

In the case of nested rings, the limits are the start and end positions of the outer ring.

Template Wrappers

If the value for Template Prompts is set to include the hints in the actual template, you can change the wrapper that surround the hints to one of

<Angle brackets> (the default)
“Curly quotes”
«Curly brackets»

Changing this pref has no effect if hints are included in the status bar.

Testing

To test this package, click on this hyperlink: test Better Templates. This will temporarily activate this package, open some dialogs allowing you to set/change various electric and special keys preferences, and then open an electric completions tutorial window in which you can experiment with the bindings.
To turn this package off, click on this hyperlink: deactivate Better Templates.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.
Source code can be found in elecTemplates.tcl, code contributions are always welcome.

License and Disclaimer

Copyright (c) 1997-2019, Vince Darley and Contributors.
Contributors: Craig Barton Upright, Joachim Kock, Bernard Desgraupes.
All rights reserved.
The Better Templates package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Vince Darley nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL VINCE DARLEY OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.