LOG4J2-1802: Convert markers manual page to asciidoc

Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/56eb7a04
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/56eb7a04
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/56eb7a04

Branch: refs/heads/master
Commit: 56eb7a040f259d814006088a79a884d411df48a9
Parents: f000b5e
Author: Matt Sicker <boa...@gmail.com>
Authored: Sun Apr 8 13:49:32 2018 -0500
Committer: Matt Sicker <boa...@gmail.com>
Committed: Sun Apr 8 13:49:32 2018 -0500

----------------------------------------------------------------------
 src/site/asciidoc/manual/markers.adoc | 104 +++++++++++++++++++++++++++
 src/site/xdoc/manual/markers.xml      | 110 -----------------------------
 2 files changed, 104 insertions(+), 110 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/56eb7a04/src/site/asciidoc/manual/markers.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/markers.adoc 
b/src/site/asciidoc/manual/markers.adoc
new file mode 100644
index 0000000..ebf1b1d
--- /dev/null
+++ b/src/site/asciidoc/manual/markers.adoc
@@ -0,0 +1,104 @@
+////
+    Licensed to the Apache Software Foundation (ASF) under one or more
+    contributor license agreements. See the NOTICE file distributed with
+    this work for additional information regarding copyright ownership.
+    The ASF licenses this file to You under the Apache License, Version 2.0
+    (the "License"); you may not use this file except in compliance with
+    the License. You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+////
+= Log4j 2 API
+Ralph Goers <rgo...@apache.org>
+
+[#Markers]
+== Markers
+
+One of the primary purpose of a logging framework is to provide the
+means to generate debugging and diagnostic information only when it is
+needed, and to allow filtering of that information so that it does not
+overwhelm the system or the individuals who need to make use of it. As
+an example, an application desires to log its entry, exit and other
+operations separately from SQL statements being executed, and wishes to
+be able to log queries separate from updates. One way to accomplish this
+is shown below:
+
+[source,java]
+----
+import org.apache.logging.log4j.Logger;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.MarkerManager;
+import java.util.Map;
+
+public class MyApp {
+
+    private Logger logger = LogManager.getLogger(MyApp.class.getName());
+    private static final Marker SQL_MARKER = MarkerManager.getMarker("SQL");
+    private static final Marker UPDATE_MARKER = 
MarkerManager.getMarker("SQL_UPDATE").setParents(SQL_MARKER);
+    private static final Marker QUERY_MARKER = 
MarkerManager.getMarker("SQL_QUERY").setParents(SQL_MARKER);
+
+    public String doQuery(String table) {
+        logger.traceEntry();
+
+        logger.debug(QUERY_MARKER, "SELECT * FROM {}", table);
+
+        String result = ... 
+
+        return logger.traceExit(result);
+    }
+
+    public String doUpdate(String table, Map<String, String> params) {
+        logger.traceEntry();
+
+        if (logger.isDebugEnabled()) {
+            logger.debug(UPDATE_MARKER, "UPDATE {} SET {}", table, 
formatCols());
+        }
+    
+        String result = ... 
+
+        return logger.traceExit(result);
+    }
+
+    private String formatCols(Map<String, String> cols) {
+        StringBuilder sb = new StringBuilder();
+        boolean first = true;
+        for (Map.Entry<String, String> entry : cols.entrySet()) {
+            if (!first) {
+                sb.append(", ");
+            }
+            sb.append(entry.getKey()).append("=").append(entry.getValue());
+            first = false;
+        }
+        return sb.toString();
+    }
+}
+----
+
+In the example above it is now possible to add MarkerFilters to only
+allow SQL update operations to be logged, all SQL updates to be logged
+or to log everything in MyApp.
+
+Some important rules about Markers must be considered when using them.
+
+1.  Markers must be unique. They are permanently registered by name so
+care should be taken to insure that Markers used in your application are
+distinct from those in the application's dependencies, unless that is
+what is desired.
+2.  Parent Markers can be added or removed dynamically. However, this is
+fairly expensive to do. Instead, it is recommended that the parents be
+identified when obtaining the Marker the first time as shown in the
+examples above. Specifically, the set method replaces all the markers in
+a single operation while add and remove act on only a single Marker at a
+time.
+3.  Evaluating Markers with multiple ancestors is much more expensive
+than Markers with no parents. For example, in one set of tests to
+evaluate whether a Marker matched its grandparent took 3 times longer
+than evaluating the Marker itself. Even then though, evaluating Markers
+is inexpensive compared to resolving the callers class name or line
+number.

http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/56eb7a04/src/site/xdoc/manual/markers.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/markers.xml b/src/site/xdoc/manual/markers.xml
deleted file mode 100644
index 145eb97..0000000
--- a/src/site/xdoc/manual/markers.xml
+++ /dev/null
@@ -1,110 +0,0 @@
-<?xml version="1.0"?>
-<!--
-    Licensed to the Apache Software Foundation (ASF) under one or more
-    contributor license agreements.  See the NOTICE file distributed with
-    this work for additional information regarding copyright ownership.
-    The ASF licenses this file to You under the Apache License, Version 2.0
-    (the "License"); you may not use this file except in compliance with
-    the License.  You may obtain a copy of the License at
-
-         http://www.apache.org/licenses/LICENSE-2.0
-
-    Unless required by applicable law or agreed to in writing, software
-    distributed under the License is distributed on an "AS IS" BASIS,
-    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-    See the License for the specific language governing permissions and
-    limitations under the License.
--->
-
-<document xmlns="http://maven.apache.org/XDOC/2.0";
-          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
-          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 
http://maven.apache.org/xsd/xdoc-2.0.xsd";>
-    <properties>
-        <title>Log4j 2 API</title>
-        <author email="rgo...@apache.org">Ralph Goers</author>
-    </properties>
-
-    <body>
-        <section name="Log4j 2 API">
-          <subsection name="Markers">
-            <a name="Markers"/>
-            <p>
-              One of the primary purpose of a logging framework is to provide 
the means to generate debugging and
-              diagnostic information only when it is needed, and to allow 
filtering of that information so that it
-              does not overwhelm the system or the individuals who need to 
make use of it. As an example, an
-              application desires to log its entry, exit and other operations 
separately from SQL statements
-              being executed, and wishes to be able to log queries separate 
from updates. One way to accomplish
-              this is shown below:
-            </p>
-        <pre class="prettyprint linenums"><![CDATA[
-import org.apache.logging.log4j.Logger;
-import org.apache.logging.log4j.LogManager;
-import org.apache.logging.log4j.MarkerManager;
-import java.util.Map;
-
-public class MyApp {
-
-    private Logger logger = LogManager.getLogger(MyApp.class.getName());
-    private static final Marker SQL_MARKER = MarkerManager.getMarker("SQL");
-    private static final Marker UPDATE_MARKER = 
MarkerManager.getMarker("SQL_UPDATE").setParents(SQL_MARKER);
-    private static final Marker QUERY_MARKER = 
MarkerManager.getMarker("SQL_QUERY").setParents(SQL_MARKER);
-
-    public String doQuery(String table) {
-        logger.traceEntry();
-
-        logger.debug(QUERY_MARKER, "SELECT * FROM {}", table);
-
-        String result = ... 
-
-        return logger.traceExit(result);
-    }
-
-    public String doUpdate(String table, Map<String, String> params) {
-        logger.traceEntry();
-
-        if (logger.isDebugEnabled()) {
-            logger.debug(UPDATE_MARKER, "UPDATE {} SET {}", table, 
formatCols());
-        }
-       
-        String result = ... 
-
-        return logger.traceExit(result);
-    }
-
-    private String formatCols(Map<String, String> cols) {
-        StringBuilder sb = new StringBuilder();
-        boolean first = true;
-        for (Map.Entry<String, String> entry : cols.entrySet()) {
-            if (!first) {
-                sb.append(", ");
-            }
-            sb.append(entry.getKey()).append("=").append(entry.getValue());
-            first = false;
-        }
-        return sb.toString();
-    }
-}]]></pre>
-            <p>
-              In the example above it is now possible to add MarkerFilters to 
only allow SQL update operations
-              to be logged, all SQL updates to be logged or to log everything 
in MyApp.
-            </p>
-            <p>
-              Some important rules about Markers must be considered when using 
them.
-            </p>
-              <ol>
-                <li>Markers must be unique. They are permanently registered by 
name so care should be taken
-                  to insure that Markers used in your application are distinct 
from those in the application's
-                  dependencies, unless that is what is desired.</li>
-                <li>Parent Markers can be added or removed dynamically. 
However, this is fairly expensive to do.
-                  Instead, it is recommended that the parents be identified 
when obtaining the Marker the first time
-                  as shown in the examples above. Specifically, the set method 
replaces all the markers in
-                  a single operation while add and remove act on only a single 
Marker at a time.</li>
-                <li>Evaluating Markers with multiple ancestors is much more 
expensive than Markers with no parents.
-                  For example, in one set of tests to evaluate whether a 
Marker matched its grandparent took 3
-                  times longer than evaluating the Marker itself. Even then 
though, evaluating Markers is
-                  inexpensive compared to resolving the callers class name or 
line number.</li>
-              </ol>
-          </subsection>
-        </section>
-    </body>
-</document>

Reply via email to