Package com.martiansoftware.rundoc

Class 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.

      • 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
      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 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

        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 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.
        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.