home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / dev / misc / adf / adf.doc < prev    next >
Text File  |  1995-02-17  |  6KB  |  155 lines
  1.  
  2.                            The AutoDoc Formatter 1.1
  3.  
  4.                  (c) 1995 Martin Mares, MJSoft System Software
  5.  
  6. ================================================================================
  7.  
  8.  
  9. Preface
  10. =======
  11.  
  12.   ADF and its documentation are Copyright (c) Martin Mares, MJSoft System
  13. Software, Prague, Czech Republic.
  14.  
  15.    This  archive  can  be  freely  redistributed as long as all of its files are
  16. included   in   their   original   form  without  any  additions,  deletions  or
  17. modifications  (excluding addition of other README-style files and icons) and no
  18. more  than a nominal fee is charged for its distribution.  All copyright notices
  19. in  the  programs and accompanying documentation files must remain intact.  It's
  20. especially  forbidden  to add various '.displayme' files and BBS advertisements.
  21. This style of distribution is generally known as FREEWARE.
  22.  
  23.    Special  permission is given to Fred Fish to distribute this program on his
  24. "Fish Disks".
  25.  
  26.    This  software  is  provided  "AS  IS" without warranty of any kind, either
  27. expressed  or implied.  The author is not responsible for any damage caused by
  28. it.
  29.  
  30.  
  31. Requirements
  32. ============
  33.  
  34.    ADF requires Kickstart 2.04 or higher and the ss.library version 5 or newer
  35. (it can be downloaded from the Aminet in archive SSLib<version>.lha).
  36.  
  37.  
  38. Introduction
  39. ============
  40.  
  41.    Some  years ago, CBM introduced a standard format for writing documentation
  42. of  libraries  and  other system modules - the Autodocs.  This is a relatively
  43. good  format  and is used by many programmers which are interested in creating
  44. of  additional  system  modules,  but it is a bit hard to maintain, because it
  45. contains  still  the  same  headers  for  each function and the parameters are
  46. described  on three different places.  The AutoDoc Formatter tries to simplify
  47. this hard work.
  48.  
  49.    This document doesn't explain the style rules of Autodocs.
  50.  
  51.    ADF  generates  the  doc  from  given  group  of  source  files  containing
  52. documentation material in comments.  Each block describing one function starts
  53. with  ??****  <funcname>  on  the  start  of  line.  The question marks may be
  54. replaced  by  any  characters (allows ADF to be used with Assembler, C, Pascal
  55. and  many  other  languages).   This  header  is  followed by doc lines of the
  56. following form:
  57.  
  58. ?* <command> <parameter>
  59.  
  60.    '?'  can  be  again  replaced  by  any  single  character, <command> is not
  61. required  (but  if  you specify no command, you have to write both the leading
  62. and  the  trailing  space  of  the  command  field  or  to use a TAB character
  63. instead).   The  second space can be replaced by a TAB.  Lines containing only
  64. the parameter are treated as a continuation of parameters of previous command.
  65. Lines  containing neither the command nor the parameter are considered to be a
  66. paragraph break.
  67.  
  68.    The function doc block is finished by line starting with ??****.
  69.  
  70.    You can freely used hard spaces (ALT+SPACE) in your AutoDoc texts,
  71. preventing ADF from breaking the line on that place. The hard spaces are
  72. replaced by normal spaces or tabulators in the output.
  73.  
  74.  
  75. Commands
  76. ========
  77.  
  78.    All standard commands consist of exactly one character.  Anything with more
  79. than  one  character  is treated as a custom heading and all underscores in it
  80. are automatically converted to blanks.
  81.  
  82.    If you specify a section header which is identical to the current one, only
  83. paragraph break will happen.
  84.  
  85. =    right-hand side of NAME chunk. If used more than once, it specifies
  86.     other whole lines appended to the NAME chunk. Must be specified before
  87.     any other chunks.
  88. i    declaration of input. Followed by: name,register,type = description.
  89.     ADF constucts SYNOPSIS and INPUT chunks from these declarations. Type is
  90.     needed only for C-language declarations. If no type is used, the second
  91.     comma may be omitted. If you enter no name, no real input will be
  92.     generated, only the description will be inserted as a paragraph to the
  93.     INPUT chunk. Such insertions are allowed only after all real parameters.
  94.     If no register name is given, D0 is assumed. Inputs and outputs  must
  95.     be specified after the '=' chunk and before all other chunks.
  96. r    declaration of result. Same syntax as 'i'.
  97. o    declaration of output. Same syntax as 'i'. Not inserted to SYNOPSIS.
  98. f    FUNCTION chunk.
  99. e    EXAMPLE
  100. n    NOTE
  101. b    BUGS
  102. s    SEE ALSO
  103. t    TAGS. Special indentation used.
  104. w    WARNING
  105. g    FLAGS. Special indentation used.
  106. !    Raw insertion. Current paragraph is flushed and the parameter is
  107.     inserted to output text before any processing except for indentation,
  108.     which is done always.
  109. >    Break current paragraph and increase indent level by 3 characters.
  110. <    Break current paragraph and decrease indent level by 3 characters.
  111. *    Comment (ignored).
  112. -    Itemization. New paragraph is started and the '-' sign is inserted
  113.     before new paragraph. Special indentation used.
  114. v    Define C Vararg stub name, optionally followed by some comments
  115.     appended to the NAME chunk (usually a version number).
  116. m    Define additional argument for C Vararg stub (may be used multiple
  117.     times). The parameters are almost the same as for INPUT parameters,
  118.     but the register name is not specified and the argument description
  119.     (after the '=' sign) is optional (if it's omitted, this argument
  120.     is not listed under the INPUT header). This _must_ be defined when
  121.     you specify 'v'. The ellipsis ('...') after the argument is added
  122.     automatically, the last argument (tag list or something similar)
  123.     of the original function is removed and replaced by these additional
  124.     arguments.
  125.  
  126.  
  127. Special control lines
  128. ---------------------
  129.  
  130.    You  can  specify global prefix of all names (such as 'ghost.library').  It
  131. can  be  done  by  including  '??****  =<prefix>'  in  your source.  The slash
  132. character will be appended automatically.
  133.  
  134.    You  can  also set C or ASM mode by including '??**** #<mode>' (the mode is
  135. given in lower case).  In the ASM mode, no C declaration in the SYNOPSIS chunk
  136. are  generated and the data types in declarations of inputs/outputs/resultsare
  137. ignored.
  138.  
  139.  
  140. History
  141. -------
  142.  
  143. 1.0 (12.12.1994) - First released version
  144.  
  145. 1.1 (17.2.1995) - C Varargs support added (thanks to Dirk Federlein for the idea)
  146.         - Parentheses in SYNOPSIS chunk have one extra space inside.
  147.         - Usage of hard spaces explained in the doc.
  148.  
  149.  
  150. Final words
  151. -----------
  152.  
  153.    Send suggestions and bug reports to <mjsoft@k332.feld.cvut.cz>.
  154.  
  155.