**docextract**

[jnc] Jan 30, 2010 - A more recent copy of doctools is now in my "Misc TCL" code fossil repo, it can be had at http://jeremy.cowgar.com/misctcl

[jnc] likes keeping documentation and source in one file. Why? Ease of editing and maintaining both the source and documentation for that source. You are more likely to update the docs when a proc changes if they are staring you in the face. Thus, I wrote this simple utility I call `docextract.tcl`. You can include [doctools] comments inline with your source code and `docextract` will extract the comments making a `.man` page suitable for processing by the [doctools] family of utilities.

You need to use a special syntax for the comments you wish to be extracted. Simply start the comment block with a `#` and one or more `*` characters. For example:

 #****
 # [para]
 # this will be extracted and placed into the .man file
 if {1==2} {
   # this will not
 }

Once a [doctools] block comment is started, all content will be placed into the man file until the first character in a line does not begin with a `#` character. Thus, if you wish to include a [doctools] comment back to back with a programmers comment, you must do something such as:

 #****
 # doctools comment
 # more comments for doctools
 
 # this is not a doctools comment and will not be extracted
 # to the resulting .man page.

 puts "Hello World!"


***Now for the source***


 #!/bin/sh
 # -*- tcl -*-
 # The next line is executed by /bin/sh, but not tcl \
 exec tclsh "$0" ${1+"$@"}
 
 package require cmdline
 
 set options {
   {o.arg "./" "set the output directory"}
   {all        "output all .man files even when no valid comments where found"}
 }
 set usage ": docextract \[options] filename ...\noptions:"
 if {[catch {array set params [::cmdline::getoptions argv $options $usage]} msg]} {
   puts $msg
   exit 0
 }
 
 file mkdir $params(o)
 
 foreach fname $argv {
   set ofname [file join $params(o) [file rootname $fname].man]
   set fh [open $fname r]
   set comments ""
   
   set inDocComment 0
   
   while {[gets $fh line] >=0} {
      set line [string trim $line]
     if {$inDocComment && [string index $line 0] != "#"} {
       set inDocComment 0
     } elseif {[string range $line 0 1]=="#*"} {
       set inDocComment 1
     } elseif {$inDocComment} {
       append comments "[string range $line 2 end]\n"
     }
   }
   
   close $fh
 
   if {$params(all) || [string length $comments] > 0} {
     set ofh [open $ofname w]
     puts $ofh $comments
     close $ofh
   }
 }

----
!!!!!!
%| [Category Documentation] | [Category Word and Text Processing] |%
!!!!!!