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.