Doc Files Help
| 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.
Introduction
There are many different ways of writing help pages for Alpha or for an
AlphaTcl package (menu, mode, feature, etc.). The following sections
explain Alpha's mechanisms for providing help and describe the
standard conventions used in the help files.
Help Resources
When it comes to displaying some help, Alpha looks for two
different kinds of resources:
- help files stored in various Help folders. Most of these files are in
Html format, but other formats are supported (in particular PDF). Html
help files are displayed in Alpha's Help Viewer.
- cached help blocks which are text blocks kept in various caches
(inside the application's bundle or in Application Support
folders). Help blocks are displayed in document windows and may contain
colors and hyperlinks.
Markup Systems
Package authors may choose either way for providing help. To assist them
in writing the documentation, two markup systems are available:
- help blocks may use a mild set of formatting conventions which are
parsed by Alpha at display time in order to colorize the text and create
hyperlinks. This approach is fine for small size help pages.
- help files in the Help folders may be written using the powerful
Aida markup language and processor. This is
the approach used for most help files in Alpha: the aida sources are
processed before each release and produce the Html files found in the Help
directories.
The purpose of this document is to explain both markup systems. This is
done in the following sections:
Help File Locations
All of Alpha's documentation can be found in one of several different places.
The first is the top-level
Help folder
inside the application's bundle.
The second and third are in the Application Support folders:
The order of precedence here is actually reversed, so that the user's Help
folder is the first one checked, followed by the local Help folder, and
finally Alpha's Help folder. The Application Support folders allow
system administrators and users to add third-party AlphaTcl packages. By
default these folders are empty. It is possible that a modified copy of a
standard help file from $HOME/Help/ will be placed in the local or
user's Application Support folders; when this is the case that is
the file that will be opened.
Note also that the local Application Support folder may not
exist. If you want to have one, you must create it explicitely and you
need admin privileges to do this.
The last place that package documentation is located is in the
individual source file of a given AlphaTcl package, in the help
argument of any [alpha::mode/menu/feature/extension/flag]
declaration. Examples of this kind of declarations may be found in the
following files:
The file marking/hyperizing/coloring routines described in the Writing text help section apply to all of the opened files or
created windows using these help blocks.
Opening Help Files/Windows
The menubar Help menu contains items that have been useful either for basic
operation of the program (i.e. Readme Alpha Manual Search Help) or for
the most commonly used AlphaTcl modes/menus/features (i.e. Electrics Help
HTML Mode Help).
Help windows for minor packages are accessed via various menu items or
procedures, and via hyperlinks in the Installed Packages help file. The
menu items More Modes Help More Menus Help and More Features Help will
open a list-pick dialog containing the names of appropriate options.
The list of items presented in the Help menu is hard-wired, and does not
require an actual $HOME/Help file to be present. Conversely, the presence
of such a file does not ensure its inclusion in the Help menu.
Any package can decide where the Help should be located, i.e. in its own file
or in any one of the Package 'help' arguments. If a package can be
adequately described in 50 lines or less, it probably doesn't need its own
separate Help file. Beyond this rough guideline, however, the inclusion of
Help folder files in standard Alpha distributions is a matter for the
maintainer of an AlphaTcl package to determine.
Writing Aida help
Alpha's help is now written using a markup language named Aida
(see the Aida project at SourceForge).
Aida has several characteristics which make it a very flexible tool:
- it is light weight. You can learn it in five minutes.
- it is dynamic. This means that it embeds a Tcl interpreter and is
able to produce output generated on the fly by executing Tcl code.
- it can produce its output in many different formats. The same aida
source file can be converted to html, latex, pdf (via hyperref), plain text
and many wiki formats like mediawiki, pmwiki, markdown etc.
- it can be easily parameterized.
- it can load libraries of macros. Alpha has a rich set of nice macros
which automatically generate hyperlinks, lists, tables etc.
- the conversion tool is based on a strict grammar and makes use of
callbacks written in Tcl. It can thus easily be extended.
Alpha makes use of Aida to produce its documentation in HTML format.
Alpha supports a protocol called alphatcl which 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.
Thanks to this mechanism, you can interact with the AlphaTcl library from
an Html page (for instance display dialogs, edit files, open preferences
panels, etc.) and Alpha's documentation makes extensive use of this mechanism.
Alpha's documentation files can be found in the Alpha sources in
the Doc subfolder of the Current folder.
To learn more about using Aida to write Alpha's documentation,
please refer to the following help files:
- Aida help is the
reference concerning Aida.
- Aida Macros Help explains the macros available
for writing Alpha's documentation. It contains a lot of examples.
- Aida Mode Help describes the commands available
in Aida mode. This mode inserts a menu called Aida in the menu bar.
- the technical note TN #2: How to update the doc gives instructions if you
want to modify and update an existing help file.
Writing text help
A complete overview of the marking conventions used in the help blocks of
AlphaTcl packages or in help files in text format may be found in the
Help Text Marking.
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/.