| Alpha |
| Version: | 9.2.3 - "Suhail" |
| Last update: | 2021-05-21 14:43:30 |
This document is intended for developers working on Alpha's documentation.
It describes the various procs which can help in building dynamic
contents, in particular to format lists and tables, print key
combinations and build many kinds of hyperlinks.
Alpha's documentation files use Aida markup as explained in
Doc Files Help. The reference for the Aida markup
language is available here.
All the macros are defined in the file AlphaHelpMacros.tcl
which is part of the Alpha sources and is located in the Doc
directory. To make them available in your document, you must add a
:Source: parameter in the header of your Aida document, like this:
:Source: /path/to/AlphaHelpMacros.tcl
All the procs described below must be enclosed in a pair of
((e e)) tags in order to be evaluated by the aida processor.
They are defined in a namespace called ah (short for Alpha Help).
Text formatting
Key combos
The proc [ah::combo] lets you print key combinations and keyboard
shortcuts in a standardized way. Its formal syntax is:
ah::combo combo {style v}
It uses the same syntax to describe key combinations as the [binding] command in Alpha. See the section Specifying a key combo.
The style argument is described in the Style section below. It also supports a letter t (for
text) to write the key modifiers litterally rather than using symbols: for
instance, with the letter t specified in the style argument, one
would get Cmd instead of ⌘.
This proc also supports composite bindings: you specify them as a
list containing the prefix and the combo itself. For instance {z 'a' o
'b'} corresponds to Ctrl-A Opt-B.
Here are a few examples:
| Command | Result |
ah::combo cosz | ⌃⌥⇧⌘ |
ah::combo {c 'a'} | ⌘A |
ah::combo {c space sz 'a'} | ⌘-Space ⌃⇧A |
ah::combo {c 'a'} i | ⌘A |
ah::combo {os 'b'} t | Opt-Shift-B |
ah::combo {cz 'b' o 'a'} ti | Ctrl-Cmd-B Opt-A |
Lists
The proc [ah::buildAidaList] builds an Aida list out of a Tcl
list. Its formal syntax is:
ah::buildAidaList tclList {style ""} {type "ul"}
The style argument is explained in the Style section below.
The type argument can be ul for unordered lists (it
is the default), ol for ordered lists, or nl for flat lists.
Typically the tclList argument is provided by a
specific command which builds it dynamically.
Here are some examples:
ah::buildAidaList "lemon orange grapefruit"
will result in
ah::buildAidaList "lemon orange grapefruit" "i" "ol"
will result in
- lemon
- orange
- grapefruit
ah::buildAidaList "lemon orange grapefruit" "b" "nl"
will result in
lemon
orange
grapefruit
Tables
The proc [ah::buildAidaTable] builds an Aida list out of a block
of text. Its formal syntax is:
ah::buildAidaTable lines {framed 1} {header ""} {options ""}
The lines argument is a list of strings in TSV
(tabulation-separated values) format. Each line should be composed of fields
separated by tabulations \t).
The header argument is a single line with
tabulation-separated header names.
The framed argument tells whether the table should have a
frame or not.
The options argument can be used to pass additional
attributes for the table, like for instance "cellpadding=4".
Here are a simple example assuming that the variable $txt
contains the following string A\tBB\nCCC\tDDDD:
ah::buildAidaTable $txt
will result in
A more complex example:
ah::buildAidaTable $txt 0 "Key\tValue" "format=rc"
will result in
Resource locations
The proc [ah::getURL] returns the location of various components
of the Alpha project on the Web. Its formal syntax is:
ah::getURL name {onlyURL 1}
The name argument can be one of the following keywords:
| Name | Description | URL |
| aida | Aida's Home Page | https://sourceforge.net/projects/aidadoc |
| bugs | Alpha's Bug Tracker | https://sourceforge.net/p/alphacocoa/tickets/ |
| co | Subversion checkout URL | https://svn.code.sf.net/p/alphacocoa/code/ |
| devlist | Alpha-Developer List | https://sourceforge.net/p/alphacocoa/mailman/alphacocoa-devel |
| files | Alpha's Release Page | https://sourceforge.net/projects/alphacocoa/files/ |
| fink | Fink | https://www.finkproject.org/ |
| home | Alpha's Home Page | https://alphacocoa.sourceforge.io |
| homebrew | Homebrew | https://brew.sh/index.html |
| macports | MacPorts | https://www.macports.org/ |
| mailing | Alpha's Mailing Lists | https://sourceforge.net/p/alphacocoa/mailman/ |
| manual | Alpha's Manual | https://alphacocoa.sourceforge.io/AlphaManual.html |
| qas | Questions and Answers | https://alphacocoa.sourceforge.io/AlphaQAs.html |
| quickstart | Alpha's Quick Start | https://alphacocoa.sourceforge.io/QuickStart.html |
| readme | Alpha's Readme | https://alphacocoa.sourceforge.io/Readme.html |
| reference | Alpha Commands Reference | https://alphacocoa.sourceforge.io/CommandsReference.html |
| sf | Alpha's Project Page | https://sourceforge.net/projects/alphacocoa |
| star | Version star (like Suhail) | https://alphacocoa.sourceforge.io/AlphaStar.html |
| svn | SVN Browser | https://sourceforge.net/p/alphacocoa/code/HEAD/tree/ |
| syntax | Alpha Commands Syntax | https://alphacocoa.sourceforge.io/CommandsSyntax.html |
| tcltk | Tcl | https://www.tcl.tk |
| tickets | Synonym of bugs | https://sourceforge.net/p/alphacocoa/tickets/ |
| tns | Technical Notes | https://alphacocoa.sourceforge.io/AlphaTNs.html |
| tracker | Synonym of bugs | https://sourceforge.net/p/alphacocoa/tickets/ |
| userlist | Alpha-User List | https://sourceforge.net/p/alphacocoa/mailman/alphacocoa-user |
| web | Synonym of home | https://alphacocoa.sourceforge.io |
| wiki | Alpha Wiki | https://sourceforge.net/p/alphacocoa/wiki/ |
If the onlyURL argument is 1 (the default), the proc just returns the URL,
otherwise it returns a two elements list containing the URL and a default
descriptive name. You should rarely use this proc directly, but rather use
the commands [ah::link site] or [ah::link url] described in
the Hyperlinks section. See examples in the
Preset urls
and
Preset sites
sections.
Date and version
The procs [ah::date] and [ah::version]
insert respectively the current date and the current version number.
The proc [ah::insertVersionDate], used with no argument,
inserts a block containing the current date and the version number of the
application, aligned on the right margin (like the one at the top of this
document). It also accepts the name of a package as an optional argument:
in that case, it displays the package's version.
Images
The [ah::img] proc inserts an image located, by default, in the
Help/Images folder inside the AlphaTcl library.
The syntax is
ah::img name ?subdir? ?alt?
The subdir argument designates a subdirectory of the Help folder.
Its default value is Images. The alt argument lets you
specify an alt attribute for the image tag.
ah::img docwin_parse_button.png |  |
Hyperlinks
The ah::link command is the main command to build links in the
documentation files. These links are hypertext links which trigger an
action, like opening another page, jumping to a particular section,
executing some code in Alpha, editing files or displaying dialogs,
revealing files or folders in the Finder, etc. The syntax is
ah::link what args
The ah::link command must
be used in a pair of ((e e)) tags in the aida source files.
Depending on the what argument, the links created with this
command can trigger different kinds of actions. The args arguments
also differ for the various kinds of links.
The possible values of the argument what are described in
the next section (see Link types).
Most of the types support two optional arguments named str
and style:
- the str argument lets you specify the string to display for the
link. The procs provide a default value for this argument when it is left
empty.
- the style argument is explained in the Style section below.
Link types
This section presents the different types of links in alphabetical order.
alpha
the alpha type lets you build a link using the alphatcl
protocol. This allows to execute Tcl code in Alpha from a hyperlink in a
web page. URLs with the alphatcl scheme are interpreted by
Alpha via the GURL/GURL AppleEvent. The formal syntax is:
ah::link alpha cmd {str ""} {style "i"}
The cmd argument is the command to execute in Alpha, the str argument
is the string displayed as a hyperlink in the navigator.
See example in the Doc links section.
bindings
the bindings type lets you display in Alpha a window
containing the bindings currently available for a given mode or package. The formal syntax is:
ah::link bindings name kind what {str ""} {style "i"}
This kind of link relies on the proc binding::displayInfoForType
defined in AlphaTcl.
The kind argument can be either tag or creator and
the what argument is the corresponding value. The name argument is
used to build up the title of the window.
See example in the Doc links section.
bug
the bug type lets you build a link to a bug report (aka ticket) on the Alpha
tracker. The formal syntax is:
ah::link bug num {str 0} {style "i"}
The str argument has different meanings:
- if it is 0 (default), the displayed string is "Ticket #$num"
where num is the number of the ticket specified by the num
argument.
- if it is 1 (default), the displayed string is "Ticket #$num: title"
where title is the ticket's summary found in the catalog.
- if it is a non empty string, it is used as the displayed string.
See example in the Doc links section.
cmd
the cmd type lets you build a link for a core command. It may be a
Tcl command or an Alpha command. If the latter, the command automatically
dispatches on the Reference or Syntax directory (inside
the Help folder). The formal syntax is:
ah::link cmd name {str ""} {style "si"}
See example in the Doc links section.
definition
the definition type lets you build a link pointing to the
definition of a concept. The formal syntax is:
ah::link definition name {basename ""} {str ""} {style "i"}
The name argument is the name of the concept. If the basename argument is not specified or is empty, use the name of the currently
processed file: as a consequence, an ((rf link is computed instead
of ((lk.
To create a definition label (which you can point to), use ah::def definition name. See example in the Definition links section.
dl
the dl type lets you build a link to download a released version
of Alpha. The formal syntax is:
ah::link dl version {str ""} {style "i"}
The version argument is the version number. Note that to get a link
to the latest release, you can use ah::link url dl.
See example in the Doc links section.
doc
the doc type lets you build a link to the help page of an AlphaTcl
package (mode, menu or feature). This uses the alphatcl protocol.
The formal syntax is:
ah::link doc name {str ""} {style "i"}
The name argument is the name of the package.
See example in the Doc links section.
example
the example type lets you build a link to edit an AlphaTcl example
file (found in the Examples directory). This uses the alphatcl protocol.
The formal syntax is:
ah::link example name {str ""} {style "i"}
The name argument is the name of the file (with or without the -Example suffix).
See example in the Doc links section.
file
the file type lets you build a link to edit a file located in the
installation directory. It is based on help::openHyper which does its best
to find the file looking in all the directories of the auto_path variable.
The formal syntax is:
ah::link file name {str ""} {style "i"}
The name argument specifies the name of the file. If the str argument is not specified, the proc uses the file name.
See example in the Doc links section.
help
the help type lets you build a link to edit an HTML file located in the
Help dir. The formal syntax is:
ah::link help basename {str ""} {sectionMark ""} {style "i"}
The basename argument specifies a path relative to the AlphaTcl/Help directory (with or without the .html extension).
If basename is the name of a core command, it is not necessary to
specify the subdir: it is substituted automatically. If the str
argument is not specified and if this is not the name of a command, use a
prettified form of the file name.
See example in the Doc links section.
helpfile
the helpfile type lets you build a link to edit a file located in
the Help dir. Use this proc for help files in PDF or text format.
The formal syntax is:
ah::link helpfile basename {str ""} {style "i"}
The type is determined by the extension. The basename argument
specifies a path relative to the AlphaTcl/Help directory. If the
str argument is not specified, use a prettified form of the file
name without extension.
See example in the Doc links section.
key
the key type lets you build a link to the documentation of a
command's key. The formal syntax is:
ah::link key name keyname {str ""} {style "i"}
The name argument is the name of the command and the keyname
argument is the name of the key.
If the str argument is not specified, the default string is
"$name $keyname".
See example in the Doc links section.
linkvar
the linkvar type lets you build a link to a linked variable (a Tcl
variable defined by Alpha that is linked to a C variable in the core).
The formal syntax is:
ah::link linkvar name {style "i"}
See example in the Doc links section.
lt
the lt type lets you build a link to a definition list item in a
given file. The formal syntax is:
ah::link lt name {basename ""} {str ""} {style "i"}
If the basename argument is not specified or is empty, use the name
of the currently processed file: as a consequence, an ((rf link
is computed instead of ((lk. If the str argument is
not specified or is empty, use the name argument instead.
See example in the Doc links section.
mailto
the mailto type lets you build a link to an e-mail address. The formal syntax is:
ah::link mailto email {str ""} {style "i"}
If the str argument is not specified, use the
e-mail itself.
See example in the Doc links section.
man
the man type lets you build a link to display a man page in Alpha
using the Man Viewer. The formal syntax is:
ah::link man name {str ""} {style "i"}
The name argument is the name of the man page.
If the str argument is not specified, the default string is
"$name manual page".
See example in the Doc links section.
menuitem
the menuitem type lets you display a menu path, that is to say a
sequence of menus, submenus and items. The formal syntax is:
ah::link menuitem items {cmd ""} {style "i"}
The items argument is a Tcl list containing the elements of the
menu path. The items are displayed separated by a rightwards arrow.
If the cmd argument is not empty, it must be a valid Tcl
instruction and the menu path is displayed as a hyperlink which executes the
cmd command in Alpha.
See example in the Doc links section.
opt
the opt type lets you build a link to the documentation of a
command's option. The formal syntax is:
ah::link opt name option {str ""} {style "i"}
The name argument is the name of the command and the option
argument is the name of the option.
If the str argument is not specified, the default string is
"$option".
See example in the Doc links section.
pref
the pref type lets you build a link to a preference panel. This
uses the alphatcl protocol. The formal syntax is:
ah::link pref name {str ""} {style "i"}
The name argument is the name of the panel. See examples in the
Preference dialogs section.
proc
the proc type lets you build a link to the source code of an
AlphaTcl proc. This uses the alphatcl protocol. The formal syntax
is:
ah::link proc name {str ""} {style "si"}
The name argument is the name of the proc.
See example in the Doc links section.
qa
the qa type lets you build a link to a Question & Answer
(QA) on Alpha's web site. The formal syntax is:
ah::link qa num {str ""} {style "i"}
If the str argument is not specified, the proc looks in the catalog
for the title of this QA. If not found (or if str is a single space
" "), it defaults to "QA #num" where num is the number of
the Q&A specified by the num argument.
See example in the Doc links section.
reveal
the reveal type lets you build a link to reveal a file or a folder
in the Finder. The path argument specifies the full path of the
file or folder. The formal syntax is:
ah::link reveal path {str ""} {style "i"}
If the str argument is not specified, the proc uses the path's last
component.
See example in the Doc links section.
root
the root type lets you build a link to the documentation of a
particular kind of root window (as used in the [view root] command). The formal syntax is:
ah::link root name {str ""} {style "i"}
See example in the Doc links section.
sec
the sec type lets you build a link to a section in a given file.
The formal syntax is:
ah::link sec name {basename ""} {str ""} {style "i"}
If the basename argument is not specified or is empty, use the name
of the currently processed file: as a consequence, an ((rf link
is computed instead of ((lk. If the str argument is
not specified or is empty, use the name argument instead.
See example in the Doc links section.
site
the site type lets you build a link to a page on the Alpha web site. See the
Resource locations section and the [ah::getURL] proc for a list of the supported names. The formal syntax is:
ah::link site name {str ""} {style "i"}
If the str argument is not specified, the proc uses a preset
string. See examples in the Preset sites section.
subcmd
the subcmd type lets you build a link for a subcommand of a command.
The formal syntax is:
ah::link subcmd name {style "si"}
The difference with the cmd type is that the string is just the name of
the subcommand rather than the command itself. For instance,
ah::link subcmd "menuItem insert" will display as
insert whereas
ah::link cmd "menuItem insert" will display as
[menuItem insert].
See example in the Doc links section.
sysprefs
the sysprefs type lets you build a link to a System Preferences panel. This
uses the alphatcl protocol. The formal syntax is:
ah::link sysprefs path {name ""} {str ""} {style "i"}
The path argument is a string representing the panel. It has the
form panelPath?/anchorName? where panelPath is the
identifier of the panel (a reverse DNS name) and anchorName is the
optional name of a subpanel separated by a slash. The name argument
is a pretty name for the panel. See the proc [sysprefs::panelIds]
in Alpha to get the list of all the panel IDs and the proc
[sysprefs::getAnchorNames] to get the name of the subpanels.
See example in the Doc links section.
table
the table type lets you build a link for a table.
The formal syntax is:
ah::link table name {str ""} {basename ""} {style "i"}
The basename argument is the name (or relative subpath) of the file
containing the table. If it is not specified or is empty, use the name of
the currently processed file. If the str argument is not specified
or is empty, the proc uses the name argument instead.
See example in the Doc links section.
tclfile
the tclfile type lets you build a link to edit a file located in the
AlphaTcl/Tcl directory. The formal syntax is:
ah::link tclfile basename {str ""} {style "i"}
The basename argument specifies a path relative to the Tcl dir. If
the str argument is not specified, the proc uses the file name.
See example in the Doc links section.
test
the test type lets you build a link to edit a file located in the
Tests directory. The formal syntax is:
ah::link test basename {str 0} {style "i"}
The basename argument specifies the name of the test file (path
relative to the Tests folder inside the application's bundle). If
basename is a command name, the corresponding test file name is
built automatically. If the str argument is not specified, use the
file name.
See example in the Doc links section.
ticket
the ticket type is synonym of the bug type. The formal syntax is:
ah::link ticket num {str 0} {style "i"}
The str argument has the same meaning as with the bug type.
tn
the tn type lets you build a link to a Technical Note (TN) on Alpha's
web site. The formal syntax is:
ah::link tn num {str ""} {style "i"}
If the str argument is not specified, the proc looks in the catalog
for the title of this TN. If not found (or if str is a single space
" "), it defaults to "TN #num" where num is the number of
the TN specified by the num argument.
See example in the Doc links section.
tutorial
the tutorial type lets you build a link to edit an AlphaTcl
tutorial file (found in the Completions directory). This uses the
alphatcl protocol. The formal syntax is:
ah::link tutorial name {str ""} {style "i"}
The name argument is the name of a mode.
See example in the Doc links section.
url
the url type lets you build a link to an Alpha web resource
location. The formal syntax is:
ah::link url name {sub ""} {str ""} {style "i"}
See the Resource locations section and the [ah::getURL] proc for a list of the supported names. If the str
argument is not specified, use the URL itself.
The sub argument specifies a complement for the url.
See examples in the Preset urls section.
var
the var type lets you build a link to display the value of a global
AlphaTcl variable. This uses the alphatcl protocol. The formal syntax is:
ah::link var name {str ""} {style "i"}
The name argument is the name of the variable (string variable or
array).
See example in the Doc links section.
view
the view type lets you build a link to the documentation of a
particular kind of view (as used in the [view create]
command). The formal syntax is:
ah::link view name {str ""} {style "i"}
See example in the Doc links section.
web
the web type lets you build a link to a page on the Web space at
SourceForge. The formal syntax is:
ah::link web name {str ""} {style "i"}
The name argument is the name of the file without the extension.
This proc automatically detects if name is the name of a command
and dispatches appropriately to the Reference or the Syntax
subdir. If the str argument is not specified, use the name itself.
See example in the Doc links section.
Empty type
As a special case, if only one argument is specified with the
ah::link command, it generates a simple hyperlink. The
argument should be an URL specifying the location of a resource. For
example:
ah::link https://alphacocoa.sourceforge.io
ah::link mailto:alphacocoa-devel@lists.sourceforge.net
will generate the following links respectively:
If you want a different text to be displayed for the link, use the
((lk lk)) tags directly.
Link examples
Here are a few examples demonstrating the use of the ah::link proc.
Doc links
Definition links
Assuming that a label for the definition of the saveHook concept has been created
like this in the file ExtendingAlpha.aida:
ah::def definition saveHook
then you can point to this location with the following syntax:
| Command | Result |
ah::link definition saveHook ExtendingAlpha | saveHook |
Preset urls
Preset sites
Preference dialogs
Style
Most of the procs described in this document have an optional argument
named style. This argument can be a combination of letters i,
b, u, v and s with the following meaning:
| Letter | Description |
| i | italic |
| b | bold |
| u | underline |
| v | verbatim |
| s | enclose in square brackets |