(logging-log4cxx) 01/01: Explain where configuration file options are documented

[sw...@apache.org]

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 <sw...@gmail.com>
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