Help Blocks Marking

Alpha
Version:	9.2.3 - "Suhail"
Last update:	2021-05-21 14:43:30

This document explains the marking conventions used in the help blocks of AlphaTcl packages.
For a more global overview of the documentation systems in Alpha, see the file Doc Files Help.

Package 'help/description' arguments
- Text to be included in a window
- Pointers to installed Help files
Package 'description' arguments
Balloon help / Help tags
AlphaTcl Help File Conventions
Auto Marking Help Files
Managing Table Of Contents
Example/Tutorial Files
Hyperlinks
Tools for Auto-Hyperizing Files
Opening Help Menu items
- Exceptions -- .tcl files
- Subdirectories in the Help folder
Help Menu Preferences
Copyright

Package 'help/description' arguments

Every AlphaTcl package defined using one of the following procs

alpha::mode

alpha::menu

alpha::feature

alpha::extension

alpha::library

alpha::flag

alpha::declare

can add an optional 'help' argument to provide useful information about how it is supposed to work, any optional preference settings, etc. The contents of this argument can take one of two forms:

Text to be included in a window

If the 'help' argument is a collection of text, this will be presented in a new window. Here's an example for the package Igor, in igorMode.tcl :

    alpha::mode Igor 1.1.1 igorMenu {*.igor *.ipf} {
    	igorMenu
    } {
    	# Script to execute at Alpha startup
    	addMenu igorMenu Igor
    	set modeCreator(IGR0) Igor
    } uninstall {
    	catch {file delete [file join $HOME Tcl Modes igorMode.tcl]}
    	catch {file delete [file join $HOME Tcl Completions IgorCompletions.tcl]}
    } maintainer {
    } description {
    	Supports the editing of Igor programming files
    } help {
    	Igor Mode supplies a menu for easy switching between Igor and Alpha,
    	and provides keyword coloring.

    	Click on this "Igor Example.igor" link for an example syntax file.
    }

It is best to maintain the AlphaTcl convention of Indent == 4 / Tabsize == 8 in these files, and to indent all of the 'help' text by four spaces. All of the Auto Marking Help Files colorizing tricks will be employed when these help windows are created.

Pointers to installed Help files

If the package has an installed $HOME/Help file, then its 'help' argument should be a two item list, where the first item is the word file and the second is the name of the installed Help file. For example, bibtexMode.tcl can use this:

    alpha::mode Bib 4.4 bibtexMenu {
    	*.bib *.inspec *.hollis *.isi *.marc *.oclc *.ovid *.refer 
    } { 
    	bibtexMenu indentUsingSpacesOnly
    } {
	   # Mode initialization script, evaluated during Alpha's startup.
		set ::mode::interfaceNames(Bib) "BibTeX"
    	...
    } help {
    	file "BibTeXModeHelp"
    }

In this case, the name of the file must exactly match the name of the installed Help file (without the extension). Case-sensitivity is important. The name can also be an absolute path, so long as it can be determined based on its relation to the AlphaTcl hierarchy, as in

    } help {
    	file [file join $HOME Help BibTeXModeHelp]
    }

These items will be opened using the Opening Help Menu items routines as described below.

Package 'description' arguments

Each [alpha::package] declaration can also include an optional 'description' argument, as in the Igor example above. These will be included in the Help ↣ Installed Packages help file, as well as in some dialogs like the Setup Assistant.
The description should be brief (i.e. 3 lines, or at most 240 characters to fit in [alertnote] dialogs or balloon help) and explain some of the extra features provided by the package. The first sentence should be a verb clause -- there is no need to start with "This package/feature provides..." -- assume that this text appears after a listing of the package's name, and that it appears in a listing context.

Balloon help / Help tags

Balloon help may appear in dialogs, or when the mouse passes over an item.
Given that, the text provided by any balloon help is created within AlphaTcl. There are currently two different methods for doing so.
First, all preferences defined using the [newPref] proc can be preceded by a series of commented lines which will be stored in a special help cache file located somewhere within the application's bundle. Here's an example for the preference named Double Spaces :

    # To place two spaces after the '.' at the end of each sentence when
    # filling blocks of text, click this box|| To place only a single space
    # after the '.' at the end of each sentence when
    # filling blocks of text, click this box
    newPref flag doubleSpaces 1

This block of commented text is actually composed of four sections, each of which is delimited by the character "|". These sections are displayed when

Item is turned off, but can be enabled
Item is turned off, but is dimmed
Item is turned on, but can be disabled
Item is turned on, but is dimmed

In practice, only the first and third blocks are used in any preference dialogs, which is why most of these balloon help comments have an empty second argument and separate (1) and (3) by "||". In addition to balloon help, these blocks of text are presented when the user clicks on a Help button in a dialog. Any trailing periods "." will be automatically inserted when this is appropriate, so don't include them in the commented help text.
The second method for creating balloon help is reserved for AlphaTcl packages, again those defined using [alpha::mode], [alpha::menu] etc. as listed above. These packages can define balloon help in their 'description' arguments, as described above.

AlphaTcl Help File Conventions

Regardless of where the Help file/argument is located, some effort should be employed to write the documentation in some sort of canonical format. Given the collaborative nature of AlphaTcl, and the fact that Help files have been written/updated by a wide variety of developers from different countries of origin, the creation of a single documentary voice or style is a challenging proposition. We don't have any paid staff devoted to documentation, although a dedicated corps of volunteers will periodically comb through the various help files and update them appropriately.
The following list of guidelines promote making individual Help files fit into a unified suite of documentation. They are intended to both make writing help files easier for developers and aid the user in finding needed information.
(1) Use the Apple Publications Style Guidelines when appropriate.
While AlphaTcl is a cross-platform library, Apple has taken the lead in providing developers with consistent Human Interface Guidelines that include documentation conventions.
Unless stated otherwise, Alpha's documentation has adopted these guidelines. In particular,

Menu commands should be written as Menu Name ↣ Menu Command, without any ellipses.
Users "select" menu commands (or menu items), they do not click on them or choose them.
The frontmost/current window is the "Active Window".
Key bindings should be referred to as "Keyboard Shortcuts".
Modifier keys should be written as capitalized words, as in Command-F, Shift-Option-H or Control-X O

All of Return, Enter, Delete, Tab and Space are capitalized, no need to surround them with any sort of brackets.
Users "Press" keys on the keyboard, they "Type" text into a window or a dialog text editing field, and they "Click" on dialog buttons. ("Press" refers to a mechanical action on the part of the user, whereas "Click" is a mouse action, and users "Hit" keys only when incredibly frustrated.)

(2) Use consistent Text Filling preferences.
All Help files/arguments should have a Fill Column length of 77, and assume that the Double Spaces text filling preference has been turned on. If all documentarians use these settings, then later changes that are committed to the Subversion repository are less likely to list a lot of changes that are based merely on formatting due to the filling of paragraphs. Assume that the Tab size in all Help windows will be "4".
(3) Turn on the Document Projects feature when writing Help files.
This feature allows for files to automatically update "save" dates in the header. See the Document Projects Help file for more information.
(4) Include version numbers on all help files.
Ideally, this number would correspond to the version number of the mode / feature / menu / extension etc. explained in the Help file. This way future programmers and users will have a much better idea of when a Help file might need to be updated
If a help file is more general, related to all of AlphaTcl rather than a specific feature (such as the Readme, Alpha Manual, Alpha Commands help files), these should take the current version number of AlphaTcl and be updated prior to any major releases.
(5) Don't refer to "new" features
This is a subtle point, but Help documents that refer to new features without any frame of reference won't make sense later -- does "new" mean in the last two months or two years ago ?? (I've found such references in Help files that haven't been updated for a very long time.) Instead, make references to version numbers, as in

    New in version 2.0
    Changes in version 3.1

or to specific dates, as in

    as of September 2003 ...

so that "new" is placed in some context.
(6) Include author / maintainer information for Help files.
The author of the package is not necessarily the author of its associated Help file, and neither of these might be the person who is currently updating or maintaining the Help file. Please give credit where it is due, and include information on where one can send suggestions on the Help file. This will help encourage users to pass on suggestions to the appropriate documentarian.
(7) Include any license and disclaimer notes somewhere in the file.
Help documents are generally placed in the public domain, to remove any doubt about whether these can be placed on web sites or included in archives other than the Alpha releases. AlphaTcl packages are usually licensed using Tcl/BSD/OpenSource style licenses, in which authors retain all rights but allow others to modify. (Note that GNU licenses do place restrictions on the distribution of source code in products that require the purchase of licenses...)

Auto Marking Help Files

AlphaTcl v 7.4 introduced auto-marking / hyperizing capabilities for Help files. If a file that contains no colors is opened through the Help Menu, AlphaTcl will go through a series of hyperizing / marking routines defined in help.tcl.
Auto-marking / hyperizing files must be clean before they are opened through the Help menu -- that is, they must not have any colors or hypers in them. If this is the case, AlphaTcl will mark the file and perform a series of search and hyperize routines following the guidelines below.
These routines make writing Help files much easier -- no need to individually Link To File anymore.
See these Alpha Dev Menu ↣ Help File Marking menu item procedures for details on what these auto-marking / hyperizing routines actually do:

Mark Colour Hyper:

[help::markColourAndHyper]

[help::confirmFileStamp]

[help::sizeHelpWindow]

[help::saveResourceChanges]

Window Marks:

[help::markHelpFile]

[help::markAsAlphaManual]

[help::markAsReferenceManual]

[help::markAsAlphaCommands]

Window Colours:

[help::colourTitle]

[help::colourMarks]

[help::underlineMarks]

[help::colourCodeInserts]

[help::colourAlphaCommands]

[help::colourAllCapLines]

[help::chooseColour]

[help::convertColour]

Window Hypers:

[help::hyperiseUrls]

[help::hyperiseEmails]

[help::hyperiseExtras]

The operations called via the proc [help::openDirect] uses these procedures, via the proc [help::markColourAndHyper], and sets some additional window information (read-only 1, dirty 0, tabsize 4).
The following sections describe the syntax required to achieve marks, hypers and colors in these files. Note: there is an additional marking regime for unix style manuals (i.e. those created for troff), that might be used instead for particular files. See the Help File Marking Exceptions section below.

Marks

To create a mark, start the line with

    <Tab><Space><Space><Tab>

which means type a tabulation, two spaces and a tabulation.
This sequence of whitespace will be stripped from the mark name. Subsequent Spaces and Tabs will indent the mark's name, which is useful for sub-sections. (Note that a Tab will indent the name of the mark only one space.) To insert a section divider, include a line that contains only = signs, optionally preceded by whitespace.
Note that the proc [help::openDirect] will automatically convert tab sizes to 4.

Help File Marking Exceptions

There is an alternative marking routine, proc [help::markAsReferenceManual], that is used in place of help::markAsAlphaManual for certain files that are identified as being in a 'manual' format. See the proc [help::markHelpFile] to find out how this is determined.
These files will still hyperize e-mails and urls and all extra, but marks are based on any word which follows the string NAME, where NAME is the first word encountered on a line. (See Error Help for an example.) Additional coloring is added for lines which contain ALL CAP WORDS.
The Alpha Commands file has it's own marking procedure as well, using the proc [help::markAsAlphaCommands], which is not be used for any other file.
Important: both of these routines only apply to Help files in Text mode.

Colors

Any line that begins with one (and only one) tab will be colored blue. Subsequent lines that begin with a tab will be colored blue as well.
The string IMPORTANT: will be colored red, as will menu directions that include Menu Name ↣ Menu Command:

Syntax	Result
`"File > Open"`	File ↣ Open
`"AlphaX > Global Setup > File Mappings"`	Alpha ↣ Global Setup ↣ File Mappings
`"Text > Fill Paragraph"`	Text ↣ Fill Paragraph
`"Alpha Dev Menu > Help File Marking > Colour Headings Etc"`	Alpha Dev Menu ↣ Help File Marking ↣ Colour Headings Etc

While several variations are allowed (i.e. double vs single quotes, the use of "-->" instead of ">"), these examples demonstrate the format that should be used in all Help files. Note that ellipses are never included in the names of the commands even if they are present in the menu.

Managing Table Of Contents

An Alpha Help file typically has a Table Of Contents consisting of one hyperlinked line for each section or subsection. If there are no other marks in the file than section marks (those picked up by the tab-space-space-tab tag), this table of contents can be generated automatically with the commands help::rebuildTableOfContents, available from Alpha Dev Menu ↣ Help File Marking ↣ Rebuild Table Of Contents.
This will replace any existing Table Of Contents with one calculated from the marks. (To build the first Table Of Contents, just put manually an empty Table Of Contents at the desired place.) Rather than just overwriting the existing Table, which might have been taylor-made for some reason, you can compare it with the one corresponding to the marks, via the command Alpha Dev Menu ↣ Help File Marking ↣ Check Table Of Contents: this will perform the comparison in a Diff window, in which you can manually patch the Table Of Contents as required.

Example/Tutorial Files

Most of Alpha's help files are contained in the Help directory. Example files, however, are in the Examples directory. Feel free to contribute additional example files, which can be accessed by hyperlinks (see the section on Hyperlinks to Examples below), menu items (as in the Filters and the Mac Menu packages), or by hyperlinks in the Examples Help file. (This last has to be updated manually -- see the notes at the bottom of that file for more information.)
Completion tutorials are kept in the Tcl/Completions folder, and can be accessed by the Alpha ↣ Mode Setup ↣ Completions Tutorial menu item, hyperlinks in the "Installed Packages" help file, or by hyperlinks created in other help files. (See the Hyperlinks to Installed Files section below.)
A word about Example and Completion Tutorial filenames:
Example files should use file mappings to properly open the window in the desired mode. If the file has a Smart Line, like this:

    -*-Setx-*-

then that will be used preferentially. The actual filename doesn't matter as of this writing: Setx-Example.stx and Setext-Example.stx will be treated the same. (Only the second file is actually installed, so the first hyperlink won't work.)
Completion tutorials, however, must follow a different set of rules. These files MUST begin with the exact name of the mode, followed by the string Tutorial. The file suffix in this case doesn't matter. Here are a few examples:

    "M2 Tutorial.m2"
    "Bib Tutorial.bib"
    "C++ Tutorial.cc"

Note that these file name syntax rules are subject to both debate and change as Alpha's Help files and routines undergo more extensive updating and revision -- watch this space for more details.

Hyperlinks

Hyperlinks are created by the procs in help.tcl.

Hyperlinks to Window Marks

Any mark in the current window can be hyperlinked by using an anchor syntax, preceding the mark's name by '#' and surrounding it with double quotes, as in Hyperlinks to Examples. It is not necessary to compensate for any extra spacing that might occur in setting the actual mark name.

Hyperlinks to Installed Files

To create a hyperlink to most .tcl files, include the file's name in quotes:

    "HtmlModeHelp.html"

To create a hyperlink to most Help files, include the file's name in quotes:

    "ExtendingAlpha"    "AlphaManual"    "CalculatorHelp"

Help for specific packages can be hyperlinked in two ways. The first is to precede the package's name with package: , as in package: latexAccents. The second way is to surround the package's name in quotes, and add Help as in "recentDirsMenu Help". Completion files and Completion Tutorials can also be hyperlinked:

        "TclCompletions.tcl"  "Text Tutorial"  "C Tutorial.r"

Hyperlinks to Examples

To include an example hyperlink, which will open any file in the Mode Examples folder in read-only format, simply put the file's name in quotes:

    "LaTeX-Example.tex"

To open the example in a shell window, which will insert some explanatory comments at the top of the window and allow for any modifications without altering the original file, omit the dash preceding Example in the file's name:

    "LaTeX Example.tex"

Note that examples which are opened in shell windows do not technically exist as files, and the window will not have any file suffix. This could disable some mode features that rely on file suffixes, and the window can not be sent to other applications.
If you want to include an example that does something different than these two default routines, you must create a -Example.sfx.tcl file. The AlphaTcl-specific modes use such scripts (i.e. Compare Example sources Compare-Example.tcl). These can also be adapted for package-specific tutorials, such as the tutorials

"Filters Example"       "Filters-Example.tcl"

See some of the .tcl files in the Examples folder for more examples.

Hyperlinks to Prefs Files

The procs in help.tcl recognize Prefs.tcl strings. Thus I can include the following lines in my Statistical Modes Help file:

To add keywords in a "SASPrefs.tcl" file, include the following commands:

	set SASuserCommands {
		blah blahdity etc
	}

Clicking on the "SASPrefs.tcl" link will prompt the user to create the file if necessary. The string "prefs.tcl" will similarly open the global preferences file.

Hyperlinks to Preference Dialogs

You can also hyperlink to open prefs dialogs, by using the strings

    preferences: <somePackage>
    Preferences: <somePackage>

Here's some examples:

    preferences: Appearance
    preferences: Help
    Preferences: WWW
    Preferences: GlobalPreferences
    
    preferences: Menus
    Preferences: Features
    Preferences: SpecialKeys
    
    preferences: Mode-Bib
    Preferences: Mode-Tcl
    Preferences: Mode-Menus
    Preferences: Mode-Menus-Tcl
    Preferences: Mode-Features
    Preferences: Mode-Features-Tcl
    
    Preferences: supersearch
    Preferences: filtersMenu

Note that there is a difference between

    Preferences: Text        and
    Preferences: Mode-Text

The helper applications (Alpha ↣ Global Setup ↣ Helper Applications) dialog can be opened with

    Preferences: HelperApps

Individual "X-service" (or external service) helpers can be set with

    Preferences: Helpers-viewURL
    Preferences: Helpers-ftpList
    Preferences: Helpers-Compare

The service name must be exact, i.e.

    Preferences: Helpers-viewUrl

will not work.
See the proc [help::openPrefsDialog] for more information about the syntax that this special procedure requires.

Hyperlinks to Hypertext

Strings embedded in << >> will be treated as hypertext. For example,

    <<WWW::renderFile [file join $HOME Help "AppleScriptModeHelp.html"]>>

will send the AppleScriptModeHelp.html file to the WWW Menu for parsing.

    <<suffixMappings>>

will open the Alpha ↣ Preferences ↣ File Mappings dialog.

Hyperlinks to Tcl Shift-Command-Double-Click

When a file is in Tcl mode, Shift-Command-Double-Clicking on a defined procedure will open the file in which that proc is contained. In Help files, the string proc: will create a hyperlink which does the same, as in

    proc: Tcl::DblClickHelper

Very handy for AlphaTcl developer help files ! This will also work for AlphaTcl or Tcl commands, as in proc: modeColoring or proc: proc.
An alternative hyperlink hint is "command: ", as in command: append or command: abbrev. Note that proc: and command: do the exact same thing, following the orders of precedence in Tcl::DblClickHelper.
A similar construction will display the current value for any defined AlphaTcl variable with

    variable: ::alpha::application
    variable: TextmodeVars
    variable: dummyVariable

Hyperlinks for Urls/Emails

Finally, email and url addresses surrounded by <> will be hyperized as well, as in <https://www.kelehers.org/alpha/> or <cupright@alumni.princeton.edu>.
There is also a special case for creating hyperlinks to bug reports: Ticket #75 or alternatively Bug #75 will open bug report #75 in your local browser. Because Requests For Enhancement are also included in the bugs tracker, strings like RFE #123 will also work.

Tools for Auto-Hyperizing Files

Using the guidelines outlined above, any clean Help file opened through the Help Menu will auto-mark / hyperize using the routines defined in the Alpha Developer's Menu. In the MacOS, the window's dirty information will then be set to "0", then the file will close and reopen. (See the proc [help::openFile] for details.)
To color and mark files, or to remove hypers, use the menu items found in Alpha Dev Menu ↣ Help File Marking. Note that any files uploaded to the Alpha Subversion repository will be distributed free of all hypers, marks and colors, so please check all of your auto-marking help files before releasing them!

Opening Help Menu items

Whenever an item is passed through the proc [help::openFile] , we check to see if there are any options available, i.e. files with similar root names but different extensions. For example, if the Help folder includes

    AppleScriptModeHelp
    AppleScriptModeHelp.html

and the mode's 'help' argument looks like

	alpha::mode Scrp 2.2 appleScriptMenu {*.script *.scr *.scpt *.ascr} {
		appleScriptMenu
	} {
		addMenu appleScriptMenu AppleScript Scrp
	} help {
		file AppleScriptModeHelp
	}

then when the user tries to open the mode/menu's Help window a list-pick dialog opens with both of them, as in "AppleScriptModeHelp". AlphaTcl can currently send .html, .pdf and .tex files to the appropriate helper application, using the proc [help::openDirect]. AlphaTcl will also present the user with any available .html file viewing options.
There are several Help Menu preferences that can help limit the options presented to the user, as described above. If there is only one file, or if the preferences narrow down the options to only one format, it is sent automatically to the proc [help::openDirect].

Exceptions -- .tcl files

If the Help folder contains a .tcl file associated with the Help menu item, such as the TclAEHelp.tcl file, this file is immediately sourced. It is up to the script to decide if more options will be presented to the user -- the script can choose to ignore the Help Menu preferences or not. For more examples see also the LaTeXHelp.tcl file.

Subdirectories in the Help folder

The name of the subdirectory will be inserted as a submenu listing the contents of the folder, unless there is an associated .tcl file present. In this case, the item will simply appear as another option (as above), and selecting it will immediately source the file containing the .tcl script.
So in both versions, if the help file for a particular feature / mode etc is a complex .html suite (like the HTML mode manual), including a subdirectory named (for example) LaTeXHelp as well as the script LaTeXHelp.tcl will simply insert LaTeX Help in the Help menu, but allow its selection to do whatever the script wants, including opening any of the files within the LaTeXHelp subdirectory.

Help Menu Preferences

The helpMenu package, defined in help.tcl, defines some preferences that can be changed by the user to refine the type of help format that they want to use; see Alpha ↣ Preferences ↣ SystemPreferences ↣ Help for the dialog that appears during the initial Setup Assistant, or click on this hyperlink Help Preferences panel.
These preferences include:

Preferred Help Format / Second Choice Help Format / Third Choice Help Format: Some Help files are available in multiple formats, such as html, pdf, etc. This preference sets a default format to open, if available. You shouldn't have to worry about these settings, the proc [help::getChoices] will use them to deliver the preferred option.
Help File Window Size: This preference only applies to text Help files that are opened within Alpha. It allows help files to be automatically shrunk to the default size or moved about the screen so that they are out of the way of the current open windows.
Help Colours: There is also a Help mode that sets the colours to use for hyperizing, etc. Click on this Help preferences hyperlink to change them.

Copyright

This document has been placed in the public domain.
Feel free to send any bugs, comments, or suggestions on this file to https://sourceforge.net/p/alphacocoa/mailman/.