ceki 01/09/07 10:36:20 Modified: src/docbook intro.xml manual.xml Added: src/docbook glossary.xml Log: More docs. Revision Changes Path 1.2 +126 -118 jakarta-log4j/src/docbook/intro.xml Index: intro.xml =================================================================== RCS file: /home/cvs/jakarta-log4j/src/docbook/intro.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- intro.xml 2001/09/07 14:39:31 1.1 +++ intro.xml 2001/09/07 17:36:20 1.2 @@ -1,127 +1,135 @@ <chapter id="intro"> -<title>Introduction</title> + <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> + <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> + 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. + </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> - + + <sect1> + <title>Copyright</title> + <para></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; + <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> - 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> + <!-- Section ----------------------------------------------------- --> + + <sect1> + <title>First run</title> + + <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 linenumbering="numbered"> + package my.com; + + import org.apache.log4j.Logger; + + public class MyApp { + <emphasis role="strong">static</emphasis> final Logger logger = Logger.getLogger(MyApp.class); + + static public void main(String[] args) { + logger.debug("Hello world."); + } + } + </programlisting> + </example> + + <para> + Using log4j in your own code is quite easy. First, you need to + import <classname>org.apache.log4j.Logger</classname> class and + then invoke the <methodname>Logger.getLogger</methodname> method + to instantiate a Logger object. Subsequently, you can invoke one + of the <link linkend="gloss-printingMethods">printing + methods</link> of the logger, e.g. debug, to log your messages. + </para> </sect1> 1.2 +4 -1 jakarta-log4j/src/docbook/manual.xml Index: manual.xml =================================================================== RCS file: /home/cvs/jakarta-log4j/src/docbook/manual.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- manual.xml 2001/09/07 14:39:31 1.1 +++ manual.xml 2001/09/07 17:36:20 1.2 @@ -1,6 +1,7 @@ <?xml version='1.0'?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" [ <!ENTITY intro SYSTEM "intro.xml"> +<!ENTITY glo SYSTEM "glossary.xml"> ]> <book lang="en"> @@ -149,9 +150,11 @@ </qandaentry> </qandaset> +</chapter> +&glo -</chapter> + </book> 1.1 jakarta-log4j/src/docbook/glossary.xml Index: glossary.xml =================================================================== <glossary><title>Glossary</title> <para> </para> <!-- ... --> <glossentry id="gloss-printingMethods"> <glossterm>Logger Printing Methods</glossterm> <glossdef> <para>Method such as debug, info, warn and error and fatal that can be invoked on a logger in order to log messsages.</para> <glossseealso otherterm="sgml">SGML</glossseealso> </glossdef> </glossentry> <glossentry id="xml"> <glossterm>Extensible Markup Language</glossterm> <acronym>XML</acronym> <glossdef> <para>Some reasonable definition here.</para> <glossseealso otherterm="sgml">SGML</glossseealso> </glossdef> </glossentry> <glossentry><glossterm>SGML</glossterm> <glosssee otherterm="sgml"/> </glossentry> <glossentry id="sgml"> <glossterm>Standard Generalized Markup Language</glossterm> <acronym>SGML</acronym> <abbrev>ISO 8879:1986</abbrev> <glossdef> <para>Some reasonable definition here.</para> <glossseealso otherterm="xml">XML</glossseealso> </glossdef> </glossentry> </glossary> --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
