com.martiansoftware.rundoc
Class RunDoc

java.lang.Object
  org.apache.tools.ant.ProjectComponent
      org.apache.tools.ant.Task
          com.martiansoftware.rundoc.RunDoc

All Implemented Interfaces:

com.martiansoftware.rundoc.MacroProcessor

public class RunDoc

extends org.apache.tools.ant.Task

implements com.martiansoftware.rundoc.MacroProcessor

An Ant task designed to help with the single-sourcing of program documentation. This task replaces special commands embedded within text files with their output in a specified format. Currently, only docbook format is supported.

For example, if a text file contains the text "@@rundoc:ls -l@@", and the task is called with the following code:

 <taskdef
     name="rundoc"
     classname="com.martiansoftware.rundoc.RunDoc" 
     classpath="rundoc-0.11.jar"/>
 
 <target name="testrundoc">
     <rundoc prompt="[mlamb@morbo]$" format="docbook">
       <fileset dir="." includes="test/*.txt"/>
     </rundoc>
 </target>
 

it might be replaced with something like:

 <prompt>[mlamb@morbo]$</prompt><command>ls -l</command>
 <computeroutput>total 40
 drwxrwxr-x    3 mlamb    mlamb        4096 Feb 15 18:45 build
 -rw-rw-r--    1 mlamb    mlamb        2365 Feb 15 19:22 build.xml
 drwxrwxr-x    2 mlamb    mlamb        4096 Feb 15 18:51 CVS
 drwxrwxr-x    2 mlamb    mlamb        4096 Feb 15 18:49 dist
 drwxrwxr-x    4 mlamb    mlamb        4096 Feb 15 18:49 javadoc
 drwxrwxr-x    3 mlamb    mlamb        4096 Feb 15 18:51 lib
 -rw-rw-r--    1 mlamb    mlamb        1481 Feb  1 19:09 LICENSE.txt
 -rw-rw-r--    1 mlamb    mlamb         336 Feb  1 20:02 README.txt
 drwxrwxr-x    4 mlamb    mlamb        4096 Feb 15 18:51 src
 drwxrwxr-x    2 mlamb    mlamb        4096 Feb 15 19:20 test
 </computeroutput>

Replacements are made in whatever files are included in the nested filesets; odds are you'll want to <copy> your files before running rundoc on the copies.

Rundoc supports nested <env> elements to pass environment variables to the executed process(es). See the documentation for <exec> for details on its use. Here's a simple example that's useful if rundoc will be running part of the current java project:

 <target name="rundocs">
     <!-- this example assumes that a temporary copy of your manual.xml
          docbook file has already been created in ${build} -->
     <rundoc prompt="[mlamb@hypno-toad]$" format="docbook">
       <fileset file="${build}/manual.xml"/>
       <env key="CLASSPATH" value="${build}/>
     </rundoc>
 </target>
 

A typical usage scenario would be to put the @@rundoc:command@@ directly in the docbook source for your documentation between <screen> tags. The build process would then create a temporary copy of the docbook source, run <rundoc> against it, and finally run the modified docbook file through a formatter.

This task goes hand-in-hand with <snip>.

Multiple rundoc commands may be defined within a single file.

Possible Enhancements:
I currently have no plans to implement these, but they would probably be useful to someone. Code contributions are welcome.

• Provide a means to specify the directory in which the command should be run.
• Support additional output formats (man? others?)

Author:

Marty Lamb

Field Summary

static java.lang.String

FORMAT_DOCBOOK Format constant indicating that output should be written in docbook format.

Fields inherited from class org.apache.tools.ant.Task

description, location, target, taskName, taskType, wrapper

Fields inherited from class org.apache.tools.ant.ProjectComponent

project

Constructor Summary

RunDoc()

Method Summary

void	addEnv(org.apache.tools.ant.types.Environment.Variable envvar) Add an environment variable.
void	addFileSet(org.apache.tools.ant.types.FileSet fs) Adds a FileSet to this Task
void	execute() Reads all snippets from the previously specified FileSets, storing their contents in project properties.
java.lang.String	formatDocbook(java.lang.String command, java.lang.String output) Formats the program output in docbook format.
java.lang.String	formatResult(java.lang.String command, java.lang.String output) Formats the program output as specified by the user (currently only docbook format is supported)
java.lang.String	processMacro(java.lang.String macro) Processes the specified macro, returning the formatted result.
void	setFormat(java.lang.String format) Sets the output format
void	setPrompt(java.lang.String prompt) Sets the prompt to include in output

Methods inherited from class org.apache.tools.ant.Task

getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, handleErrorFlush, handleErrorOutput, handleFlush, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName

Methods inherited from class org.apache.tools.ant.ProjectComponent

getProject, setProject

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORMAT_DOCBOOK

public static final java.lang.String FORMAT_DOCBOOK

Format constant indicating that output should be written in docbook format.

See Also:

Constant Field Values

Constructor Detail

RunDoc

public RunDoc()

Method Detail

addFileSet

public void addFileSet(org.apache.tools.ant.types.FileSet fs)

Adds a FileSet to this Task

Parameters:

fs - the FileSet to add

addEnv

public void addEnv(org.apache.tools.ant.types.Environment.Variable envvar)

Add an environment variable.

Parameters:

envvar - new environment variable

setPrompt

public void setPrompt(java.lang.String prompt)

Sets the prompt to include in output

Parameters:

prompt - the prompt to include in output

formatDocbook

public java.lang.String formatDocbook(java.lang.String command,
                                      java.lang.String output)

Formats the program output in docbook format.

Parameters:

command - the command executed

output - the command's output

Returns:

the program output in docbook format (minus enclosing <screen> tags)

formatResult

public java.lang.String formatResult(java.lang.String command,
                                     java.lang.String output)

Formats the program output as specified by the user (currently only docbook format is supported)

Parameters:

command - the command executed

output - the command's output

Returns:

the formatted output

setFormat

public void setFormat(java.lang.String format)

Sets the output format

Parameters:

format - the output format (currently only "docbook" is supported)

processMacro

public java.lang.String processMacro(java.lang.String macro)

Processes the specified macro, returning the formatted result.

Specified by:

processMacro in interface com.martiansoftware.rundoc.MacroProcessor

Parameters:

macro - the macro to run

Returns:

the formatted output of the specified macro

execute

public void execute()
             throws org.apache.tools.ant.BuildException

Reads all snippets from the previously specified FileSets, storing their contents in project properties.

Throws:

org.apache.tools.ant.BuildException - if any I/O errors occur while reading files.