ceki 01/09/18 15:03:15
Modified: src/docbook architecture.xml configuration.xml intro.xml
Log:
Improvementst to manual.
Revision Changes Path
1.7 +29 -28 jakarta-log4j/src/docbook/architecture.xml
Index: architecture.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/architecture.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- architecture.xml 2001/09/10 22:20:29 1.6
+++ architecture.xml 2001/09/18 22:03:15 1.7
@@ -1,14 +1,14 @@
<chapter>
<title>Logger, Appenders and Layouts</title>
- <para>Log4j has three main components:
- <emphasis>loggers</emphasis>, <emphasis>appenders</emphasis> and
- <emphasis>layouts</emphasis>. These three types of components
- work together to enable developers to log messages according to
- message type and priority, and to control at runtime how these
- messages are formatted and where they are reported.
+ <para>Log4j has three main components: <emphasis>loggers</emphasis>,
+ <emphasis>appenders</emphasis> and
+ <emphasis>layouts</emphasis>. These three types of components work
+ together to enable developers to log messages according to their
+ level and to control at runtime how these messages are formatted
+ and where they are reported.
</para>
-
+
<sect1>
<title>Logger hierarchy</title>
@@ -22,9 +22,11 @@
<para>This observation had previously led us to choose
<emphasis>category</emphasis> as the central concept of the
package. However, since log4j version 1.2, <ulink
-
url="http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/Logger.html";>Logger</ulink>
- <classname>Logger</classname> class has replaced the
- <classname>Category</classname> class.
+
url="http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/Logger.html";>Logger</ulink>
+ class has replaced the <classname>Category</classname>
+ class. For those familiar with earlier versions of log4j, the
+ logger class can be considered as just an alias to the category
+ class.
</para>
@@ -38,14 +40,13 @@
<term><emphasis role="strong">Named Hierarchy Rule</emphasis></term>
<listitem>
- <para>A category is said to be an
- <emphasis>ancestor</emphasis> of another category if
- its name followed by a dot is a prefix of the
- <emphasis>descendant</emphasis> category name. A
- category is said to be a <emphasis>parent</emphasis>
- of a <emphasis>child</emphasis> category if there are
- no ancestors between itself and the descendant
- category.
+ <para>A logger is said to be an
+ <emphasis>ancestor</emphasis> of another logger if its
+ name followed by a dot is a prefix of the
+ <emphasis>descendant</emphasis> logger name. A logger is
+ said to be a <emphasis>parent</emphasis> of a
+ <emphasis>child</emphasis> logger if there are no other
+ ancestors between itself and the descendant logger.
</para>
</listitem>
</varlistentry>
@@ -54,7 +55,7 @@
<para>For example, the logger named
- <classname>"com.foo"</classname> is a parent of the category
+ <classname>"com.foo"</classname> is a parent of the logger
named <classname>"com.foo.Bar"</classname>. Similarly,
<classname>"java"</classname> is a parent of
<classname>"java.util"</classname> and an ancestor of
@@ -62,7 +63,7 @@
should be familiar to most developers.
</para>
- <para>The root logger resides at the top of the category
+ <para>The root logger resides at the top of the logger
hierarchy. It is exceptional in two ways:
</para>
@@ -75,7 +76,7 @@
<para>Invoking the class static <ulink
url="../api/org/apache/log4j/Logger.html#getRootLogger()">Logger.getRootLogger</ulink>
- method retrieves it. All other logger are instantiated and
+ method retrieves it. All other loggers are instantiated and
retrieved with the class static <ulink
url="../api/org/apache/log4j/Logger.html#geLogger()">Logger.getLogger</ulink>
method. This method takes the name of the desired logger as
@@ -91,8 +92,8 @@
public <emphasis role="strong">Logger</emphasis> class {
// Creation & retrieval methods:
- public static Category getRoot();
- public static Category getInstance(String name);
+ public static Logger getRootLogger();
+ public static Logger getLogger(String name);
// printing methods:
public void debug(Object message);
@@ -101,7 +102,7 @@
public void error(Object message);
// generic printing method:
- public void log(Priority p, Object message);
+ public void log(Level p, Object message);
}
</programlisting>
@@ -141,7 +142,7 @@
logger <emphasis>L</emphasis>, is equal to the first
non-null level in the logger hierarchy, starting at
<emphasis>L</emphasis> and proceeding upwards in the
- hierarchy towards the root category.
+ hierarchy towards the root logger.
</para>
</listitem>
</varlistentry>
@@ -370,7 +371,7 @@
<listitem>
<para>A log request of priority
- <emphasis>p</emphasis> in a category with
+ <emphasis>p</emphasis> in a logger with
inherited priority <emphasis>q</emphasis>, is
enabled if <emphasis> p >= q</emphasis>.
</para>
@@ -444,7 +445,7 @@
<para>Configuration of the log4j environment is typically done
at application initialization. The preferred way is by reading
a configuration file. This approach will be discussed in <xref
- linkend="chap-configuration"/>.
+ linkend="configuration"/>.
</para>
<para>Log4j makes it easy to name loggers by <emphasis>software
@@ -460,7 +461,7 @@
logger as she wishes.
</para>
- <para>Nevertheless, naming loggers after the class where they
+ <para>Nevertheless, naming loggers after the class where they
are located seems to be the best strategy known so far.</para>
</sect1>
1.4 +1 -1 jakarta-log4j/src/docbook/configuration.xml
Index: configuration.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/configuration.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- configuration.xml 2001/09/10 12:00:31 1.3
+++ configuration.xml 2001/09/18 22:03:15 1.4
@@ -1,4 +1,4 @@
-<chapter id="chap-configuration">
+<chapter id="configuration">
<title>Configuration</title>
1.5 +27 -22 jakarta-log4j/src/docbook/intro.xml
Index: intro.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/intro.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- intro.xml 2001/09/08 17:57:38 1.4
+++ intro.xml 2001/09/18 22:03:15 1.5
@@ -72,7 +72,15 @@
<sect1>
<title>Copyright</title>
- <para></para>
+ <para>
+ Copyright 2000-2001 Ceki Gülcü. All rights reserved.
+ </para>
+
+ <para>
+ You are free to copy and distribute this document in electronic
+ form but not in printed form.. Translations or modifications of
+ this document require prior written permission.
+ </para>
</sect1>
<!-- Section ----------------------------------------------------- -->
@@ -124,21 +132,21 @@
</programlisting>
</example>
- <caution>
+ <note>
<para>
Running this example will not produce any logging output but the
following warning.
<literallayout>
- <computeroutput>
-log4j:ERROR No appenders could be found for logger (chapter1.MyApp1).
-log4j:ERROR Please initialize the log4j system properly.
- </computeroutput>
+<computeroutput>
+ log4j:ERROR No appenders could be found for logger (chapter1.MyApp1).
+ log4j:ERROR Please initialize the log4j system properly.
+</computeroutput>
</literallayout>
</para>
- </caution>
+ </note>
- <para>Log4j is complaining because we have not configured
- it. There are many different ways for configuring log4j. The
+ <para>Log4j is complaining because we have not configured it just
+ yet. There are many different ways for configuring log4j. The
simplest way is by calling the
<function>BasicConfigurator.configure()</function> method.
</para>
@@ -163,11 +171,9 @@
</example>
<para>
Running this example will produce the following output.
- <literallayout>
- <computeroutput>
- 0 [main] DEBUG chapter1.MyApp2 - Hello world.
- </computeroutput>
- </literallayout>
+ </para>
+ <para>
+ <screen>0 [main] DEBUG chapter1.MyApp2 - Hello world.</screen>
</para>
<procedure>
@@ -182,9 +188,8 @@
Configure log4j for your environment. Log4j offers many
sophisticated means of configuration,
<function>BasicConfigurator.configure()</function> being the
- simplest but also the least flexible. There is a whole
- chapter dedicated to this topic. Please refer to <xref
- linkend="chap-configuration"/> for more details.
+ simplest but also the least flexible. <xref
+ linkend="configuration"/> is dedicated to this topic.
</para>
<para>
@@ -192,7 +197,7 @@
<para>
Log4j normally needs to be configured only once. Some
new users try to configure log4j in each and every
- class. This is wrong and must be avoided.
+ class. This is very inefficient and just plain wrong.
</para>
</tip>
</para>
@@ -200,11 +205,11 @@
<step performance="required">
<para>In every class where you wish to perform logging,
- instantiate a Logger object by invoking the
+ retrieve a Logger object by invoking the
<function>Logger.getLogger</function> method and passing it
- a string, usualy (but not necessarily) the fully qualified
- name of the containing class. The logger object is usually
- declared as a <varname>static final</varname>.
+ a string, commonly the fully qualified name of the
+ containing class. The logger object is usually declared as a
+ <varname>static final</varname>.
</para>
</step>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
