This is an automated email from the ASF dual-hosted git repository. swebb2066 pushed a commit to branch improve_configuration_documentation in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit dc6c3ca315736787f142765c02a741ae807b1c97 Author: Stephen Webb <[email protected]> AuthorDate: Sat Aug 23 13:06:36 2025 +1000 Explain where configuration file options are documented --- src/site/markdown/1-usage.md | 2 +- src/site/markdown/configuration-samples.md | 33 ++++++++++++++++++++---------- src/site/markdown/example-programs.md | 2 +- 3 files changed, 24 insertions(+), 13 deletions(-) diff --git a/src/site/markdown/1-usage.md b/src/site/markdown/1-usage.md index 15f76cac..67402fbf 100644 --- a/src/site/markdown/1-usage.md +++ b/src/site/markdown/1-usage.md @@ -25,7 +25,7 @@ See the following pages for usage information: * @subpage quick-start * @subpage concepts -* @subpage configuration-samples +* @subpage configuration-files * @subpage filters * @subpage extending-log4cxx * @subpage qt-support diff --git a/src/site/markdown/configuration-samples.md b/src/site/markdown/configuration-samples.md index ee1446fd..ad1d3dab 100644 --- a/src/site/markdown/configuration-samples.md +++ b/src/site/markdown/configuration-samples.md @@ -1,4 +1,4 @@ -Configuration Samples {#configuration-samples} +Configuration Files {#configuration-files} === <!-- Note: License header cannot be first, as doxygen does not generate @@ -23,7 +23,14 @@ Configuration Samples {#configuration-samples} [TOC] -The following snippets show various ways of configuring Log4cxx. +As Log4cxx was designed to be extendable, +property names are not constrained by the core library. +Refer to the [setOption method documentation](@ref log4cxx::spi::OptionHandler::setOption) +for the names of the configurable properties. +Note that a base class may implement some options +while the concrete class implements others. +Check the full class hierarchy when looking +for a configuration option. # Default Initialization Behaviour {#default-initialization} @@ -64,14 +71,18 @@ relative to the executable location, not just the current working directory. The variable names are [documented here](@ref log4cxx.spi.Configurator.properties). -To check the corrent values are used when your configuration file is loaded, +To check the correct values are used when your configuration file is loaded, use [Log4cxx internal debugging]. -# Properties Files {#properties} +# Configuration Samples {#configuration-samples} + +The following snippets show various ways of configuring Log4cxx. + +## Properties Files {#properties} Log4cxx may be configured using a Java properties (key=value) type file. -## Properties Example 1 {#properties-example-1} +### Properties Example 1 {#properties-example-1} This simple example writes messages to stdout. If you want to send messages to stderr instead, @@ -90,7 +101,7 @@ log4j.appender.A1.layout=org.apache.log4j.PatternLayout log4j.appender.A1.layout.ConversionPattern=%.30c - %Y%m%y%n ~~~ -## Properties Example 2 {#properties-example-2} +### Properties Example 2 {#properties-example-2} The following Log4cxx 1.6 configuration file uses the variables added in the \ref com/foo/config4.cpp example @@ -141,12 +152,12 @@ log4j.appender.csvData.layout.ConversionPattern=%m,%d{yyyy-MM-dd,HH:mm,ss.SSS}%n #log4j.debug=true ~~~ -# XML Files {#xmlfiles} +## XML Files {#xmlfiles} Another way of configuring Log4cxx is with an XML file. The following are some XML configuration examples. -## XML Example 1 {#xml-example-1} +### XML Example 1 {#xml-example-1} This simple example writes messages to stdout. If you want to send messages to stderr instead, @@ -176,7 +187,7 @@ Sample output: Hello there! ~~~ -## XML Example 2 {#xml-example-2} +### XML Example 2 {#xml-example-2} This example sends data to both stdout, as well as to a file. @@ -214,7 +225,7 @@ Sample output: [2020-12-24 15:57:35] root INFO - Hello there! ~~~ -## XML Example 3 {#xml-example-3} +### XML Example 3 {#xml-example-3} This example shows how you can configure logging for a particular category. @@ -289,7 +300,7 @@ Sample output: [2020-12-24 16:05:48] com.example TRACE - com.example trace message ~~~ -## XML Example 4 {#xml-example-4} +### XML Example 4 {#xml-example-4} This example shows how to add a filter to an appender that will accept messages that match a certain string. If our loggers are configured as such: diff --git a/src/site/markdown/example-programs.md b/src/site/markdown/example-programs.md index 344686f7..97834df8 100644 --- a/src/site/markdown/example-programs.md +++ b/src/site/markdown/example-programs.md @@ -202,4 +202,4 @@ This file is an example of how to use the current module name to select the Log4 \example com/foo/config4.cpp This file is a simpler example of how to use the current module name to select the Log4cxx configuration file. -[Configuration Samples]:configuration-samples.html +[Configuration Samples]:configuration-files.html#configuration-samples
