Class RunDoc
- All Implemented Interfaces:
Cloneable
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
FieldsModifier and TypeFieldDescriptionstatic 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 -
Method Summary
Modifier and TypeMethodDescriptionvoid
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.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)processMacro
(String macro) Processes the specified macro, returning the formatted result.void
Sets the output formatvoid
Sets the prompt to include in outputMethods 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
-
Field Details
-
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
Sets the prompt to include in output- Parameters:
prompt
- the prompt to include in output
-
formatDocbook
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
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
Sets the output format- Parameters:
format
- the output format (currently only "docbook" is supported)
-
processMacro
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.BuildExceptionReads 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.
-