Class RunDoc

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
com.martiansoftware.rundoc.RunDoc
All Implemented Interfaces:
Cloneable

public class RunDoc extends org.apache.tools.ant.Task
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

    Fields
    Modifier and Type
    Field
    Description
    static final String
    Format constant indicating that output should be written in docbook format.

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

    target, taskName, taskType, wrapper

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

    description, location, project
  • Constructor Summary

    Constructors
    Constructor
    Description
     
  • Method Summary

    Modifier and Type
    Method
    Description
    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
    Reads all snippets from the previously specified FileSets, storing their contents in project properties.
    formatDocbook(String command, String output)
    Formats the program output in docbook format.
    formatResult(String command, String output)
    Formats the program output as specified by the user (currently only docbook format is supported)
    Processes the specified macro, returning the formatted result.
    void
    setFormat(String format)
    Sets the output format
    void
    setPrompt(String prompt)
    Sets the prompt to include in output

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

    bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

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

    clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • FORMAT_DOCBOOK

      public static final String FORMAT_DOCBOOK
      Format constant indicating that output should be written in docbook format.
      See Also:
  • Constructor Details

    • RunDoc

      public RunDoc()
  • Method Details

    • 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(String prompt)
      Sets the prompt to include in output
      Parameters:
      prompt - the prompt to include in output
    • formatDocbook

      public String formatDocbook(String command, 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 String formatResult(String command, 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(String format)
      Sets the output format
      Parameters:
      format - the output format (currently only "docbook" is supported)
    • processMacro

      public String processMacro(String macro)
      Processes the specified macro, returning the formatted result.
      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.
      Overrides:
      execute in class org.apache.tools.ant.Task
      Throws:
      org.apache.tools.ant.BuildException - if any I/O errors occur while reading files.