You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4j-cvs@jakarta.apache.org by ce...@apache.org on 2001/09/07 19:36:20 UTC
cvs commit: jakarta-log4j/src/docbook glossary.xml intro.xml manual.xml
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: log4j-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: log4j-cvs-help@jakarta.apache.org