home *** CD-ROM | disk | FTP | other *** search
/ Nebula 2 / Nebula Two.iso / SourceCode / MiscKit1.7.1 / MiscKit / Examples / AutoDoc / bin / autodoc
Encoding:
Text File  |  1995-11-02  |  22.5 KB  |  766 lines
  1. #!/usr/local/bin/perl5
  2.  
  3. ###############################################################################
  4. ###############################################################################
  5. ##
  6. ##    Written by Adam Swift (c) 1995 by Friday Software and Consulting
  7. ##                           All rights reserved.
  8. ##
  9. ##      This notice may not be removed from this source code.
  10. ##
  11. ##    This program is included in the MiscKit by permission from the author
  12. ##    and its use is governed by the MiscKit license, found in the file
  13. ##    "LICENSE.rtf" in the MiscKit distribution.  Please refer to that file
  14. ##    for a list of all applicable permissions and restrictions.
  15. ##
  16. ##    Because AutoDoc is licensed free of charge, there is no warranty 
  17. ##    for the program.  Copyright holder, Friday Software and Consulting, 
  18. ##    is providing this program "as is" and this program is distributed in 
  19. ##    the hope that it will be useful, but WITHOUT ANY WARRANTY; without 
  20. ##    even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
  21. ##    PARTICULAR PURPOSE.
  22. ##
  23. ###############################################################################
  24. ###############################################################################
  25.  
  26. ##
  27. ## Set the required packages for normal execution 
  28. ##
  29. require 5.000;
  30.  
  31. ##
  32. ## Set this perl file's descriptive variables
  33. ##
  34. $file_name           = 'autodoc';
  35. $file_release       = '1.8.4';
  36.  
  37. $file_mlist    = '<autodoc@friday.com>';
  38. $file_copyright       = 'Friday Software and Consulting, 1995';
  39. $file_author       = 'Adam Swift <aswift@friday.com>';
  40. @file_contributors = 
  41.   ('Bill Bumgarner <bbum@friday.com>',
  42.    'Todd Anthony Nathan <todd@icebox.com>',
  43.    'Kim Shrier <kim@media.com>',
  44.    'Craig Kelley <ckelley@capaccess.org>');
  45.  
  46. $file_version       = '$Revision: 1.5 $'; #'
  47. $file_version       =~ s!(\$\w+: | \$)!!g; 
  48. $file_id           = '$Id: autodoc,v 1.5 1995/10/20 22:10:41 aswift Exp $'; #'
  49. $file_id           =~ s!(\$\w+: | \$)!!g;
  50.  
  51.  
  52. ###############################################################################
  53. #
  54. # Purpose:    This script extracts comments and other data from Objective-C 
  55. #         source and header files.  It processes this input to produce 
  56. #        Rich Text Formatted documentation, designed to look like the 
  57. #        NEXTSTEP developer documentation for Objective-C objects.
  58. #
  59. # HISTORY: START
  60. # $Log: autodoc,v $
  61. # Revision 1.5  1995/10/20  22:10:41  aswift
  62. # Completed checkin using DevMan Logs
  63. #
  64. # Revision 1.4  1995/10/20  16:45:28  aswift
  65. # Continuing to try DevMan Log history
  66. #
  67. # Release 1.8.4
  68. # - fixed "up to date documentation" testing 
  69. # - added missing small newlines between the methods and their documentation
  70. # - moved tab locations in the Defined Types stuff to improve doc apperance
  71. # - long method lines are now broken into multiple lines
  72. # - added new paragraph styles to the GenerateRTF module
  73. #
  74. # Release 1.8.3
  75. # - completely documented GenerateRTF.pm Autodoc module
  76. # - abstracted DumpDocs to remove rtf dependancies
  77. # - fixed case insensitive argument parsing to differentiate -D from -d (bbum)
  78. # - cleaned up usage of 'require' and 'use' to remove redundancy (bbum)
  79. # - added support for documenting what protocols an object conforms to.
  80. # - added support for documenting protocols. (Craig Kelley)
  81. # 
  82. # Release 1.8.2
  83. # - added version control to the support modules, and their version is now
  84. #    reported when the -version option is used
  85. # - removed some warning messages in file_expandpath
  86. # - fixed bug preventing doc creation with .[hm] files with no object def.
  87. # - fixed resource naming when files are specified with no project dir
  88. # - fixed boldifying values of typedef-type structures
  89. # - allowed multiple levels of indention to follow curly braces in typedef's
  90. #
  91. # Release 1.8.1 - MiscKit Release 1.6.1
  92. # - fixed documentation extraction failure detection
  93. # - added support for AD_PMLIBDIR to specify perl module lib directory
  94. # - added more log debugging to Autodoc .pm files
  95. # - moved LogDebug::Log.pm into Autodoc::LogDebug.pm
  96. # - moved FileSupport::Misc.pm into Autodoc::FileSupport.pm
  97. #
  98. # Release 1.8
  99. # - added -nosingles option to exclude unpaired '.h' and '.m' files from docs
  100. # - added support for functions, typedefs, defines, macros, and globals
  101. # - moved all autodoc doc creation into Autodoc::DumpDocs
  102. # - moved all autodoc source reading into Autodoc::ReadSource
  103. # - moved autodoc comment parsing into Autodoc::ParseComment
  104. # - moved source file scanning code into Autodoc::ScanFile module
  105. # - added timestamping capability for documentation
  106. # - can now set copyright string with environment var: AD_COPYRIGHT
  107. # - moved debug logging into LogDebug::Log
  108. # - moved filepath expansion into FileSupport::Misc
  109. #
  110. # Release 1.7 - contributions by b.bum
  111. # - added support for GetOpts::Long package; GetOpts::Long can deal w/single 
  112. #   character argnames as long as they aren't ambiguous.
  113. # - removed all warnings produced by perl -w
  114. # - modified scan_line to discard stars from the beginning of ADC lines
  115. # - added -help option;  shows help and exits.
  116. # - made a Source directory and moved code files into (as per the README)
  117. # - look for '## bbum';  i fixed a bunch of a stuff that produced
  118. #   warnings when the rtf documentation did not yet exist.
  119. # - fixed -force so that it actually works.
  120. # - added NULL to list of bold words
  121. # - any instance variable on a line w/the word "INTERNAL" will be skipped.
  122. # - fixed method parameter matching to allow whitespace between the : and arg.
  123. #   (Kim Shrier)
  124. # - fixed argument italicising in method docs to parse out whitespace between 
  125. #   the : and arg (Kim Shrier)
  126. #
  127. # Release 1.6
  128. # - added \ escaping for % and # characters to force display 
  129. #
  130. # Release 1.5.1
  131. # - fixed the "Category Description" bug.  Was putting out "Class Description"
  132. #   (Todd Nathan)
  133. #
  134. # Release 1.5 - MiscKit Release
  135. # - added option to force overwriting up-to-date documentation files
  136. # - added time check for source and doc files to prevent unnecessary work
  137. # - added support for copying .rtf and .rtfd files to the doc dir
  138. # - added support for specifying a copyright owner on the command line
  139. # - fixed ivar parsing so it doesn't skip the line with the starting brace
  140. #
  141. # Release 1.4
  142. # - added minimal category support.
  143. # - changed filename to autodoc (from AutoDoc)
  144. # - added support for relative path naming for documentation and project dirs.
  145. # - fixed bug which aborted doc creation if no newline was found on @end line
  146. # 
  147. # Release 1.3
  148. # - Added minimal support for lists of items via _{xxx desc} format
  149. # - Fixed matching problems at beginning and ends of text strings
  150. # - Added "id" to the list of bold words.
  151. # - Filtered out @public/@private/@protected modifiers in ivars.
  152. # - Fixed incorrect struct detection in ivars with curly braces in a following
  153. #   AutoDoc comment.
  154. #
  155. # Release 1.2
  156. # - Started tracking changes
  157. #
  158. # HISTORY: END
  159. ###############################################################################
  160. #
  161. # GOBAL VARIABLES THAT HOLD OBJECT INFORMATION:
  162. #
  163. #  @objects             The array of objects to generate docs for
  164. #
  165. # GLOBAL VARIABLES THAT HOLD EXECUTION MODE INFORMATION
  166. #
  167. #  $proj_dir        The object source project directory (input)
  168. #  $dest_dir        The object documentation destination directory (output)
  169. #  $cwd                 The current working directory autodoc was executed from
  170. #  $opt_silent        The console logging mode, 0 = not silent, 1 = silent
  171. #  $opt_tree            The documentation file organization, 0 = flat, 1 = tree
  172. #  $opt_force           True if doc creation should be forced when up-to-date
  173. #  $opt_rtf             True if rtf and rtfd files should be copied 
  174. #  $opt_nosingles       True if unpaired '.[hm]' files are excluded from docs 
  175. # 
  176. # GLOBAL VARIABLES THAT AFFECT DATA EXTRACTION
  177. #
  178. #  $obj_h               The path and file name of the object header file
  179. #  $obj_m               The path and file name of the object source file
  180. #
  181. # GLOBAL VARIABLES THAT AFFECT DOCUMENTATION DUMP
  182. #
  183. #  $obj_r               The path and file name of the object documentation file
  184. #
  185. # GLOBAL VARIABLES THAT SUPPORT SPECIAL BEHAVIORS
  186. #  $rtffiles
  187. #
  188. ##############################################################################
  189.  
  190. ##############################################################################
  191. #
  192. # PROGRAM INITIALIZATION AND ARGUMENT PROCESSING
  193. #
  194. #    Read in the command line arguments and configure the execution mode 
  195. #  variables appropriately.  Read in the files to operate on, and begin 
  196. #  processesing source files.
  197. #
  198. ##############################################################################
  199.  
  200. ##################
  201. # READ ARGUMENTS #
  202. ##################
  203. ## load GetOpt::Long, fix @INC, and check arguments.
  204. BEGIN {
  205.   use Getopt::Long;
  206.   $Getopt::Long::ignorecase = 0;
  207.  
  208.   $show_usage = "unrecognized or invalid argument"
  209.     unless &GetOptions('lib=s@',
  210.                        'project=s',
  211.                        'destination=s',
  212.                        'copyright=s',
  213.                        'version',
  214.                        'rtf',
  215.                        'force',
  216.                        'timestamp',
  217.                        'nosingles',
  218.                        'tree',
  219.                        'silent',
  220.                        'Debug:i',
  221.                        'help'
  222.                       );
  223.   
  224.   unshift (@INC, @opt_lib)
  225.     if @opt_lib;
  226.   unshift (@INC, $ENV{'AD_PMLIBDIR'})
  227.     if defined($ENV{'AD_PMLIBDIR'});
  228. }
  229.  
  230. #  $show_usage if GetOptions failed
  231. if ($show_usage) {
  232.   usage($show_usage);
  233. }
  234.  
  235. ##########################
  236. # Load Required Packages #
  237. ##########################
  238. use Cwd;
  239. use Autodoc::FileSupport;
  240. use Autodoc::LogDebug;
  241. use Autodoc::ScanFile;
  242. use Autodoc::ParseComments;
  243. use Autodoc::GenerateRTF;
  244. use Autodoc::ReadSource;
  245. use Autodoc::DumpDocs;
  246.  
  247. ######################
  248. # INITIALIZE GLOBALS #
  249. ######################
  250. $proj_dir    = "";        # no project directory
  251. $dest_dir    = "";        # no destination directory
  252. $cwd         = getcwd();
  253.  
  254. dblog (2, "Current working dir: $cwd\n");
  255.  
  256. ################################
  257. # Process Command Line Options #
  258. ################################
  259. # if -help, show usage and exit.
  260. if ($opt_help) {
  261.   $opt_help += 0; # shut up perl -w
  262.   &usage;
  263. }
  264.  
  265. # if -version appeared on the command line, show version and exit
  266. if ($opt_version) {
  267.   $opt_version += 0; # shut up perl -w
  268.   &show_version;
  269.   exit;
  270. }
  271.  
  272. # -silent causes autodoc to run silently
  273. if ($opt_silent) {
  274.   dblog (0, "Operating silently.");
  275.   $opt_silent = 1;
  276. }
  277.  
  278. # -rtf will copy rtf files
  279. if ($opt_rtf){
  280.   dblog (0, "Copying documentation files found in source.");
  281.   $opt_rtf = 1;
  282. }
  283.  
  284. # force document creation
  285. if ($opt_force) {
  286.     dblog (0, "Forcing documentation creation.");
  287.     $opt_force = 1;
  288. }
  289.  
  290. # build document tree
  291. if ($opt_tree) {
  292.   dblog (0, "Building documentation tree.");
  293.   $opt_tree = 1;
  294. }
  295.  
  296. # timestamp documentation
  297. if ($opt_timestamp) {
  298.   dblog (0, "Including timestamp in documentation.");
  299.   set_usetimestamp($opt_timestamp);
  300. }
  301.  
  302. # exclude unpaired source files from documentation
  303. if ($opt_nosingles) {
  304.   dblog (0, "Excluding unmatched source files from documentation");
  305.   $opt_nosingles += 0;
  306. }
  307.  
  308. # set copyright notice
  309. if ($opt_copyright) {
  310.   set_copyrightowner($opt_copyright);
  311.   dblog (0, "Setting copyright owner: ", copyrightowner());
  312. } else {
  313.   if (grep (m!AD_COPYRIGHT!, keys (%ENV))) {
  314.     set_copyrightowner($ENV{'AD_COPYRIGHT'});
  315.     dblog (0, "Setting copyright owner: ", copyrightowner());
  316.   }
  317. }
  318.  
  319. # set project directory
  320. if ($opt_project) {
  321.   $proj_dir = &file_expandpath ($opt_project);
  322.   
  323.   # if there isn't a trailing "/", append it
  324.   $proj_dir = "$proj_dir/" if (!($proj_dir =~ m!/$!));
  325.   dblog (0, "Project directory: $proj_dir");
  326. }
  327.  
  328. # destination directory specified
  329. if ($opt_destination) {
  330.   $dest_dir = &file_expandpath ($opt_destination);
  331.   
  332.   # if there isn't a trailing "/", append it
  333.   $dest_dir = "$dest_dir/" if (!($dest_dir =~ m/\/$/));
  334.   dblog (0, "Destination directory: $dest_dir");
  335. }
  336.  
  337. # set debugging level
  338. if ($opt_Debug) {
  339.   &set_dblog_debuglevel($opt_Debug);
  340.   dblog (0, "Debug level: $opt_Debug.");
  341. }
  342.  
  343. foreach (@ARGV) {
  344.   # strip of the .h or .m from the object source name
  345.   s/\.[hm]$//;
  346.   
  347.   $path = &file_expandpath ($_);
  348.   
  349.   # if it's root name isn't already in the list, then add it.
  350.   if (!(grep (/$path/, @objects))) {
  351.     push (@objects, $path);
  352.   } else {
  353.     dblog (1, "Source file specified twice: $path.");
  354.   }
  355. }
  356.  
  357. &check_inputfiles;
  358.  
  359.  
  360. ###############################################################################
  361. # 
  362. # MAIN PROGRAM OPERATION LOOP
  363. # 
  364. ###############################################################################
  365. MAINLOOP:                        # Main operating loop
  366.   foreach $currobject (@objects) {
  367.     
  368.     # prepare the object (h,m,rtf) file paths
  369.     &set_obj_filepaths ($currobject); 
  370.     
  371.     # check for a .mdoc file (used for documenting protocols)
  372.     if ((!(-e $obj_m))) {
  373.       $obj_mdoc = "${obj_m}doc";
  374.       if ((-e $obj_mdoc)) {
  375.         $obj_m = $obj_mdoc;
  376.       }
  377.     }
  378.     
  379.     $obj_m = ""
  380.       if ((!$opt_nosingles) && (!(-e $obj_m)));
  381.     
  382.     # check whether the doc file exists and is up to date
  383.     if ((-r $obj_h) && (($obj_m eq "") || (-r $obj_m))) {
  384.       
  385.       $docs_expired = 0;
  386.       $docs_expired = 1
  387.         if (file_findnewest($obj_h, $obj_m, $obj_r) ne $obj_r);
  388.       
  389.       unless ($opt_force || $docs_expired || !(-r $obj_r)) {
  390.         # Documentation file is up to date, skip this object
  391.         print "autodoc documentation up to date for $currobject.\n" 
  392.           if (!$opt_silent);
  393.         next MAINLOOP;
  394.       } 
  395.     } else {
  396.       warn ("Data extraction failed for $currobject, ",
  397.             "could not read source files.\n");
  398.       next MAINLOOP;
  399.     }
  400.     
  401.     # read object info and try to generate doc's
  402.     if (&read_objectinfo ($currobject, $obj_h, $obj_m)) {
  403.       
  404.       # Make any directories necessary for the docs...
  405.       if (($obj_r =~ m/\//) && (!&make_docdir ($obj_r))) {
  406.         warn ("Could not write to documentation directory for: ",
  407.               "$obj_r\n");
  408.         return 0;
  409.       } else {
  410.         if (dump_documentation ($currobject, $obj_r, $opt_silent)) {
  411.           &dblog (0, "Completed processing for object:\t",
  412.                   $currobject);
  413.         } else {
  414.           warn ("Documentation file dump failed for ",
  415.                 "$currobject.\n");
  416.         }
  417.       }
  418.     } else {
  419.       if ($obj_m ne "") {
  420.         warn ("Data extraction failed for $currobject, ",
  421.               "no documentation file generated.\n");
  422.       } else {
  423.         dblog (0, "Data extraction failed for $currobject, ",
  424.                "no documentation file generated.\n");
  425.       }
  426.     }
  427.   }
  428. # End MAINLOOP
  429.  
  430. COPYLOOP:                        # Copy loop for rtf files
  431.   foreach $rtffile (@rtffiles) {
  432.     
  433.     &set_rtf_filepaths ($rtffile);
  434.     
  435.     # Check if the source file is readable
  436.     if (!(-r $rtf_src)) {
  437.       warn ("Documentation copy failed for: $rtffile, ",
  438.             "Could not read file.\n");
  439.       next COPYLOOP;
  440.     }
  441.     
  442.     $docs_expired = 1
  443.       if (file_findnewest($rtf_src, $rtf_dest) eq $rtf_src);
  444.     
  445.     # Check if it is up to date
  446.     unless ($opt_force || $docs_expired || !(-r $rtf_dest)) {
  447.       print "autodoc documentation up to date for $rtffile.\n" 
  448.         if (!$opt_silent);
  449.       next COPYLOOP;
  450.     }
  451.     
  452.     # Make any directories necessary...
  453.     if ($rtf_dest =~ m/\//) {
  454.       if (!&make_docdir ($rtf_dest)) {
  455.         warn ("Could not write to documentation directory for: ",
  456.               "$rtf_dest\n");
  457.         next COPYLOOP;
  458.       }
  459.     }
  460.     print "autodoc copying $rtffile to $rtf_dest." 
  461.       if (!$opt_silent);
  462.     #    open (CP, "cd $cwd; cp -r $rtf_src $rtf_dest |");  Why?
  463.     system "cd $cwd; cp -r $rtf_src $rtf_dest";
  464.   }
  465. # End COPYLOOP
  466.  
  467.  
  468.  
  469. ###############################################################################
  470. # 
  471. # EXECUTION CONTROL AND GENERAL SUPPORT SUBROUTINES
  472. #
  473. #    Execution mode configuration from command line switches, and 
  474. #  preprocessing of input files and paths.  
  475. #
  476. ###############################################################################
  477.  
  478. #
  479. # Create all of the directories necessary for the documentation file specified
  480. #
  481. sub make_docdir
  482.   {
  483.     local ($docfile, $docdir, $partdir, @alldirs, $dir, $lastdir);
  484.     $docfile = $_[0];
  485.     
  486.     $docdir = $docfile;
  487.     $docdir =~ s/\/[^\/]+$//;
  488.     
  489.     if (-e $docdir) {
  490.       if (-d $docdir) {
  491.         if (-w $docdir) {
  492.           return 1;                # the directory exists, and is writable
  493.         } else {
  494.           warn ("Cannot write to directory: $docdir");
  495.         }
  496.         warn ("Directory would replace file: $docdir");
  497.       }
  498.       return 0;
  499.     } 
  500.     dblog (1, "Need to create documentation directory: $docdir");
  501.     
  502.     if ($docdir =~ m/^[^\/\.]/) {
  503.       $docdir = "./$docdir";
  504.     }
  505.     
  506.     @alldirs = split (/\//, $docdir);
  507.     
  508.   MKDIRS:
  509.     foreach $dir (@alldirs) {
  510.       if (!$lastdir) {
  511.         if (!$dir) {
  512.           $lastdir = "/";
  513.           next MKDIRS;
  514.         }
  515.         $lastdir = "$dir";
  516.         $partdir = "$dir";
  517.         next MKDIRS;
  518.       } 
  519.       
  520.       $partdir .= "/$dir";
  521.       if (!(-e $partdir)) {
  522.         if (-d $lastdir) {
  523.           if (-w $lastdir) {
  524.             print "autodoc creating $partdir ... " if (!$opt_silent);
  525.             if (mkdir ("$partdir", oct (755))) {
  526.               print "done\n" if (!$opt_silent);
  527.               dblog (2, "Made directory $partdir, with mode 755");
  528.             } else {
  529.               print "failed!\n" if (!$opt_silent);
  530.               warn ("Could not make directory: $partdir");
  531.               return 0;
  532.             } 
  533.           } else {
  534.             warn ("Cannot write to directory: $lastdir  ",
  535.                   "Can not create directory: $partdir");
  536.             return 0;
  537.           }
  538.         } else {
  539.           warn ("Directory would replace file: $lastdir  ",
  540.                 "Can not create directory: $partdir");
  541.           return 0;
  542.         }
  543.       }
  544.       $lastdir = "$partdir";
  545.     }
  546.  
  547.     return 1;
  548.   }
  549.  
  550.  
  551.  
  552. #
  553. # Check if we have valid object files or a project directory, create the 
  554. # list of object source files if none are specified.
  555. #
  556. sub check_inputfiles
  557.   {
  558.     dblog(2, "Checking input files");
  559.     
  560.     # check if the project directory is valid
  561.     if ($proj_dir ne "") {
  562.       if (!(-r $proj_dir)) {
  563.         die ("The project directory {$proj_dir} specified "
  564.              ."is not readable.\nDied");
  565.       }
  566.       if (!(-d $proj_dir)) {
  567.         die ("The project directory specified is not a directory.\nDied");
  568.       }
  569.     }
  570.     
  571.     if (scalar(@objects) == 0) {
  572.       if ($proj_dir ne "") {
  573.         &find_objectfiles;
  574.       }
  575.     }
  576.     
  577.     dblog (1, "Auto-documenting objects: (@objects)");
  578.     
  579.     if (($proj_dir ne "") && ($opt_rtf)) {
  580.       &find_rtffiles;
  581.     }
  582.     
  583.     dblog (1, "Copying documentation files: (@rtffiles)");
  584.     
  585.     if ((scalar(@objects) == 0) && ($proj_dir eq "")) {
  586.       &usage ("No source files or project directory specified.");
  587.     }
  588.  
  589. }
  590.  
  591.  
  592. #
  593. # Use find to recursively scan the project directory for object source files
  594. # then file @objects with all of the matched pairs of .h and .m files from 
  595. # the project directory
  596. #
  597. sub find_objectfiles
  598.   {
  599.     local (@projfiles, $pfile, $find_proj_dir);
  600.     
  601.     dblog (0, "Scanning project directory for object source files.");
  602.     
  603.     $find_proj_dir = $proj_dir;    # This is lame ... I'm just removing 
  604.     $find_proj_dir =~ s/\/$//;    # the trailing '/' from the file path
  605.     
  606.     open (FIND, "cd $cwd; find $find_proj_dir -name '*.[hm]' -print |");
  607.     while (<FIND>) {
  608.       chop;
  609.       s/$proj_dir//;
  610.       s/.[hm]$//;
  611.       push (@projfiles, $_);
  612.     }
  613.     @projfiles = sort @projfiles;
  614.     
  615.     while (@projfiles) {
  616.       $pfile = shift (@projfiles);
  617.       if (defined($pfile)) {
  618.         if (defined($projfiles[0]) && ($pfile eq $projfiles[0])) { 
  619.           # there must have been both a .h and a .m with the same root 
  620.           # since the only file names in @projfiles end in .h or .m
  621.           # the test to see if it is an object file is based on this.
  622.           push (@objects, $pfile);
  623.           shift (@projfiles);
  624.         } else {
  625.           # there is only one file with the .h or .m extension, if
  626.           # the option to disallow singles is not set, we add it 
  627.           push (@objects, $pfile)
  628.             if (!$opt_nosingles);
  629.         }
  630.       }
  631.     }
  632.   }
  633.  
  634.  
  635. #
  636. # Use find to recursively scan the project directory for 'rtf' and 'rtfd'
  637. # files.  Store the files to the array rtffiles
  638. #
  639. sub find_rtffiles
  640.   {
  641.     local ($pfile, $find_proj_dir);
  642.  
  643.     dblog (0, "Scanning project directory for rtf/rtfd files.");
  644.  
  645.     $find_proj_dir = $proj_dir;    # This is lame ... I'm just removing 
  646.     $find_proj_dir =~ s/\/$//;    # the trailing '/' from the file path
  647.     
  648.     open (FIND, "cd $cwd; find $find_proj_dir \\( -name '*.rtf' -o -name '*.rtfd' \\) -print |");
  649.     while (<FIND>) {
  650.       chop;
  651.       s/$proj_dir//;
  652.       push (@rtffiles, $_);
  653.     }
  654.     @rtffiles = sort @rtffiles;
  655.     
  656.   }
  657.  
  658.  
  659. #
  660. # generate the $obj_h, $obj_m and $obj_rtf file path variables.
  661. #
  662. sub set_obj_filepaths
  663.   {
  664.     local ($obj_root) = $_[0];
  665.     
  666.     $obj_h = "${proj_dir}${obj_root}.h";
  667.     $obj_m = "${proj_dir}${obj_root}.m";
  668.     
  669.     if ($opt_tree) {
  670.       $obj_r = $obj_root;        # if the obj_root is in a subdirectory
  671.       # remove any file extension on the 
  672.       # subdirectory name.
  673.       $obj_r =~ s/\.[^\.]+\//\//g;
  674.     } else {
  675.       if ($obj_root =~ m!/([^/]+)$!) {
  676.           $obj_r = $1;
  677.         } else {
  678.           $obj_r = $obj_root;
  679.         }
  680.     }
  681.     $obj_r = "$dest_dir$obj_r.rtf";
  682.     dblog(2, "Destination file set to: $obj_r");
  683. }
  684.  
  685. #
  686. # Generate the $rtf_src and $rtf_dest file path variables
  687. #
  688. sub set_rtf_filepaths
  689.   {
  690.     local ($rtf_root) = $_[0];
  691.     
  692.     # prepare the rtf source and dest file path
  693.     $rtf_src = "${proj_dir}${rtf_root}";
  694.     
  695.     if ($opt_tree) {
  696.       $rtf_dest = $rtf_root; 
  697.       
  698.       # If the rtf_root is in a subdirectory
  699.       # remove any file extension on the subdirectory name.
  700.       $rtf_dest =~ s/\.[^\.]+\//\//g;
  701.     } else {
  702.       if ($rtf_root =~ m!/([^/]+)$!) {
  703.         $rtf_dest =~ $1;
  704.       } else {
  705.         $rtf_dest = $rtf_root;
  706.       }
  707.     }
  708.     $rtf_dest = "$dest_dir$rtf_dest";
  709.   }
  710.  
  711. sub usage {
  712.   $error_fmt = shift;
  713.     
  714.   select(STDERR);
  715.     
  716.   printf "$file_name: $error_fmt\n", @_
  717.     if $error_fmt;
  718.  
  719.   print <<_ENDOFUSAGE_;
  720. Usage: $file_name [-force] [-rtf] [-tree] [-nosingles] [-timestamp] 
  721.            [-help] [-version] [-silent] [-Debug [#]]
  722.            [-copyright "Copyright String"] [-destination "dest path"]
  723.            [-project "project directory"] [ sourcefiles ...]
  724.  
  725.    -force            Force document creation for up to date files.
  726.    -rtf              Copy rtf and rtfd files fount in project tree.
  727.    -tree         Create a tree of documentation files.
  728.    -nosingles        Exclude unpaired ".h" and ".m" files from documentation
  729.    -timestamp         Insert a timestamp into the documentation
  730.    -help             Show this help and exit.       
  731.    -version         Show AutoDoc version/copyright and exit.
  732.    -silent         Operate silently;  do not generate log entries.
  733.    -Debug [#]        Set debugging level to #; 0 (default) is least, 5 is most.
  734.    -copyright "..."  Set copyrightowner in the copyright line to "...".
  735.    -destination ".." Create documentation files in directory "..".
  736.    -project "..."    Look for source files in the directory "...".
  737. _ENDOFUSAGE_
  738.    exit(1);
  739. }
  740.  
  741. #
  742. # Show version and copyright information
  743. #
  744. sub show_version
  745. {
  746.     local (@module_versions);
  747.  
  748.     @module_versions = (Autodoc::FileSupport::module_versionstamp(),
  749.                         Autodoc::LogDebug::module_versionstamp(),
  750.                         Autodoc::ScanFile::module_versionstamp(),
  751.                         Autodoc::ReadSource::module_versionstamp(),
  752.                         Autodoc::ParseComments::module_versionstamp(),
  753.                         Autodoc::DumpDocs::module_versionstamp(),
  754.                         Autodoc::GenerateRTF::module_versionstamp());
  755.     
  756.     print "This is $file_name Release $file_release (rev-$file_version)\n";
  757.     print "Module versions:\n\t", join ("\n\t", @module_versions), "\n";
  758.     print "Written by $file_author\n";
  759.     print "Copyright $file_copyright - All Rights Reserved\n";
  760.     print "Please send bugs and suggestions to:$file_mlist\n";
  761.     print "Contributions by:\n\t";
  762.     print join("\n\t", @file_contributors), "\n"
  763.       if scalar(@file_contributors);
  764.     exit(0);
  765. }
  766.