home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Contributions / Olaf_Barthel / Tools / AmigaGuide / CheckGuide / CheckGuide.doc < prev    next >
Encoding:
Text File  |  1997-08-21  |  13.5 KB  |  389 lines

  1. CheckGuide - A tool to check the consistency of AmigaGuide databases
  2. ====================================================================
  3. Copyright © 1997 by Olaf Barthel <olsen@sourcery.han.de>
  4. All Rights Reserved
  5.  
  6. 1. What this program does
  7. -------------------------
  8. Authoring AmigaGuide files is easy; the difficult part is to produce
  9. consistent databases AmigaGuide will display correctly and which don't
  10. contain unused nodes, references to undefined nodes, syntax errors and other
  11. troubles that are really difficult to spot.
  12.    The original AmigaGuide was rewritten for Workbench 3.0 where it was
  13. implemented as a datatypes class. As it turned out, the new implementation
  14. behaved differently. This was caused by the introduction of the backslash
  15. ("\") as an escape character and a different parser which was less tolerant.
  16.    The big problem of AmigaGuide is that it has no strict syntax definition.
  17. Nobody really seems to know when and where a backslash has its effects. Also,
  18. AmigaGuide does not detect errors in the documents it reads. It may behave
  19. unpredictably, but no errors are reported.
  20.    CheckGuide does a number of consistency checks on the databases and
  21. reports them. Some of the problems reported really count as warnings,
  22. AmigaGuide will still process and display the document, but may behave in an
  23. unpredictable way. Other problems reported really belong into the realm of
  24. "style". See for yourself.
  25.  
  26. 2. What this program does not
  27. -----------------------------
  28. As no strict syntax definition of the AmigaGuide "language" exists and there
  29. is no complete list of keywords which AmigaGuide understands, CheckGuide
  30. cannot find all possible problems. An AmigaGuide file may still count as
  31. "correct" if it fails any of the tests CheckGuide makes, because as a last
  32. resort, the actual AmigaGuide implementation defines compliance.
  33.    A specific problem is in the treatment of the escape character ("\") which
  34. due to incomplete documentation is not always treated the same way as
  35. AmigaGuide treats it.
  36.  
  37. 3. Starting the program
  38. -----------------------
  39. CheckGuide takes any number of arguments, each of which must refer to the
  40. name of a file to read and check. The following options are supported:
  41.  
  42.    -r, --recursive
  43.  
  44.    CheckGuide will operate in recursive mode, which means that if a link
  45.    to a file is found, CheckGuide will proceed to follow this link and
  46.    check the file. When following links, each file is checked exactly
  47.    once, so no processing time is wasted or circular dependencies crop up.
  48.  
  49.    -o, --onlyguidefiles
  50.  
  51.    This works in conjunction with the -r option: when following a link,
  52.    CheckGuide will silently stop processing any file that does not
  53.    qualify as an AmigaGuide database (i.e. if it does not have the
  54.    @DATABASE keyword in the first line).
  55.  
  56.    -w, --nowarnings
  57.  
  58.    This option suppresses reporting of problems that do not really count
  59.    as errors.
  60.  
  61. 4. Errors reported
  62. ------------------
  63. The following list explains what error messages CheckGuide produces and what
  64. they mean. As said before, some of the messages really count as warnings
  65. only.
  66.  
  67. 4.1. Buttons
  68. ------------
  69. By default, AmigaGuide displays hyperlinks as buttons (although the
  70. appearance is configurable). These buttons are declared using a common syntax
  71. like this:
  72.  
  73.    @{<Label> (Command) (Parameters)}
  74.  
  75. Some commands take additional parameters (such as the "LINK" command), while
  76. some do not (such as the "QUIT" command).
  77.  
  78. Messages:
  79.  
  80.     Unknown link command <Name>
  81.  
  82.         The command specified for the button is not recognized. Known
  83.     commands include LINK, ALINK, CLOSE, RX, RXS, SYSTEM and QUIT.
  84.  
  85.     Missing closing brace in button declaration
  86.     Unbalanced open brace in button declaration
  87.  
  88.         Button declarations cannot span multiple lines, which
  89.     means that the closing brace has to be on the same line as the
  90.     "@{" token that introduces the link.
  91.  
  92.     Missing quote in button declaration
  93.  
  94.         The button label must be enclosed in quotes. With
  95.     some of the commands you need to enclose the parameters in
  96.     quotes. If the quotes are unbalanced, AmigaGuide may fail to
  97.     parse the remainder of the line correctly.
  98.  
  99.     Incomplete/invalid link declaration
  100.  
  101.         The original AmigaGuide V34 would tolerate button
  102.     declarations which had blank spaces between the @ character
  103.     and the open brace (as in "@ {"). However, AmigaGuide V39
  104.     and up no longer recognize this syntax.
  105.  
  106.     Button label <Text> must be enclosed in quotes
  107.  
  108.         The label of each button must be enclosed in quotes,
  109.     even if it includes no blank space characters. If the quotes
  110.     are missing, AmigaGuide V40 will start throwing Enforcer hits.
  111.  
  112. 4.1.1. Link commands
  113. --------------------
  114. Links are declared with the following commands:
  115.  
  116.    @{<Label> LINK <Node or file> [Line number]}
  117.    @{<Label> ALINK <Node or file> [Line number]}
  118.  
  119. The line numbers may be omitted. The first parameter must refer to a node;
  120. AmigaGuide will always try to find the node in the current database and then
  121. attempt to open a file bearing the node name. If this happens, the given name
  122. is assumed to consist of a document name and a node name, like this:
  123.  
  124.    foo:bar/baz/MAIN
  125.  
  126. In this example "foo:bar/baz" is the name of the file to open and "MAIN" is
  127. the node to display. "MAIN" is the general catchall, i.e. links to
  128. non-AmigaGuide-files can be established only if the node name is "MAIN".
  129. Otherwise, AmigaGuide will complain about being unable to open the file.
  130. The same happens if the node name is omitted, i.e. the plain file name is not
  131. sufficient to define a link.
  132.  
  133. Messages:
  134.  
  135.     ALINK line number invalid
  136.     LINK line number invalid
  137.  
  138.         The line number given is not a number but contains
  139.     alphanumeric characters.
  140.  
  141.     ALINK node name required
  142.     LINK node name required
  143.  
  144.         The node or file name parameter has been omitted.
  145.  
  146.     File found in relative path only <Name>
  147.  
  148.         You can create links to other files which AmigaGuide will
  149.     load and display instead of the database you originally started
  150.     from. The current implementation of AmigaGuide (V40) tries to
  151.     open files pointed to by links by the names given. Thus, a file
  152.     name "foo/bar/baz/MAIN" will cause the file "foo/bar/baz" to be
  153.     opened, relative to the current directory of the AmigaGuide
  154.     program. This directory may not be the same as the directory the
  155.     file you originally started from is found in. Naturally, this can
  156.     cause some confusion as AmigaGuide may complain about being unable
  157.     to open a file a link points to. Generally, it is safer to use
  158.     absolute paths instead (as in "foo:bar/baz/MAIN"), but this
  159.     approach has its own risks and disadvantages.
  160.  
  161.     Reference to undefined node <Name>
  162.  
  163.         The file or node a link refers to is neither found in
  164.     the current document nor on the filing system. CheckGuide
  165.     tries to interprete file names relative to the name of the
  166.     database it checks, but even that can fail if files are
  167.     simply not there. AmigaGuide also uses an environment variable
  168.     "PATH" to locate nodes. CheckGuide does not support this feature.
  169.     And really, you should not depend on it in your databases.
  170.  
  171. 4.1.2. ARexx and AmigaDOS commands
  172. ----------------------------------
  173. ARexx and AmigaDOS commands are declared with the following commands:
  174.  
  175.    @{<Label> RX <Command>}
  176.    @{<Label> RXS <Command>}
  177.    @{<Label> SYSTEM <Command>}
  178.  
  179. Messages:
  180.  
  181.     RX command required
  182.     RXS command required
  183.     SYSTEM command required
  184.  
  185.         The required command parameter was omitted.
  186.  
  187. 4.1.3. Shutdown commands
  188. ------------------------
  189. Shutdown commands include CLOSE and QUIT:
  190.  
  191.    @{<Label> CLOSE}
  192.    @{<Label> QUIT}
  193.  
  194. Messages:
  195.  
  196.     Too many arguments for CLOSE command
  197.     Too many arguments for QUIT command
  198.  
  199.         Neither command takes any parameters.
  200.  
  201. 4.2. Commands
  202. -------------
  203. AmigaGuide recognizes a database it understands by a command found in the first
  204. line of the file. Other commands are used to convey information (such as
  205. copyrights, version numbers, etc.) and to provide structure (such as the node
  206. declarations). Commands are introduced by the @ character.
  207.  
  208. Messages:
  209.  
  210.     Command <Name> has no effect
  211.  
  212.         A command such as @DATABASE must be placed in the first
  213.     column of a line for AmigaGuide to recognize it. If it shows up
  214.     anywhere else in the line, AmigaGuide will show it as plain text,
  215.     which is probably not what you want.
  216.  
  217.     The first line must contain the @DATABASE keyword
  218.  
  219.         An AmigaGuide database must begin with the @DATABASE command
  220.     in its first line for AmigaGuide to recognize it as such.
  221.  
  222.     MAIN node missing
  223.  
  224.         An AmigaGuide database has to contain at least one single
  225.     node, the MAIN node.
  226.  
  227.     Unknown keyword <Name>
  228.  
  229.         An unknown command was found at the beginning of a line.
  230.  
  231. 4.3. Nodes
  232. ----------
  233. An AmigaGuide database consists of a set of so-called nodes. At least one
  234. node has to be defined, the MAIN node. Nodes are defined with the @NODE and
  235. @ENDNODE commands.
  236.  
  237. Messages:
  238.  
  239.     Duplicate @NODE <Name> (see line <Number>)
  240.  
  241.         You assigned the same name to more than one node. As the name
  242.     is no longer unique (note: case does not matter), AmigaGuide may
  243.     display either one when you move to it. Which one is displayed is
  244.     subject to undefined behaviour. The line number displayed in this
  245.     error message refers to the first line in which a node with the
  246.     given name is declared.
  247.  
  248.     Unbalanced @ENDNODE
  249.  
  250.         Each @NODE declaration has to be matched by exactly one
  251.     @ENDNODE command. Here an unused @ENDNODE command has been
  252.     found.
  253.  
  254.     Unbalanced @NODE
  255.  
  256.         Each @NODE declaration has to be matched by exactly one
  257.     @ENDNODE command. Here an unterminated @NODE command has been
  258.     found.
  259.  
  260.     Unused @NODE <Name>
  261.  
  262.         This is an indication of a node that has been declared
  263.     but has no links from this file to it. This may be exactly what
  264.     you want if these nodes are referred to from other AmigaGuide
  265.     databases only.
  266.  
  267. 4.4. Table of contents, index and browsing
  268. ------------------------------------------
  269. For each node you may declare the name of the node that should be displayed
  270. when the "Contents" and "Index" buttons are pressed.
  271.  
  272. Messages:
  273.  
  274.     INDEX node <Name> missing
  275.     TOC node <Name> missing
  276.  
  277.         The node you specified with the @INDEX/@TOC command could
  278.     not be found.
  279.  
  280.     More than one @INDEX at top level
  281.     More than one @TOC at top level
  282.  
  283.         While no node is currently being defined you can still
  284.     declare the names of the @INDEX and @TOC nodes valid for the
  285.     remainder of the document. Normally, these should be declared
  286.     before any other nodes are defined. And there better be only
  287.     a single declaration of these.
  288.  
  289.     @NEXT references undefined node <Name>
  290.     @PREV references undefined node <Name>
  291.  
  292.         The two browsing commands must of course refer to
  293.     existing nodes.
  294.  
  295. 4.5. Text colour and style
  296. --------------------------
  297. AmigaGuide V39 introduced control commands for text colour and style. Like
  298. buttons, these can appear anywhere in the text. The control commands look
  299. like this:
  300.  
  301.    @{fg text}
  302.    @{bg shine}
  303.    @{b}
  304.    @{ub}
  305.  
  306. Messages:
  307.  
  308.     Invalid colour control string <Name>
  309.     Invalid colour <Name>
  310.  
  311.         The colour specified with the @{fg } and @{bg } commands is
  312.     not known. Known colours include TEXT, SHINE, SHADOW, FILL, FILLTEXT,
  313.     BACK and HIGHLIGHT.
  314.  
  315.     Unbalanced <Command> in column <Number>
  316.  
  317.         Text style commands should be balanced, e.g. @{u} should be
  318.     followed by @{uu} somewhere down the text.
  319.  
  320.     Command <Command> in column <Number> has no effect
  321.  
  322.         Turning off a text style command (e.g. @{ub}) while it is
  323.     already turned off will have no noticeable effect.
  324.  
  325. 4.6. Style
  326. ----------
  327. The following messages deal with the @DATABASE command at the beginning of
  328. each AmigaGuide file and the file name.
  329.  
  330. Messages:
  331.  
  332.     Database <Name> and file name <Name> do not match
  333.  
  334.         Database and file name should be identical.
  335.  
  336.     Database <Suffix> and file name <Suffix> suffixes do not match
  337.  
  338.         The file name suffixes (.guide) are not identical,
  339.     they might even have been omitted.
  340.  
  341.     Database name <Name> contains path specifiers
  342.  
  343.         The @database name should only contain the
  344.     base name of the file.
  345.  
  346.     Database name uses obsolete .hyper suffix
  347.     File uses obsolete .hyper name suffix
  348.  
  349.         The original AmigaGuide specs defined that each database
  350.     name should have the suffix ".hyper" appended. This was changed
  351.     later to ".guide".
  352.  
  353. 4.7. Escape characters
  354. ----------------------
  355. CheckGuide reports when and where the escape character "\" is used.
  356. You may want to check these locations yourself as consistency checks on
  357. this construct are beyond the scope of this program.
  358.    The same holds true for the use of the "@" character which can be
  359. escaped with another "@". CheckGuide also warns you when it encounters
  360. single "@" and "\" characters that don't seem to belong to a command or
  361. control sequence.
  362.  
  363. 4.8. Other messages
  364. -------------------
  365. In addition to the errors listed above, CheckGuide also performs consistency
  366. checks on command parameters which will be reported with AmigaDOS error
  367. messages.
  368.  
  369. 5. Implementation
  370. -----------------
  371. Don't expect documentation, CheckGuide grew out of a ten minute hack I wrote
  372. in order to find errors in the CygnusEd online documentation, and the source
  373. code still shows. CheckGuide does two passes on the document; the first to
  374. collect node names and the second to match them with link commands. During
  375. both passes CheckGuide attempts to detect and report defects. The net effect
  376. being that the error messages it produces are not necessarily in ascending
  377. line number order.
  378.    The keyword tests are not complete. I tried to collect all known keywords
  379. AmigaGuide understands, but hit a brick wall since they are so poorly
  380. documented.
  381.    While I am determined to retain the rights to this software, don't let
  382. that put you off. Enhancement requests and improvements to the actual
  383. implementation are always welcome.
  384.  
  385. 6. Conclusions
  386. --------------
  387. As testing with CheckGuide revealed, the majority of AmigaGuide databases
  388. have severe defects. I guess CheckGuide was badly necessary.
  389.