docextract

docextract

jnc Feb 14, 2010 - Docextract will now extract *any* documentation from a tcl source file, not just doctool formatted code. With the latest version you can specify the extension of the resulting file. Thus, your source files could be documented with HTML, LaTeX, a wiki format or some other format all together. Docextract could care less what the format is, it simply searches the source file for comments to extract and writes those comments to a file for later processing.

Now, docextract does have a -doctools parameter that will cause it to process the resulting file through the doctools package, so it does supply a little help when using doctools, but it is no longer limited to doctools format.

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

To retrieve the source, please see my "MiscTCL" source repository located at: https://github.com/jcowgar/misctcl specifically, https://github.com/jcowgar/misctcl/blob/master/docextract.tcl