Bug 40172: Make log4j 1.2 and 1.3 documentation consistent
git-svn-id: https://svn.apache.org/repos/asf/logging/log4j/branches/v1_2-branch@443258 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/build.xml b/build.xml
index c2dd5e5..8d79337 100644
--- a/build.xml
+++ b/build.xml
@@ -73,6 +73,12 @@
<property name="javac.source" value="1.1"/>
<property name="javac.target" value="1.1"/>
+
+ <!-- destination for generated documentation on Apache web host -->
+ <property name="apache.javadoc_dest" value="/www/logging.apache.org/log4j/docs"/>
+ <!-- Apache web host -->
+ <property name="apache.host" value="people.apache.org"/>
+
<!-- Construct compile classpath -->
@@ -574,6 +580,35 @@
</target>
+<target name="deploy-site" depends="javadoc" description="Deploy log4j documentation">
+ <fail unless="apache.user">-Dapache.user=USERNAME must be specified.</fail>
+ <tar destfile="${packaging.dir}/apache-log4j12-site.tar.gz" compression="gzip">
+ <tarfileset dir="${javadoc.dest}" prefix="api-${version}"/>
+ </tar>
+ <exec executable="scp" dir="${packaging.dir}">
+ <arg value="apache-log4j12-site.tar.gz"/>
+ <arg value="${apache.user}@${apache.host}:"/>
+ </exec>
+ <exec executable="ssh">
+ <arg value="-l"/>
+ <arg value="${apache.user}"/>
+ <arg value="${apache.host}"/>
+ <arg value="tar"/>
+ <arg value="--directory=${apache.javadoc_dest}"/>
+ <arg value="-xvzf"/>
+ <arg value="apache-log4j12-site.tar.gz"/>
+ </exec>
+ <exec executable="ssh">
+ <arg value="-l"/>
+ <arg value="${apache.user}"/>
+ <arg value="${apache.host}"/>
+ <arg value="chmod"/>
+ <arg value="-R"/>
+ <arg value="g+w"/>
+ <arg value="${apache.javadoc_dest}"/>
+ </exec>
+</target>
+
<!-- ================================================================= -->
<!-- Build a complete distribution. Results go to ${dist.images} -->
<!-- ================================================================= -->
diff --git a/src/xdocs/contributors.xml b/src/xdocs/contributors.xml
index 0d9f333..b28c204 100644
--- a/src/xdocs/contributors.xml
+++ b/src/xdocs/contributors.xml
@@ -19,6 +19,14 @@
<!-- ======================================== -->
<!-- LISTED IN ALPHABETICAL ORDER (last name) -->
<!-- ======================================== -->
+
+ <li><b>Curt Arnold</b>
+
+ <p>Curt is an independent software developer and current Logging Services PMC chair.
+ Curt developed the test framework for the W3C DOM test suites and has contributed to the
+ Apache Ant, Apache Xerces, Apache Batik, JSUnit, ArgoUML and ant-contrib
+ projects.</p>
+ </li>
<li><b>Mathias Bogaert</b>
diff --git a/src/xdocs/documentation.xml b/src/xdocs/documentation.xml
index 01988e2..2209a1c 100644
--- a/src/xdocs/documentation.xml
+++ b/src/xdocs/documentation.xml
@@ -3,62 +3,44 @@
<properties>
<author email="not@disclosed">Ceki Gülcü</author>
- <author email="yoavs@apache.org">Yoav Shapira</author>
+ <author email="not@disclosed">Yoav Shapira</author>
<title>Documentation</title>
</properties>
<body>
- <section name="Official log4j documentation">
+ <section name="log4j documentation">
- <p>With the exception of the complete manual, the following
- documentation is included with the standard log4j distribution
- and also browsable online:
- </p>
-
- <ul>
- <p>
<a
href="http://www.qos.ch/shop/products/eclm/"><img
- align="right" src="images/coverSmall.png"></img></a> <li><a
- href="manual.html"><b>short manual</b></a>,
+ align="right" src="images/coverSmall.png"></img></a>
+ <ul>
+ <p>
+ <li><a href="manual.html"><b>Short introduction to log4j</b></a>
</li>
</p>
<p>
- <li><a href="http://www.qos.ch/shop/products/eclm/"><b>complete manual</b></a> (commercial),
+ <li><a href="http://www.qos.ch/shop/products/eclm/"><b>log4j: The complete manual</b></a> (commercial)
+ </li>
+ </p>
+
+ <p>
+ <li>
+ <b>javadoc: <a href="api/index.html">1.2.14</a>, <a href="http://logging.apache.org/log4j/docs/api-1.3/index.html">1.3 (alpha)</a></b>
</li>
</p>
<p>
<li>
- <a href="api/index.html"><b>javadoc documentation</b></a>,
+ <a href="http://wiki.apache.org/logging-log4j/Log4JProjectPages"><b>Wiki</b></a>
</li>
</p>
-
- <p>
- <li>
- <a href="HISTORY"><b>project history</b></a>,
- </li>
- </p>
-
-
- <p>
- <li>
- <a href="FAQ.html"><b>FAQ</b></a>,
- </li>
- </p>
-
- <p>
- <li>
- <a href="TROUBLESHOOT.html"><b>troubleshooting guide</b></a>.
- </li>
- </p>
</ul>
</section>
- <section name="Translations to other languages">
+ <section name="Translations">
<ul>
<li><a
href="http://www.vimeworks.com/~mauricio/manualLog4J.html">Spanish
@@ -158,17 +140,10 @@
<ul>
- <p><li> <a href="http://www.jug-l.org/log4j.html">Advanced
- Log4j</a> Louisville JUG presentation by Jonathan Cowherd </li></p>
-
<p><li><a href="http://www.johnmunsch.com/projects/Presentations/">Log4J
In 30 Minutes Or Less</a> by John Munsch</li></p>
- <p><li><a href="https://www.qos.ch/ac2001/F11-10.html">Log4j, a logging package for the Java language</a> by Ceki Gülcü</li></p>
-
- <p><li><a
- href="http://www.ejug.org/OpenSource%20Log4j2_files/frame.htm">Log4j presentation by the</a>
- Edmonton Java Users Group</li></p>
+ <p><li><a href="http://www.qos.ch/ac2001/F11-10.html">Log4j, a logging package for the Java language</a> by Ceki Gülcü</li></p>
<p><li><a href="http://www.ociweb.com/javasig/knowledgebase/January2001/Log4J.ppt">Log4j</a> by Brent Twenter
</li></p>
diff --git a/src/xdocs/download.xml b/src/xdocs/download.xml
index eb5678d..fd702fa 100644
--- a/src/xdocs/download.xml
+++ b/src/xdocs/download.xml
@@ -147,17 +147,17 @@
<!-- ============================================================================== -->
- <dt><a href="http://cvs.apache.org/viewcvs/jakarta-log4j/log4jMini/"><b>log4j<em>ME</em></b></a></dt>
+ <dt><a href="http://svn.apache.org/viewcvs.cgi/logging/sandbox/log4j/log4jMini/trunk/"><b>log4j<em>ME</em></b></a></dt>
<dd>Log4j<em>ME</em>, or log4j MiniEdition, is based on the
same code as log4j. However, as the name indicates the
mini-edition is much smaller. It offers the same client
- interface such that code compiled for log4jME is 100%
+ interface such that code compiled for log4jME is
compatible with log4j standard edition. You can choose to
upgrade to log4j standard edition at any time by replacing
<em>log4jME.jar</em> with <em>log4j.jar</em> in your
classpath. At this time, log4jME is only available through
- CVS.
+ ASF Subversion repository in the Logging Services Sandbox.
</dd>
<!-- ============================================================================== -->
diff --git a/src/xdocs/index.xml b/src/xdocs/index.xml
index 2915668..c6555d4 100644
--- a/src/xdocs/index.xml
+++ b/src/xdocs/index.xml
@@ -10,6 +10,7 @@
<body>
+
<section name="Introduction">
<p>Inserting log statements into your code is a low-tech method
@@ -50,8 +51,7 @@
<p>The target of the log output can be a file, an
<code>OutputStream</code>, a <code>java.io.Writer</code>, a
- remote log4j server, a remote Unix Syslog daemon, or even a NT
- Event logger among many other output targets.</p>
+ remote log4j server, a remote Unix Syslog daemon, or many other output targets.</p>
<p>On an AMD Duron clocked at 800Mhz running JDK 1.3.1, it costs
about 5 nanoseconds to determine if a logging statement should
diff --git a/src/xdocs/plan.xml b/src/xdocs/plan.xml
index 3c35ab6..1c10af3 100644
--- a/src/xdocs/plan.xml
+++ b/src/xdocs/plan.xml
@@ -4,6 +4,7 @@
<properties>
<author email="not@disclosed">Ceki Gülcü</author>
<author email="not@disclosed">Mark Womack</author>
+ <author email="not@disclosed">Curt Arnold</author>
<title>Release roadmap for log4j</title>
</properties>
@@ -11,8 +12,7 @@
<section name="The Roadmap">
- <p>The log4j committers have adopted a roadmap for future releases
- of log4j. This page documents that roadmap and gives you an idea of what
+ <p>This page documents that roadmap and gives you an idea of what
to expect from future versions and timeframes for release.
</p>
@@ -29,274 +29,38 @@
</section>
- <section name="Release 1.2.12">
- <p>Expected timeframe: End of July, 2005</p>
+ <section name="Release 1.2.15">
+ <p>Expected timeframe: As needed</p>
- <p>Version 1.2.12 is planned primarily as a bug fix release. It will be
- addressing major bugs where the fixes do not require api changes. If you
- have a bug or problem that you feel should be addressed, please make sure
- that is reported in the log4j bug database and highlight it as a candidate
- for the 1.2.12 release.
- </p>
-
- <p>The log4j committers did decide to include one change in the 1.2 api
- for the 1.2.12 release: adding the TRACE level as a level choice with
- supporting methods to log messages for that level and check if the level
- is enabled. The change is minor and should not cause problems with
- existing deployments that use version 1.2.12 throughout. However, the
- committers reserve the right to not include it if it appears to break too
- much.
- </p>
-
- <p>It is expected that version 1.2.12 will be the last release for the
- 1.2 branch, the next major release being version 1.3. However, if a
- critical bug fix is needed, another version will be released.
- </p>
+ <p>log4j 1.2.14 was released in September 2006. log4j 1.2 is continuing to be maintained
+ in response to reported, but no active development is anticipated in the near future. Backporting
+ the org.apache.log4j.rolling package from log4j 1.3 might be desirable since usage problems
+ with the original org.apache.log4j.RollingFileAppender and org.apache.log4j.DailyRollingFileAppender
+ are commonly reported.</p>
</section>
<section name="Release 1.3">
- <p>Expected timeframe: October, 2005</p>
+ <p>Expected timeframe: indeterminate</p>
+
+ <p>Compatibility with earlier releases (as implied by a minor verion number change) was not enforced during the
+ development process and much of the recent effort has been to restore compatibility. However, it does not
+ seem likely that log4j 1.3 will ever been sufficiently compatible with log4j 1.2
+ to recommend it as a general replacement for log4j 1.2. Additional alpha releases are expected,
+ however it is possible that the development focus may shift to log4j 2.0.</p>
+
+ </section>
+
+ <section name="Release 2.0">
+ <p>Expected timeframe: indeterminate</p>
- <p>The work for version 1.3 has been ongoing for a long time now, and it
- is time to button it up and let others take it for a ride. Reviewing,
- stablizing, and testing the 1.3 code for release is the major goal for
- the log4j committers for this year.
- </p>
-
- <p>Version 1.3 is going to contain some very extensive changes and new
- features. You should expect a number of api changes. Early release
- alpha versions have been available for a while, and the releases will be
- accelerating as the committers review and cleanup the current code base
- for release. As part of those releases, the committers plan to include
- jDiff reports that will clearly outline the changes and additions to the
- log4j code since the most recent 1.2.X release. This should help you in
- seeing what might need to be reviewed or fixed in your own code related
- to log4j.
- </p>
-
- <p>Below is a table from previous documentation about the 1.3 work plan
- and it is somewhat out of date. The committers will be updating this page
- with more and better documentation about what has changed, what has been
- reviewed, and what tasks remain as we work toward the 1.3 release.
- </p>
-
- <table class="ls" cellpadding="3" cellspacing="2">
-
- <tr>
- <th>Label</th>
- <th>Comment</th>
- <th>Volunteer</th>
- <th>Status</th>
- </tr>
-
- <tr bgcolor="DDDDDD">
- <td><b>test cases</b></td>
-
- <td>
- <p>Writing test cases is not the most sexy part of
- software development but it is one of the most
- important. Automated test cases allow us to catch bugs
- as early is possible. It is strongly recommended to add
- a new test case with each new feature or component.</p>
-
- <p>Existing <em>Perl</em> language based test cases have been
- migrated to junit (all-Java)based test
- cases. The new tests are placed under the
- <code>tests/</code> directory. It should be thus
- possible for participants in the project to understand
- the stucture of our tests and add tests for their
- components.
- </p>
- </td>
-
- <td>All committers</td>
- <td>ongoing effort</td>
- </tr>
-
- <tr>
- <td>Extensible XML configuration files</td>
-
- <td>
- <p>The DOMConfigurator is complex and not very
- flexible. It can only deal with elements that the
- developer knew about at compilation time. This has been
- an important drawback in the design of several appenders
- such as the the SMTPAppender and the
- RollingFileAppenders and its variants. These appenders
- need to delegate certain task to sub-components which
- are configured separately.
- </p>
-
- <p>The new JoranConfigurator being created by Ceki Gülcü will be based on
- a new 'module' know as Joran, which can convert XML files into other
- objects based on rules. You can read more abouth Joran <b><u>
- <a href="http://www.qos.ch/logging/JoranConfigurator.html">here</a>
- </u></b>
- </p>
- </td>
- <td>Ceki Gülcü</td>
- <td>Significantly progressed</td>
- </tr>
-
- <tr>
- <td>Log4j Domains</td>
-
- <td>
- <p>This is a very powerful and innovative concept that
- extends the notion of hierarchical loggers. It will also
- allow dynamic logging with pin-point accuracy. It was
- first suggested to me by Scott Stark of <a
- href="http://www.jboss.org">JBoss</a> fame.
- </p>
- </td>
- <td>Ceki Gülcü</td>
- <td>design board</td>
- </tr>
-
- <tr>
- <td>Multiple implementations of Logger</td>
-
- <td>
- <p>Based on <code>RepositorySelectors</code> introduced in
- log4j 1.2, the user will be able to replace the
- <code>Logger</code> implementation. Several
- implementations will be provided offering different
- properties and functionality although none of the
- implementations will add new public methods.
- </p>
- </td>
-
-
- <td>?</td>
- <td>vaporware</td>
- </tr>
- <tr>
- <td>Plugins/Receivers</td>
-
- <td>
- <p>A Plugin framework has been designed and implemented.</p>
- <p>All of the currently developed plugins are "Receivers", which can be
- thought of as the reverse of an appender; something
- that <b>accepts</b> LoggingEvents from some external source.
- </p>
- <p>This has proven particulaly useful with the log4j ports, with the
- addition of the XML-based Receivers able to accept
- LoggingEvents generated from other languages (see "Overture to other
- programming languages" below)
- </p>
-
- </td>
- <td>All</td>
- <td>Significantly progressed</td>
- </tr>
-
- <tr>
- <td>Improvements to Chainsaw</td>
-
- <td>
- <p><a href="http://logging.apache.org/log4j/docs/chainsaw.html">Chainsaw v2</a> development has now progressed
- to the point where the main developers of it
- and many other members of the logging community are using it daily. It's
- still pre-alpha but only
- because we keep thinking up things to add.
- </p>
-
- </td>
- <td>Scott Deboy and Paul Smith</td>
- <td>Significantly progressed </td>
- </tr>
-
- <tr>
- <td>Custom conversion characters in PatternLayout</td>
- <td>Users often want to add new conversions characters or
- override the existing ones. This should be made easy using
- new configuration directives. This feature would use the
- extensions to XML configuration language mentioned
- above.</td>
-
- <td>Ceki Gülcü</td>
- <td>Completed, still testing</td>
- </tr>
-
- <tr>
- <td>Overture to other programming languages</td>
-
- <td><p>It is higly desriable to allow log4j ports in other languages
- to access log4j services in a language independent way. </p>
-
- <p>The use of a standard XML format to represent a LoggingEvent has been
- established and many of the related logging projects from
- non-Java languages have begun to support it. In fact, a number of the
- log4j ports have volunteered to join Apache!</p>
-
- <p>Scott Deboy has completed work to create a fex XML-based Receiver
- classes that can accept logging events from an external source, and
- 'import' them into the local log4j environment. </p> </td>
-
- <td>Ceki Gülcü, Scott Deboy</td>
- <td>Significantly Progressed (if not completed)</td>
- </tr>
-
- <tr>
- <td>Strategy based rollovers</td>
-
- <td>
- <p>Contrary to our own DailyRollingFileAppender, Avalon's
- logkit has a nice and clean implementation for rolling
- files. See the
- <code>org.apache.log.output.io.rotate</code> package for
- exact details.
- </p>
-
- <p>Their implementation is based on strategies which are
- sub-components of appender. We will be able to configure
- such sub-components with the new XML configuration
- scripts.
- </p>
- </td>
- <td>Ceki Gülcü</td>
- <td>Significantly Progressed</td>
- </tr>
-
-
-
- <tr>
- <td>Redesign of configure and watch architecture in
- configurators</td>
-
- <td>This is a very useful feature and the current architecture is not
- very good.
-
- <p>Contributions have been received by Mark Womack and others.</p>
-
- <p>See
- <pre>
- http://www.mail-archive.com/log4j-dev@jakarta.apache.org/msg01390.html
- http://www.mail-archive.com/log4j-user@jakarta.apache.org/msg00666.html
- http://marc.theaimsgroup.com/?t=101010070500002&r=1&w=2
- </pre>
- </p>
- </td>
- <td>Mark Womack</td>
- <td>initial implementation</td>
- </tr>
-
- <tr>
- <td>Performance improvements to LoggingEvent serialization</td>
-
- <td>
- <p>Ole Dalgaard has shown that by implementing the
- java.io.Externalizable interface instead of
- java.io.Serializable in the LoggingEvent class, the
- speed of serialiazation is increased by a factor of 4 or
- more.
- </p>
-
- </td>
- <td>Ole Dalgaard?</td>
- <td>initial implementation</td>
- </tr>
- </table>
+ <p>log4j 2.0 is still conceptual but would be designed for Java 5 and later,
+ would use be designed for fine-grain concurrency to maximize performance on
+ multi-processor systems, would minimize exposure of implementation details and
+ adhere to current Java coding practices. The design of log4j 2.0 may attempt to
+ support javax.util.logging by allowing, for example, a log4j 2.0 Appender to serve
+ as a javax.util.logging.Handler. log4j 2.0 would likely be modularized, possibly using
+ OSGi and would include a facade that emulates the log4j 1.3 API but would not be compatible
+ with user written appenders and other components.</p>
</section>
</body>
