home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 144.lha / SDX.doc < prev    next >
Text File  |  1986-11-21  |  3KB  |  74 lines
  1.  
  2.                                 SDX
  3.                   Simple Documentation Extractor
  4.                  Copyright (C) 1988 by Bryan Ford
  5.  
  6.     SDX is a program which scans through C source code for documentation,
  7. and extracts it into a file.  I wrote it because Fred Fish's dex was much
  8. more than I needed, and somewhat harder to use, mainly because you had to
  9. have a .dexrc file.  Also, it required its output to be run through a
  10. text processor, and for some reason my text processor didn't like the
  11. output files it created, in that backslashes were inserted before
  12. every period.  This is why I call it the "simple" documentation extractor -
  13. because it doesn't have any fancy styles or boxes around titles - it just
  14. extracts documentation.
  15.     To run SDX, just type SDX file1 file2 file3...  Wildcards are allowed,
  16. but right now my wildcard routines are quite buggy (I just wanted to get
  17. this program *out*), so the only wildcards you can use are the single
  18. asterisk (*), or a single #?, both of which mean "all the files in this
  19. directory".  This shouldn't be too much of a problem, because I *doubt* it
  20. will find documentation in non-source code.  The output goes to the
  21. standard output, so you'll probably want to redirect it.
  22.     In all source files, SDX searches for strings like this:
  23. <nl>/*<nl><sp>*<sp><sp>, where <nl> is a newline and <sp> is a space.
  24. Then it checks the line that started with <sp>*<sp><sp>.  If all of the
  25. characters on that line are either non-alphabetic or uppercase, it starts
  26. extracting.  If there are any lowercase characters, it skips it and tries
  27. to find the search string again.
  28.     If it finds documentation, it will extract it to stdout, with the
  29. <sp>*<sp><sp> changed to four spaces.  Tabs just after the first asterisk
  30. are changed to six spaces, but others aren't affected.  It stops extracting
  31. when it comes to a line without <sp>* at the beginning, finds a <sp>*/
  32. line, or finds the end of the file.  It will then output a form-feed
  33. character to the standard output (which will clear the screen on the
  34. Amiga's console device).
  35.     Now that the technical junk is over, this sample doc should clarify
  36. things.  It is for a function named `xyz' which prints the specified string
  37. to the screen, and returns TRUE if it was successful.
  38.  
  39. /*
  40.  *  FUNCTION
  41.  *    xyz - Prints a string to the screen
  42.  *
  43.  *  SYNOPSIS
  44.  *    Success = xyz(String)
  45.  *
  46.  *  DESCRIPTION
  47.  *    Prints the string to the screen
  48.  *
  49.  *  INPUTS
  50.  *    String - Pointer to the string to print
  51.  *
  52.  *  RETURNS
  53.  *    Returns TRUE if it was successful, or FALSE if unsuccessful.
  54.  *
  55.  */
  56.  
  57.     Although this might not be a very good example, it shows how things
  58. work.  I have used this program to extract documentation on my huge (30K)
  59. custom library, and it has worked nicely.
  60.     Now for what you've all been waiting for.  This program is in a way
  61. Shareware, but I won't require you to send a donation.  If you like this
  62. program, and think it's worth something, just send whatever you think it's
  63. worth to my address below.  This program is freely distributable, so you
  64. can copy it as much as you like, and are encouraged to do so.
  65.     I'm also interested in what anyone has to say about this program, or
  66. ideas for other useful utilities which need making.  My address is below.
  67.  
  68.               Snail:      Bryan Ford
  69.                           1790 East 1400 North
  70.                           Logan, UT 84321
  71.               Fone:       (801)753-1159
  72.               Bitnet:     FATQW@USU
  73.  
  74.