ceki 01/09/07 07:39:31 Added: src/docbook intro.xml manual.xml Log: Moved sgml files to xml format as has been suggested by Jeff Turner on the log4j-dev list. Revision Changes Path 1.1 jakarta-log4j/src/docbook/intro.xml Index: intro.xml =================================================================== <chapter id="intro"> <title>Introduction</title> <para> Almost every large application includes its own logging or tracing API. In conformance with this rule, the E.U. <ulink url="http://www.semper.org";>SEMPER</ulink> project decided to write its own tracing API. This was in early 1996. After countless enhancements, several incarnations and much work that API has evolved to become log4j, a popular logging package for Java. The package is distributed under the <ulink url="../LICENSE.txt">Apache Software License</ulink>, a fully-fledged open source license certified by the <ulink url="http://www.opensource.org";>open source</ulink> initiative. The latest log4j version, including full-source code, class files and documentation can be found at <ulink url="http://jakarta.apache.org/log4j/";>http://jakarta.apache.org/log4j/</ulink>. </para> <para>Igor Poteryaev, an independent author, has ported log4j to the Python language. Bastiaan Bakker has initiated a C++ port. Their projects are unsurprisingly called <ulink url="http://log4p.sourceforge.net";>log4p</ulink> and <ulink url="http://log4cpp.sourceforge.net";>log4cpp</ulink>. </para> <para>Inserting log statements into code is a low-tech method for debugging it. It may also be the only way because debuggers are not always available or applicable. This is usually the case for multithreaded applications and distributed applications at large. </para> <para>Experience indicated that logging was an important component of the development cycle. It offered several advantages. It could provide precise <emphasis>context</emphasis> about a run of the application. Once inserted into the code, the generation of logging output required no human intervention. Moreover, log output could be saved in persistent medium to be studied at a later time. In addition to its use in the development cycle, a sufficiently rich logging package could also be viewed as an auditing tool. </para> <para>As Brian W. Kernigan and Rob Pike put it in their truly excellent book <emphasis>"The Practice of Programming"</emphasis> <blockquote> <literallayout> As personal choice, we tend not to use debuggers beyond getting a stack trace or the value of a variable or two. One reason is that it is easy to get lost in details of complicated data structures and control flow; we find stepping through a program less productive than thinking harder and adding output statements and self-checking code at critical places. Clicking over statements takes longer than scanning the output of judiciously-placed displays. It takes less time to decide where to put print statements than to single-step to the critical section of code, even assuming we know where that is. More important, debugging statements stay with the program; debugging sessions are transient. </literallayout> </blockquote> </para> <para>Logging does have its drawbacks. It can slow down an application. If too verbose, it can cause scrolling blindness. To alleviate these concerns, log4j is designed to be fast and flexible. Since logging is rarely the main focus of an application, log4j API strives to be simple to understand and to use. </para> <!-- Section ----------------------------------------------------- --> <sect1> <title>Copyright</title> <para></para> </sect1> <!-- Section ----------------------------------------------------- --> <sect1> <title>Installing</title> <para>The latest version of log4j can be fetched from <ulink url="http://jakarta.apache.org/log4j/docs/download.html";>http://jakarta.apache.org/log4j/docs/download.html</ulink>. </para> <para>Releases are available in two formats: <filename>zip</filename> and <filename>tar.gz</filename>. After unpacking the distribution, you should have the file <filename>$LOG4J_HOME/dist/lib/log4j-VERSION.jar</filename> where <varname>$LOG4J_HOME</varname> is the directory where you unpacked the log4j distribution and <varname>VERSION</varname> is the version of the log4j distibution you downloaded.</para> <para>To start using log4j simply add this jar file to your <varname>CLASSPATH</varname>.</para> </sect1> <!-- Section ----------------------------------------------------- --> <sect1> <title>First run</title> <para></para> <para>After you have installed <filename>log4j-VERSION.jar</filename> in your <varname>CLASSPATH</varname>, we can try to write a small program that uses log4j.</para> <para>Please also see <xref linkend="faq-threadSafe"/>.</para> <example> <title>First attempt</title> <programlisting> package my.com; import org.apache.log4j.Logger; public class MyApp { static final Logger logger = Logger.getLogger(MyApp.class); static public void main(String[] args) { logger.debug("Hello world."); } } </programlisting> </example> </sect1> </chapter> 1.1 jakarta-log4j/src/docbook/manual.xml Index: manual.xml =================================================================== <?xml version='1.0'?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" [ <!ENTITY intro SYSTEM "intro.xml"> ]> <book lang="en"> <bookinfo> <title>log4j manual</title> <author> <firstname>Ceki</firstname> <surname>Gülcü</surname> </author> <author> <firstname>Other authors</firstname> <surname>as appropriate</surname> </author> <revhistory> <revision> <revnumber>v1.0</revnumber> <date>2001-08-15</date> <authorinitials>cgu</authorinitials> </revision> </revhistory> <abstract> <para> This document describes the log4j API, its features and design rationale. Log4j is an open source project based on the work of many authors. It allows the developer to control which log statements are output with arbitrary granularity. It is fully configurable at runtime using external configuration files. Best of all, log4j has a gentle learning curve. Beware: judging from user feedback, it is also quite addictive. </para> </abstract> </bookinfo> &intro <chapter> <title>Architecture</title> <para></para> <sect1> <title>Selecting</title> <para></para> </sect1> <sect1> <title>Directing Output</title> <para></para> </sect1> <sect1> <title>Formatting output</title> <para></para> </sect1> <sect1> <title>Object Renderers</title> <para></para> </sect1> <sect1> <title>Performance</title> <para></para> </sect1> </chapter> <chapter> <title>Configuration</title> <sect1> <title>PropertyConfigurator</title> <para></para> </sect1> <sect1> <title>DOMConfigurator</title> <para></para> </sect1> <sect1> <title>Default configuration</title> <para></para> </sect1> <sect1> <title>Filters</title> <para></para> </sect1> <sect1> <title>Error handlers</title> <para></para> </sect1> <sect1> <title>Category Factories</title> <para></para> </sect1> </chapter> <chapter> <title>Logging in servers and other Multithreaded environments</title> <sect1> <title>NDC</title> <para></para> </sect1> <sect1> <title>MDC</title> <para></para> </sect1> </chapter> <chapter> <title>Frequently Asked Questions</title> <qandaset> <qandaentry> <question> <para>What are the installation requirements for log4j?</para> </question> <answer> <para>Log4j requires JDK 1.1.</para> </answer> </qandaentry> <qandaentry> <question id="faq-threadSafe"> <para>Is log4j thread safe?</para> </question> <answer> <para>Yes it is.</para> </answer> </qandaentry> </qandaset> </chapter> </book> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
