home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / misc / robodoc.lha / ROBODoc.doc < prev    next >
Encoding:
Text File  |  1992-09-02  |  13.0 KB  |  417 lines
  1. ===============================================================================
  2.  
  3.                 ROBODoc v1.0a
  4.  
  5. -------------------------------------------------------------------------------
  6.  
  7.     (c) 1995, by Jacco van Weert, Maverick Software Development
  8.     email: weertj@euronet.nl
  9.  
  10.     ROBODoc documentation for the;
  11.       Amiga computers.
  12.       DEC Alpha systems.
  13.       DEC VAX systems.
  14.  
  15.     New versions of ROBODoc are made available on AmiNet.
  16.  
  17.     or
  18.  
  19.     On the Amigoline BBS;
  20.         Tel:    +31-8347-84968    (International)
  21.         Tel:    08347-84968    (From the Netherlands)
  22.  
  23. ===============================================================================
  24.  
  25.  
  26.  
  27.                 Preface
  28.                 -------
  29.  
  30. The complete ROBODoc archive is copyrighted by Jacco van Weert,
  31. Maverick Software Development.
  32.  
  33. ROBODoc can be freely distributed on FREEWARE base as long as all files remains
  34. in there original state, no files may be added to the archive, and also no files
  35. may be excluded.
  36.  
  37. This software is provided on an "AS IS" basis without warranty of any kind. The
  38. author is not responsible for any damage caused by using this software.
  39.  
  40.  
  41.                 Hardware requirements
  42.                 ---------------------
  43.  
  44. Amiga version:
  45.     ROBODoc runs well on every Amiga, no special requirements are necessary.
  46.  
  47. DEC Alpha/VAX:
  48.     ROBODoc v1.0a has been tested on a DEC Alpha system using OpenVMS-AXP 
  49.     v1.5, but in general terms there should be no problem to run this
  50.     program on other systems. It is a general C program.
  51.  
  52.  
  53.                 Introduction
  54.                 ------------
  55.  
  56. ROBODoc is based on the AutoDocs program written some time ago by Commodore.
  57. The idea is to include for every procedure/function a standard header
  58. containing all sorts of information about that procedure/function.
  59. ROBODoc will extract those headers from the source file and put them in a
  60. autodocs-file. This autodocs-file can be written in three different formats;
  61.  
  62. - Normal format;
  63.     The autodocs-file is just a plain ASCII text-file, this file is very
  64.     closely related to the one that the original AutoDocs program would
  65.     generated.
  66.  
  67. - HTML format;
  68.     The autodocs-file will be written as a HTML-file (HyperText Markup
  69.     Language), this format is used on the WWW-Internet. By using a
  70.     Mosiac/Netscape program you view the documentation.
  71.  
  72. - AmigaGuide format;
  73.     This is a format used on the Amiga computers to view in a HyperText
  74.     way a text-file. The AmigaGuide (OS3.0 tags are supported) program
  75.     is necessary to view the resulting autodocs-file.
  76.  
  77.  
  78.                 This Version
  79.                 ------------
  80.  
  81. This is the first 'real' version of ROBODoc, the previous 0.x versions where
  82. test versions. In version 1.0a all the options are included which I had
  83. in mind.
  84.  
  85.                 Procedure/Function Header
  86.                 -------------------------
  87.  
  88. We shall now discuss the general format of a procedure/function header.
  89. Full discussion of the header can be found in AutoDocs-documentation, this
  90. is a brief explanation of the header and the ROBODoc special items.
  91.  
  92. ROBODoc handles three different type of headers;
  93.  
  94. - MainProgram header (optional);
  95.     These headers are placed at the start of a program and containing
  96.     some general information about the program. These where not
  97.     available in the original AutoDocs program.
  98.  
  99. - Normal header;
  100.     The normal header, available to the general public.
  101.  
  102. - Internal header;
  103.     The internal header not available to the general public, mainly
  104.     used by the programmer him/herself.
  105.  
  106.  
  107.  
  108.                 MainProgram header
  109.                 ------------------
  110.  
  111. We now discuss an example of a MainProgram header. The following header was
  112. taken from the original ROBODoc program.
  113.  
  114. /****h* AUTODOC/ROBODoc ***************************************************
  115. *
  116. *    NAME
  117. *      ROBODoc -- AutoDoc formatter
  118. *
  119. *    COPYRIGHT
  120. *      Maverick Software Development
  121. *      This software is public domain and can be freely redistributed as
  122. *      long as it is in it's original state.
  123. *
  124. *    FUNCTION
  125. *      ROBODoc is indented as a replacement for the original AutoDocs program
  126. *      ROBODoc will extract from a source file the procedure comment headers
  127. *      and put them in a seperate documentation file. There are basically
  128. *      three different file outputs, Basic (Normal text based)/ HTML
  129. *      Markup langauge mainly used on the Internet thus the files can be viewed
  130. *      with a normal Mosaic viewer/ and finally AmigaGuide format, this format
  131. *      can be viewed by an AmigaGuide program (AMIGA ONLY).
  132. *
  133. *    AUTHOR
  134. *      Jacco van Weert
  135. *
  136. *    CREATION DATE
  137. *      20-Dec-94
  138. *
  139. *    MODIFICATION HISTORY
  140. *      25-Jan-94    -    v0.92: First version
  141. *         10-Mar-95     -       v1.0 : Complete version
  142. *
  143. *    NOTES
  144. *      None  
  145. *
  146. ****************************************************************************
  147. */
  148.  
  149. Because the program was written in C the header is in this form, in assembler
  150. or other langauges it would look a little bit different.
  151. MOST IMPORTANT is that the first line of the header must be reconized by the
  152. ROBODoc program. Therefore is the following rule;
  153.  
  154. The first character is not important.
  155. The next 4 characters must be asterics '*'.
  156. The next character defines the header type;
  157.     'h' = MainProgram
  158.     '*' = Normal header
  159.     'i' = Internal header
  160. Then follows 1 asteric '*' and 1 space.
  161. After this follows the [module name]/[procedure name]
  162.  
  163. Example:
  164.  
  165. In C    ->    /****h* programs/greatprogram.library *********
  166.     or    /****** greatprogram.library/program_init ******
  167.     or    /****i* greatprogram.library/very_secret *******
  168. In Assembler
  169.     ->    ;****h* programs/greatprogram.library ********
  170.     ->    ******* greatprogram.library/program_init ******
  171.     ->    *****i* greatprogram.library/internal_affairs *****
  172.  
  173. The header ends with a following line;
  174.  
  175. *********..etc
  176. or
  177. ;********..etc
  178. or
  179. %********..etc
  180.  
  181. In general the first character of the line is not important.
  182.  
  183.  
  184. But now back to the MainProgram header, it has the following items;
  185.  
  186. NAME            - The name of the program.
  187. COPYRIGHT        - The copyright note.
  188. FUNCTION        - The general function of the program.
  189. AUTHOR            - The author of the program (very important :)
  190. CREATION DATE        - When did you started?
  191. MODIFICATION HISTORY    - All the changed made to the program.
  192. NOTES            - General notes.
  193.  
  194. Important is that all items have the same indent.
  195.  
  196.  
  197.                 Normal header
  198.                 -------------
  199.  
  200. The normal header differs not from the original AutoDoc header which we
  201. will give here;
  202.  
  203. /****** financial.library/StealMoney ******************************************
  204. * 
  205. *   NAME    
  206. *     StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  207. * 
  208. *   SYNOPSIS
  209. *    error = StealMoney( userName,amount,destAccount,falseTrail )
  210. *    D0,Z                D0       D1.W    A0         [A1]
  211. *
  212. *    BYTE StealMoney
  213. *         ( STRPTR,UWORD,struct AccountSpec *,struct falseTrail *);
  214. *
  215. *   FUNCTION
  216. *    Transfer money from the Federal Reserve Bank into the specified
  217. *    interest-earning checking account.  No records of the transaction
  218. *    will be retained.
  219. * 
  220. *   INPUTS
  221. *     userName      - name to make the transaction under.  Popular favorites
  222. *                    include "Ronald Reagan" and "Mohamar Quadaffi".
  223. *    amount        - Number of dollars to transfer (in thousands).
  224. *    destAccount   - A filled-in AccountSpec structure detailing the
  225. *                    destination account (see financial/accounts.h).
  226. *            If NULL, a second Great Depression will be triggered.
  227. *    falseTrail    - If the DA_FALSETRAIL bit is set in the destAccount,
  228. *            a falseTrail structure must be provided.
  229. *    
  230. *   RESULT
  231. *     error - zero for success, else an error code is returned (see
  232. *            financial/errors.h).  The Z condition code is guaranteed.
  233. * 
  234. *   EXAMPLE
  235. *    Federal regulations prohibit a demonstration of this function. 
  236. *
  237. *   NOTES
  238. *    Do not run on Tuesdays!
  239. *
  240. *   BUGS
  241. *     Before V88, this function would occasionally print the address and
  242. *    home phone number of the caller on local police 976 terminals.
  243. *    We are confident that this problem has been resolved.
  244. * 
  245. *   SEE ALSO
  246. *     CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  247. *    financial/misc.h
  248. * 
  249. *****************************************************************************/
  250.  
  251.  
  252.                 Internal header
  253.                 ---------------
  254.  
  255. The same as the Normal header, except the internal header starts with the line
  256. /****i* or ;****i* or *****i* or......
  257.  
  258.  
  259.                 Items file
  260.                 ----------
  261.  
  262. ROBODoc uses a items-file (ROBODoc.ITM) for the definition of the items.
  263. In this file all the possible item headers are stored. By default,
  264. only the discussed item header are placed but the user can add up to
  265. 50 items. The items-file must be in the directory from where ROBODoc is
  266. started.
  267.  
  268. The default items-file has the following layout;
  269.  
  270.     NAME            3
  271.     COPYRIGHT        20
  272.     SYNOPSIS        5
  273.     FUNCTION        40
  274.     AUTHOR            0
  275.     CREATION_DATE        0
  276.     MODIFICATION_HISTORY    8
  277.     INPUTS               8
  278.     RESULT               8
  279.     EXAMPLE              4
  280.     NOTES                0
  281.     BUGS                 10
  282.     SEE_ALSO             2
  283.  
  284. Every line holds first the item header name and then a item type number.
  285. The items must appear in order as they appear in a procedure header.
  286. Please note that a '_' in an item name is replaced by a space.
  287.  
  288. Item Type Number - This number is used when a HTML or AmigaGuide output
  289. is generated, it defined the layout of the text body in the resulting file.
  290.  
  291. In this Item Type Number flags are stored, current definitions;
  292.  
  293.     1    =    Item Header in Large Font.        (HTML)
  294.     2    =    Text body in Large Font.        (HTML)
  295.     4    =    Text body in Italics.            (HTML/AMIGAGUIDE)
  296.     8    =    Text body in NON-Proportional font. (HTML)
  297.     16    =    Text body in Small Font.        (HTML)
  298.     32    =    Text body in Bold.            (HTML/AMIGAGUIDE)
  299.  
  300. Add the numbers together of the options you want to have.
  301.  
  302.  
  303.                 XREF files
  304.                 ----------
  305.  
  306. The 0.x versions of ROBODoc had a simple XREF mechanism. But starting from
  307. version 1.0 ROBODoc can make references to other files.
  308. Please note that references can only be used when creating HTML or AmigaGuide
  309. files.
  310.  
  311. The [GENXREF] parameter ROBODoc will generate a standard XREF-File of the
  312. source-file. In this way XREF-files of the different source-files can be
  313. generated. When this parameter is used, ONLY the XREF-File is created NOT
  314. the autodocs-file.
  315.  
  316. As soon as all the XREF-files are created the documentation can be created.
  317. The [XREF] parameter contains the name of the file IN which the names
  318. all XREF-files are defined (xreflist_filename). This file must be created
  319. by the user.
  320. XREF-Files can also be created by the user or taken by other means, e.g.
  321. the Autodoc.xref. ROBODoc uses the same format as these standard XREF
  322. files, in v1.0a the exceptions are not yet supported.
  323.  
  324. Example:
  325.  
  326. In the ROBODoc.lha archive there are two example programs PROG1.C and PROG2.C.
  327.  
  328. First create the XREF-Files when want to create HTML autodocs-files:
  329.  
  330. >ROBODoc PROG1.C PROG1.HTML GENXREF PROG1.XREF HTML TOC SORT INTERNAL
  331. >ROBODoc PROG2.C PROG2.HTML GENXREF PROG2.XREF HTML TOC SORT INTERNAL
  332.  
  333. At this moment the XREF-Files PROG1.XREF and PROG2.XREF are created.
  334.  
  335. Now create a <xreflist_filename> file.
  336. This file will hold only two lines;
  337.  
  338. >PROG1.XREF
  339. >PROG2.XREF
  340.  
  341. More XREF-Files can being added. The name of this file can be anything,
  342. e.g. 'XREF_Files'.
  343.  
  344. Now generate the final documentation;
  345.  
  346. >ROBODoc PROG1.C PROG1.HTML XREF XREF_Files HTML TOC SORT INTERNAL
  347. >ROBODoc PROG2.C PROG2.HTML XREF XREF_Files HTML TOC SORT INTERNAL
  348.  
  349. When the source-code is not changed it not neccesary to create
  350. everytime a new XREF-File.
  351.  
  352.  
  353.                 Usage of ROBODoc
  354.                 ----------------
  355.  
  356. To list the arguments needed by ROBODoc just enter ROBODoc or ROBODoc ?
  357. To following message will be printed;
  358.  
  359. ROBODoc v1.0a, autodocs formatter
  360. ==============================================
  361. (c) 10-3-95, Maverick Software Development
  362. Written by J.v.Weert, email: weertj@euronet.nl
  363. FORMAT
  364.   ROBODoc filename docfilename [GENXREF xref_filename] [HTML] [GUIDE] [INTERNAL]
  365.  [SORT] [TOC] [XREF xreflist_filename]
  366.  
  367. The parameters;
  368.  
  369.     filename    = The source code filename.
  370.     docfilename    = The name of the documentation file,
  371.               which will be created.
  372.     GENXREF xref_filename
  373.             = Generate a XREF-file of the source code.
  374.               The <xref_filename> file is created as XREF-file.
  375.     HTML        = The documentation will be in HTML format.
  376.     GUIDE        = The documentation will be in AmigaGuide format.
  377.     INTERNAL    = The internal headers are also included.
  378.     SORT        = The procedures will be sorted.
  379.     TOC        = A table of contents will be added. TOC will be
  380.               automatically set when HTML or GUIDE is set.
  381.     XREF xreflist_filename
  382.             = Cross-references will be generated, the XREF-Files
  383.               names are stored in the <xreflist_filename> file.
  384.               
  385.  
  386.                 CONCLUSION
  387.                 ----------
  388.  
  389. This is the first complete version of ROBODoc. In the future probably more
  390. features will be added.
  391.  
  392.  
  393.                 SUGGESTIONS EN BUGS
  394.                 -------------------
  395.  
  396. Suggestions and bug reports (please use the included Bug-report form) can
  397. be send to;
  398.  
  399.     Email:    weertj@euronet.nl
  400.  
  401.     or
  402.  
  403.     Maverick Software Development, T.a.v. J.v.Weert
  404.     Haverdreef 131,
  405.     7006 LH, Doetinchem.
  406.     The Netherlands.
  407.  
  408.  
  409.                 __  __________
  410.              __/  \/         /   weertj@euronet.nl
  411.           __/  \__/ Maverick
  412.          /  \__/  \ Software
  413.          \__/  \__/ Development
  414.          _______________/        slothoub@xs4all.nl
  415.  
  416.  
  417.