Class RunDoc
- java.lang.Object
-
- org.apache.tools.ant.ProjectComponent
-
- org.apache.tools.ant.Task
-
- com.martiansoftware.rundoc.RunDoc
-
- All Implemented Interfaces:
java.lang.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 java.lang.String
FORMAT_DOCBOOK
Format constant indicating that output should be written in docbook format.
-
Constructor Summary
Constructors Constructor Description RunDoc()
-
Method Summary
All Methods Instance Methods Concrete Methods 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 Taskvoid
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 formatvoid
setPrompt(java.lang.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
-
-
-
-
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
-
-
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 executedoutput
- 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 executedoutput
- 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.- 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 classorg.apache.tools.ant.Task
- Throws:
org.apache.tools.ant.BuildException
- if any I/O errors occur while reading files.
-
-