:Subscript Help: 		  General and detailed help for Subscript

;###########################################################################################
;tag
;  @`TAG-Mark` List 


::Subscript v1.2:

;###########################################################################################
;tag
:A. General:

 Subscript creates a table of lines within an editable file which contain a predefined "label".
 The Label consists of predefined characters (Marker) which must appear within the selected 
 lines.

 The Table, which can be alphabetically sorted, shows text adjacent to the label and selecting
 the entry from the Subscript table clears the Label-List and sends commands to the editor 
 to find the selected line in the file. For default extensions listed on key "TxtTypeExt=",
 when the Label-List appears, pressing a letter (A-Z) will locate the entry starting with the 
 same letter. 
 The "Search" command string is configurable for editors specified in the "Subscript.ini" 
 file, (the default command is [CONTROL]-F), and default for "GOTO-LINE" is [CONTROL]-G).
 The "Clear-Block is optionally configurable.

 The option exists to redefine label selection to include a marker at the START-of_Line, marker
 at START OR END of line, or lines with predefined markers at BOTH START AND END of line.

 Labels can be predefined within Subscript.ini for different specified file .extensions.
 In addition, provision is made for defining an ALTernate Label marker, to select a different
 group of lines.

 The Label-List can optionally also display last 10 selected Labels, and allows rapid 
 selection of top of file (@TOP entry) and END-of-file (~~Bottom~~). The Label-List can be
 scrolled to show remaining text (comments) on the marked lines.

 Also, the program allows creation of a file "TAG-list" recording Line-No. and starting text
 to quickly TAG up to 10 locations within a file, facilitating fast return to originally 
 TAGged locations. These locations do not need associated Label-markers.
 These TAGGED locations are stored along with the associated filename for up to 20 files and
 remembered between editing sessions.

 Within the program ini file, provision has been made to quickly define up to TWENTY NEW file extensions, along 
 with START marker, END marker, Alternate marker and marker selection mode,
 (eg. START/END of line, or BOTH).

 The following file extensions are predefined within Subscript for extensions:
			 .txt,.txx,.bat,.ahk,.rtf,.doc,.docx,.dot.
 using a colon at START-of-Line, or END-of-Line. The Alternate marker is a double colon "::"
 to mark "Headings".

 The INI file extension ".ini" is also predefined for section labels within the program
 The program will automatically identify Section Labels within .ini files.

 The example Subscript.ini file provided, uses the first configurable file extension to 
 provide a simple example for .HTML files.

 HotKeys:
   [Shift]f5:   	Restore program Label-List, or if Label-List displayed, refresh List
   [Alt][Ctrl]esc: 	exitapp
   [Alt][Ctrl]F10:	exitapp
   [Alt][Ctrl]f5:  	Create a "Tag-Marker" line in file: 

   [Shift]f5:       With no Active window containing defined .extension, Subscript exits
   F5: 				Toggle list for Labels OR ";Tag-Marker" for Selection. Configurable.
   F10:				Clear Subscript Table

Tag-Marker:
	Employs ";tag-Marker" lines written into file for search
    Uses ";tag" as the marker key to jump to a sub/routine
	whatever is on the next line after ";tag", is displayed in the subscript window as
	TAG label.
  	Ctrl+ALT+F5 will insert one where ever it is needed. (NOTE: THIS ALTERS THE FILE!)
	The two following shows the current "Tag-Marker" befor a label:

;###########################################################################################
;tag
:B. Requirements:

The program is a utility which works closely with a program editor or text editor. It requires an editor which offers Keyboard shortcuts for the following facitities:
 "Search" facility (Usually initiated with Control-F)
 "Goto Line", default is Control-G

The program assumes the following keyboard shortcuts:
 "Goto Top", default is Control-Home
 "Goto Start of line", default is [Home] key
 "Goto End of line", default is [End] key

The program requires the edited filename to appear in the Editor's Window Title.

	platform:       win9x/nt/xp/vista/Windows 7
 Subscript has been tested on XP and Vista

;###########################################################################################
;tag
:C. Install:

 UNZIP zip file to the directory from which the program will be run.
 Included in zip is "Anchor.ahk" which is needed by the program.

 With the use of a hotkey management program to provide a program-specific hotkey/macro set,
 program [Shift]+F5  to run Subscript.exe, (under Editor s/r),

 Using AutoHotkey, the following line can define [Shift]+F5  to run Subscript.exe
	+F5::Run, [Drive]:\[Path..]\Subscript\Subscript.exe
 	
 or if Editor permits programmable Tools, call program from within the Editor.

 Alternatively, Subscript can be run using a Desktop shortcut

 When first run, (from within an editor displaying a file with a preselected extension, 
 eg. .txt,.bat,.ahk file), if an inappropriate or no subscript.ini file exists, the program 
 will take a little time initially to create a basic subscript.ini file.

 The default hotkey to display label/Tag-Mark lines is [Shift]+F5 (configurable in the ini file.)

;###########################################################################################
;tag
:D. OPERATION:

If subscript is run while editing a file with a preselected extension, (an ".ahk", .txt or .bat, .rtf, .doc, .ini .. etc.), the program creates a Table listing "Labels:" or ":Headings"(or ";Tag" marker, according to  settings) contained in the ".ahk" or .txt or .bat script. These are the default extensions, to which others can be added using "Setup Label/Tag", or pressing hotkey "F5" when Subscript menu is visible.
(Right-click Taskbar icon).

 If an Entry within the table is selected, the program will use the Editor (Active App) to 
 locate the Label (or ";Tag" marker).
 Also operates on .BAT files or .ahk files(ie. for ":Headings" . . ), where Labels have 
 a colon ":" at the start/end of line.
 
 The default for text (.txt) and .RTF and .DOC or .DOCx is :label or Heading:
 The default for Alternate marker is defined as a double colon "::"
 For .txt files which have not been pre-configured with a preceeding colon, ":...(Headings)",
 for Subscript to locate and store as "TAGS", selecting "@T-Lmark: + END" in the Table listing 
 will include lines which END a portion of text with a colon, since these lines are often 
 useful. 
 To change the Text file default from a colon, see example subscriptALT.ini, which allows 
 modification of label marker for .txt, .RTF and .DOC or .DOCx files, by transfering the
 extensions from key "TxtTypeExt=" to PresetExtN2= key. Remaining keys still define Colon 
 markers ":", but can easily be changed.
 (subscriptALT.ini would need to be renamed as subscript.ini in this case).

 Selecting "@T-Lmark: START" restores the default start of line marker as selected Label mark.
 Selecting "@T-Lmark: + END" shows lines with either Start-of-Line OR End-of-Line markers.
 Selecting "@T-Lmark: BOTH" shows only lines with both start-of-line and End-of-Line markers.

 If the top entry in the table, "Reload S-List" is selected, The Label-List is updated.
 If the Hotkey (Default:[Shift]F5)is pressed when Label-List is displayed, the Label list will
 be updated.

 Selecting "SORT List ON/OFF" at the top of the table will toggle list-SORT option. 
 Default is SORT OFF (ini file key: SortLst=0), so labels are not ordered alphabetically.
 When Label-List is displayed, select label using mouse or cursor keys. Typing a letter will
 move successively to each entry starting with the letter pressed. "Enter" selects label.

 Label-List also includes:
 	" @Reload S-List" 	- Create new Label-list (Exclude defined "AltLabel" Subs)
 	" @Reload Alt-List" - Create new Label-list (using only defined "AltLabel" Subs)
 	" @SORT List On"	- Set display to "Sorted"
 	" @T-Lmark: + END" 	- Switch Label marker to START/START or END of line, or BOTH 
 	" @TOP" 			- Goto top of file
 	"~Bottom"			- Goto end of file

 AltMark:	(Default)
 For ".ahk",".bat",".txt",".DOC","RTF" files, AltMark is a Double-Colon, "::Label" or "Label::"
Note: This is configurable within the subscript,ini file.
 More sophisticated editors allow Syntax highlighting, which can be configured using Regex
 to colour/highlight headings and labels like ":Heading", or "SubHeading::" and "Heading:".
 Subscript can provide fast navigation to "labels:" and ":Headings" and ":Labels"

 For text files, headings of the form "Label::" can be used for automatic Folding if editor 
 permits this.

 REM or "comment" text after ":label" [;]...text... is also displayed if subscript window is 
 scrolled or enlarged.
 
;###########################################################################################
;tag
:"Previous-Label" feature:

 For "Labels-List", the last 10 labels selected can be shown beneath " @TOP" in the table, 
 these "Prev-Labels" being stored under the "filename" edited, in SubscrTag.ini, which stores
 data for the last 20 files for which subscript was called. After the list of "Prev-Labels"
 there is an entry " ~~~~~~~Clr~Prev~", which if selected clears the "Previous-labels" listing
 from the subscript list and SubscrTag.ini file, (No alteration is made to the edited file).

 "Previous-Label" feature can be turned on/off by Right-clicking the Taskbar icon and 
 selecting "Setup Label/Tag". Clicking on "Cancel" to the first prompt, move directly 
 to the "Previous-Label" Prompt.
 
 Note: 
 The more recent Prev-Labels are placed higher in the list, unless List is "SORT ON", in
 which case they are alphabetically listed.
 
 Only the settings for the Last 20 filenames are kept.
 
;###########################################################################################
;tag
:"Label-Tag" List:

The program also provides a quick "Label-Tag" List to record 10 locations, which are saved
and recalled for the last 20 edited filenames in which subscript was run.

The "Label-Tag" List (not to be confused with ";Tag-Marker" Labels which are physically written
into the file) is created by storing the line position (and current line content) when the 
Label-List is called, (using [Shift]F5).
To view the "Label-Tag" list, Hold down [Control] while Label-List is displayed.
While [Ctrl] is held down, press a number from (1) - 1(0) to store the previous location in 
the file to the "Tag-No.". If, while [Ctrl] is held down, [Shift]-No. is pressed, the Label 
SELECTED in the "Label-List" is transferred into "Label-Tag-No.". Note that even when [Ctrl] 
is held down, it is still possible to change the selected row in the "Label-List" using the 
keys: "Up/Down" or "Page-Up/Down" or the scroll-bar.

To jump to a position in the edited file stored as a "Label-Tag-No.", press ([Shift]+F5 to 
summon "Label-List", then) hold down [Ctrl] and press [Alt]-No. to go to Label-Tag-No. position. 

To Clear all entries in "Label-Tag" list, hold down [Control] while Label-List is displayed
and press [Shift]-[+], (i.e. [Shift]-[Grey+]). To continue to delete all entries press 
[Shift]-[-], (i.e. [Shift]-[Grey-]).

Do not hold down [Alt] and [Ctrl] keys down longer than is necessary. The program should 
respond quickly and Hotkeys ([Ctrl+[ALt]) will be picked up by the system/editor.

;###########################################################################################
;tag
:"Label-Tag" Hotkeys: 
	
	[Ctrl]:	 			While Label-List is displayed, Hold down [Control] for "Tag" List
	Ctrl+[No.]:			When "Tag" List displayed, Stores current Line No. & Line content
	Ctrl+Alt+[No.]:  	When "Tag" List displayed, returns to Line stored in selected "Tag"
	Ctrl+Shift+[No.]:  	When "Tag" List displayed, stores label focused in Label-List into 
							"Tag-[No.]"
	
 Note: [No.] refers to a numeral in the range: 1,2,3,4,5,6,7,8,9,0
 (Editor should be pre-configured for "Label-Tag" facilities to operate)

Tag-List contents will be stored to the ini file "SubscrTag.ini" under the current Filename 
being edited, and retrieved automatically if the same file is re-edited later,
(up to last 20 filenames limit).

If, while "Label-Tag" list is viewed, Ctrl+Shift+{NumPadAdd}, ie Ctrl-Shift-Grey+ is pressed,
Tag-List contents will be stored to the ini file "SubscrTag.ini".

Also, while "Label-Tag" list is displayed, pressing: Ctrl+Shift+{NumPadSub} or Ctrl-Shift-Grey-,
deletes ALL the Tags.

If the current_Filename section is stored in the ini file, exiting from subscript will cause
the ini filename section to be updated with the current Label-Tags if these were amended. If
the editor is run with the same file, the last stored Label-Tags for that file will be loaded,
(up to last 20 filenames limit).

If at the TOP of the file (Lines N0.1 OR 2), the "Label-Tag" list is displayed and the current
location (and contents) are stored to a Tag-No using Ctrl+[No.], the Line-No and contents
for that Tag-No. will be deleted. Similarly, if the row selected in the "Label-List" is:
	"@Reload List" or "@SORT List" or "@TOP" or "~~Bottom~~" or "~~~~~~~Clr~Prev~"
and [Ctrl]+[Shift]+No. is pressed to transfer Label in "Label List" to "Label-Tag" list, the
the "Tag No." will be cleared.


Note: 
Stored Line Nos. in the Label-Tag list will not be amended if lines above that position in the
file are added to or removed. 
The program assumes that the Editor does not automaically begin a String Search from the 
top of the file.

To move to a stored file position, a search on stored contents is applied, from currently 
20 lines prior to the stored line No., thus reducing the likelyhood of locating to an earlier 
duplicat string in the file matching the stored Search string.
Because of the subsequent stored content search (if stored line has more than 4 characters), 
errors can occur, especially for shorter lines, or if up to 75 characters at the start of the 
stored line is repeated in the file. 
The Label-Tag list should allow file search if EITHER Line No. OR Line Content OR BOTH
are stored in the Label-Tag list.
If the Search fails because the searched line has moved more than 20 lines higher in the file, 
perform a Backwards Search to relocate.

Using "Label-Tag" list switches program automatically to mode: "Persist_fast=2"

Subscript assumes that editors use [Ctrl]-F for "Find", but the "Label-Tag" list needs to be 
aware of the "Goto-Line" hotkey for each editor. The default is [Ctrl]+G.
When necessary, hotkeys to "unBlock" text can also be included in the subscript.ini file.

The subscript.ini file should be pre-configured for "Label-Tag" Line-No references to operate.
Setting the keys: "AutGotoKey= ??" (and "BlockClear= ??" if this is necessary) from the 
"Reconfigure Editor" option (Right-click Taskbar icon) enables the "Go To Line" hotkey which 
the program sends to the editor, to be changed from "[Ctrl]+g" (default).
If [Ctrl] is pressed while Label list is displayed in order to display "Label-Tag" list,
with an editor which has not been preconfigured, the program will present the "Re-Configure"
setup to add the editor presets to subscript.ini when subscript is run for the first time.

The Default for AutGotoKey is [Ctrl]+g (= ^g). If "Enter" is pressed on the Re-Configure box, 
AutGotoKey will be set to "0", disabling subscript "GoToLine" functions.

;###########################################################################################
;tag
:HotKeys programmed into Subscript.ahk, (.exe)

	F5: 				Toggle list for ":" Labels OR ";Tag-Marker" for Selection. Configurable.
	[Shift]+F5: 		Show/Refresh list of Labels / ";Tags" for Selection. Configurable.
	[Alt]+[Ctrl]+F5: 	Write ";Tag" + Separator line
	[Alt]+[Ctrl]+Esc: 	exit
	[Ctrl]+[Alt]+F10: 	exit
	[Escape] OR F10:	Suspends subscript, hides program window or quits, to return to editor
						(program only suspended when "Persist_fast=2" or 1, or quits if =0)
	F1:					(If Label-List displayed) Run README.TXT help file 
 											(Requires .txt file association)

If the Hotkey (Default:[Shift]F5)is pressed when Label-List is displayed, the Label list will
be updated.

To indicate TAT Marker on display, include (at top of file) the following lines:-
;###########################################################################################
;tag
Followed on next line by:
;  @`TAG-Mark` List 
	
Note: If "Persist_fast"=2 in the .ini file, under [settings], (and Subscript was not launched 
from a shortcut previous to the Editor being called)
when the Editor is closed, or switched to a file which is not a configured extension,
".txt", ".bat", or ".ahk", subscript will be closed.

 If the Editor "WindowTitle" does not show the current edited file and extension,(eg. .AHK  or 
 .TXT  or .BAT etc,) the editor must show filenames in Tabs, these being first Window controls.
 Subscript should work with most editors.

;###########################################################################################
;tag
:E. DEFINED Labels:

Click on item in List to jump to Subroutine Label/";Tag"-Marker
Selecting "SORT List ON/OFF" will toggle list-SORT ON or OFF
For .ini files, labels start with "[" and end with "]"
For .ahk files, labels end with ":"
For .BAT files, label line starts with ":"
For .Txt and other files, label lines start or end with ":" depending on selection made, for 
    the default  subscript.ini file


;###########################################################################################
;tag
:INI File: - keys used:

[Settings]
InitConfigini=0		(Default=0), if =1: Adjust Table height for font & Screen Res.
ConfigEdt=1			Enter "configure Subscript" when next run
SscrHKey=+F5		Subscript Hotkey - Key to call Label-List
Persist_fast=2		if =2   Subscript exits* when Editor/configured .Ext not Active window
			if =1  	is Persistant (TSR), with fast mode- but no SetTimer-(autoExit)
(test only)	if =0  	prog is NOT Persistant, always rescan Editor, Exit after "Find"
labelscout=1		if =1 (Deflt), Use Labels, e.g. ":", if = 0 - use ";Tag"
SortLst=1			if =1 (Deflt), Label-list sorted, if =0, unsorted
fontsize=10			Set according to preference
ScreenHeight=600	set by program
rowheight=17		set by program
winheightwaste=70	set by program
PrgPreset=(editor)	Title name for Active Editor

ALLPresetPrg=0_Default,other_editor,..	
					Lists Window title names for precofiured Editors
EndMkMode=0			Use default Label Marker only at start of line,
					 (if = 1, use START OR END markers, if = 2, use BOTH
ALLPresetExt=.txt,.txx,.bat,.ahk, etc.:	
					Lists configured file extensions, excluding "Preset" .extensions
TxtTypeExt			The default Text file type extension Label marker (colon ":")- configurable
TxtTypStMark=:		StartMark for "TxtTypeExt" extensions (default is colon ":")
TxtTypEndMark=:		EndMark for "TxtTypeExt" extensions (default is colon ":")
TxtTypAltMark=::	AltMark for "TxtTypeExt" extensions (default is colon "::")
TxtTypREMMark=		Comment Mark for "TxtTypeExt" extensions (default is colon "")
PresetExtN1=.html,.htm			(Preset .extension "N1")
StartMarkN1=<H1,<h1,<H2,<h2,<H3,<h3,<H4,<h4,<H5,<h5
EndMarkN1=			
AltMarkN1=HREF =,href =,HREF=,href=
EndMkModeN1=0		If =0, START-OF-LINE, if = 1, use START OR END markers, if = 2, use BOTH
REMMarkN1=			marker denoting "Comment" statements
SpaceExclN1=		Allow spaces in Labels (if =1, spaces excluded)
PresetExtN2=
StartMarkN2=
EndMarkN2=
AltMarkN2=
...
[0_Default]
PrgPrmpt=UnSpecified
PrgPreset=0_Default
AutGotoKey=0

[EditPad]
PrgPreset=other_editor			A word from window title for Active Editor
WinTitle=Editor_name
PrgPrmpt=General Editor:		Window description
AutGotoKey=!l				Keys sent to editor for "Goto-Line"
AutFindKey=^r				Keys sent to editor for "Find" (/+Replace) text
BlockClear={F8}{F7}{F7}{F8}^+{F9}

[...]
other Editors

;###########################################################################################
;tag
INI Keys::

Hotkey characters used within subscript.ini for "Goto-Line", "Find" and "Clear-Block".
need to be redefined as necessary for Hotkey as follows:-

[Alt] = !`, [Shift] = +`, [Ctrl] = ^, [WIN] key = #, F1 - F12 = {F1} - {F12}

Note:  if AutGotoKey = 0 program presets to ^g  (i.e. [Ctrl]+g)
Note:  if AutFindKey = 0 program presets to ^f  (i.e. [Ctrl]+f), or ^r for EditPad
Note:  It is not normally necessary to redefine "Clear-Block"
The defaults are used when keys are missing from the .ini file
The program might not function correctly with non-standard editors.

;###########################################################################################
;tag
:Label Search:

The normal "Setup Label/Tag" (right-click Taskbar icon) uses Labels, NOT "Tags",
as Label-List does not require any changes to be made to the edited file.
SetUp Label/TAG will Re-check Screen settings & select listing of "Labels" or ";Tag" markers.

This version includes a special facility to allow the hotkey [Ctrl]+R (Default)in EditPad Pro 
Editor, to call "Replace" prompt. (The Hotkey is re-settable in the INI file.)
The search string is then entered and the "Repeat Find" key,[Ctrl]-f, is then sent to the 
Editor.
(For EditPad, Tab characters change focus in the "Search & Replace" prompt to the 
"Replace With" entry pane, so Tabs in the "Search" string need to be replaced with [Shift]+Tab, 
allowing subscript to refine the search).

The "BIGNOTE" feature is now removed.


There is support for .BAT, text file (labels) ":Headings", and ".AHK" "labels:"

In ALL cases, {Tab} characters are automatically removed from Search text.

Default .txt type extensions::
File labels of the form ":????? [Tab] ;Comment", or "?????:[Tab][;]Comment"... etc. are also accepted for the editors tested, using default text file marker.
".TXT" file labels of the form ":A.{Tab}?????",":B. ?????","B: ?????"... etc are also 
accepted as Start Labels, using default text file marker.

REM or "comment" text after "label:" [;] text is also displayed if subscript window is 
scrolled or enlarged.

Currently, the default preselected extensions specified in ALLPresetExt key under "Settings" in Subscript.ini are: .txt,.txx,.bat,.ahk,.rtf,.doc,.docx,.dot

TABS:
However, because editor "Find" windows often cycle through different controls
(e.g. buttons, Replace panel etc.), 1 or more tabs at the start of a line, or 
mid-line TABs in a search line would normally fail for many editors which would
cycle through controls. For this reason, subscript searches on a substring between Tabs 
and searches may fail if the substring is duplicated in the file.

(For EditPad, Tabs are replaced with [Shift]+Tab allowing subscript to refine the search).


;###########################################################################################
;tag
:F. New File/Label Definitions:

The subscript.ini file contains keys for twenty new file extensions under [Settings].
The key "PresetExtN1" up to "PresetExtN20" can each define a new file-extension for the program.
So the file extension "PresetExtN1" allows new Label markers (StartMarkN1 and EndMarkN1)
to provide the Label identifier, both for START of line, or START and optionally end-of-line,
or BOTH, as set by "T-Lmark:" in table.

The "AltMarkN?" permits Label search based exclusevely on the presence on a line of characters
defined by the key "AltMarkN?=" when table-Entry "Reload Alt-List" is selected. 
The normal "Reload S-List" refreshes Label list, but excludes lines with AltMark markers.

As an example, using ini file section names within an .ini file, identified as Labels:
....
PresetExtN2=.ini
StartMarkN2=[
EndMarkN2=]
AltMarkN2=

Note:  .INI files are already programmed into subscript.

The subscript.ini file supplied here is using the first of these presets for a simplified
HTML: definition

....
PresetExtN1=.html,.htm
StartMarkN1=<H1,<h1,<H2,<h2,<H3,<h3,<H4,<h4,<H5,<h5
EndMarkN1=
AltMarkN1=HREF =,href =,HREF=,href=
EndMkModeN1=0
REMMarkN1=
SpaceExclN1=0
.....
The key "EndMkModeN1=0" initially creates label-List by selecting only Start marker,
						if =1, selectes lines containig START-Line OR END_Line markers
						if =2, selectes lines containig START-Line AND END_Line markers

The key "REMMarkN1="	can specify "Comment" marker				
The key "SpaceExclN1=0" denotes spaces are allowed in Labels, if =1 spaces are excluded


:G. Original Program:

	Employs ";tag-Marker" lines written into file for search
    Uses ";tag" as the marker key to jump to a sub/routine
	whatever is on the next line after ";tag", is displayed in the subscript window as
	TAG label.
  	Ctrl+ALT+F5 will insert one where ever it is needed. (NOTE: THIS ALTERS THE FILE!)
    "BIGNOTE" facility. (Now removed)
 
Original program from www.autohotkey.com:

	language:       english
	platform:       win9x/nt/xp/vista
	author:         Trubbleguy <trubbleguy@trubbleguy.com> 
	November 21 2007

