CheckGuide - A tool to check the consistency of AmigaGuide databases
====================================================================
Copyright © 1997 by Olaf Barthel <olsen@sourcery.han.de>
All Rights Reserved

1. What this program does
-------------------------
Authoring AmigaGuide files is easy; the difficult part is to produce
consistent databases AmigaGuide will display correctly and which don't
contain unused nodes, references to undefined nodes, syntax errors and other
troubles that are really difficult to spot.
   The original AmigaGuide was rewritten for Workbench 3.0 where it was
implemented as a datatypes class. As it turned out, the new implementation
behaved differently. This was caused by the introduction of the backslash
("\") as an escape character and a different parser which was less tolerant.
   The big problem of AmigaGuide is that it has no strict syntax definition.
Nobody really seems to know when and where a backslash has its effects. Also,
AmigaGuide does not detect errors in the documents it reads. It may behave
unpredictably, but no errors are reported.
   CheckGuide does a number of consistency checks on the databases and
reports them. Some of the problems reported really count as warnings,
AmigaGuide will still process and display the document, but may behave in an
unpredictable way. Other problems reported really belong into the realm of
"style". See for yourself.

2. What this program does not
-----------------------------
As no strict syntax definition of the AmigaGuide "language" exists and there
is no complete list of keywords which AmigaGuide understands, CheckGuide
cannot find all possible problems. An AmigaGuide file may still count as
"correct" if it fails any of the tests CheckGuide makes, because as a last
resort, the actual AmigaGuide implementation defines compliance.
   A specific problem is in the treatment of the escape character ("\") which
due to incomplete documentation is not always treated the same way as
AmigaGuide treats it.

3. Starting the program
-----------------------
CheckGuide takes any number of arguments, each of which must refer to the
name of a file to read and check. The following options are supported:

   -r, --recursive

   CheckGuide will operate in recursive mode, which means that if a link
   to a file is found, CheckGuide will proceed to follow this link and
   check the file. When following links, each file is checked exactly
   once, so no processing time is wasted or circular dependencies crop up.

   -o, --onlyguidefiles

   This works in conjunction with the -r option: when following a link,
   CheckGuide will silently stop processing any file that does not
   qualify as an AmigaGuide database (i.e. if it does not have the
   @DATABASE keyword in the first line).

   -w, --nowarnings

   This option suppresses reporting of problems that do not really count
   as errors.

4. Errors reported
------------------
The following list explains what error messages CheckGuide produces and what
they mean. As said before, some of the messages really count as warnings
only.

4.1. Buttons
------------
By default, AmigaGuide displays hyperlinks as buttons (although the
appearance is configurable). These buttons are declared using a common syntax
like this:

   @{<Label> (Command) (Parameters)}

Some commands take additional parameters (such as the "LINK" command), while
some do not (such as the "QUIT" command).

Messages:

	Unknown link command <Name>

		The command specified for the button is not recognized. Known
	commands include LINK, ALINK, CLOSE, RX, RXS, SYSTEM and QUIT.

	Missing closing brace in button declaration
	Unbalanced open brace in button declaration

		Button declarations cannot span multiple lines, which
	means that the closing brace has to be on the same line as the
	"@{" token that introduces the link.

	Missing quote in button declaration

		The button label must be enclosed in quotes. With
	some of the commands you need to enclose the parameters in
	quotes. If the quotes are unbalanced, AmigaGuide may fail to
	parse the remainder of the line correctly.

	Incomplete/invalid link declaration

		The original AmigaGuide V34 would tolerate button
	declarations which had blank spaces between the @ character
	and the open brace (as in "@ {"). However, AmigaGuide V39
	and up no longer recognize this syntax.

	Button label <Text> must be enclosed in quotes

		The label of each button must be enclosed in quotes,
	even if it includes no blank space characters. If the quotes
	are missing, AmigaGuide V40 will start throwing Enforcer hits.

4.1.1. Link commands
--------------------
Links are declared with the following commands:

   @{<Label> LINK <Node or file> [Line number]}
   @{<Label> ALINK <Node or file> [Line number]}

The line numbers may be omitted. The first parameter must refer to a node;
AmigaGuide will always try to find the node in the current database and then
attempt to open a file bearing the node name. If this happens, the given name
is assumed to consist of a document name and a node name, like this:

   foo:bar/baz/MAIN

In this example "foo:bar/baz" is the name of the file to open and "MAIN" is
the node to display. "MAIN" is the general catchall, i.e. links to
non-AmigaGuide-files can be established only if the node name is "MAIN".
Otherwise, AmigaGuide will complain about being unable to open the file.
The same happens if the node name is omitted, i.e. the plain file name is not
sufficient to define a link.

Messages:

	ALINK line number invalid
	LINK line number invalid

		The line number given is not a number but contains
	alphanumeric characters.

	ALINK node name required
	LINK node name required

		The node or file name parameter has been omitted.

	File found in relative path only <Name>

		You can create links to other files which AmigaGuide will
	load and display instead of the database you originally started
	from. The current implementation of AmigaGuide (V40) tries to
	open files pointed to by links by the names given. Thus, a file
	name "foo/bar/baz/MAIN" will cause the file "foo/bar/baz" to be
	opened, relative to the current directory of the AmigaGuide
	program. This directory may not be the same as the directory the
	file you originally started from is found in. Naturally, this can
	cause some confusion as AmigaGuide may complain about being unable
	to open a file a link points to. Generally, it is safer to use
	absolute paths instead (as in "foo:bar/baz/MAIN"), but this
	approach has its own risks and disadvantages.

	Reference to undefined node <Name>

		The file or node a link refers to is neither found in
	the current document nor on the filing system. CheckGuide
	tries to interprete file names relative to the name of the
	database it checks, but even that can fail if files are
	simply not there. AmigaGuide also uses an environment variable
	"PATH" to locate nodes. CheckGuide does not support this feature.
	And really, you should not depend on it in your databases.

4.1.2. ARexx and AmigaDOS commands
----------------------------------
ARexx and AmigaDOS commands are declared with the following commands:

   @{<Label> RX <Command>}
   @{<Label> RXS <Command>}
   @{<Label> SYSTEM <Command>}

Messages:

	RX command required
	RXS command required
	SYSTEM command required

		The required command parameter was omitted.

4.1.3. Shutdown commands
------------------------
Shutdown commands include CLOSE and QUIT:

   @{<Label> CLOSE}
   @{<Label> QUIT}

Messages:

	Too many arguments for CLOSE command
	Too many arguments for QUIT command

		Neither command takes any parameters.

4.2. Commands
-------------
AmigaGuide recognizes a database it understands by a command found in the first
line of the file. Other commands are used to convey information (such as
copyrights, version numbers, etc.) and to provide structure (such as the node
declarations). Commands are introduced by the @ character.

Messages:

	Command <Name> has no effect

		A command such as @DATABASE must be placed in the first
	column of a line for AmigaGuide to recognize it. If it shows up
	anywhere else in the line, AmigaGuide will show it as plain text,
	which is probably not what you want.

	The first line must contain the @DATABASE keyword

		An AmigaGuide database must begin with the @DATABASE command
	in its first line for AmigaGuide to recognize it as such.

	MAIN node missing

		An AmigaGuide database has to contain at least one single
	node, the MAIN node.

	Unknown keyword <Name>

		An unknown command was found at the beginning of a line.

4.3. Nodes
----------
An AmigaGuide database consists of a set of so-called nodes. At least one
node has to be defined, the MAIN node. Nodes are defined with the @NODE and
@ENDNODE commands.

Messages:

	Duplicate @NODE <Name> (see line <Number>)

		You assigned the same name to more than one node. As the name
	is no longer unique (note: case does not matter), AmigaGuide may
	display either one when you move to it. Which one is displayed is
	subject to undefined behaviour. The line number displayed in this
	error message refers to the first line in which a node with the
	given name is declared.

	Unbalanced @ENDNODE

		Each @NODE declaration has to be matched by exactly one
	@ENDNODE command. Here an unused @ENDNODE command has been
	found.

	Unbalanced @NODE

		Each @NODE declaration has to be matched by exactly one
	@ENDNODE command. Here an unterminated @NODE command has been
	found.

	Unused @NODE <Name>

		This is an indication of a node that has been declared
	but has no links from this file to it. This may be exactly what
	you want if these nodes are referred to from other AmigaGuide
	databases only.

4.4. Table of contents, index and browsing
------------------------------------------
For each node you may declare the name of the node that should be displayed
when the "Contents" and "Index" buttons are pressed.

Messages:

	INDEX node <Name> missing
	TOC node <Name> missing

		The node you specified with the @INDEX/@TOC command could
	not be found.

	More than one @INDEX at top level
	More than one @TOC at top level

		While no node is currently being defined you can still
	declare the names of the @INDEX and @TOC nodes valid for the
	remainder of the document. Normally, these should be declared
	before any other nodes are defined. And there better be only
	a single declaration of these.

	@NEXT references undefined node <Name>
	@PREV references undefined node <Name>

		The two browsing commands must of course refer to
	existing nodes.

4.5. Text colour and style
--------------------------
AmigaGuide V39 introduced control commands for text colour and style. Like
buttons, these can appear anywhere in the text. The control commands look
like this:

   @{fg text}
   @{bg shine}
   @{b}
   @{ub}

Messages:

	Invalid colour control string <Name>
	Invalid colour <Name>

		The colour specified with the @{fg } and @{bg } commands is
	not known. Known colours include TEXT, SHINE, SHADOW, FILL, FILLTEXT,
	BACK and HIGHLIGHT.

	Unbalanced <Command> in column <Number>

		Text style commands should be balanced, e.g. @{u} should be
	followed by @{uu} somewhere down the text.

	Command <Command> in column <Number> has no effect

		Turning off a text style command (e.g. @{ub}) while it is
	already turned off will have no noticeable effect.

4.6. Style
----------
The following messages deal with the @DATABASE command at the beginning of
each AmigaGuide file and the file name.

Messages:

	Database <Name> and file name <Name> do not match

		Database and file name should be identical.

	Database <Suffix> and file name <Suffix> suffixes do not match

		The file name suffixes (.guide) are not identical,
	they might even have been omitted.

	Database name <Name> contains path specifiers

		The @database name should only contain the
	base name of the file.

	Database name uses obsolete .hyper suffix
	File uses obsolete .hyper name suffix

		The original AmigaGuide specs defined that each database
	name should have the suffix ".hyper" appended. This was changed
	later to ".guide".

4.7. Escape characters
----------------------
CheckGuide reports when and where the escape character "\" is used.
You may want to check these locations yourself as consistency checks on
this construct are beyond the scope of this program.
   The same holds true for the use of the "@" character which can be
escaped with another "@". CheckGuide also warns you when it encounters
single "@" and "\" characters that don't seem to belong to a command or
control sequence.

4.8. Other messages
-------------------
In addition to the errors listed above, CheckGuide also performs consistency
checks on command parameters which will be reported with AmigaDOS error
messages.

5. Implementation
-----------------
Don't expect documentation, CheckGuide grew out of a ten minute hack I wrote
in order to find errors in the CygnusEd online documentation, and the source
code still shows. CheckGuide does two passes on the document; the first to
collect node names and the second to match them with link commands. During
both passes CheckGuide attempts to detect and report defects. The net effect
being that the error messages it produces are not necessarily in ascending
line number order.
   The keyword tests are not complete. I tried to collect all known keywords
AmigaGuide understands, but hit a brick wall since they are so poorly
documented.
   While I am determined to retain the rights to this software, don't let
that put you off. Enhancement requests and improvements to the actual
implementation are always welcome.

6. Conclusions
--------------
As testing with CheckGuide revealed, the majority of AmigaGuide databases
have severe defects. I guess CheckGuide was badly necessary.