Browse Source

Applied Bill's DVSL work and template patch. Also added "docs" target to main build.xml to <ant> to the HTML generation build.

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271637 13f79535-47bb-0310-9956-ffa450edef68
master
Erik Hatcher 23 years ago
parent
commit
cb2a0a80b1
8 changed files with 471 additions and 15 deletions
  1. +4
    -0
      proposal/xdocs/build.xml
  2. +16
    -0
      proposal/xdocs/dvsl/README.txt
  3. +36
    -0
      proposal/xdocs/dvsl/build.xml
  4. BIN
      proposal/xdocs/dvsl/lib/dom4j-1.1.1.jar
  5. BIN
      proposal/xdocs/dvsl/lib/velocity-dep-1.3-dev.jar
  6. BIN
      proposal/xdocs/dvsl/lib/velocity-dvsl-0.42.jar
  7. +396
    -0
      proposal/xdocs/dvsl/task.dvsl
  8. +19
    -15
      proposal/xdocs/templates/task_xdoc.template

+ 4
- 0
proposal/xdocs/build.xml View File

@@ -76,5 +76,9 @@
</document> --> </document> -->


</target> </target>
<target name="docs" depends="gen">
<ant dir="dvsl"/>
</target>
</project> </project>



+ 16
- 0
proposal/xdocs/dvsl/README.txt View File

@@ -0,0 +1,16 @@
This directory contains support for generating HTML task documentation
from the XDoclet generated XML. DVSL
(http://jakarta.apache.org/velocity/dvsl/) is used for this purpose. It has
many of the benefits of XSLT but uses Velocity as its template language.

This is in a subdirectory as it is effectively a sub-proposal demonstrating
one way the task XML can be transformed into HTML.

Directions:
1. Generate the XML task docs by running the build.xml in the parent
directory.
2. Generate the HTML docs by running the build file in this directory.
The output is written to ../build/docs/manual.

-Bill Burton <billb@progress.com>


+ 36
- 0
proposal/xdocs/dvsl/build.xml View File

@@ -0,0 +1,36 @@
<project name="AntManual" default="taskdocs" basedir=".">

<property file="${basedir}/build.properties"/>

<property name="lib.dir" value="${basedir}/lib" />
<property name="build.dir" value="${basedir}/../build" />
<property name="docs.src" value="${basedir}/../../../xdocs" />
<property name="taskdocs.src" value="${build.dir}/gen" />

<!-- The docs destination directory -->
<property name="docs.dest" value="${build.dir}/docs"/>
<property name="manual.dest" value="${docs.dest}/manual" />

<!-- Construct compile classpath -->
<path id="classpath">
<fileset dir="${lib.dir}">
<include name="**/*.jar"/>
</fileset>
</path>

<target name="init">
<taskdef name="dvsl" classname="org.apache.tools.dvsl.DVSLTask">
<classpath>
<path refid="classpath"/>
</classpath>
</taskdef>
</target>

<target name="taskdocs" depends="init"
description="Generate Task Documentation">
<dvsl basedir="${taskdocs.src}" destdir="${manual.dest}"
style="task.dvsl" extension=".html"
includes="**/*.xml" />
</target>

</project>

BIN
proposal/xdocs/dvsl/lib/dom4j-1.1.1.jar View File


BIN
proposal/xdocs/dvsl/lib/velocity-dep-1.3-dev.jar View File


BIN
proposal/xdocs/dvsl/lib/velocity-dvsl-0.42.jar View File


+ 396
- 0
proposal/xdocs/dvsl/task.dvsl View File

@@ -0,0 +1,396 @@
#*
* DVSL Stylesheet to format the Ant Task documentation.
*#

#set( $relative-path = "." )
#if (false)
#set( $body-bg = '#ffffff' )
#set( $body-fg = '#000000' )
#set( $body-link = '#525D76' )
##set( $banner-bg = '#EEEEEE')
#set( $banner-fg = '#000000')
#set( $sub-banner-bg = '#828DA6')
#set( $sub-banner-fg = '#ffffff')
##set( $table-th-bg = '#FFEEEE')
##set( $table-td-bg = '#FFEEEE')
##set( $source-color = '#CCFFFF')

#set( $table-th-bg = '#EEEEEE')
#set( $table-td-bg = '#EEEEEE')
#set( $banner-bg = '#a0ddf0')
##set( $banner-bg = '#525D76')
##set( $table-th-bg = '#039acc')
##set( $table-td-bg = '#a0ddf0')
#set( $source-color = '#023264')
#end

#set( $body-bg = '#ffffff' )
#set( $body-fg = '#000000' )
#set( $body-link = '#525D76' )
#set( $banner-bg = '#525D76')
#set( $banner-fg = '#ffffff')
#set( $sub-banner-bg = '#828DA6')
#set( $sub-banner-fg = '#ffffff')
#set( $table-th-bg = '#cccccc')
#set( $table-td-bg = '#eeeeee')
#set( $source-color = '#023264')
#set( $source-font-size = '+0')

## Double quote for convenience
#set ($qq = '"')

## Macro to output argument if test evaluates to true
#macro(ifset $test $output)
#if ( $test )$output#end
#end

#match( "task" )
#set( $task_name = $attrib.name )
## Create task title with first letter in upper case
#set( $task_title = "$task_name.substring(0,1).toUpperCase()$task_name.substring(1)" )
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>$task_title Task</title>
</head>

<body bgcolor="$body-bg" text="$body-fg" link="$body-link"
alink="$body-link" vlink="$body-link">

<table border="0" width="100%" cellspacing="4">

## PAGE HEADER
<tr>
<td>

## JAKARTA LOGO
<a href="http://jakarta.apache.org/">
<img src="http://jakarta.apache.org/images/jakarta-logo.gif"
align="left" alt="The Jakarta Project" border="0"/>
</a>

#if( $project.logo )

#set( $alt = $project.logo )
#set( $home = $project.attribute("href") )
#set( $src = $project.logo.attribute( "href" ) )

## PROJECT LOGO
<a href="$home">
<img src="$src" align="right" alt="$alt" border="0"/>
</a>
#end

</td>
</tr>

## HEADER SEPARATOR
<tr>
##<td colspan="2">
<td>
<hr noshade="" size="1"/>
</td>
</tr>

<tr>
<!-- RIGHT SIDE MAIN BODY -->
<td valign="top" align="left">
$context.applyTemplates("long-description")
$context.applyTemplates("structure/attributes")
$context.applyTemplates("structure/elements")
</td>
</tr>

<!-- FOOTER SEPARATOR -->
<tr>
<td>
<hr noshade="" size="1"/>
</td>
</tr>

<!-- PAGE FOOTER -->
<tr>
<td>
<div align="center"><font color="$body-link" size="-1"><em>
Copyright &#169; 2000-2002, Apache Software Foundation
</em></font></div>
</td>
</tr>

</table>

</body>
</html>
#end

#*
Macro to format a table heading cell
*#
#macro( th $text )
<td bgcolor="$table-th-bg" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<b>$text</b></font>
</td>
#end

#*
Macro to format a table body cell
*#
#macro( td $text )
<td bgcolor="$table-td-bg" valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
$text
</font>
</td>
#end

#*
Macro to format a section banner
*#
#macro( section $anchor $name )
<tr><td bgcolor="$banner-bg">
<font color="$banner-fg" face="arial,helvetica.sanserif">
<a name="$anchor">
<strong>$name</strong></a></font>
</td></tr>
#end

#*
Macro to format a subsection banner
*#
#macro( subsection $anchor $name )
<tr><td bgcolor="$sub-banner-bg">
<font color="$sub-banner-fg" face="arial,helvetica.sanserif">
<a name="$anchor">
<strong>$name</strong></a></font>
</td></tr>
#end


#*
Match long-description section
*#
#match( "long-description" )
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td>&nbsp;</td></tr>

#section($task_name "$task_title Task Description")

<tr><td><blockquote>
$node.value()
</blockquote></td></tr>

</table>
#end

#*
Match structure/attributes section
*#
#match( "structure/attributes" )
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td>&nbsp;</td></tr>

#section("attributes" "Parameters")

<tr><td><blockquote>
<table>
<tr>
#th("Attribute")
#th("Description")
#th("Type")
</tr>
$context.applyTemplates("*")
</table>
</blockquote></td></tr>

</table>
#end

#*
Match structure/elements section
*#
#match( "structure/elements" )
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td>&nbsp;</td></tr>

#section("elements" "Parameters as nested elements")

<tr><td><blockquote>
$context.applyTemplates("*")
</blockquote></td></tr>

</table>
#end

#match( "attribute" )
<tr>
#td($attrib.name)
#td($node.description)
#td($attrib.type)
</tr>
#end

#match( "element" )
<table border="0" cellspacing="0" cellpadding="2" width="100%">
#subsection($attrib.name $attrib.name)
<tr><td><blockquote>
$node.description
</blockquote></td></tr>
</table>
#end


#*
* Process a menu for the navigation bar
*#
#match( "menu" )
<tr><td>
<p>
<strong>$attrib.name</strong>
</p>
</td><td>
<ul>
$context.applyTemplates("item")
</ul></td></tr>
#end


#*
* Process a menu item for the navigation bar
*#
#match( "item" )
#if( $attrib.href.endsWith("$outputfilename") && !$attrib.href.startsWith("http"))
<strong>$attrib.name</strong>
#else
#if( $attrib.href.startsWith("http") )
<a href="$attrib.href">$attrib.name</a>
#else
<a href="${relative-path}$attrib.href">$attrib.name</a>
#end
#end
#end

#*
* process a documentation section
*#
#match( "section" )
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td>&nbsp;</td></tr>

<tr><td bgcolor="$banner-bg">
<font color="$banner-fg" face="arial,helvetica.sanserif">
#if ( $attrib.anchor )
#set( $anchor = $attrib.anchor )
#else
#set( $anchor = $attrib.name )
#end
<a name="$anchor">
<strong>$attrib.name</strong></a></font>
</td></tr>

<tr><td><blockquote>
$context.applyTemplates("*")
</blockquote></td></tr>

</table>
#end

#match( "subsection" )
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<!-- Subsection heading -->
<tr><td bgcolor="$sub-banner-bg">
<font color="$sub-banner-fg" face="arial,helvetica.sanserif">
#if ( $attrib.anchor )
#set( $anchor = $attrib.anchor )
#else
#set( $anchor = $attrib.name )
#end
<a name="$anchor">
<strong>$attrib.name</strong></a></font>
</td></tr>
<!-- Subsection body -->
<tr><td>
$context.applyTemplates("*")
</td></tr>
</table>
#end

#match( "source" )
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="$source-color" width="1" height="1">
<img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/>
</td>
<td bgcolor="$source-color" height="1">
<img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/>
</td>
<td bgcolor="$source-color" width="1" height="1">
<img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/>
</td>
</tr>
<tr>
<td bgcolor="$source-color" width="1">
<img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/>
</td>
<td bgcolor="#ffffff" height="1">
<font size="$source-font-size"><pre>$toolbox.htmlescape.getText( $node.value() )</pre></font>
</td>
<td bgcolor="$source-color" width="1">
<img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/>
</td>
</tr>
<tr>
<td bgcolor="$source-color" width="1" height="1">
<img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/>
</td>
<td bgcolor="$source-color" height="1">
<img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/>
</td>
<td bgcolor="$source-color" width="1" height="1">
<img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/>
</td>
</tr>
</table>
</div>
#end


#match("table")
<table>
$context.applyTemplates("*")
</table>
#end

#match("tr")
<tr>
$context.applyTemplates("*")
</tr>
#end

#match( "td" )
<td bgcolor="$table-td-bg" #*
*##ifset($attrib.colspan "colspan=$qq$attrib.colspan$qq ")#*
*##ifset($attrib.rowspan "rowspan=$qq$attrib.rowspan$qq ")#*
*#valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
$node.copy( $node.children() )
</font>
</td>
#end

#match( "th" )
<td bgcolor="$table-th-bg" #*
*##ifset($attrib.colspan "colspan=$qq$attrib.colspan$qq ")#*
*##ifset($attrib.rowspan "rowspan=$qq$attrib.rowspan$qq ")#*
*#valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<b>$node.copy( $node.children())</b>
</font>
</td>
#end

#match("*")
$node.copy()
#end


+ 19
- 15
proposal/xdocs/templates/task_xdoc.template View File

@@ -10,21 +10,25 @@


<structure> <structure>


<XDtAnt:forAllAttributes>
<attribute name="<XDtMethod:propertyName/>" type="<XDtParameter:forAllMethodParams><XDtParameter:methodParamType/></XDtParameter:forAllMethodParams>">
<description><![CDATA[
<XDtMethod:methodComment no-comment-signs="true"/>
]]></description>
</attribute>
</XDtAnt:forAllAttributes>

<XDtAnt:forAllElements>
<element name="<XDtAnt:elementName/>">
<description><![CDATA[
<XDtMethod:methodComment no-comment-signs="true"/>
]]></description>
</element>
</XDtAnt:forAllElements>
<attributes>
<XDtAnt:forAllAttributes>
<attribute name="<XDtMethod:propertyName/>" type="<XDtParameter:forAllMethodParams><XDtParameter:methodParamType/></XDtParameter:forAllMethodParams>">
<description><![CDATA[
<XDtMethod:methodComment no-comment-signs="true"/>
]]></description>
</attribute>
</XDtAnt:forAllAttributes>
</attributes>

<elements>
<XDtAnt:forAllElements>
<element name="<XDtAnt:elementName/>">
<description><![CDATA[
<XDtMethod:methodComment no-comment-signs="true"/>
]]></description>
</element>
</XDtAnt:forAllElements>
</elements>


<!-- @todo: wrap setCurrentMethod inside AntTagsHandler --> <!-- @todo: wrap setCurrentMethod inside AntTagsHandler -->
<XDtMethod:setCurrentMethod name="addText" parameters="java.lang.String"> <XDtMethod:setCurrentMethod name="addText" parameters="java.lang.String">


Loading…
Cancel
Save