public class RunDoc
extends org.apache.tools.ant.Task
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.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
FORMAT_DOCBOOK
Format constant indicating that output should be written
in docbook format.
|
Constructor and Description |
---|
RunDoc() |
Modifier and Type | Method and 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 |
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
|
bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType
public static final java.lang.String FORMAT_DOCBOOK
public void addFileSet(org.apache.tools.ant.types.FileSet fs)
fs
- the FileSet to addpublic void addEnv(org.apache.tools.ant.types.Environment.Variable envvar)
envvar
- new environment variablepublic void setPrompt(java.lang.String prompt)
prompt
- the prompt to include in outputpublic java.lang.String formatDocbook(java.lang.String command, java.lang.String output)
command
- the command executedoutput
- the command's outputpublic java.lang.String formatResult(java.lang.String command, java.lang.String output)
command
- the command executedoutput
- the command's outputpublic void setFormat(java.lang.String format)
format
- the output format (currently only "docbook" is
supported)public java.lang.String processMacro(java.lang.String macro)
macro
- the macro to runpublic void execute() throws org.apache.tools.ant.BuildException
execute
in class org.apache.tools.ant.Task
org.apache.tools.ant.BuildException
- if any I/O errors occur while reading files.