Setext Mode Help
Name:Setext Mode
Version:2.8
Last update:2019-11-27 14:13:01



This document describes the Setext mode for Alpha.

Introduction

Setext stands for [S]tructure [E]nhanced [TEXT]. It is a markup scheme for plain text documents such as email messages and e-zines. Setext's primary goal is to provide a way of marking text that is visually unobtrusive, so that if you don't have a special setext browser, like EasyView, you can still read the text. (Have you ever tried to make sense of HTML source without your web browswer?)
The Setext Example demonstration file is a description of setext concepts written by Ian Feldman. Setext grabbed a foothold in the Mac world with the online publication TidBITS (https://www.tidbits.com/tb-issues/TidBITS-222.html#lnk5).
Alpha's Setext mode not only facilitates marking of Setext files, but also provides a handy menu for file navigation, template insertion, and utilities to create Setext mark-up tags. If you write a lot of text documents and wished you could mark them with Alpha's Marks popup menu (the little box up in the righthand corner of the window), then you might find the Setext mode useful. Or if Alpha doesn't contain a mode for a particular programming syntax, Setext could be adapted to provide a quick surrogate until a proper mode is written for you.

How the file marking works

Any two lines that look like this: 
    Any string of words
    ===================
will be marked as a Chapter heading. Any two lines that look like this: 
    Any other string of words
    -------------------------
will be marked as a Section heading. That's all there is to it.
The keyboard shortcuts Control-Equals (⌃=) and Control-Dash (⌃-) will turn the current line into a chapter or section heading, and re-mark the file.

Setext mode Preferences

All of the Setext mode preferences can be changed when the active window is in Setext mode, by using the Alpha ↣ Setext Mode Setup ↣ Mode Preferences… menu item, which is also bound to F12. Many of the flag preferences can also be toggled on and off using the Setext ↣ Setext Options menu. Click here to display the Setext Mode Preferences.
Alpha's Setext mode is useful even if you are not editing Setext documents. You can set additional preferences, including comment characters, magic characters, keyword definitions, keyword symbols and string colors. In some ways, Setext could be thought of as Text2, with the same functionality, but greater customization available. If Alpha does not have a mode that you need, Setext could be adapted to serve as a surrogate until you've convinced someone to write one for you.

Marking Preferences

Auto Mark
If the Auto Mark preference is turned on, then any window opened in Setext mode that does not have any saved marks will be automatically marked. In addition, whenever a new mark is created using either the Setext Marks menu items or their keyboard shortcut equivalents, the file will be re-marked, and any floating menu of marks will be updated. Click here to display the Setext Mode Preferences.
Mark File As
Setext files can be marked using any scheme available for any other mode. Changing this preference affects all of the various ways to mark a file, i.e. the Marks menu, Search ↣ Named Marks ↣ Mark File, the Re-Mark File item in the floating marks menu ... If this alternate scheme fails (which might be true if the alternative mode's marking routine relies on some preferences specific to that mode), you will be notified. Click here to display the Setext Mode Preferences.

Comment Characters

Comment Character
Comment Color
Comment Pair1
Comment Pair2
Prefix String
Use Paired Comments
Setext per se has no comment character, but I often use one in my README.TXT files. Setext's Mode Preferences now allows the user to define both a single comment character, as well as paired (or bracketed) comment characters. The flag preference Use Paired Comments determines which style to use.
When using single comment characters, be sure to adjust the Prefix String preference as well, adding a single whitespace after the character. Any Section or Subsection heading which is preceded by the single comment character will be colorized using the Comment Color, but the comment character (and any leading white-spaces) will be stripped from the mark.
This is an example of 
 /* bracketed comments */
which can also 
 /* extend 
    over 
    several */
lines. Click here to display the Setext Mode Preferences.

Keywords, Colorizing

Add Keywords1
Add Keywords2
Add Keywords3
Symbols
-
Keyword1 Color
Keyword2 Color
Keyword3 Color
String Color
Symbol Color
Colorizing of keywords is available, including a separate symbols category (for characters such as @ or %). While true Setext might not have any special keywords that need to be colored, you can easily specify three different lists that can be colored individually.
The String color will affect all text contained within double quotes.
The Underline color is used for all sequences of - and = symbols within the window. The Symbol color is used for the list of additional symbols specified with the Symbols preference. Click here to display the Setext Mode Preferences.
If the lists of desired keywords is rather long, the user might rather include them in a separate SetxPrefs.tcl file. To create such a list, select the Alpha ↣ Setext Mode Setup ↣ Edit Prefs File menu item, and add these lines: 
    colors::register keywords Setx keyword1Color {blah bladdity} 
    colors::register keywords Setx keyword2Color {blah2 bladdity2} 
    colors::register keywords Setx keyword3Color {blah2 bladdity2} 
    colors::register symbol Setx symbolColor "!"
Include as many keywords as desired within the braces, separating each keyword by at least one space or carriage return. After editing a SetxPrefs.tcl file, you must select the Alpha ↣ Setext Mode Setup ↣ Load Prefs File menu item. Alpha will automatically load this preferences file when it restarts.
The default mode preferences are intended to show off some of Setext's new functionality, which can be observed in the Setext Example help file. All of these preferences could be set empty if desired.

Magic Characters

Magic Character
Magic Color
The user can also specify one (and only one) magic character. Any alpha-numeric string appearing after the magic character and before the next space will be colored according to the magic color preference. Click here to display the Setext Mode Preferences.

Shift-Command-Double-Click

Search Url1
Search Url2
Search Url3
Search Url4
Setext Home Page
Setext mode contains four Search Url preferences that are initially set to four different popular web search engines. Shift-Command-Double-Clicking on any text will send it to Search Url 1.
Note that Shift-Command-Double-Clicking can also be accessed using the F6 keyboard shortcut. This means that one can first highlight text, and then hit F6 to send a phrase to the first search url. The other modifiers, however, can only send the word surrounding the current cursor point. Click here to display the Setext Mode Preferences.
These urls (as well as that for the Setext Home Page) are also used by the Setext ↣ Setext Help submenu.

Navigation

Navigate Paragraphs
Setext mode allows for two different styles of window navigation, using the Next/Prev/... Paragraph menu items and their keyboard equivalents. Navigating Paragraphs is the default, and makes the most sense for true Setext documents. Here a paragraph is defined by a block of text separated by at least one line which is either empty or only contains whitespace.
If the Navigate Paragraphs preference is turned off, then these menu items (and their keyboard shortcuts) are changed to Next/Prev/... Function, where a Function is defined by a block of text that starts in the first column of a row, and continues until another function starts, as in 
    set Setx::PrefsInMenu {
        autoMark keypadFindsMark navigateParagraphs renderOnOpen
        usePairedComments
    }
    proc Setx::rebuildMenu {{pref ""}} {
        if {[llength $pref]} {status::msg "Rebuilding the Setext menu …"}
        menu::buildSome setextMenu
        requireOpenWindowsHook 1
        Setx::postEval
        if {[llength $pref]} {status::msg "The Setext menu has been rebuilt"}
    }
This is of use only if Setext mode is being used as a surrogate for some programming language. Click here to display the Setext Mode Preferences.
Tip: While the Next/Prev Paragraph/Function menu items are bound to Control-Shift-N/P (⌃⇧N and ⌃⇧P), they are also available using the Arrow keys with Control (⌃) and Shift (⇧). Up/Down will simply move the cursor, while Right/Left will also reposition the window so that the cursor is at the top.
Tip: If there is any selection highlighted when using these navigation items, the selection is extended to the beginning/end of the prev/next paragraph or function.
Keypad Finds Mark
Alpha has the ability to take over the numeric keypad on extended keyboards, and to use various keys for navigation items. In Setext mode, Keys 1 and 3 are bound to either navigate the next/prev paragraph/function, or (if the preference named Keypad Finds Mark is turned on) to find the next/prev mark in the active window. Click here to display the Setext Mode Preferences.

More Preferences

Indent Setx File As
If Setext is being used for a programming mode, its indentation scheme can be set to mimic that of any other mode distributed with Alpha. This will probably take some experimentation. Click here to display the Setext Mode Preferences.
Fill Column
This is the length of a row that is allowed before auto-wrapping of the window sets in, automatically inserting a carriage return. This preference is found in many modes. Click here to display the Setext Mode Preferences.
Word Break
This preference is a regular expression that determines when a word ends, and is used for various word breaking navigation items. In general, it is not necessary to change these settings unless you are using Setext as a programming mode. In that case, you probably want to include any special symbols that can be found in the program's word syntax, such as "-" for LISP files, or ":" for Tcl files. Click here to display the Setext Mode Preferences.

The Setext Menu

Whenever a file is opened in Setext mode, the Setext menu is automatically inserted into the menu bar. This section describes some of the menu items available.

Setext Templates

The New Setext Window menu item will create a new window, using the templates described below. If any of these templates include template stops (bullets • by default), you can navigate this new window using your next stop key, set in the Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Special Keys dialog. This menu item inserts the Header and Footer templates.
Both the Header and the Footer templates can be customized by using the Edit Header etc menu items. These templates are stored as files in Alpha's Prefs folder. Restoring the templates will remove these files, and use the default values set in the setextMode.tcl file. Three additional templates can also be defined, and inserted at any time using the items in this submenu.

Setext Marks

Any line of text can be turned into a Setext mark using the keyboard shortcuts found in the Setext Marks submenu. If the text is already a mark, but is now a different length that the dash line below it, as in 
    This mark has changed
    ==================
then the keyboard shortcut will readjust the dash line, as in 
    This mark has changed
    =====================
If the Auto Mark preference is turned on, then the active window will be automatically re-marked whenever these shortcuts are employed.
If you are using Setext mode as a surrogate for some other syntax style, you can try to mark the active window using any of the other mode file marking procedures available using the Mark File As menu item.

Setext Text

This submenu contains some handy keyboard shortcuts for marking Setext windows using the (never completed) Setext markup specification. These shortcuts will all work on either highlighted selections, or within the middle of some text. The Fill Paragraph menu item preserves the special leading indentation found in some Setext files.

Setext Help

This submenu contains menu items to open the Setext Home Page, a user customized url, this Help file, or a dialog to send some text to a specific search engine. Both the search engine and the home page url can be modified using the Alpha ↣ Setext Mode Setup ↣ Mode Preferences… menu item when the active window is in Setext mode.

Setext Options

Most of the items in this submenu are toggleable menu items that flip various flag preferences for Setext mode. See the sections above concerning specific preferences.

Setext Keywords

While Setext doesn't have any keywords per se, I often find it handy to colorize a list of keywords that I use often within text documents that I'm writing, as in IMPORTANT or NOTE. This menu allows you to manipulate three different lists of keywords. The Alpha ↣ Setext Mode Setup ↣ Mode Preferences… will open a dialog allowing you to change the colors used for each list. Click here to display the Setext Mode Preferences.

Additional Menu Items

Next/Prev Paragraph/Function
These items allow you to navigate the active window, moving the cursor to the next/previous paragraph or function. The Navigate Paragraphs preference determines which style of navigation will be used. See the section above on Navigation for more information.
Select Paragraph/Function
Highights the paragraph or function surrounding the cursor.
Reformat Paragraph/Function
If there is no selection currently highlighted, highlights the paragraph or function surrounding the cursor. Then this region is properly indented. Note that this is NOT the same as the Text ↣ Fill Paragraph menu item, but is instead a simple combination of the Setext ↣ Select Paragraph/Function and Text ↣ Indent Selection menu commands.
New Comment
Inserts a new comment immediately preceding the current paragraph/function in which the cursor resides, respecting all of the comment character preferences as well as Navigate Paragraphs. A standard paragraph style comment is inserted, unless you have previously created a template using ...
Comment Template…
Creates a new template used in the New Comment menu item. Simply type your template in any window, highlight it, and then select this item. The selection will be saved as a Setext mode preference, which can be modified (or deleted entirely) using the Alpha ↣ Setext Mode Setup ↣ Mode Preferences… menu item. If you want to include template stops, which can be navigated using the keyboard shortcut for Next Stop defined in the Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Special Keys dialog, enter two bullets •• using Option-8 for each template stop.
Render Window
Alpha can be used as a Setext rendering engine, converting all marks and typotags to stylized text. See the end of the Setext Example window for more information on the Setext mark-up specification.
Text To Setext
Convert a file with Text style file marks (such as Alpha Help files) to a Setext format. This includes some conversions that only make sense for Alpha Help files, including special hyperlink syntaxes.
Note that while this item properly converts window marks, it probably needs to be refined further to include all of the Setext typotags.

Known problems

Please report any problem or bug you encounter in Alpha's Bug Tracker.

License and Disclaimer

Original Author: Tom Pollard.
Co-Authors: Craig Barton Upright, Donavan Hall.
Copyright (c) 2000-2019, Craig Barton Upright and Contributors.
Contributors: Craig Barton Upright, Donavan Hall.
All rights reserved.
The Setext Mode 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: 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 CRAIG BARTON UPRIGHT 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.