The AutoDoc Formatter 1.0 (c) 1994 Martin Mares, MJSoft System Software ================================================================================ Preface ======= ADF and its documentation are Copyright (c) Martin Mares, MJSoft System Software, Prague, Czech Republic. This archive can be freely redistributed, as long as all of its files are included in their original form without any additions, deletions or modifications, and no more than a nominal fee is charged for its distribution. All copyright notices in the programs and accompanying documentation files must remain on their places. Also '.displayme' and other similar files may not be added. This is generally known as FREEWARE. Special permission is given to Fred Fish to distribute this program on his "Fish Disks". This software is provided "AS IS" without warranty of any kind, either expressed or implied. The author is not responsible for any damage caused by it. Requirements ============ ADF requires Kickstart 2.04 or higher and the ss.library version 4 or newer (it can be downloaded from the Aminet in archive SSLib.lha). Introduction ============ Some years ago, CBM introduced a standard format for writing documentation of libraries and other system modules - the Autodocs. This is a relatively good format and is used by many programmers which are interested in creating of additional system modules, but it is a bit hard to maintain, because it contains still the same headers for each function and the parameters are described on three different places. The AutoDoc Formatter tries to simplify this hard work. This document doesn't explain the style rules of Autodocs. ADF generates the doc from given group of source files containing documentation material in comments. Each block describing one function starts with ??**** on the start of line. The question marks may be replaced by any characters (allows ADF to be used with Assembler, C, Pascal and many other languages). This header is followed by doc lines of the following form: ?* '?' can be again replaced by any single character, is not required (but if you specify no command, you have to write both the leading and the trailing space of the command field or to use a TAB character instead). The second space can be replaced by a TAB. Lines containing only the parameter are treated as a continuation of parameters of previous command. Lines containing neither the command nor the parameter are considered to be a paragraph break. The function doc block is finished by line starting with ??****. Commands ======== All standard commands consist of exactly one character. Anything with more than one character is treated as a custom heading and all underscores in it are automatically converted to blanks. If you specify a section header which is identical to the current one, only paragraph break will happen. = right-hand side of NAME chunk. If used more than once, it specifies other whole lines appended to the NAME chunk. Must be specified before any other chunks. i declaration of input. Followed by: name,register,type = description. ADF constucts SYNOPSIS and INPUT chunks from these declarations. Type is needed only for C-language declarations. If no type is used, the second comma may be omitted. If you enter no name, no real input will be generated, only the description will be inserted as a paragraph to the INPUT chunk. Such insertions are allowed only after all real parameters. If no register name is given, D0 is assumed. Inputs and outputs must be specified after the '=' chunk and before all other chunks. r declaration of result. Same syntax as 'i'. o declaration of output. Same syntax as 'i'. Not inserted to SYNOPSIS. f FUNCTION chunk. e EXAMPLE n NOTE b BUGS s SEE ALSO t TAGS. Special indentation used. w WARNING g FLAGS. Special indentation used. ! Raw insertion. Current paragraph is flushed and the parameter is inserted to output text before any processing except for indentation, which is done always. > Break current paragraph and increase indent level by 3 characters. < Break current paragraph and decrease indent level by 3 characters. * Comment (ignored). - Itemization. New paragraph is started and the '-' sign is inserted before new paragraph. Special indentation used. Special control lines --------------------- You can specify global prefix of all names (such as 'ghost.library'). It can be done by including '??**** =' in your source. The slash character will be appended automatically. You can also set C or ASM mode by including '??**** #' (the mode is given in lower case). In the ASM mode, no C declaration in the SYNOPSIS chunk are generated and the data types in declarations of inputs/outputs/resultsare ignored. Final words ----------- Send suggestions and bug reports to .