diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/main/java/net/sf/antcontrib/cpptasks/CCTask.java | 2 | ||||
| -rw-r--r-- | src/main/java/net/sf/antcontrib/cpptasks/ProcessorDef.java | 12 | ||||
| -rw-r--r-- | src/samples/hello/build.xml | 26 | ||||
| -rw-r--r-- | src/samples/hello/src/main/c/hello.c | 25 | ||||
| -rw-r--r-- | src/site/apt/index.apt | 60 | ||||
| -rw-r--r-- | src/site/fml/faq.fml | 766 | ||||
| -rw-r--r-- | src/site/site.xml | 26 | ||||
| -rw-r--r-- | src/taskdocs/java/net/sf/antcontrib/taskdocs/TaskDoclet.java | 1 | ||||
| -rw-r--r-- | src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt | 210 |
9 files changed, 358 insertions, 770 deletions
diff --git a/src/main/java/net/sf/antcontrib/cpptasks/CCTask.java b/src/main/java/net/sf/antcontrib/cpptasks/CCTask.java index beeed89..92ead13 100644 --- a/src/main/java/net/sf/antcontrib/cpptasks/CCTask.java +++ b/src/main/java/net/sf/antcontrib/cpptasks/CCTask.java @@ -79,7 +79,7 @@ import org.apache.tools.ant.types.Environment; * <ul><li>Ant 1.6 or later: add xmlns:cpptasks="antlib:org.sf.net.antcontrib.cpptasks" to <project> element.</li> * <li>Ant 1.5 or later: Add <taskdef resource="cpptasks.tasks"/> and <typedef * resource="cpptasks.types"/> to body of <project> element.</li></ul></li> - * <li>Add <cc/>, <compiler/> and <linker/> elements to + * <li>Add <cc/>, <compiler/> and <linker/> elements to * project.</li> * <li>Set path and environment variables to be able to run compiler from * command line.</li> diff --git a/src/main/java/net/sf/antcontrib/cpptasks/ProcessorDef.java b/src/main/java/net/sf/antcontrib/cpptasks/ProcessorDef.java index 24c1a1f..334efa6 100644 --- a/src/main/java/net/sf/antcontrib/cpptasks/ProcessorDef.java +++ b/src/main/java/net/sf/antcontrib/cpptasks/ProcessorDef.java @@ -65,7 +65,7 @@ public abstract class ProcessorDef extends DataType { */ private String ifProp; /** - * if true, processor definition inherits values from containing <cc> + * if true, processor definition inherits values from containing cc * element */ private boolean inherit; @@ -175,7 +175,7 @@ public abstract class ProcessorDef extends DataType { * Creates a configuration * * @param baseDef - * reference to def from containing <cc>element, may be null + * reference to def from containing cc element, may be null * @return configuration * */ @@ -192,7 +192,7 @@ public abstract class ProcessorDef extends DataType { return proc.createConfiguration(task, linkType, defaultProviders, this, targetPlatform, versionInfo); } /** - * Prepares list of processor arguments ( <compilerarg>, <linkerarg>) that + * Prepares list of processor arguments ( compilerarg, linkerarg ) that * are active for the current project settings. * * @return active compiler arguments @@ -219,7 +219,7 @@ public abstract class ProcessorDef extends DataType { return array; } /** - * Prepares list of processor arguments ( <compilerarg>, <linkerarg>) that + * Prepares list of processor arguments ( compilerarg, linkerarg) that * are active for the current project settings. * * @return active compiler arguments @@ -315,7 +315,7 @@ public abstract class ProcessorDef extends DataType { } /** * Gets the inherit attribute. If the inherit value is true, this processor - * definition will inherit default values from the containing <cc>element. + * definition will inherit default values from the containing cc element. * * @return if true then properties from the containing <cc>element are * used. @@ -523,7 +523,7 @@ public abstract class ProcessorDef extends DataType { } /** * If inherit has the default value of true, defines, includes and other - * settings from the containing <cc>element will be inherited. + * settings from the containing cc element will be inherited. * * @param inherit * new value diff --git a/src/samples/hello/build.xml b/src/samples/hello/build.xml new file mode 100644 index 0000000..afefbc7 --- /dev/null +++ b/src/samples/hello/build.xml @@ -0,0 +1,26 @@ +<!-- + Licensed to the Ant-Contrib Project under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +--> +<project name="hello" default="compile"> + <taskdef resource="cpptasks.tasks"/> + <target name="compile"> + <mkdir dir="target/main/obj"/> + <cc outtype="executable" subsystem="console" outfile="target/hello" objdir="target/main/obj"> + <fileset dir="src/main/c" includes="*.c"/> + </cc> + </target> +</project> diff --git a/src/samples/hello/src/main/c/hello.c b/src/samples/hello/src/main/c/hello.c new file mode 100644 index 0000000..b0183a5 --- /dev/null +++ b/src/samples/hello/src/main/c/hello.c @@ -0,0 +1,25 @@ +/* + + Licensed to the Ant-Contrib Project under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +*/ + +#include <stdio.h> + +int main(int argc, const char** argv) { + puts("Hello, World."); + return 1; +} diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt new file mode 100644 index 0000000..2218ba5 --- /dev/null +++ b/src/site/apt/index.apt @@ -0,0 +1,60 @@ +~~ Licensed to the Ant-Contrib Project under one or more +~~ contributor license agreements. See the NOTICE file distributed with +~~ this work for additional information regarding copyright ownership. +~~ The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0 +~~ (the "License"); you may not use this file except in compliance with +~~ the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, software +~~ distributed under the License is distributed on an "AS IS" BASIS, +~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +~~ See the License for the specific language governing permissions and +~~ limitations under the License. + ------ +cpptasks for Apache Ant + ------ + ------ + ------ + +cpptasks for Apache Ant + + The cc task can compile various source languages and produce executables, + shared libraries (aka DLL's) and static libraries. Compiler adaptors are currently available + for several C/C++ compilers, FORTRAN, MIDL and Windows Resource files. + + The task can be used with Apache Ant 1.5 and later. This software is not a product + of the Apache Software Foundation (ASF) and no endorsement by the ASF is implied. + + + To use: + * Place cpptasks.jar into Ant's classpath by placing in Ant's lib directory, + adding to CLASSPATH environment variable or using the -lib command line option. + + * Add type and task definitions in build file: + Ant 1.6 or later: add xmlns:cpptasks="antlib:sf.net.antcontrib.cpptasks" to <project> element. + Ant 1.5 or later: Add <taskdef resource="cpptasks.tasks"/> and <typedef resource="cpptasks.types"/> to body of <project> element. + + * Add {{{antdocs/CCTask.html}cc}} element to some target in your build file. + + * Set path and environment variables to be able to run compiler from command line. + + * Build project. + + Trivial Sample: + ++-- +<project name="hello" default="compile"> + <taskdef resource="cpptasks.tasks"/> + <target name="compile"> + <mkdir dir="target/main/obj"/> + <cc outtype="executable" subsystem="console" outfile="target/hello" objdir="target/main/obj"> + <fileset dir="src/main/c" includes="*.c"/> + </cc> + </target> +</project> ++-- + + More complex samples appear in src/samples. + diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml index 546d8b6..04bfb65 100644 --- a/src/site/fml/faq.fml +++ b/src/site/fml/faq.fml @@ -1,9 +1,9 @@ <?xml version="1.0"?> <!-- - Licensed to the Apache Software Foundation (ASF) under one or more + Licensed to the Ant-Contrib Project under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 + The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at @@ -16,766 +16,12 @@ limitations under the License. --> -<faqs title="Frequently Asked Technical Questions"> +<faqs title="Frequently Asked Questions"> <part id="faq"> - <faq id="1.1"> - <question>What is log4j?</question> - <answer> <p>log4j is a tool to help the programmer output log statements to a - variety of output targets. - </p> - - <p>In case of problems with an application, it is helpful to - enable logging so that the problem can be located. With log4j - it is possible to enable logging at runtime without modifying - the application binary. The log4j package is designed so that - log statements can remain in <i>shipped</i> code without - incurring a high performance cost. It follows that the speed - of logging (or rather not logging) is capital. - </p> - - <p>At the same time, log output can be so voluminous that it quickly - becomes overwhelming. One of the distinctive features of log4j is the - notion of <i>hierarchical loggers</i>. Using loggers it is - possible to selectively control which log statements are output at - arbitrary granularity. - </p> - - <p>log4j is designed with two three goals in mind: - reliability, speed and flexibility. There is a tight balance - between these requirements. We believe that log4j strikes the - right balance. - </p> -</answer> - </faq> - - - <faq id="1.2"><question>Is log4j a reliable logging system?</question> - <answer><p>No. log4j is not reliable. It is a best-effort - <em>fail-stop</em> logging system. - </p> - - <p>By fail-stop, we mean that log4j will not throw unexpected - exceptions at run-time potentially causing your application to - crash. <b>If for any reason, log4j throws an uncaught exception, - please send an email to the <a href="mailto:[email protected]">[email protected]</a> - mailing list</b>. Uncaught exceptions are handled as serious bugs - requiring immediate attention. - </p> - - <p>Moreover, log4j will not revert to System.out or System.err - when its designated output stream is not opened, is not writable or - becomes full. This avoids corrupting an otherwise working program by - flooding the user's terminal because logging fails. However, log4j - will output a single message to System.err indicating that logging can - not be performed. - </p></answer></faq> - - <faq id="1.3"><question>What are the prerequisites for log4j?</question> - <answer> - <p>Log4j versions upto and including 1.2.8 are - compatible with JDK 1.1.x and later. Log4j version 1.3 will - be compatilble with JDK 1.2 and later. - </p> - - <p>The DOMConfigurator is based on the DOM Level 1 - API. The DOMConfigurator.configure(Element) method will work - with any XML parser that will pass it a DOM tree. - </p> - <p>The DOMConfigurator.configure(String filename) method and its - variants require a JAXP compatible XML parser, for example <a href="http://xml.apache.org/">Xerces</a> or Sun's - parser. Compiling the DOMConfigurator requires the presence of a - JAXP parser in the classpath. - </p> - - <p>The <code>org.apache.log4j.net.SMTPAppender</code> - relies on the <a href="http://java.sun.com/products/javamail/">JavaMail - API</a>. It has been tested with JavaMail API version - 1.2. The JavaMail API requires the <a href="http://java.sun.com/beans/glasgow/jaf.html">JavaBeans - Activation Framework</a> package. - </p> - - <p>The <code>org.apache.log4j.net.JMSAppender</code> - requires the presence of the JMS API as well as JNDI. - </p> - - <p>log4j test code relies on the <a href="http://www.junit.org">JUnit</a> testing framework. - </p> - </answer></faq> - - <faq id="1.4"><question>What are the features of log4j?</question> - <answer> - <p>log4j is optimized for speed.</p> - - <p>log4j is based on a named logger hierarchy.</p> - - <p>log4j is fail-stop. However, altough it certainly - strives to ensure delivery, log4j does not guarantee that - each log statement will be delivered to its destination. - </p> - - <p>log4j is thread-safe.</p> - - <p>log4j is not restricted to a predefined set of - facilities.</p> - - <p>Logging behavior can be set at runtime using a - configuration file. Configuration files can be property - files or in XML format. </p> - - <p>log4j is designed to handle Java Exceptions from the - start.</p> - - <p>log4j can direct its output to a file, the console, - an <code>java.io.OutputStream</code>, - <code>java.io.Writer</code>, a remote server using TCP, a - remote Unix Syslog daemon, to a remote listener using JMS, - to the NT EventLog or even send e-mail. </p> - - <p>log4j uses 5 levels, namely DEBUG, INFO, WARN, ERROR and - FATAL. - </p> - - <p>The format of the log output can be easily changed by - extending the <code>Layout</code> - class. </p> - - <p>The target of the log output as well as the writing - strategy can be altered by implementations of the - <code>Appender</code> interface. </p> - - <p>log4j supports multiple output appenders per logger. - </p> - - <p>log4j supports internationalization.</p> - </answer></faq> - - <faq id="1.5"><question>Is there example code for using log4j?</question> - <answer> - <p>See the <code>examples/</code> directory.</p> - </answer> - </faq> - - <faq id="1.6"> - <question>What documentation should I read to learn more about - log4j?</question> - <answer><p>Make sure to read the <a href="manual.html">short - manual</a>. It is also recommended to you read <a href="https://www.qos.ch/shop/products/log4j/log4j-Manual.jsp">The complete - log4j manual</a> which is much more detailed and up to - date. Both documents were written by Ceki Gülcü. - </p></answer> - </faq> - - <faq id="1.7"><question>Is log4j thread-safe?</question> - <answer> - <p>Yes, log4j is thread-safe. Log4j components are designed to - be used in heavily multithreaded systems.</p> - - </answer></faq> - - <faq id="1.8"><question>What does log output look like?</question> - <answer> - <p>The log output can be customized in many ways. Moreover, - one can completely override the output format by implementing - one's own Layout. - </p> - - <p>Here is an example output using <em>PatternLayout</em> with - the conversion pattern <b>"%r [%t] %-5p %c{2} %x - %m%n"</b> - </p> - - <pre class="screen_output"> -176 [main] INFO examples.Sort - Populating an array of 2 elements in reverse order. -225 [main] INFO examples.SortAlgo - Entered the sort method. -262 [main] DEBUG SortAlgo.OUTER i=1 - Outer loop. -276 [main] DEBUG SortAlgo.SWAP i=1 j=0 - Swapping intArray[0] = 1 and intArray[1] = 0 -290 [main] DEBUG SortAlgo.OUTER i=0 - Outer loop. -304 [main] INFO SortAlgo.DUMP - Dump of interger array: -317 [main] INFO SortAlgo.DUMP - Element [0] = 0 -331 [main] INFO SortAlgo.DUMP - Element [1] = 1 -343 [main] INFO examples.Sort - The next log statement should be an error message. -346 [main] ERROR SortAlgo.DUMP - Tried to dump an uninitialized array. - at org.log4j.examples.SortAlgo.dump(SortAlgo.java:58) - at org.log4j.examples.Sort.main(Sort.java:64) -467 [main] INFO examples.Sort - Exiting main method. - </pre> - - <p>The first field is the number of milliseconds elapsed since - the start of the program. The second field is the thread - outputting the log statement. The third field is the level of - the log statement. The fourth field is the rightmost two - components of the logger making the log request. The fifth - field (just before the '-') is the <em>nested diagnostic - context</em> (NDC). Note the nested diagnostic context may be - empty as in the first two statements. The text after the '-' - is the message of the statement. - </p> - </answer></faq> - - <faq id="1.9"><question>Why should I use log4j when JDK 1.4 already ships with a - logging API?</question> - <answer> - - <p> - Although both APIs are conceptually similar, the log4j API is - significantly more flexible and offers many more features, too - numerous to be listed here. You will discover that the - additional features and flexibility turn out to be - indispensable in the context of a mission-critical - application. - </p> - - <p>The open and collaborative way in which log4j is developped - ensures that it continues to preserve and even widen its - competitive edge. At some point, input from bright developers - from all over the world is bound to make a difference. - </p> - </answer> - </faq> - - - <faq id="2.1"><question>What are <em>Loggers</em>?</question> - <answer> - - <p>Lggers lie at the heart of log4j. Loggers define a hierarchy and give - the programmer <em>run-time</em> control on which statements are - printed or not. - </p> - - <p>Loggers are assigned levels. A log statement is printed - depending on its level <em>and</em> its logger. - </p> - - <p>Make sure to read the <a href="manual.html">log4j manual</a> - for more information. - </p> - </answer></faq> - -<faq id="2.2"><question>How can I change log behavior at runtime?</question> - <answer> - <p>Log behavior can be set using configuration files which are parsed - at runtime. Using configuration files the programmer can define - loggers and set their levels. - </p> - - <p>The <code>PropertyConfigurator</code> defines a particular format - of a configuration file. See also the <code>examples/Sort.java</code> - example and associated configuration files. - </p> - - <p>Configuration files can be specified in XML. See - <code>log4j.dtd</code> and - <code>org.log4j.xml.DOMConfigurator</code> for more details. - </p> - - <p>See the various Layout and Appender components for specific - configuration options. - </p> - - <p>In addition to configuration files, the user may disable all - messages belonging to a set of levels. See next item. - </p> - - </answer></faq> - - <faq id="2.3"><question>What is the fastest way of (not) logging?</question> - <answer> - <p> For some logger <code>l</code>, writing, - </p> - - <pre class="source"> - l.debug("Entry number: " + i + " is " + String.valueOf(entry[i])); - </pre> - - <p>incurs the cost of constructing the message parameter, that is - converting both integer <code>i</code> and <code>entry[i]</code> to a - String, and concatenating intermediate strings. This, regardless of - whether the message will be logged or not. - </p> - - <p>If you are worried about speed, then write</p> - <pre class="source"> - if(l.isDebugEnabled()) { - l.debug("Entry number: " + i + " is " + String.valueOf(entry[i])); - } - </pre> - - <p>This way you will not incur the cost of parameter - construction if debugging is disabled for logger - <code>l</code>. On the other hand, if the logger is debug - enabled, you will incur the cost of evaluating whether the - logger is enabled or not, twice: once in - <code>debugEnabled</code> and once in <code>debug</code>. - This is an insignificant overhead since evaluating a logger - takes less than 1% of the time it takes to actually log a - statement. - </p> -</answer></faq> - - <faq id="2.4"><question>Are there any suggested ways for naming loggers?</question> - <answer> - <p>Yes, there are.</p> - - <p>You can name loggers by <strong>locality</strong>. It turns out - that instantiating a logger in each class, with the logger name - equal to the fully-qualified name of the class, is a useful and - straightforward approach of defining loggers. This approach has - many benefits: - </p> - - <ul> - <li>It is very simple to implement.</li> - - <li>It is very simple to explain to new developers.</li> - - <li>It automatically mirrors your application's own modular design. - </li> - <li>It can be further refined at will.</li> - - <li>Printing the logger automatically gives information on the locality - of the log statement. </li> - </ul> - - <p>However, this is not the only way for naming loggers. A - common alternative is to name loggers by <strong>functional - areas</strong>. For example, the "database" logger, "RMI" - logger, "security" logger, or the "XML" logger. - </p> - - <p>You may choose to name loggers by functionality and - subcategorize by locality, as in "DATABASE.com.foo.some.package.someClass" or - "DATABASE.com.foo.some.other.package.someOtherClass". - </p> - - <p><em>You are totally free in choosing the names of your - loggers.</em> The log4j package merely allows you to manage your - names in a hierarchy. However, it is your responsibility to define - this hierarchy. - </p> - - <p>Note by naming loggers by locality one tends to name things by - functionality, since in most cases the locality relates closely to - functionality. - </p> - </answer></faq> - - <faq id="2.5"><question>How do I get the fully-qualified name of a class in a static block?</question> - <answer> - <p>You can easily retrieve the fully-qualified name of a class in a - static block for class X, with the statement - <code>X.class.getName()</code>. Note that <code>X</code> is the class - name and not an instance. The <code>X.class</code> statement does - <i>not</i> create a new instance of class <code>X</code>. - </p> - - <p>Here is the suggested usage template:</p> - - <pre class="source"> -package a.b.c; - -public class Foo { - final static Logger logger = Logger.getLogger(Foo.class); - ... other code - -} - </pre> - </answer></faq> - - <faq id="2.6"><question>Can the log output format be customized? </question> - <answer> - <p>Yes, you can extend the <code>Layout</code> class to create - you own customized log format. Appenders can be parameterized - to use the layout of your choice. - </p> -</answer></faq> - - <faq id="2.7"><question>What are the configurable options for <code>FooBarAppender</code>?</question> - <answer> - <p>Log4j uses JavaBeans style configuration.</p> - - <p>Thus, any setter method in <code>FooBarAppender</code> - corresponds to a configurable option. For example, in <a href="apidocs\org\apache\log4j\RollingFileAppender.html"><code>RollingFileAppender</code></a> - the <a href="apidocs/org/apache/log4j/RollingFileAppender.html#setMaxBackupIndex(int)"><code>setMaxBackupIndex(int - maxBackups)</code></a> method corresponds to the - <code>maxBackupIndex</code> option. The first letter of the - option can be upper case, i.e. <code>MaxBackupIndex</code> - and <code>maxBackupIndex</code> are equivalent but not - <code>MAXBACKUPIndex</code> nor <code>mAXBackupIndex</code>. - </p> - - <p>Layouts options are also defined by their setter methods. The same goes - for most other log4j components. - </p> - </answer></faq> - - <faq id="2.8"><question>What is the recommended way of migrating from - java.util.logging to log4j?</question> - <answer> - - <p>We suggest to just use global file search/replace. You should be able - to replace all the "java.util.Logger" references with - "org.apache.log4j.Logger", and you should be on your way. - </p> - - <p>If you're on a Win32 platform, we recommend <a href="http://www.textpad.com/">Textpad</a>. You can use the - CTRL+SHIFT+O to open all *.java files from a directory including all - its sub-directories, and then use the search/replace function to - replace in all files, and then CTRL+SHIFT+S to save all. Should take - about 60 seconds! :) - </p> - </answer></faq> - - <faq id="2.9"><question>Is it possible to direct log output to - different appenders by level? </question><answer> - <p>Yes it is. Setting the <b>Threshold</b> option of any appender - extending <a href="api/org/apache/log4j/AppenderSkeleton.html">AppenderSkeleton</a>, - (most log4j appenders extend AppenderSkeleton) to filter out all log - events with <em>lower</em> level than the value of the threshold - option. - </p> - - <p>For example, setting the threshold of an appender to DEBUG - also allow INFO, WARN, ERROR and FATAL messages to log along - with DEBUG messages. This is usually acceptable as there is - little use for DEBUG messages without the surrounding INFO, - WARN, ERROR and FATAL messages. Similarly, setting the - threshold of an appender to ERROR will filter out DEBUG, INFO - and WARN messages but not ERROR or FATAL messages. - </p> - - <p>This policy usually best encapsulates what the user - actually wants to do, as opposed to her mind-projected - solution. - </p> - <p>See <i>examples/sort4.lcf</i> for an example threshold - configuration.</p> - - <p>If you must filter events by exact level match, then you can - attach a <a href="apidocs/org/apache/log4j/varia/LevelMatchFilter.html">LevelMatchFilter</a> - to any appender to filter out logging events by exact level match. - </p> - </answer></faq> - - - <faq id="2.10"><question>What does the Windows NT Event Viewer complain about - missing descriptions for my event messages when I use the - <code>NTEventLogAppender</code>?</question> - - <answer> - <p>The NT Event Viewer relies on <i>message resource</i> DLLs - to properly view an event message. The NTEventLogAppender.dll - contains these message resources, but that DLL must be copied - to %SYSTEMROOT%\SYSTEM32 for it to work properly. - </p> - </answer></faq> - - <faq id="2.11"><question>Why can't I map my logger names to the loggers that - appear in the NT Event Log when I use the - NTEventLogAppender?</question> - - <answer> - <p>Unfotunately, the logger names are hardcoded within the - message resource DLL (see previous question about - NTEventLogAppender), so there isn't any easy way to override - those dynamically... in fact, I don't think it's possible to - do it, as you'd have to modify the DLL resources for every - application. Since most native applications don't use the - Logger column anyway... - </p> - </answer></faq> - - <faq id="2.12"><question>Are there suggested approaches for logging in JSP pages?</question> - <answer> - <p> - The suggested approach depends on your design requirements. If you or - your organization has no constraints on the use of Java in JSP pages, - simply use log4j normally in <code><% ... %></code> statements - as indicated in the Short Manual and the rest of the documentation. - </p> - <p> - However, if your design calls for a minimum amount of Java in your JSP - pages, consider using the - <a href="http://jakarta.apache.org/taglibs/doc/log-doc/intro.html">Log Taglib</a> - from the Jakarta Taglibs project. It provides logging JSP tags that invoke - log4j. - </p> - </answer> - </faq> - - <faq id="3.1"><question>Can the outputs of multiple client request go to - different log files?</question> - <answer> - <p>Many developers are confronted with the problem of - distinguishing the log output originating from the same class - but different client requests. They come up with ingenious - mechanisms to fan out the log output to different files. In - most cases, this is not the right approach. - </p> - - <p>It is simpler to use a nested diagnostic context - (NDC). Typically, one would <em>NDC.push()</em> client - specific information, such as the client's hostname, ID or any - other distinguishing information when starting to handle the - client's request. Thereafter, log output will automatically - include the nested diagnostic context so that you can - distinguish logs from different client requests even if they - are output to the same file. - </p> - - <p>See the <code>NDC</code> and the <code>PatternLayout</code> - classes for more information. The <code>NumberCruncher</code> - example shows how the NDC can be used to distinguish the log - output from multiple clients even if they share the same log - file. - </p> - - <p>For select applications, such as virtual hosting - web-servers, the NDC solution is not sufficient. As of version - 0.9.0, log4j supports multiple hierarchy trees. Thus, it is - possible to log to different targets from the same logger - depending on the current context. - </p> - </answer></faq> - - - <faq id="3.2"><question>Logger instances seem to be create only. Why isn't - there a method to remove logger instances?</question> - <answer> - <p>It is quite nontrivial to define the semantics of a - "removed" logger escecially if it is still referenced by the - user. Future releases <em>may</em> include a remove method in - the Logger class.</p></answer></faq> - - <faq id="3.3"><question>How do I get multiple process to log to the same file?</question> - <answer> - <p>You may have each process log to a - <a href="apidocs/org/apache/log4j/net/SocketAppender.html"><code>SocketAppender</code></a>. - The receiving - <a href="apidocs/org/apache/log4j/net/SocketServer.html"><code>SocketServer</code></a> - (or - <a href="apidocs/org/apache/log4j/net/SimpleSocketServer.html"><code>SimpleSocketServer</code></a>) - can receive all the events and send them to a single - log file. - </p> - </answer></faq> - - <faq id="3.4"><question>How about the timesamps of events generated by multiple - processes across multiple hosts (possibly across multiple - timezones)?</question> - <answer> - <p>The timestamp is created when the logging event is created. - That is so say, when the <code>debug</code>, - <code>info</code>, <code>warn</code>, <code>error</code> or - <code>fatal</code> method is invoked. Thus, the timestamp is - unaffected by the time at which event arrive at a remote - socket server. - </p> - - <p>Timestamps are stored in UTC format inside the - event. Consequently, when displayed or written to a log file, - timestamps appear in the same timezone as the host displaying - or creating the logfile. Note that because the clocks of - various machines may not be synchronized, there may be - timestamp inconsistencies between events generated on - different hosts. - </p> - </answer></faq> - - <faq id="3.5"><question>Why can't log4j find my properties file in a J2EE or WAR - application?</question><answer> - <p>The short answer: the log4j classes and the properties file - are not within the scope of the same classloader. - </p> - - <p>The long answer (and what to do about it): J2EE or Servlet - containers utilize Java's class loading system. Sun changed - the way classloading works with the release of Java 2. In - Java 2, classloaders are arranged in a hierarchial - parent-child relationship. When a child classloader needs to - find a class or a resource, it first delegates the request to - the parent. - </p> - - <p>Log4j only uses the default <code>Class.forName()</code> - mechanism for loading classes. Resources are handled - similarly. See the documentation for - <code>java.lang.ClassLoader</code> for more details. - </p> - - <p>So, if you're having problems, try loading the class or - resource yourself. If you can't find it, neither will - log4j. ;) - </p></answer></faq> - - - <faq id="3.6"><question>Is there a way to get log4j to automatically reload a - configuration file if it changes?</question><answer> - - <p>Yes. Both the DOMConfigurator and the PropertyConfigurator support - automatic reloading through the <code>configureAndWatch</code> method. - See the API documentation for more details. - </p> - - - <p>Because the <code>configureAndWatch</code> launches a - separate wathdog thread, and because there is no way to stop - this thread in log4j 1.2, the <code>configureAndWatch</code> - method is unsafe for use in J2EE envrironments where - applications are recycled. - </p></answer></faq> - - - <faq id="4.1"><question>Why should I donate my extensions to log4j back to the - project?</question><answer> - <p>Contrary to the GNU Public License (GPL) the Apache - Software License does not make any claims over your - extensions. By extensions, we mean totally new code that - invokes existing log4j classes. <em>You are free to do - whatever you wish with your proprietary log4j extensions.</em> - In particular, you may choose to never release your extensions - to the wider public. - </p> - - <p>We are very careful not to change the log4j client API so - that newer log4j releases are backward compatible with - previous versions. We are a lot less scrupulous with the - internal log4j API. Thus, if your extension is designed to - work with log4j version <code>n</code>, then when log4j - release version <code>n+1</code> comes out, you will probably - need to adapt your proprietary extensions to the new release. - </p> - - <p>Thus, you will be forced to spend precious resources in - order to keep up with log4j changes. This is commonly referred - to as the "stupid-tax." By donating the code and making it - part of the standard distribution, you save yourself the - unnecessary maintenance work. - </p> - - <p>If your extensions are useful then someone will eventually - write an extension providing the same or very similar - functionality. Your development effort will be wasted. Unless - the proprietary log4j extension is business critical, there is - little reason for not donating your extensions back to the - project. - </p></answer></faq> - - <faq id="4.2"><question>What should I keep in mind when contributing code?</question> - <answer> - <ol> - - <li> - <p>Write a test case for your contribution.</p> - - <p>There is nothing more irritating than finding the bugs - in debugging (i.e. logging) code. Writing a test case - takes some effort but is crucial for a widely used library - such as log4j. Writing a test case will go a long way in - earning you the respect of fellow developers. See the - tests/ directory for exiting test cases. - </p> - </li> - - - <li> - <p>Stick to the existing indentation style even if you hate it.</p> - - <p>Alternating between indentation styles makes it hard to - understand the source code. Make it a little harder on - yourself but easier on others. - </p> - - <p>Log4j has adopted a rather conservative approach by - following the <a href="http://java.sun.com/docs/codeconv/">Code Conventions - for the JavaTM Programming Language</a>. <b>We use 2 (two) - spaces for indentation and no tabs.</b> - </p> - </li> - - <li> - <p>Please do not both modify the code and change the - indentation in a single commit.</p> - - <p>If you change the code and reformat it at the same time - and then commit, the commit notification message will be - hard to read. It will contain many diffs associated with - the reformatting in addition to logical changes. - </p> - - <p>If you must reformat and change the code, then perform - each step separately. For example, reformat the code and - commit. Following that, you can change the logic and - commit. The two steps can be performed in the reverse - order just as well. You can first change the logic and - commit and only later reformat and commit. - </p> - - </li> - <li> - <p>Make every effort to stick to the JDK 1.1 API.</p> - - <p>One of the important advantages of log4j is its - compatibility with JDK 1.1.x. - </p> - </li> - - <li> - <p>Always keep it simple, small and fast when - possible.</p> - - <p>It's all about the application not about logging.</p> - </li> - - <li> - <p>Identify yourself as a contributor at the top of the - relevant file. - </p> - </li> - <li> - <p>Take responsibility for your code.</p> - - <p>Authoring software is very much like running a marathon. It - takes time and endurance. - </p> - </li> - <li> - <p>Did we mention sticking with the indentation style? </p> - </li> - <li><p>Did we mention writing test cases? </p> - </li> - - </ol> - </answer></faq> - - - <faq id="duplicate-messages"> - <question>Why am I getting multiple copies of messages in my log file?</question> - <answer> - <p>There are several reasons this can occur: - <ul> - <li>Repeated configuration of log4j: By default, each call to - PropertyConfigurator.configure or DOMConfigurator.configure is - culmulative. If your configuration file defines a file appender, - calling PropertyConfigurator.configure three times will create - three distinct instances and connect each of them to the specified logger.</li> - <li>Attaching the same appender to multiple loggers: if an appender is - attached to the root logger and child logger, then any message - sent to the child logger will go to the appender twice (unless - additivity is set to false).</li> - </ul></p> - </answer> - </faq> - <faq id="custom-level"> - <question>How do I add a custom level?</question> - <answer> - <p>It is possible, but rarely appropriate. The - request is commonly for a level named something like "audit" - that doesn't obviously fit in the progression "trace", "debug", - "info", "warn", "error" and "fatal". In that case, the request - for a level is really a request for a mechanism to specify - a different audience. The appropriate mechanism is to use a distinct - logger name (or tree) for "audit" related messages.</p> - </answer> + <faq id="hello"> + <question>A Question?</question> + <answer>An Answer.</answer> </faq> </part> </faqs> diff --git a/src/site/site.xml b/src/site/site.xml index aba7b8d..bb61d92 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -16,6 +16,15 @@ --> <project name="cpptasks: Compile tasks for Apache Ant"> + <bannerLeft> + <name>ant-contrib</name> + <href>http://ant-contrib.sourceforge.net/</href> + </bannerLeft> + <bannerRight> + <name>SourceForge.net Logo</name> + <src>http://sflogo.sourceforge.net/sflogo.php?group_id=36177&type=5</src> + <href>http://www.sourceforge.net/</href> + </bannerRight> <body> <breadcrumbs> <item name="ant-contrib" href="http://ant-contrib.sourceforge.net/"/> @@ -31,19 +40,30 @@ <menu name="About cpptasks"> <item name="Usage" href="/index.html"/> <item name="FAQ" href="/faq.html"/> - <item name="Roadmap" href="/roadmap.html"/> + </menu> + + <menu name="Elements"> + <item name="cc" href="/antdocs/CCTask.html"/> + <item name="compiler" href="/antdocs/CompilerDef.html"/> + <item name="defineset" href="/antdocs/DefineSet.html"/> + <item name="distributer" href="/antdocs/DistributerDef.html"/> + <item name="libraryset" href="/antdocs/LibrarySet.html"/> + <item name="linker" href="/antdocs/LinkerDef.html"/> + <item name="syslibraryset" href="/antdocs/SystemLibrarySet.html"/> + <item name="targetplatform" href="/antdocs/TargetDef.html"/> + <item name="versioninfo" href="/antdocs/VersionInfo.html"/> </menu> <menu name="Community"> <item name="Mailing Lists" href="/mail-lists.html"/> <item name="Issue Tracking" href="/issue-tracking.html"/> + <item name="Project Page" href="http://sourceforge.net/projects/ant-contrib/"/> + <item name="News" href="http://sourceforge.net/news/?group_id=36177"/> </menu> <menu name="Development"> <item name="Repository" href="/source-repository.html"/> <item name="JavaDoc" href="/apidocs/index.html"/> - <item name="Cross Reference" href="/jxr.html"/> - <item name="Dependencies" href="/dependencies.html"/> <item name="Continuous Integration" href="/integration.html"/> </menu> </body> diff --git a/src/taskdocs/java/net/sf/antcontrib/taskdocs/TaskDoclet.java b/src/taskdocs/java/net/sf/antcontrib/taskdocs/TaskDoclet.java new file mode 100644 index 0000000..e3a6c3f --- /dev/null +++ b/src/taskdocs/java/net/sf/antcontrib/taskdocs/TaskDoclet.java @@ -0,0 +1 @@ +/*
Licensed to the Ant-Contrib Project under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
package net.sf.antcontrib.taskdocs;
import com.sun.javadoc.*;
import org.xml.sax.*;
import org.xml.sax.helpers.AttributesImpl;
import org.xml.sax.helpers.DefaultHandler;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.transform.Source;
import javax.xml.transform.sax.SAXTransformerFactory;
import javax.xml.transform.sax.TransformerHandler;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;
import java.io.File;
import java.io.StringReader;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Locale;
import java.util.Map;
/**
* This document writes an XML representation of the
* Ant related Javadoc through an XSLT transform that creates xdoc files.
*
*/
public final class TaskDoclet {
/**
* Process Javadoc content.
* @param root root of javadoc content.
* @return true if successful
* @throws Exception IO exceptions and the like.
*/
public static boolean start(RootDoc root) throws Exception {
SAXTransformerFactory tf = (SAXTransformerFactory) SAXTransformerFactory.newInstance();
Source typeStyle = new StreamSource(new File("src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt"));
//
// replace with tf.newTransformerHandler() if you want to see raw generated XML.
TransformerHandler typeHandler = tf.newTransformerHandler(typeStyle);
Map referencedTypes = new HashMap();
Map documentedTypes = new HashMap();
ClassDoc[] classes = root.classes();
for (int i = 0; i < classes.length; ++i) {
ClassDoc clazz = classes[i];
if (clazz.isPublic() && !clazz.isAbstract()) {
if (isTask(clazz) || isType(clazz)) {
writeClass(typeHandler, clazz, referencedTypes);
documentedTypes.put(clazz.qualifiedTypeName(), clazz);
}
}
}
Map additionalTypes = new HashMap();
for (Iterator iter = referencedTypes.keySet().iterator(); iter.hasNext();) {
String referencedName = (String) iter.next();
if (documentedTypes.get(referencedName) == null) {
ClassDoc referencedClass = root.classNamed(referencedName);
if (referencedClass != null) {
if (!referencedClass.qualifiedTypeName().startsWith("org.apache.tools.ant")) {
writeClass(typeHandler, referencedClass, additionalTypes);
documentedTypes.put(referencedClass.qualifiedTypeName(), referencedClass);
}
}
}
}
return true;
}
/**
* Determine if class is an Ant task.
* @param clazz class to test.
* @return true if class is an Ant task.
*/
private static boolean isTask(final ClassDoc clazz) {
if (clazz == null) return false;
if ("org.apache.tools.ant.Task".equals(clazz.qualifiedTypeName())) {
System.out.print("true");
return true;
}
return isTask(clazz.superclass());
}
/**
* Determine if class is an Ant type.
* @param clazz class to test.
* @return true if class is an Ant type.
*/
private static boolean isType(final ClassDoc clazz) {
if (clazz == null) return false;
if ("org.apache.tools.ant.types.DataType".equals(clazz.qualifiedTypeName())) {
return true;
}
return isType(clazz.superclass());
}
/**
* Namespace URI for class description elements.
*/
private static final String NS_URI = "http://ant-contrib.sf.net/taskdocs";
/**
* Namespace URI for XHTML elements.
*/
private static final String XHTML_URI = "http://www.w3.org/1999/xhtml";
/**
* Write a Java type.
* @param tf content handler.
* @param type documented type.
* @throws Exception if IO or other exception.
*/
private static void writeType(final TransformerHandler tf, final Type type) throws Exception {
AttributesImpl attributes = new AttributesImpl();
attributes.addAttribute(null, "name", "name", "CDATA", type.simpleTypeName());
attributes.addAttribute(null, "qualifiedTypeName", "qualifiedTypeName", "CDATA", type.qualifiedTypeName());
tf.startElement(NS_URI, "type", "type", attributes);
ClassDoc typeDoc = type.asClassDoc();
if (typeDoc != null && typeDoc.commentText() != null && typeDoc.commentText().length() > 0) {
writeDescription(tf, typeDoc.commentText());
} else {
tf.characters(type.typeName().toCharArray(), 0, type.typeName().length());
}
tf.endElement(NS_URI, "type", "type");
}
/**
* Write an Ant task or type attribute (aka property).
* @param tf content handler.
* @param method set method for property.
* @throws Exception if IO or other exception.
*/
private static void writeAttribute(final TransformerHandler tf, final MethodDoc method) throws Exception {
AttributesImpl attributes = new AttributesImpl();
attributes.addAttribute(null, "name", "name", "CDATA", method.name().substring(3).toLowerCase(Locale.US));
tf.startElement(NS_URI, "attribute", "attribute", attributes);
writeType(tf, method.parameters()[0].type());
attributes.clear();
tf.startElement(NS_URI, "comment", "comment", attributes);
writeDescription(tf, method.commentText());
tf.endElement(NS_URI, "comment", "comment");
tf.endElement(NS_URI, "attribute", "attribute");
}
/**
* Write an Ant nested element.
* @param tf content handler.
* @param method method to add element to task or type.
* @param name name of nested element.
* @param type type of nested element.
* @param referencedTypes map of types referenced in documentation.
* @throws Exception if IO or other exception.
*/
private static void writeChild(final TransformerHandler tf,
final MethodDoc method,
final String name,
final Type type,
final Map referencedTypes) throws Exception {
AttributesImpl attributes = new AttributesImpl();
attributes.addAttribute(null, "name", "name", "CDATA", name.toLowerCase(Locale.US));
tf.startElement(NS_URI, "child", "child", attributes);
attributes.clear();
tf.startElement(NS_URI, "comment", "comment", attributes);
writeDescription(tf, method.commentText());
tf.endElement(NS_URI, "comment", "comment");
writeType(tf, type);
tf.endElement(NS_URI, "child", "child");
referencedTypes.put(type.qualifiedTypeName(), type);
}
/**
* Redirects parsed XHTML comment into output stream.
* Drops start and end document and body element.
*/
private static class RedirectHandler extends DefaultHandler {
/**
* output handler.
*/
private final ContentHandler tf;
/**
* Create new instance.
* @param tf output handler, may not be null.
*/
public RedirectHandler(final TransformerHandler tf) {
if (tf == null) { throw new IllegalArgumentException("tf"); }
this.tf = tf;
}
/** {@inheritDoc} */
public void characters(final char[] ch, final int start, final int length) throws SAXException {
tf.characters(ch, start, length);
}
/** {@inheritDoc} */
public void endDocument() {
}
/** {@inheritDoc} */
public void endElement(final String namespaceURI,
final String localName,
final String qName) throws SAXException {
if (!"body".equals(localName)) {
tf.endElement(namespaceURI, localName, qName);
}
}
/** {@inheritDoc} */
public void endPrefixMapping(final String prefix) throws SAXException {
tf.endPrefixMapping(prefix);
}
/** {@inheritDoc} */
public void ignorableWhitespace(char[] ch, int start, int length) throws SAXException {
tf.ignorableWhitespace(ch, start, length);
}
/** {@inheritDoc} */
public void processingInstruction(final String target, final String data) throws SAXException {
tf.processingInstruction(target, data);
}
/** {@inheritDoc} */
public void setDocumentLocator(final Locator locator) {
tf.setDocumentLocator(locator);
}
/** {@inheritDoc} */
public void skippedEntity(String name) throws SAXException {
tf.skippedEntity(name);
}
/** {@inheritDoc} */
public void startDocument() {
}
/** {@inheritDoc} */
public void startElement(final String namespaceURI,
final String localName,
final String qName,
final Attributes atts) throws SAXException {
if (!"body".equals(localName)) {
tf.startElement(namespaceURI, localName, qName, atts);
}
}
/** {@inheritDoc} */
public void startPrefixMapping(String prefix, String uri) throws SAXException {
tf.startPrefixMapping(prefix, uri);
}
}
/**
* Writes description.
* @param tf destination.
* @param description description, may contain XHTML elements.
* @throws SAXException if IO or other exception.
*/
private static void writeDescription(final TransformerHandler tf,
final String description) throws SAXException {
if (description.indexOf('<') == -1) {
tf.characters(description.toCharArray(), 0, description.length());
} else {
//
// attempt to fabricate an XHTML fragment
//
StringBuffer buf = new StringBuffer(description);
buf.insert(0, "<body xmlns='" + XHTML_URI + "'>");
buf.append("</body>");
try {
SAXParserFactory sf = SAXParserFactory.newInstance();
sf.setNamespaceAware(true);
SAXParser parser = sf.newSAXParser();
parser.parse(new InputSource(new StringReader(buf.toString())), new RedirectHandler(tf));
} catch (Exception ex) {
tf.characters(ex.toString().toCharArray(), 0, ex.toString().length());
}
}
}
/**
* Write all Ant attributes in this class and superclasses.
* @param tf destination.
* @param clazz class documentation.
* @param processed map of processed methods.
* @param referencedTypes map of referenced types.
* @throws Exception if IO or other exception.
*/
private static void writeAttributes(final TransformerHandler tf,
final ClassDoc clazz,
final Map processed,
final Map referencedTypes) throws Exception {
MethodDoc[] methods = clazz.methods();
for (int i = 0; i < methods.length; i++) {
MethodDoc method = methods[i];
if (processed.get(method.name()) == null) {
if (method.name().startsWith("set") && method.isPublic() && method.parameters().length == 1) {
writeAttribute(tf, method);
referencedTypes.put(method.parameters()[0].typeName(), method.parameters()[0].type());
}
processed.put(method.name(), method);
}
}
if (clazz.superclass() != null) {
writeAttributes(tf, clazz.superclass(), processed, referencedTypes);
}
}
/**
* Write all Ant nested elements in this class and superclasses.
* @param tf destination.
* @param clazz class documentation.
* @param processed map of processed methods.
* @param referencedTypes map of referenced types.
* @throws Exception if IO or other exception.
*/
private static final void writeChildren(final TransformerHandler tf,
final ClassDoc clazz,
final Map processed,
final Map referencedTypes) throws Exception {
MethodDoc[] methods = clazz.methods();
for (int i = 0; i < methods.length; i++) {
MethodDoc method = methods[i];
if (processed.get(method.name()) == null) {
if (method.name().startsWith("addConfigured") && method.isPublic() && method.parameters().length == 1) {
writeChild(tf, method, method.name().substring(13), method.parameters()[0].type(), referencedTypes);
}
if (method.name().startsWith("add") && method.isPublic() && method.parameters().length == 1) {
writeChild(tf, method, method.name().substring(3), method.parameters()[0].type(), referencedTypes);
}
if (method.isPublic() && method.parameters().length == 0 && method.name().startsWith("create")) {
writeChild(tf, method, method.name().substring(6), method.returnType(), referencedTypes);
}
processed.put(method.name(), method);
}
}
if (clazz.superclass() != null) {
writeChildren(tf, clazz.superclass(), processed, referencedTypes);
}
}
/**
* Write Ant documentation for this class.
* @param tf destination.
* @param clazz class documentation.
* @param referencedTypes map of referenced types.
* @throws Exception if IO or other exception.
*/
private static void writeClass(final TransformerHandler tf,
final ClassDoc clazz,
final Map referencedTypes) throws Exception {
StreamResult result = new StreamResult(new File("src/site/xdoc/antdocs/" + clazz.name() + ".xml"));
tf.setResult(result);
AttributesImpl attributes = new AttributesImpl();
attributes.addAttribute(null, "name", "name", "CDATA", clazz.name());
StringBuffer firstSentence = new StringBuffer();
Tag[] tags = clazz.firstSentenceTags();
for (int i = 0; i < tags.length; i++) {
firstSentence.append(tags[i].text());
}
if (firstSentence.length() > 0) {
attributes.addAttribute(null, "firstSentence", "firstSentence", "CDATA", firstSentence.toString());
}
tf.startDocument();
tf.startElement(NS_URI, "class", "class", attributes);
attributes.clear();
tf.startElement(NS_URI, "comment", "comment", attributes);
writeDescription(tf, clazz.commentText());
tf.endElement(NS_URI, "comment", "comment");
tf.startElement(NS_URI, "attributes", "attributes", attributes);
Map methods = new HashMap();
methods.put("setProject", "setProject");
methods.put("setRuntimeConfigurableWrapper", "setRuntimeConfigurableWrapper");
writeAttributes(tf, clazz, methods, referencedTypes);
tf.endElement(NS_URI, "attributes", "attributes");
tf.startElement(NS_URI, "children", "children", attributes);
Map children = new HashMap();
writeChildren(tf, clazz, children, referencedTypes);
tf.endElement(NS_URI, "children", "children");
tf.endElement(NS_URI, "class", "class");
tf.endDocument();
}
}
\ No newline at end of file diff --git a/src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt b/src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt new file mode 100644 index 0000000..b489247 --- /dev/null +++ b/src/taskdocs/resources/net/sf/antcontrib/taskdocs/element.xslt @@ -0,0 +1,210 @@ +<!-- + Licensed to the Ant-Contrib Project under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +--> +<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:taskdocs="http://ant-contrib.sf.net/taskdocs" + xmlns:xhtml="http://www.w3.org/1999/xhtml" + xsl:version="1.0"> + + <xsl:output method="xml" indent="yes"/> + + <xsl:apply-templates select="/"/> + + <xsl:template match="/"> + + <xsl:comment> + +Licensed to the Ant-Contrib Project under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The Ant-Contrib Project licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + </xsl:comment> + <document> + <xsl:apply-templates/> + </document> +</xsl:template> + + <xsl:template match="xhtml:*"> + <xsl:element name="{local-name()}"> + <xsl:apply-templates/> + </xsl:element> + </xsl:template> + + <xsl:template match="text()"> + <xsl:value-of select="."/> + </xsl:template> + + <xsl:template name="pretty-name"> + <xsl:param name="name"/> + <xsl:choose> + <xsl:when test="contains($name, 'SystemLibrarySet')">syslibset</xsl:when> + <xsl:when test="contains($name, 'LibrarySet')">libset</xsl:when> + <xsl:when test="contains($name, 'TargetDef')">targetplatform</xsl:when> + <xsl:when test="string-length(substring-before($name, 'Task'))"> + <xsl:call-template name="pretty-name"> + <xsl:with-param name="name"> + <xsl:value-of select="substring-before($name, 'Task')"/> + </xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="string-length(substring-before($name, 'Def'))"> + <xsl:call-template name="pretty-name"> + <xsl:with-param name="name"> + <xsl:value-of select="substring-before($name, 'Def')"/> + </xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:when test="string-length(substring-before($name, 'Argument'))"> + <xsl:call-template name="pretty-name"> + <xsl:with-param name="name"> + <xsl:value-of select="substring-before($name, 'ument')"/> + </xsl:with-param> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="translate($name, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template match="taskdocs:class"> + <properties> + <title> + <xsl:call-template name='pretty-name'> + <xsl:with-param name="name"> + <xsl:value-of select="@name"/> + </xsl:with-param> + </xsl:call-template> + </title> + </properties> + <body> + + <section> + <xsl:attribute name="name"> + <xsl:call-template name='pretty-name'> + <xsl:with-param name="name"> + <xsl:value-of select="@name"/> + </xsl:with-param> + </xsl:call-template> + </xsl:attribute> + <subsection name="Description"> + <xsl:apply-templates select="taskdocs:comment"/> + </subsection> + <xsl:if test="taskdocs:attributes/taskdocs:attribute"> + <subsection name="parameters"> + <table> + <tr> + <td><b>Attribute</b></td> + <td><b>Description</b></td> + <td><b>Type</b></td> + </tr> + <xsl:apply-templates select="taskdocs:attributes/taskdocs:attribute"> + <xsl:sort select="@name"/> + </xsl:apply-templates> + </table> + </subsection> + </xsl:if> + <xsl:if test="taskdocs:children/taskdocs:child"> + <subsection name="parameters as nested elements"> + <dl> + <xsl:apply-templates select="taskdocs:children/taskdocs:child"> + <xsl:sort select="@name"/> + </xsl:apply-templates> + </dl> + + </subsection> + </xsl:if> + </section> + </body> + + </xsl:template> + + <xsl:template match="taskdocs:attribute"> + <tr> + <td> + <xsl:value-of select="@name"/> + </td> + <td> + <xsl:apply-templates select="taskdocs:comment"/> + </td> + <td> + <xsl:for-each select="taskdocs:type"> + <xsl:call-template name="attribute-type"/> + </xsl:for-each> + </td> + </tr> + + </xsl:template> + + <xsl:template name="attribute-type"> + <xsl:choose> + <xsl:when test="starts-with(@qualifiedTypeName, 'net.sf.antcontrib.cpptasks.')"> + <a href="../apidocs/{translate(@qualifiedTypeName, '.', '/')}.html"> + <xsl:value-of select="@name"/> + </a> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="@name"/> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <xsl:template name="child-type"> + <xsl:param name="anchor"><xsl:value-of select="@name"/></xsl:param> + <xsl:element name="a"> + <xsl:attribute name="href"> + <xsl:choose> + <xsl:when test="starts-with(@qualifiedTypeName, 'net.sf.antcontrib.cpptasks')"><xsl:value-of select="@name"/>.html</xsl:when> + <xsl:when test="starts-with(@qualifiedTypeName, 'org.apache.tools.ant.types.PatternSet')">http://ant.apache.org/manual/CoreTypes/patternset.html</xsl:when> + <xsl:when test="starts-with(@qualifiedTypeName, 'org.apache.tools.ant.types.Path')">http://ant.apache.org/manual/using.html#path</xsl:when> + <xsl:when test="starts-with(@qualifiedTypeName, 'org.apache.tools.ant.types.Commandline')">http://ant.apache.org/manual/CoreTasks/exec.html</xsl:when> + <xsl:otherwise>about:blank</xsl:otherwise> + </xsl:choose> + </xsl:attribute> + <xsl:value-of select="$anchor"/> + </xsl:element> + </xsl:template> + + <xsl:template match="taskdocs:child"> + <dt> + <xsl:variable name="anchor"> + <xsl:value-of select="@name"/> + </xsl:variable> + <xsl:for-each select="taskdocs:type"> + <xsl:call-template name="child-type"> + <xsl:with-param name="anchor"> + <xsl:value-of select="$anchor"/> + </xsl:with-param> + </xsl:call-template> + </xsl:for-each> + </dt> + <dd><xsl:value-of select="taskdocs:comment"/></dd> + </xsl:template> + + +</xsl:transform> |