finished features page

src/site/antora/modules/ROOT/nav.adoc

@@ -16,6 +16,8 @@
 ////
 
 * xref:development.adoc[]
+* xref:manual/index.adoc[]
+** xref:manual/configuration.adoc[]
 * xref:features.adoc[]
 * xref:release-notes.adoc[]
 * {logging-services-url}/download.html[Download]

src/site/antora/modules/ROOT/pages/features.adoc

@@ -1,24 +1,147 @@
 ////
-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.
+    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.
 ////
 
+[#features]
 = Features
 
+[#overview]
+== Overview
 log4net is a tool to help the programmer output log statements to a variety of output targets.
 In case of problems with an application, it is helpful to enable logging so that the problem can be located.
 With log4net it is possible to enable logging at runtime without modifying the application binary.
 The log4net package is designed so that log statements can remain in shipped code without incurring a high performance cost.
-It follows that the speed of logging (or rather not logging) is crucial.
+It follows that the speed of logging (or rather not logging) is crucial.
+
+At the same time, log output can be so voluminous that it quickly becomes overwhelming.
+One of the distinctive features of log4net is the notion of hierarchical loggers.
+Using these loggers it is possible to selectively control which log statements are output at arbitrary granularity.
+
+log4net is designed with two distinct goals in mind: speed and flexibility
+
+[#featurelist]
+== Features
+* Support for multiple frameworks
+* Output to multiple logging targets
+* Hierarchical logging architecture
+* XML Configuration
+* Dynamic Configuration
+* Logging Context
+* Proven architecture
+* Modular and extensible design
+* High performance with flexibility
+
+[#frameworks]
+== Support for multiple frameworks
+log4net has specific builds for the following frameworks:
+
+* .NET Core 8 or higher - using netstandard-2.0
+* Microsoft .NET Framework 4.6.2 or higher
+
+[#appenders]
+== Output to multiple logging targets
+log4net ships with the following appenders
+[cols="Type,Description"]
+|===
+|Type |Description
+
+|AdoNetAppender
+|Writes logging events to a database using either prepared statements or stored procedures.
+
+|AnsiColorTerminalAppender
+|Writes color highlighted logging events to a an ANSI terminal window.
+
+|AspNetTraceAppender
+|Writes logging events to the ASP trace context. These can then be rendered at the end of the ASP page or on the ASP trace page.
+
+|ColoredConsoleAppender
+|Writes color highlighted logging events to the application's Windows Console.
+
+|ConsoleAppender
+|Writes logging events to the application's Console.
+The events may go to either the standard our stream or the standard error stream.
+
+|DebugAppender
+|Writes logging events to the .net debugger (https://web.archive.org/web/20240930165834/https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.debug?view=net-8.0[System.Diagnostics.Debug]).
+
+|EventLogAppender
+|Writes logging events to the Windows Event Log.
+
+|FileAppender
+|Writes logging events to a file in the file system.
+
+|LocalSyslogAppender
+|Writes logging events to the local https://datatracker.ietf.org/doc/html/rfc3164[syslog] service (UNIX only).
+
+|MemoryAppender
+|Stores logging events in an in memory buffer.
+
+|OutputDebugStringAppender
+|Writes logging events to the debugger (using https://web.archive.org/web/20241118170546/https://learn.microsoft.com/en-us/windows/win32/api/debugapi/nf-debugapi-outputdebugstringw[OutputDebugString]).
+If the application has no debugger, the system debugger displays the string.
+If the application has no debugger and the system debugger is not active, the message is ignored.
+
+|RemoteSyslogAppender
+|Writes logging events to a remote https://datatracker.ietf.org/doc/html/rfc3164[syslog] service using UDP networking.
+
+|RollingFileAppender
+|Writes logging events to a file in the file system.
+The RollingFileAppender can be configured to log to multiple files based upon date or file size constraints.
+
+|SmtpAppender
+|Sends logging events to an email address.
+
+|SmtpPickupDirAppender
+|Sends logging events to an email address but writes the emails to a configurable directory rather than sending them directly via SMTP.
+
+|TelnetAppender
+|*Clients* connect via Telnet to receive logging events.
+
+|TraceAppender
+|Writes logging events to the .NET trace system (https://web.archive.org/web/20240907024634/https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.trace?view=net-8.0[System.Diagnostics.Trace]).
+
+|UdpAppender
+|Sends logging events as connectionless UDP datagrams to a remote host or a multicast group using a UdpClient.
+
+|ForwardingAppender
+|Can be used to wrap another appender, for example to attach additional filters.
+
+|===
+
+[#hierarchy]
+== Hierarchical logging architecture
+Hierarchical logging is an ideal fit with component based development.
+Each component has its own of logger.
+When individually tested, the properties of these loggers may be set as the developer requires.
+When combined with other components, the loggers inherit the properties determined by the integrator of the components.
+One can selectively elevate logging priorities on one component without affecting the other components.
+This is useful when you need a detailed trace from just a single component without crowding the trace file with messages from other components.
+All this can be done through configuration files - no code changes are required.
+
+[#xml-config]
+== XML Configuration
+log4net is configured using an XML configuration file.
+The configuration information can be embedded within other XML configuration files (such as the application's .config file) or in a separate file.
+The configuration is easily readable and updateable while retaining the flexibility to express all configurations.
+
+Alternatively log4net can be configured programmatically.
+
+[#dynamic-config]
+== Dynamic Configuration
+log4net can monitor its configuration file for changes and dynamically apply changes made by the configurator.
+The logging levels, appenders, layouts, and just about everything else can be adjusted at runtime.
+In many cases it is possible to diagnose application issues without terminating the process in question.
+This can a very valuable tool in investigating issues with deployed applications.

src/site/antora/modules/ROOT/pages/manual/configuration.adoc

@@ -0,0 +1,19 @@
+////
+    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.
+////
+
+[#configuration]
+= Configuration

src/site/antora/modules/ROOT/pages/manual/index.adoc

@@ -0,0 +1,71 @@
+////
+    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.
+////
+= Manual
+
+log4net is a tool to help the programmer output log statements to a variety of output targets.
+
+In case of problems with an application, it is helpful to enable logging so that the problem can be located.
+With log4net it is possible to enable logging at runtime without modifying the application binary.
+The log4net package is designed so that log statements can remain in _production_ code without incurring a high performance cost.
+It follows that the speed of logging (or rather not logging) is crucial.
+
+At the same time, log output can be so voluminous that it quickly becomes overwhelming.
+One of the distinctive features of log4net (and common to all of
+the log4x libraries) is the notion of _hierarchical loggers_.
+Using these loggers it is possible to selectively control
+which log statements are output at arbitrary granularity.
+
+log4net is designed with two distinct goals in mind: speed and flexibility.
+There is a tight balance between these two requirements.
+
+== What are the prerequisites for log4net?
+
+log4net runs on net462 or higher and any framework supporting netstandard2.0.
+
+== Is there example code for using log4net?
+
+You can find many examples in https://github.com/apache/logging-log4net/tree/master/examples[log4net/examples].
+
+== What does log4net offer?
+
+log4net offers numerous features, including:
+
+* log4net is optimized for speed
+* log4net is based on a named logger hierarchy
+* log4net is thread-safe
+* Logging behavior can be set at runtime using a configuration file (xml)
+* log4net is designed to handle exceptions from the start
+* log4net can direct its output to many sinks including: a file, the console, Syslog/EventLog or even e-mail
+* log4net categorizes logging into levels: DEBUG, INFO, WARN, ERROR and FATAL.
+* The format of the log output can be easily changed by implementing a new layout class
+* The target of the log output as well as the writing strategy can be altered by writing a new appender class
+* log4net supports multiple output appenders per logger
+
+See xref:features.adoc[]
+
+////
+
+== How to learn more?
+
+    * xref:manual/getting-started.adoc[How can I get started with Log4j?]
+    * xref:manual/installation.adoc[How can I install Log4j?]
+    * xref:manual/configuration.adoc[How can I configure Log4j?]
+    * xref:manual/api.adoc[How can I use Log4j API?]
+    * xref:manual/performance.adoc[How can I tune my Log4j setup for performance?]
+    * xref:manual/plugins.adoc[What are Log4j plugins] and xref:manual/extending.adoc[how can I use them to extend Log4j?]
+
+////