Rewrote manual intro

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

@@ -16,122 +16,57 @@
 ////
 = 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!
+
+Welcome to Apache Log4j, one of the world's most widely used logging frameworks.
+
+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 trying to track down a bug or understand 
+why a particular piece of code is running slow.
+
+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, becoming 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.
+
+== Benefits of Log4j
+
+Log4j offers numerous advantages, including:
+
+1. **Easy to use**: Log4j is easy to use and configure. You can get started
+   with just a few lines of code.
+2. **Speed**: Log4j is fast and has a low overhead. For more information see: xref:manual/async.adoc[Asynchronous Loggers]
+3. **Reliable**: Log4j is reliable and has been used in many production applications.
+4. **Audit-ready**: Log4j is designed to be a reliable audit logging framework that 
+   does not lose any events, unlike some competing frameworks.
+5. **Small footprint**: Log4j has a small impact on the garbage collector. For details, see: xref:manual/garbagefree.adoc[garbage-free].
+6. **Extensible**: Log4j is designed to be easily extended using a xref:manual/plugins.adoc[plugin system], 
+   allowing users to customize it to xref:manual/extending.adoc[fit their specific needs].
+7. **Modern Syntax**: Log4j supports xref:manual/api.adoc#LambdaSupport[lambda expressions]
+8. **Integration**: Log4j integrates with numerous other frameworks and libraries.
+9. **ASF Standards**: Developed at the Apache Software Foundation, adhering to rigorous standards and best practices.
+
+== How to learn more?
+
+To get started, learn more about the xref:manual/api.adoc[Log4j API] and it's xref:manual/architecture.adoc[architecture.]