[logging-log4cxx] 01/01: LOGCXX-571 Env and macro documentation updates

[rm...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rmiddleton pushed a commit to branch LOGCXX-571
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git

commit 549fc1e60263d096d9ad73d9c9893f5038bbfc61
Author: Robert Middleton <ro...@rm5248.com>
AuthorDate: Fri Dec 16 22:10:13 2022 -0500

    LOGCXX-571 Env and macro documentation updates
    
    Create new pages that explicitly list out all of the macros and environment
    variables that can be set in order to influence Log4cxx.
---
 src/site/markdown/1-usage.md                       |  2 ++
 src/site/markdown/environment-variables.md         | 38 ++++++++++++++++++++++
 .../{1-usage.md => macros-influencing-log4cxx.md}  | 23 ++++++-------
 3 files changed, 52 insertions(+), 11 deletions(-)

diff --git a/src/site/markdown/1-usage.md b/src/site/markdown/1-usage.md
index 8d3d5a28..3d94cd89 100644
--- a/src/site/markdown/1-usage.md
+++ b/src/site/markdown/1-usage.md
@@ -32,3 +32,5 @@ See the following pages for usage information:
 * @subpage performance
 * @subpage map-filter
 * @subpage multiprocess-logging
+* @subpage environment-variables
+* @subpage macros-influencing-log4cxx
diff --git a/src/site/markdown/environment-variables.md b/src/site/markdown/environment-variables.md
new file mode 100644
index 00000000..aeed4697
--- /dev/null
+++ b/src/site/markdown/environment-variables.md
@@ -0,0 +1,38 @@
+Environment Variables {#environment-variables}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+# Environment Variables Used by Log4cxx
+
+There are several environment variables that can be set in order to influence how
+Log4cxx works.  They are summarized in the following table:
+
+
+| Environment Variable | Usage |
+| -------------------- | ----- |
+| LOG4CXX\_DEBUG       | Set to the value 'true' to enable internal debugging of Log4cxx.  All output goes to stderr.  This can be useful to determine why a configuration file is not loading |
+| log4j.configuratorClass | Used to determine what class to use to configure the logging system |
+| LOG4CXX\_CONFIGURATOR\_CLASS | Used to determine what class to use to configure the logging system.  Takes precedence over log4j.configuratorClass |
+| log4j.configuration | Set the file to load to configure the logging system |
+| LOG4CXX\_CONFIGURATION | Set the file to load to configure the logging system.  Takes precedence over log4j.configuration |
+| LOG4CXX\_CONFIGURATION\_WATCH\_SECONDS | Set how often the configuration file should be checked for changes |
+
diff --git a/src/site/markdown/1-usage.md b/src/site/markdown/macros-influencing-log4cxx.md
similarity index 52%
copy from src/site/markdown/1-usage.md
copy to src/site/markdown/macros-influencing-log4cxx.md
index 8d3d5a28..fc2edc48 100644
--- a/src/site/markdown/1-usage.md
+++ b/src/site/markdown/macros-influencing-log4cxx.md
@@ -1,4 +1,4 @@
-Usage {#usage-overview}
+Macros Influencing Log4cxx {#macros-influencing-log4cxx}
 ===
 <!--
  Note: License header cannot be first, as doxygen does not generate
@@ -21,14 +21,15 @@ Usage {#usage-overview}
  limitations under the License.
 -->
 
-See the following pages for usage information:
+# Macros that influence Log4cxx
 
-* @subpage usage
-* @subpage threading
-* @subpage extending-log4cxx
-* @subpage faq
-* @subpage configuration-samples
-* @subpage qt-support
-* @subpage performance
-* @subpage map-filter
-* @subpage multiprocess-logging
+The following macros can be defined in client code to influence how log messages
+are set or not.
+
+These macros may be set on a per-file basis(in which case they must be before any
+Log4cxx includes), or they may be set globally via your build system.
+
+| Macro | Usage |
+| ----- | ----- |
+| LOG4CXX\_THRESHOLD | Used to determine if log messages are compiled in or not.  A higher value causes more messages to be compiled out.  See [removing log statements](usage.html#removing-log-statements) for more information. |
+| LOG4CXX\_DISABLE\_LOCATION\_INFO | Define this macro to disable location information on log statements.  Location information includes the filename, class name, method name, and line number |