Rewrote manual intro

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

@@ -33,31 +33,6 @@ The project is actively maintained by a {logging-services-url}/team-list.html[te
 [#features]
 == Features
 
-We share below some highlights from Log4j features.
-
-Batteries included::
-Log4j bundles a rich set of components to assist various use cases.
-* xref:manual/appenders.adoc[Appenders] targeting files, network sockets, databases, SMTP servers, etc.
-* xref:manual/layouts.adoc[Layouts] that can render CSV, HTML, JSON, Syslog, etc. formatted outputs
-* xref:manual/filters.adoc[Filters] that can be configured using log event rates, regular expressions, scripts, time, etc.
-* xref:manual/lookups.adoc[Lookups] for accessing system properties, environment variables, log event fields, etc.
-
-API separation::
-The API for Log4j (i.e., `log4j-api`) is separate from the implementation (i.e., `log4j-core`) making it clear for application developers which classes and methods they can use while ensuring forward compatibility.
-(See xref:manual/api-separation.adoc[API Separation] for details.)
-The Log4j API also provides the most feature rich logging facade in the market; support for various `Message` types (`Object`, `Map`, etc.) besides plain `String`, lambda expressions, parametrized logging, markers, levels, diagnostic contexts (aka. MDC/NDC), etc.
-Check out the xref:manual/api.adoc[Java API], {logging-services-url}/log4j/kotlin[Kotlin API], and {logging-services-url}/log4j/scala[Scala API] pages for further information.
-
-No vendor lock-in::
-Even though the Log4j API is implemented by the Log4j at its fullest, users can choose to use another logging backend.
-This can be achieved by either using another backend implementing the Log4j API, or forwarding Log4j API calls to another logging facade (e.g., SLF4J) and using a backend for that particular facade.
-
-Performance::
-When configured correctly, Log4j can deliver excelling performance without almost any burden on the Java garbage collector.
-This is made possible via an asynchronous logger founded on the https://lmax-exchange.github.io/disruptor/[LMAX Disruptor] technology (having its roots in the demanding industry of financial trading) and the garbage-free features baked at hot paths.
-Check out the xref:manual/performance.adoc[Performance] page for details.
-
-Extensibility::
-Log4j contains a fully-fledged xref:manual/plugins.adoc[plugin support] that users can leverage to extend its functionality.
-You can easily add your own components (layouts, appenders, filters, etc.) or customizing existing ones (e.g., adding new directives to the xref:manual/layouts.adoc#PatternLayout[Pattern] or xref:manual/json-template-layout.adoc#extending[JSON Template Layout]).
-Check out the xref:manual/extending.adoc[Extending Log4j] page.
+Below, we share some highlights from Log4j features.
+
+include::partial$log4j-features.adoc[]

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

@@ -16,122 +16,52 @@
 ////
 = Manual
 
-== Welcome to Log4j!
-
-Almost every large application includes its own logging or tracing API.
-In conformance with this rule, the E.U. http://www.semper.org[SEMPER]
-project decided to write its own tracing API. This was in early 1996.
-After countless enhancements, several incarnations and much work that
-API has evolved to become log4j, a popular logging package for Java. The
-package is distributed under the https://www.apache.org/licenses/LICENSE-2.0[Apache Software
-License], a fully-fledged open source license certified by the
-http://www.opensource.org[open source] initiative. The latest log4j
-version, including full-source code, class files and documentation can
-be found at
-https://logging.apache.org/log4j/2.x/index.html[*https://logging.apache.org/log4j/2.x/index.html*].
-
-Inserting log statements into code is a low-tech method for debugging
-it. It may also be the only way because debuggers are not always
-available or applicable. This is usually the case for multithreaded
-applications and distributed applications at large.
-
-Experience indicates that logging was an important component of the
-development cycle. It offers several advantages. It provides precise
-_context_ about a run of the application. Once inserted into the code,
-the generation of logging output requires no human intervention.
-Moreover, log output can be saved in persistent medium to be studied at
-a later time. In addition to its use in the development cycle, a
-sufficiently rich logging package can also be viewed as an auditing
-tool.
-
-As Brian W. Kernighan and Rob Pike put it in their truly excellent book
-_"The Practice of Programming":_
-
-____
-As personal choice, we tend not to use debuggers beyond getting a stack
-trace or the value of a variable or two. One reason is that it is easy
-to get lost in details of complicated data structures and control flow;
-we find stepping through a program less productive than thinking harder
-and adding output statements and self-checking code at critical places.
-Clicking over statements takes longer than scanning the output of
-judiciously-placed displays. It takes less time to decide where to put
-print statements than to single-step to the critical section of code,
-even assuming we know where that is. More important, debugging
-statements stay with the program; debugging sessions are transient.
-____
-
-Logging does have its drawbacks. It can slow down an application. If too
-verbose, it can cause scrolling blindness. To alleviate these concerns,
-log4j is designed to be reliable, fast and extensible. Since logging is
-rarely the main focus of an application, the log4j API strives to be
-simple to understand and to use.
-
-== Log4j 2
-
-Log4j 1 has been widely adopted and used in many applications.
-However, through the years development on it has slowed down. It has
-become more difficult to maintain due to its need to be compliant with
-very old versions of Java and became
-https://blogs.apache.org/foundation/entry/apache_logging_services_project_announces[End
-of Life] in August 2015. Its alternative, SLF4J/Logback made many needed
-improvements to the framework. So why bother with Log4j 2? Here are a
-few of the reasons.
-
-1. Log4j 2 is designed to be usable as an audit logging framework. Both
-Log4j 1.x and Logback will lose events while reconfiguring. Log4j 2 will
-not. In Logback, exceptions in Appenders are never visible to the
-application. In Log4j 2 Appenders can be configured to allow the
-exception to percolate to the application.
-2. Log4j 2 contains next-generation xref:manual/async.adoc[Asynchronous
-Loggers] based on the https://lmax-exchange.github.io/disruptor/[LMAX
-Disruptor library]. In multi-threaded scenarios Asynchronous Loggers
-have 10 times higher throughput and orders of magnitude lower latency
-than Log4j 1.x and Logback.
-3. Log4j 2 is xref:manual/garbagefree.adoc[garbage free] for stand-alone
-applications, and low garbage for web applications during steady state
-logging. This reduces pressure on the garbage collector and can give
-better response time performance.
-4. Log4j 2 uses a xref:manual/plugins.adoc[Plugin system] that makes it
-extremely easy to xref:manual/extending.adoc[extend the framework] by adding
-new xref:manual/appenders.adoc[Appenders], xref:manual/filters.adoc[Filters],
-xref:manual/layouts.adoc[Layouts], xref:manual/lookups.adoc[Lookups], and Pattern
-Converters without requiring any changes to Log4j.
-5. Due to the Plugin system configuration is simpler. Entries in the
-configuration do not require a class name to be specified.
-6. Support for xref:manual/customloglevels.adoc[custom log levels]. Custom log
-levels can be defined in code or in configuration.
-7. Support for xref:manual/api.adoc#LambdaSupport[lambda expressions]. Client
-code running on Java 8 can use lambda expressions to lazily construct a
-log message only if the requested log level is enabled. Explicit level
-checks are not needed, resulting in cleaner code.
-8. Support for xref:manual/messages.adoc[Message objects]. Messages allow
-support for interesting and complex constructs to be passed through the
-logging system and be efficiently manipulated. Users are free to create
-their own `Message` types and write custom xref:manual/layouts.adoc[Layouts],
-xref:manual/filters.adoc[Filters] and xref:manual/lookups.adoc[Lookups] to manipulate
-them.
-9. Log4j 1.x supports Filters on Appenders. Logback added TurboFilters
-to allow filtering of events before they are processed by a Logger.
-Log4j 2 supports Filters that can be configured to process events before
-they are handled by a Logger, as they are processed by a Logger or on an
-Appender.
-10. Many Logback Appenders do not accept a Layout and will only send
-data in a fixed format. Most Log4j 2 Appenders accept a Layout, allowing
-the data to be transported in any format desired.
-11. Layouts in Log4j 1.x and Logback return a String. This resulted in
-the problems discussed at
-http://logback.qos.ch/manual/encoders.html[Logback Encoders]. Log4j 2
-takes the simpler approach that xref:manual/layouts.adoc[Layouts] always return
-a byte array. This has the advantage that it means they can be used in
-virtually any Appender, not just the ones that write to an OutputStream.
-12. The xref:manual/appenders.adoc#SyslogAppender[Syslog Appender] supports
-both TCP and UDP as well as support for the BSD syslog and the
-http://tools.ietf.org/html/rfc5424[RFC 5424] formats.
-13. Log4j 2 takes advantage of Java 5 concurrency support and performs
-locking at the lowest level possible. Log4j 1.x has known deadlock
-issues. Many of these are fixed in Logback but many Logback classes
-still require synchronization at a fairly high level.
-14. It is an Apache Software Foundation project following the community
-and support model used by all ASF projects. If you want to contribute or
-gain the right to commit changes just follow the path outlined at
-http://jakarta.apache.org/site/contributing.html[Contributing].
+== Welcome to Apache Log4j!
+
+Apache Log4j is a versatile, industrial-grade Java logging framework composed of an API, its implementation, and components to assist the deployment for various use cases.
+Log4j is https://security.googleblog.com/2021/12/apache-log4j-vulnerability.html[used by 8% of the Maven ecosystem] and listed as one of https://docs.google.com/spreadsheets/d/1ONZ4qeMq8xmeCHX03lIgIYE4MEXVfVL6oj05lbuXTDM/edit#gid=1024997528[the top 100 critical open source software projects].
+The project is actively maintained by a {logging-services-url}/team-list.html[team] of several volunteers and {logging-services-url}/support[support]ed by a big community.
+
+Logging is an essential part of the software development process. 
+It provides a way to track the flow of execution in a program, allowing developers 
+to understand the application's behavior without needing a debugger. 
+This is particularly useful when tracking bugs or understanding why a particular code runs slowly.
+
+The original concept for Log4j was conceived in early 1996 when the 
+E.U. SEMPER project decided to develop its own tracing API. 
+In 2003, the project was donated to the Apache Software Foundation, which became Apache Log4j. 
+
+Since then, Log4j has seen numerous releases and has become a widely adopted solution.
+
+== When should you use Log4j?
+
+Log4j is an excellent choice for any Java application that needs logging capabilities. 
+It is user-friendly, fast, and flexible. You can use it to log messages at 
+different levels of severity, from debug to fatal, and you can configure it to 
+log messages to various destinations, such as files, databases, or the console.
+
+== When not to use Log4j?
+
+While Log4j is a highly suitable choice for many applications, 
+it may be challenging to locate the information you require when 
+logging a high volume of messages. 
+Additionally, logging can impact your application's performance.
+
+Log4j offers solutions to address these concerns. However, if you are in 
+a unique situation where you are concerned about logging overhead or volume, you may wish 
+to consider not using logging at all.
+
+== What does Log4j offer?
+
+Log4j offers numerous features, including:
+
+include::partial$log4j-features.adoc[]
+
+== How to learn more?
+
+* 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/migration.adoc[How can I migrate from Log4j 1 to Log4j 2]?
+* xref:manual/plugins.adoc[What are Log4j plugins] and xref:manual/extending.adoc[how can I use them to extend Log4j?]

src/site/antora/modules/ROOT/partials/log4j-features.adoc

@@ -0,0 +1,47 @@
+////
+ 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.
+////
+
+Batteries included::
+Log4j bundles a rich set of components to assist various use cases.
+* xref:manual/appenders.adoc[Appenders] targeting files, network sockets, databases, SMTP servers, etc.
+* xref:manual/layouts.adoc[Layouts] that can render CSV, HTML, JSON, Syslog, etc. formatted outputs
+* xref:manual/filters.adoc[Filters] based on log event rates, regular expressions, scripts, time, etc.
+* xref:manual/lookups.adoc[Lookups] for accessing system properties, environment variables, log event fields, etc.
+
+API separation::
+The API for Log4j (i.e., `log4j-api`) is separate from the implementation (i.e., `log4j-core`), making it straightforward for application developers which classes and methods to use while ensuring forward compatibility.
+(See xref:manual/api-separation.adoc[API Separation] for details.)
+The Log4j API also provides the most feature-rich logging facade in the market; support for various `Message` types (such as `Object` or `Map`) besides plain `String`, lambda expressions, parametrized logging, markers, levels, diagnostic contexts (aka. MDC/NDC), etc.
+Check out the xref:manual/api.adoc[Java API], {logging-services-url}/log4j/kotlin[Kotlin API], and {logging-services-url}/log4j/scala[Scala API] pages for further information.
+
+No vendor lock-in::
+Even though Log4j implements the Log4j API at its fullest, users can use another logging backend.
+This can be achieved by either using another backend implementing the Log4j API or forwarding Log4j API calls to another logging facade (e.g., SLF4J) and using a backend for that particular facade.
+
+Reliability::
+Log4j is built with solid reliability in mind.
+It can automatically reload its configuration upon modification and will do so without losing log events while reconfiguration occurs.
+
+Performance::
+When configured correctly, Log4j can deliver excelling performance without almost any burden on the Java garbage collector, and it will do so without sacrificing reliability.
+This is made possible via an asynchronous logger founded on the https://lmax-exchange.github.io/disruptor/[LMAX Disruptor] technology (having its roots in the demanding industry of financial trading) and the garbage-free features baked at hot paths.
+Check out the xref:manual/performance.adoc[Performance] page for details.
+
+Extensibility::
+Log4j contains a fully-fledged xref:manual/plugins.adoc[plugin support] that users can leverage to extend functionality.
+You can easily add your components (layouts, appenders, filters, etc.) or customize existing ones (e.g., adding new directives to the xref:manual/layouts.adoc#PatternLayout[Pattern] or xref:manual/json-template-layout.adoc#extending[JSON Template Layout]).
+Check out the xref:manual/extending.adoc[Extending Log4j] page.