Author: jhm Date: Thu Mar 1 01:06:12 2007 New Revision: 513231 URL: http://svn.apache.org/viewvc?view=rev&rev=513231 Log: * Use of Java5 * A target for generating the plugin * Spaces instead tabs * M4E-Task: validate() for checking its configuration * antlib.xml * docs Added: ant/sandbox/antlibs/manual4eclipse/build.properties ant/sandbox/antlibs/manual4eclipse/docs/buildPlugin.html ant/sandbox/antlibs/manual4eclipse/docs/cover.html ant/sandbox/antlibs/manual4eclipse/docs/favicon.ico (with props) ant/sandbox/antlibs/manual4eclipse/docs/index.html ant/sandbox/antlibs/manual4eclipse/docs/m4e.html ant/sandbox/antlibs/manual4eclipse/docs/toc.html ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/antlib.xml Modified: ant/sandbox/antlibs/manual4eclipse/build.xml ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/Manual4EclipseTask.java Added: ant/sandbox/antlibs/manual4eclipse/build.properties URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/build.properties?view=auto&rev=513231 ============================================================================== --- ant/sandbox/antlibs/manual4eclipse/build.properties (added) +++ ant/sandbox/antlibs/manual4eclipse/build.properties Thu Mar 1 01:06:12 2007 @@ -0,0 +1,6 @@ +# Overwrite JavaC properties +# This AntLib is not part of the Core and only intended for building +# an Eclipse help plugin from the manual. This AntLib was not designed +# for other use. So we could use Java5 here (instead of 1.2). +javac.-source=1.5 +javac.-target=1.5 Modified: ant/sandbox/antlibs/manual4eclipse/build.xml URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/build.xml?view=diff&rev=513231&r1=513230&r2=513231 ============================================================================== --- ant/sandbox/antlibs/manual4eclipse/build.xml (original) +++ ant/sandbox/antlibs/manual4eclipse/build.xml Thu Mar 1 01:06:12 2007 @@ -18,5 +18,20 @@ under the License. --> + - \ No newline at end of file + + + You must point property $${ant.core} to Ant's TRUNK directory + + + + Added: ant/sandbox/antlibs/manual4eclipse/docs/buildPlugin.html URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/docs/buildPlugin.html?view=auto&rev=513231 ============================================================================== --- ant/sandbox/antlibs/manual4eclipse/docs/buildPlugin.html (added) +++ ant/sandbox/antlibs/manual4eclipse/docs/buildPlugin.html Thu Mar 1 01:06:12 2007 @@ -0,0 +1,98 @@ + + + + + + +BuildPlugin Task + + + + + + +

BuildPlugin

+

Description

+

+Building an Eclipse Help plugin is more than creating a toc.xml and a plugin.xml. +You have to collect all needed files in the needed file structure and create a JAR with OSGi bundle +information. Also references between the files should not be go outside the structure in a relative way (you could use links like http://ant.apache.org but no ../images). The makro buildPlugin does this work. +

+

+Mainly the cover.html from the Ant Manual loads an image from the site directory (../images). +The link will be modified an the graphic will be copied. +

+ + + +

Parameters

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
manualDirThe directory where Ant's manual is.Yes
antVersionThe version of Ant's Manual.Yes
buildDirWhere to build the artefacts.Yes
pluginDirWhether to generate the plugin files.No, default "@{buildDir}/manual4eclipse"
pluginPackageIn which package should the plugin reside.No, default "org.apache.ant.manual"
+ + + +

Examples

+
+<target name="gen" xmlns:m4e="antlib:org.apache.ant.manual4eclipse">
+    <property name="build" value="build"/>
+    <property name="ant.trunk" location="path/to/my/svn/checkout/of/Ant/Core"/>
+    <mkdir dir="${build}"/>
+    <m4e:buildPlugin manualDir="${ant.trunk}/docs/manual"
+                     antVersion="1.7.1alpha"
+                     buildDir="${build}"
+    />
+</target>
+
+This target generates an Eclipse Help plugin org.apache.ant.manual_1.7.1alpha.v20070301.jar +(with 20070301 as timestamp) into build with the plugin files and the html manual from +path/to/my/svn/checkout/of/Ant/Core/docs/manual. + + + + + Added: ant/sandbox/antlibs/manual4eclipse/docs/cover.html URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/docs/cover.html?view=auto&rev=513231 ============================================================================== --- ant/sandbox/antlibs/manual4eclipse/docs/cover.html (added) +++ ant/sandbox/antlibs/manual4eclipse/docs/cover.html Thu Mar 1 01:06:12 2007 @@ -0,0 +1,18 @@ + + + + + +Antlib Manual4Eclipse + + + + +

Antlib Manual4Eclipse

+ + +

This AntLib provides tasks for generating an Eclipse Help PlugIn from Ant's manual.

+ + + + Added: ant/sandbox/antlibs/manual4eclipse/docs/favicon.ico URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/docs/favicon.ico?view=auto&rev=513231 ============================================================================== Binary file - no diff available. Propchange: ant/sandbox/antlibs/manual4eclipse/docs/favicon.ico ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: ant/sandbox/antlibs/manual4eclipse/docs/index.html URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/docs/index.html?view=auto&rev=513231 ============================================================================== --- ant/sandbox/antlibs/manual4eclipse/docs/index.html (added) +++ ant/sandbox/antlibs/manual4eclipse/docs/index.html Thu Mar 1 01:06:12 2007 @@ -0,0 +1,18 @@ + + + + + +User Manual - Antlib Manual4Eclipse + + + + + + + + <H2>User Manual - Antlib Manual4Eclipse</H2> + <a href="toc.html">User Manual - Antlib Manual4Eclipse</a> + + + Added: ant/sandbox/antlibs/manual4eclipse/docs/m4e.html URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/docs/m4e.html?view=auto&rev=513231 ============================================================================== --- ant/sandbox/antlibs/manual4eclipse/docs/m4e.html (added) +++ ant/sandbox/antlibs/manual4eclipse/docs/m4e.html Thu Mar 1 01:06:12 2007 @@ -0,0 +1,79 @@ + + + + + + +M4E Task + + + + + + +

M4E

+

Description

+

+The m4e task scans the Ant manual table of content files by starting from a given file. +It acts like a spider. The task is dependent on the frame structure of the manual because +it uses all pages opened in the left navigation frame navFrame as references toc file. +There are build-in ignore lists, but they are not changeable from outside at the moment. +

+

+With the scanned information it generates a toc.xml which is needed for +Eclipse Help. It writes a plugin.xml with static content, too. +

+ + + +

Parameters

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
dirThe directory where to generate the files.yes
manualDirThe directory where Ant's manual is.yes
+ + + +

Examples

+
+<target name="gen" xmlns:m4e="antlib:org.apache.ant.manual4eclipse">
+    <property name="build" value="build"/>
+    <property name="ant.trunk" location="path/to/my/svn/checkout/of/Ant/Core"/>
+    <mkdir dir="${build}"/>
+    <m4e:m4e dir="${build}" manualDir="${ant.trunk}/docs/manual"/>
+</target>
+
+This target reads the data from Ant's manual living in path/to/my/svn/checkout/of/Ant/Core/docs/manual and generates a toc.xml and a plugin.xml to build. + + + + + Added: ant/sandbox/antlibs/manual4eclipse/docs/toc.html URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/docs/toc.html?view=auto&rev=513231 ============================================================================== --- ant/sandbox/antlibs/manual4eclipse/docs/toc.html (added) +++ ant/sandbox/antlibs/manual4eclipse/docs/toc.html Thu Mar 1 01:06:12 2007 @@ -0,0 +1,22 @@ + + + + + +Antlib Manual4Eclipse + + + + + +Overview
+ +

Tasks

+ + +m4e
+buildPlugin
+ + + + Modified: ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/Manual4EclipseTask.java URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/Manual4EclipseTask.java?view=diff&rev=513231&r1=513230&r2=513231 ============================================================================== --- ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/Manual4EclipseTask.java (original) +++ ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/Manual4EclipseTask.java Thu Mar 1 01:06:12 2007 @@ -41,266 +41,283 @@ */ public class Manual4EclipseTask extends Task { - - /** Line Separator. */ - String BR = System.getProperty("line.separator"); - - /** Ant Property: The output directory for generated files. */ - private File dir; - - /** Ant Property: The directory where the Ant manual (sources) is. */ - private File manualDir; - - - /** List of files which are already processed. */ - List processedFiles = new ArrayList(); - - /** List of Link references to ignore. */ - List ignoreLinks = new ArrayList(); - - /** List of Link references to ignore. */ - List ignoreTargets = new ArrayList(); - - /** List of Link references to ignore. */ - List ignoreText = new ArrayList(); - - - public Manual4EclipseTask() { - ignoreLinks.add("api/index.html"); - ignoreTargets.add("_main"); - ignoreText.add("Ant API"); - ignoreText.add("Table of Contents"); - } - - - @Override - public void execute() throws BuildException { - log("Generate Eclipse plugin files"); - try { - createToc(new File(manualDir, "toc.html")); - createPluginXml(); - } catch (Exception e) { - throw new BuildException(e, getLocation()); - } - } - - - private void createPluginXml() throws IOException { - log("generating plugin.xml", Project.MSG_INFO); - StringBuffer sb = new StringBuffer(); - sb.append("").append(BR); - sb.append("").append(BR); - sb.append("").append(BR); - sb.append(" ").append(BR); - sb.append(" ").append(BR); - sb.append(" ").append(BR); - sb.append(" ").append(BR); - sb.append(" ").append(BR); - sb.append(" ").append(BR); - sb.append(" ").append(BR); - sb.append("").append(BR); - write(sb, new File(dir, "plugin.xml")); - } - - - - private void createToc(File listHtml) throws IOException, SAXException { - log("generating toc.xml", Project.MSG_INFO); - StringBuffer toc = new StringBuffer(); - toc.append("").append(BR); - toc.append("").append(BR); - toc.append("").append(BR); - createTopic(toc, listHtml); - toc.append("").append(BR); - write(toc, new File(dir, "toc.xml")); - } - - - - private void createTopic(StringBuffer toc, File listHtml) - throws SAXException, IOException { - if (processedFiles.contains(listHtml)) { - return; - } - log("Processing " + listHtml, Project.MSG_VERBOSE); - processedFiles.add(listHtml); - Document document = JAXPUtils.getDocumentBuilder().parse(listHtml); - NodeList tagsA = document.getElementsByTagName("a"); - for (int i = 0; i < tagsA.getLength(); i++) { - Topic topic = new Topic(tagsA.item(i)); - if (topic.isIgnorable()) continue; - - if (topic.hasNestedTopics()) { - // start recursion - toc.append("<").append(topic).append(">").append(BR); - if ("anttaskslist.html".equals(topic.href)) { - createTopic4TaskOverview(toc); - } else { - createTopic(toc, new File(manualDir, topic.href)); - } - toc.append("").append(BR); - } else { - toc.append("<").append(topic).append("/>").append(BR); - } - } - } - - - - /** - * Generate topics for the core and optional tasks. - * Because the task lists (overview, core, optional) have a TOC-header, - * the generic recursion-algorithm does not work. So we have to deal - * with that. - * @param toc StringBuffer with the toc.xml in progress - * @param label Label for the root node - * @throws IOException - * @throws SAXException - * @throws BuildException - */ - private void createTopic4TaskOverview(StringBuffer toc) throws BuildException, SAXException, IOException { - File taskListFile = new File(manualDir, "anttaskslist.html"); - File coreTaskFile = new File(manualDir, "coretasklist.html"); - File optionalTask = new File(manualDir, "optionaltasklist.html"); - processedFiles.add(taskListFile); - processedFiles.add(coreTaskFile); - processedFiles.add(optionalTask); - - log("Using hard coded TOC-structure instead of " + taskListFile, Project.MSG_VERBOSE); - - toc.append("").append(BR); - toc.append("").append(BR); - // Core Tasks - createTopics4TaskList(toc, coreTaskFile); - toc.append("").append(BR); - toc.append("").append(BR); - // Optional Tasks - toc.append("").append(BR); - createTopics4TaskList(toc, optionalTask); - toc.append("").append(BR); - } - - - - /** - * Creates a element (with nested) for Task list. - * The task lists are placed after a <h3> header and there are - * <a> tags before that. So we have to do more work and search - * for the right are. - * @param toc StringBuffer with the toc.xml in progress - * @param file The file with the task list - * @throws BuildException - * @throws SAXException - * @throws IOException - */ - private void createTopics4TaskList(StringBuffer toc, File file) throws BuildException, SAXException, IOException { - log("Processing " + file, Project.MSG_VERBOSE); - Document doc = JAXPUtils.getDocumentBuilder().parse(file); - // Access to the HTML root element - Element html = doc.getDocumentElement(); - // search for the element - Element body = null; - NodeList childNodes = html.getChildNodes(); - for (int i=0; i").append(BR); - } - } - if (n.getNodeName().equalsIgnoreCase("h3")) { - needSection = true; - } - } - } - - - - - /** - * Writes a StringBuffer to file. - * @param sb The StringBuffer to write - * @param file The file to write into - * @throws IOException if writing throws an IOException - */ - private void write(StringBuffer sb, File file) throws IOException { - FileWriter out = new FileWriter(file); - out.write(sb.toString()); - out.close(); - } - - - - public void setDir(File dir) { - this.dir = dir; - } - - public void setManualDir(File manualDir) { - this.manualDir = manualDir; - } - - - - - /** - * This class encapsulates the information of a tag from a - * toc-listing from the Ant manual. - */ - public class Topic { - /** s label attribute gets the value from <a>s text content. */ - String label; - /** Internal value coming from <a>s target attribute. */ - String target; - /** s href attribute gets the value from <a>s href attribute. */ - String href; - - /** - * Constructor analyzes a DOMNode and creates a Topic object. - * @param n the DOMNode - */ - public Topic(Node n) { - Node item = n.getAttributes().getNamedItem("href"); - href = (item!=null) ? item.getTextContent() : ""; - item = n.getAttributes().getNamedItem("target"); - target = (item!=null) ? item.getTextContent() : ""; - label = n.getTextContent().trim(); - } - /** - * Checks the data against the three ignore-lists. - * @return true if one (or more) of the lists matches - */ - public boolean isIgnorable() { - return ignoreLinks.contains(href) - || ignoreTargets.contains(target) - || ignoreText.contains(label); - } - /** - * You have to create nested elements if the link-target - * would open the linked page in the navigation frame. This method - * does the check. - * @return true if nestd elements could come. - */ - public boolean hasNestedTopics() { - return "navFrame".equals(target); - } - @Override - public String toString() { - StringBuffer rv = new StringBuffer("topic"); - if (label.length()>0) rv.append(" label=\"").append(label).append("\""); - if (href.length()>0 && !hasNestedTopics()) rv.append(" href=\"").append(href).append("\""); - return rv.toString().replaceAll("&", "&"); - } - } - + + /** Line Separator. */ + String BR = System.getProperty("line.separator"); + + /** Ant Property: The output directory for generated files. */ + private File dir; + + /** Ant Property: The directory where the Ant manual (sources) is. */ + private File manualDir; + + + /** List of files which are already processed. */ + List processedFiles = new ArrayList(); + + /** List of Link references to ignore. */ + List ignoreLinks = new ArrayList(); + + /** List of Link references to ignore. */ + List ignoreTargets = new ArrayList(); + + /** List of Link references to ignore. */ + List ignoreText = new ArrayList(); + + + public Manual4EclipseTask() { + ignoreLinks.add("api/index.html"); + ignoreTargets.add("_main"); + ignoreText.add("Ant API"); + ignoreText.add("Table of Contents"); + } + + + @Override + public void execute() throws BuildException { + validate(); + log("Generate Eclipse plugin files"); + try { + createToc(new File(manualDir, "toc.html")); + createPluginXml(); + } catch (Exception e) { + throw new BuildException(e, getLocation()); + } + } + + + private void validate() { + if (dir==null) { + throw new BuildException("'dir' must point to a directory where to generate the files."); + } + if (manualDir==null) { + throw new BuildException("'manualDir' must point to the directory of the Ant Manual."); + } + if (!dir.canWrite()) { + throw new BuildException("Output directory '" + dir + "' is not writable."); + } + if (!manualDir.canRead()) { + throw new BuildException("Manual directory '" + manualDir + "' is not readable."); + } + } + + + private void createPluginXml() throws IOException { + log("generating plugin.xml", Project.MSG_INFO); + StringBuffer sb = new StringBuffer(); + sb.append("").append(BR); + sb.append("").append(BR); + sb.append("").append(BR); + sb.append(" ").append(BR); + sb.append(" ").append(BR); + sb.append(" ").append(BR); + sb.append(" ").append(BR); + sb.append(" ").append(BR); + sb.append(" ").append(BR); + sb.append(" ").append(BR); + sb.append("").append(BR); + write(sb, new File(dir, "plugin.xml")); + } + + + + private void createToc(File listHtml) throws IOException, SAXException { + log("generating toc.xml", Project.MSG_INFO); + StringBuffer toc = new StringBuffer(); + toc.append("").append(BR); + toc.append("").append(BR); + toc.append("").append(BR); + createTopic(toc, listHtml); + toc.append("").append(BR); + write(toc, new File(dir, "toc.xml")); + } + + + + private void createTopic(StringBuffer toc, File listHtml) + throws SAXException, IOException { + if (processedFiles.contains(listHtml)) { + return; + } + log("Processing " + listHtml, Project.MSG_VERBOSE); + processedFiles.add(listHtml); + Document document = JAXPUtils.getDocumentBuilder().parse(listHtml); + NodeList tagsA = document.getElementsByTagName("a"); + for (int i = 0; i < tagsA.getLength(); i++) { + Topic topic = new Topic(tagsA.item(i)); + if (topic.isIgnorable()) continue; + + if (topic.hasNestedTopics()) { + // start recursion + toc.append("<").append(topic).append(">").append(BR); + if ("anttaskslist.html".equals(topic.href)) { + createTopic4TaskOverview(toc); + } else { + createTopic(toc, new File(manualDir, topic.href)); + } + toc.append("").append(BR); + } else { + toc.append("<").append(topic).append("/>").append(BR); + } + } + } + + + + /** + * Generate topics for the core and optional tasks. + * Because the task lists (overview, core, optional) have a TOC-header, + * the generic recursion-algorithm does not work. So we have to deal + * with that. + * @param toc StringBuffer with the toc.xml in progress + * @param label Label for the root node + * @throws IOException + * @throws SAXException + * @throws BuildException + */ + private void createTopic4TaskOverview(StringBuffer toc) throws BuildException, SAXException, IOException { + File taskListFile = new File(manualDir, "anttaskslist.html"); + File coreTaskFile = new File(manualDir, "coretasklist.html"); + File optionalTask = new File(manualDir, "optionaltasklist.html"); + processedFiles.add(taskListFile); + processedFiles.add(coreTaskFile); + processedFiles.add(optionalTask); + + log("Using hard coded TOC-structure instead of " + taskListFile, Project.MSG_VERBOSE); + + toc.append("").append(BR); + toc.append("").append(BR); + // Core Tasks + createTopics4TaskList(toc, coreTaskFile); + toc.append("").append(BR); + toc.append("").append(BR); + // Optional Tasks + toc.append("").append(BR); + createTopics4TaskList(toc, optionalTask); + toc.append("").append(BR); + } + + + + /** + * Creates a element (with nested) for Task list. + * The task lists are placed after a <h3> header and there are + * <a> tags before that. So we have to do more work and search + * for the right are. + * @param toc StringBuffer with the toc.xml in progress + * @param file The file with the task list + * @throws BuildException + * @throws SAXException + * @throws IOException + */ + private void createTopics4TaskList(StringBuffer toc, File file) throws BuildException, SAXException, IOException { + log("Processing " + file, Project.MSG_VERBOSE); + Document doc = JAXPUtils.getDocumentBuilder().parse(file); + // Access to the HTML root element + Element html = doc.getDocumentElement(); + // search for the element + Element body = null; + NodeList childNodes = html.getChildNodes(); + for (int i=0; i").append(BR); + } + } + if (n.getNodeName().equalsIgnoreCase("h3")) { + needSection = true; + } + } + } + + + + + /** + * Writes a StringBuffer to file. + * @param sb The StringBuffer to write + * @param file The file to write into + * @throws IOException if writing throws an IOException + */ + private void write(StringBuffer sb, File file) throws IOException { + FileWriter out = new FileWriter(file); + out.write(sb.toString()); + out.close(); + } + + + + public void setDir(File dir) { + this.dir = dir; + } + + public void setManualDir(File manualDir) { + this.manualDir = manualDir; + } + + + + + /** + * This class encapsulates the information of a tag from a + * toc-listing from the Ant manual. + */ + public class Topic { + /** s label attribute gets the value from <a>s text content. */ + String label; + /** Internal value coming from <a>s target attribute. */ + String target; + /** s href attribute gets the value from <a>s href attribute. */ + String href; + + /** + * Constructor analyzes a DOMNode and creates a Topic object. + * @param n the DOMNode + */ + public Topic(Node n) { + Node item = n.getAttributes().getNamedItem("href"); + href = (item!=null) ? item.getTextContent() : ""; + item = n.getAttributes().getNamedItem("target"); + target = (item!=null) ? item.getTextContent() : ""; + label = n.getTextContent().trim(); + } + /** + * Checks the data against the three ignore-lists. + * @return true if one (or more) of the lists matches + */ + public boolean isIgnorable() { + return ignoreLinks.contains(href) + || ignoreTargets.contains(target) + || ignoreText.contains(label); + } + /** + * You have to create nested elements if the link-target + * would open the linked page in the navigation frame. This method + * does the check. + * @return true if nestd elements could come. + */ + public boolean hasNestedTopics() { + return "navFrame".equals(target); + } + @Override + public String toString() { + StringBuffer rv = new StringBuffer("topic"); + if (label.length()>0) rv.append(" label=\"").append(label).append("\""); + if (href.length()>0 && !hasNestedTopics()) rv.append(" href=\"").append(href).append("\""); + return rv.toString().replaceAll("&", "&"); + } + } + } Added: ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/antlib.xml URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/antlib.xml?view=auto&rev=513231 ============================================================================== --- ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/antlib.xml (added) +++ ant/sandbox/antlibs/manual4eclipse/src/main/org/apache/ant/manual4eclipse/antlib.xml Thu Mar 1 01:06:12 2007 @@ -0,0 +1,67 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org For additional commands, e-mail: dev-help@ant.apache.org