You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by sw...@apache.org on 2022/12/17 02:45:24 UTC
[logging-log4cxx] branch improve_documentation created (now f9e4936f)
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a change to branch improve_documentation
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
at f9e4936f Restructure usage documentation. Prevent some doxygen warnings
This branch includes the following new commits:
new f9e4936f Restructure usage documentation. Prevent some doxygen warnings
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[logging-log4cxx] 01/01: Restructure usage documentation. Prevent some doxygen warnings
Posted by sw...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch improve_documentation
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit f9e4936fbd12344b7b8553192d8db72f65483030
Author: Stephen Webb <st...@sabreautonomous.com.au>
AuthorDate: Sat Dec 17 13:45:02 2022 +1100
Restructure usage documentation. Prevent some doxygen warnings
---
src/main/cpp/propertyconfigurator.cpp | 2 +-
src/main/include/log4cxx/appenderskeleton.h | 2 +-
src/main/include/log4cxx/helpers/optionconverter.h | 12 +-
src/main/include/log4cxx/logger.h | 46 ++--
src/main/include/log4cxx/net/smtpappender.h | 4 +-
src/main/include/log4cxx/patternlayout.h | 7 +-
src/main/include/log4cxx/propertyconfigurator.h | 5 +-
src/site/doxy/Doxyfile.in | 30 ---
src/site/markdown/change-report-gh.md | 88 +++-----
src/site/markdown/development/build-cmake.md | 24 +-
src/site/markdown/usage.md | 250 ++++++++++-----------
11 files changed, 212 insertions(+), 258 deletions(-)
diff --git a/src/main/cpp/propertyconfigurator.cpp b/src/main/cpp/propertyconfigurator.cpp
index 221674a6..ea5c340a 100644
--- a/src/main/cpp/propertyconfigurator.cpp
+++ b/src/main/cpp/propertyconfigurator.cpp
@@ -441,7 +441,7 @@ AppenderPtr PropertyConfigurator::parseAppender(
props, prefix, Appender::getStaticClass(), 0);
appender = log4cxx::cast<Appender>( obj );
- // Map obsolete DailyRollingFileAppender propertiy configuration
+ // Map obsolete DailyRollingFileAppender property configuration
if (!appender &&
StringHelper::endsWith(OptionConverter::findAndSubst(prefix, props), LOG4CXX_STR("DailyRollingFileAppender")))
{
diff --git a/src/main/include/log4cxx/appenderskeleton.h b/src/main/include/log4cxx/appenderskeleton.h
index b04c2c05..f91545e2 100644
--- a/src/main/include/log4cxx/appenderskeleton.h
+++ b/src/main/include/log4cxx/appenderskeleton.h
@@ -146,7 +146,7 @@ class LOG4CXX_EXPORT AppenderSkeleton :
/**
Set the layout for this appender. Note that some appenders have
their own (fixed) layouts or do not use one. For example, the
- {@link net::SocketAppender SocketAppender} ignores the layout set
+ {@link net::XMLSocketAppender XMLSocketAppender} ignores the layout set
here.
*/
void setLayout(const LayoutPtr layout1) override;
diff --git a/src/main/include/log4cxx/helpers/optionconverter.h b/src/main/include/log4cxx/helpers/optionconverter.h
index 4b20ac65..6edab8ee 100644
--- a/src/main/include/log4cxx/helpers/optionconverter.h
+++ b/src/main/include/log4cxx/helpers/optionconverter.h
@@ -81,9 +81,9 @@ class LOG4CXX_EXPORT OptionConverter
<p>For example, if the System properties contains "key=value", then
the call
- <pre>
- String s = OptionConverter.substituteVars("Value of key is ${key}.");
- </pre>
+ ~~~{.cpp}
+ auto s = OptionConverter.substituteVars("Value of key is ${key}.");
+ ~~~
will set the variable <code>s</code> to "Value of key is value.".
@@ -94,9 +94,9 @@ class LOG4CXX_EXPORT OptionConverter
<p>For example, if system propeties contains no value for the key
"inexistentKey", then the call
- <pre>
- String s = OptionConverter.subsVars("Value of inexistentKey is [${inexistentKey}]");
- </pre>
+ ~~~{.cpp}
+ auto s = OptionConverter.subsVars("Value of inexistentKey is [${inexistentKey}]");
+ ~~~
will set <code>s</code> to "Value of inexistentKey is []"
<p>An IllegalArgumentException is thrown if
diff --git a/src/main/include/log4cxx/logger.h b/src/main/include/log4cxx/logger.h
index fb42bc64..01882fce 100644
--- a/src/main/include/log4cxx/logger.h
+++ b/src/main/include/log4cxx/logger.h
@@ -953,11 +953,12 @@ class LOG4CXX_EXPORT Logger :
* Is this logger is enabled for <code>DEBUG</code> level logging events?
*
* <p>By writing
- * <pre>
- * if(logger->isDebugEnabled()) {
+ * ~~~{.cpp}
+ * if(logger->isDebugEnabled()) {
* logger->debug("Component: " + std::to_string(componentNumber));
* }
- * </pre>you will not incur the cost of parameter construction
+ * ~~~
+ * you will not incur the cost of parameter construction
* (integer to string conversion plus string concatonation in this case)
* if debugging is disabled for <code>logger</code>.
* You avoid the cost constructing the message
@@ -965,9 +966,9 @@ class LOG4CXX_EXPORT Logger :
*
* <p>This function allows you to reduce the computational cost of
* disabled log debug statements compared to writing:
- * <pre>
+ * ~~~{.cpp}
* logger->debug("Component: " + std::to_string(componentNumber));
- * </pre>
+ * ~~~
*
* <p>On the other hand, if the <code>logger</code> is enabled for <code>DEBUG</code> logging events,
* you will incur the cost of evaluating whether the logger is
@@ -988,11 +989,12 @@ class LOG4CXX_EXPORT Logger :
* Is \c logger is enabled for <code>DEBUG</code> level logging events?
*
* <p>By writing
- * <pre>
+ * ~~~{.cpp}
* if(log4cxx::Logger::isDebugEnabledFor(logger)) {
* logger->forcedLog(log4cxx::Level::getDebug(), "Component: " + std::to_string(componentNumber));
* }
- * </pre>you minimise the computational cost
+ * ~~~
+ * you minimise the computational cost
* when \c logger is not enabled for <code>DEBUG</code> logging events.
* This function may be inlined thereby avoiding a function call
* as well as the cost constructing the message
@@ -1642,7 +1644,7 @@ class LOG4CXX_EXPORT Logger :
/**
Set the level of this logger.
- <p>As in <pre> logger->setLevel(Level::getDebug()); </pre>
+ <p>As in <code>logger->setLevel(Level::getDebug());</code>
<p>Null values are admitted. */
virtual void setLevel(const LevelPtr level);
@@ -1957,7 +1959,7 @@ LOG4CXX_LIST_DEF(LoggerList, LoggerPtr);
/**
-Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events..
+Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events.
@param logger the logger to be used.
@param level the level to log.
@@ -1980,7 +1982,7 @@ Add a new logging event containing libfmt formatted <code>...</code> to attached
logger->forcedLog(level, fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
/**
-Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events..
+Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events.
@param logger the logger to be used.
@param level the level to log.
@@ -1999,7 +2001,7 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message a valid r-value expression of an <code>operator<<(std::basic::ostream&. ...)</code> overload.
<p>Example:
-<pre>
+~~~{.cpp}
LOG4CXX_DEBUG(m_log, "AddMesh:"
<< " name " << meshName
<< " type 0x" << std:: hex << traits.Type
@@ -2008,7 +2010,7 @@ LOG4CXX_DEBUG(m_log, "AddMesh:"
<< " at " << obj->getBoundingBox().getCenter()
<< " +/- " << obj->getBoundingBox().getHalfSize()
);
-</pre>
+~~~
*/
#define LOG4CXX_DEBUG(logger, message) do { \
if (LOG4CXX_UNLIKELY(::log4cxx::Logger::isDebugEnabledFor(logger))) {\
@@ -2037,9 +2039,9 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message a valid r-value expression of an <code>operator<<(std::basic::ostream&. ...)</code> overload.
<p>Example:
-<pre>
+~~~{.cpp}
LOG4CXX_TRACE(m_log, "AddVertex:" << " p " << p[j] << " n " << n << ' ' << color);
-</pre>
+~~~
*/
#define LOG4CXX_TRACE(logger, message) do { \
@@ -2069,14 +2071,14 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message a valid r-value expression of an <code>operator<<(std::basic::ostream&. ...)</code> overload.
<p>Example:
-<pre>
+~~~{.cpp}
LOG4CXX_INFO(m_log, surface->GetName()
<< " successfully planned " << std::fixed << std::setprecision(1) << ((plannedArea / (plannedArea + unplannedArea)) * 100.0) << "%"
<< " planned area " << std::fixed << std::setprecision(4) << plannedArea << "m^2"
<< " unplanned area " << unplannedArea << "m^2"
<< " planned segments " << surface->GetSegmentPlanCount() << " of " << surface->GetSegmentCount()
);
-</pre>
+~~~
*/
#define LOG4CXX_INFO(logger, message) do { \
if (::log4cxx::Logger::isInfoEnabledFor(logger)) {\
@@ -2105,12 +2107,12 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message the message string to log.
<p>Example:
-<pre>
+~~~{.cpp}
catch (const std::exception& ex)
{
LOG4CXX_WARN(m_log, ex.what() << ": in " << m_task->GetParamFilePath());
}
-</pre>
+~~~
*/
#define LOG4CXX_WARN(logger, message) do { \
if (::log4cxx::Logger::isWarnEnabledFor(logger)) {\
@@ -2139,12 +2141,12 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message the message string to log.
<p>Example:
-<pre>
+~~~{.cpp}
catch (std::exception& ex)
{
LOG4CXX_ERROR(m_log, ex.what() << " in AddScanData");
}
-</pre>
+~~~
*/
#define LOG4CXX_ERROR(logger, message) do { \
if (::log4cxx::Logger::isErrorEnabledFor(logger)) {\
@@ -2199,9 +2201,9 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message the message string to log.
<p>Example:
-<pre>
+~~~{.cpp}
LOG4CXX_FATAL(m_log, m_renderSystem->getName() << " is not supported");
-</pre>
+~~~
*/
#define LOG4CXX_FATAL(logger, message) do { \
if (::log4cxx::Logger::isFatalEnabledFor(logger)) {\
diff --git a/src/main/include/log4cxx/net/smtpappender.h b/src/main/include/log4cxx/net/smtpappender.h
index ae878384..d181027d 100644
--- a/src/main/include/log4cxx/net/smtpappender.h
+++ b/src/main/include/log4cxx/net/smtpappender.h
@@ -111,8 +111,8 @@ class LOG4CXX_EXPORT SMTPAppender : public AppenderSkeleton
/**
- The <code>SMTPAppender</code> requires a {@link
- Layout layout}. */
+ The <code>SMTPAppender</code> requires a <code>Layout</code>.
+ */
bool requiresLayout() const override;
/**
diff --git a/src/main/include/log4cxx/patternlayout.h b/src/main/include/log4cxx/patternlayout.h
index 0a555e92..5e3db25f 100644
--- a/src/main/include/log4cxx/patternlayout.h
+++ b/src/main/include/log4cxx/patternlayout.h
@@ -57,10 +57,11 @@ LOG4CXX_LIST_DEF(FormattingInfoList, log4cxx::pattern::FormattingInfoPtr);
* <p>
* Let the conversion pattern be <strong>"%-5p [%t]: %m%n"</strong> and assume that the log4cxx
* environment was set to use a PatternLayout. Then the statements
- * <pre>
- * LoggerPtr root = Logger::getRoot();
+ * ~~~{.cpp}
+ * auto root = Logger::getRootLogger();
* root->debug("Message 1");
- * root->warn("Message 2");</pre>
+ * root->warn("Message 2");
+ * ~~~
* would yield the output
* <pre>
* DEBUG [main]: Message 1
diff --git a/src/main/include/log4cxx/propertyconfigurator.h b/src/main/include/log4cxx/propertyconfigurator.h
index 31d20ab4..38433143 100644
--- a/src/main/include/log4cxx/propertyconfigurator.h
+++ b/src/main/include/log4cxx/propertyconfigurator.h
@@ -335,9 +335,8 @@ class LOG4CXX_EXPORT PropertyConfigurator :
// --------------------------------------------------------------------------
protected:
/**
- Check the provided <code>Properties</code> object for a
- #loggerFactory
- entry specified by LOGGER_FACTORY_KEY. If such an entry
+ Check the provided <code>Properties</code> object for a #LoggerFactory
+ entry specified by *log4j.loggerFactory*. If such an entry
exists, an attempt is made to create an instance using the default
constructor. This instance is used for subsequent Logger creations
within this configurator.
diff --git a/src/site/doxy/Doxyfile.in b/src/site/doxy/Doxyfile.in
index a383fa71..1a867fad 100644
--- a/src/site/doxy/Doxyfile.in
+++ b/src/site/doxy/Doxyfile.in
@@ -259,14 +259,6 @@ ALIASES =
# A mapping has the form "name=value". For example adding "class=itcl::class"
# will allow you to use the command class in the itcl::class meaning.
-TCL_SUBST =
-
-# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
-# only. Doxygen will then generate output that is more tailored for C. For
-# instance, some of the names that are used will be different. The list of all
-# members will be omitted, etc.
-# The default value is: NO.
-
OPTIMIZE_OUTPUT_FOR_C = NO
# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
@@ -1117,13 +1109,6 @@ CLANG_OPTIONS =
ALPHABETICAL_INDEX = YES
-# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in
-# which the alphabetical index list will be split.
-# Minimum value: 1, maximum value: 20, default value: 5.
-# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
-
-COLS_IN_ALPHA_INDEX = 5
-
# In case all classes in a project start with a common prefix, all classes will
# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
# can be used to specify a prefix (or a list of prefixes) that should be ignored
@@ -2185,12 +2170,6 @@ EXTERNAL_GROUPS = YES
EXTERNAL_PAGES = YES
-# The PERL_PATH should be the absolute path and name of the perl script
-# interpreter (i.e. the result of 'which perl').
-# The default file (with absolute path) is: /usr/bin/perl.
-
-PERL_PATH = /usr/bin/perl
-
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
@@ -2204,15 +2183,6 @@ PERL_PATH = /usr/bin/perl
CLASS_DIAGRAMS = YES
-# You can define message sequence charts within doxygen comments using the \msc
-# command. Doxygen will then run the mscgen tool (see:
-# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the
-# documentation. The MSCGEN_PATH tag allows you to specify the directory where
-# the mscgen tool resides. If left empty the tool is assumed to be found in the
-# default search path.
-
-MSCGEN_PATH =
-
# You can include diagrams made with dia in doxygen documentation. Doxygen will
# then run dia to produce the diagram and insert it in the documentation. The
# DIA_PATH tag allows you to specify the directory where the dia binary resides.
diff --git a/src/site/markdown/change-report-gh.md b/src/site/markdown/change-report-gh.md
index 223473e3..ca451c6a 100644
--- a/src/site/markdown/change-report-gh.md
+++ b/src/site/markdown/change-report-gh.md
@@ -25,25 +25,24 @@ Changelog {#changelog}
| Version | Date | Description |
| -------------------------------------------------------------------------------------- | ---------- | -------------------- |
-| [0.13.0](#0.13.0) | 2022-04-15 | Maintenance release |
-| [0.12.1](#0.12.1) | 2021-09-21 | Bugfix for 0.12.0 |
-| [0.12.0](#0.12.0) | 2021-05-01 | First release to require C++11. Updates for smart pointers. Standardization on CMake for building. |
-| [0.11.0](#0.11.0) | 2020-08-09 | Maintenance release. |
-| [0.10.0](#0.10.0) | 2008-04-03 | First Apache release |
-| [0.9.7](#0.9.7) | 2004-05-10 | |
-| [0.9.6](#0.9.6) | 2004-04-11 | |
-| [0.9.5](#0.9.5) | 2004-02-04 | |
-| [0.9.4](#0.9.4) | 2003-10-25 | |
-| [0.9.3](#0.9.3) | 2003-09-19 | |
-| [0.9.2](#0.9.2) | 2003-08-10 | |
-| [0.9.1](#0.9.1) | 2003-08-06 | |
-| [0.9.0](#0.9.0) | 2003-08-06 | |
-| [0.1.1](#0.1.1) | 2003-07-09 | |
-| [0.1.0](#0.1.0) | 2003-07-08 | |
-| [0.0.1](#0.0.1) | 2003-05-31 | |
-
-<a name="0.13.0"/>
-## Release 0.13.0 - 2022-04-15
+| [0.13.0](#rel_13_0) | 2022-04-15 | Maintenance release |
+| [0.12.1](#rel_12_1) | 2021-09-21 | Bugfix for 0.12.0 |
+| [0.12.0](#rel_12_0) | 2021-05-01 | First release to require C++11. Updates for smart pointers. Standardization on CMake for building. |
+| [0.11.0](#rel_11_0) | 2020-08-09 | Maintenance release. |
+| [0.10.0](#rel_10_0) | 2008-04-03 | First Apache release |
+| [0.9.7](#rel_9_7) | 2004-05-10 | |
+| [0.9.6](#rel_9_6) | 2004-04-11 | |
+| [0.9.5](#rel_9_5) | 2004-02-04 | |
+| [0.9.4](#rel_9_4) | 2003-10-25 | |
+| [0.9.3](#rel_9_3) | 2003-09-19 | |
+| [0.9.2](#rel_9_2) | 2003-08-10 | |
+| [0.9.1](#rel_9_1) | 2003-08-06 | |
+| [0.9.0](#rel_9_0) | 2003-08-06 | |
+| [0.1.1](#rel_1_1) | 2003-07-09 | |
+| [0.1.0](#rel_1_0) | 2003-07-08 | |
+| [0.0.1](#rel_0_1) | 2003-05-31 | |
+
+## Release 0.13.0 - 2022-04-15 {#rel_13_0}
This release fixes a number of issues. Notable new features include the
ability to block signals from threads that the library creates, automatic
@@ -111,8 +110,7 @@ Wish
shared\_mutex
-<a name="0.12.0"/>
-## Release 0.12.1 - 2021-09-21
+## Release 0.12.1 - 2021-09-21 {#rel_12_1}
This is a minor bugfix release to fix issues found with 0.12.0. Notably, this version fixes a bug
where a multithreaded application would crash when using a rolling file.
@@ -126,8 +124,7 @@ Bug
log4cxx fails to build on Centos 7.6 / g++ 4.8.5 / Boost 1.53
-<a name="0.12.0"/>
-## Release 0.12.0 - 2021-05-01
+## Release 0.12.0 - 2021-05-01 {#rel_12_0}
This is the first release to require a minimum version of C++11. This means that all objects in log4cxx
are now created using `std::shared_ptr` as the smart pointer implementation.
@@ -189,8 +186,7 @@ Improvement
- \[[LOGCXX-523](https://issues.apache.org/jira/browse/LOGCXX-523)\] -
Add in error handling for rollover errors
-<a name="0.11.0"/>
-### Release 0.11.0 - 2020-08-09
+## Release 0.11.0 - 2020-08-09 {#rel_11_0}
| | | |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -250,7 +246,7 @@ Improvement
|  | Please make sure that the LOG4CXX\_\* macro's can be used as ordinary statements. Fixes [LOGCXX-319](https://issues.apache.org/jira/browse/LOGCXX-319). | |
|  | Log4cxx triggers locking inversion which can result in a deadlock. Fixes [LOGCXX-317](https://issues.apache.org/jira/browse/LOGCXX-317). | |
|  | Build process fails in case of absence of iconv support in apr-util Fixes [LOGCXX-313](https://issues.apache.org/jira/browse/LOGCXX-313). | |
-|  | Property/DOMConfigurator::configureAndWatch can continue to run after APR termination Fixes [LOGCXX-305](https://issues.apache.org/jira/browse/LOGCXX-305). | |
+|  | Property/xml::DOMConfigurator::configureAndWatch can continue to run after APR termination Fixes [LOGCXX-305](https://issues.apache.org/jira/browse/LOGCXX-305). | |
|  | BasicConfigurator::configure results in writer not set warning. Fixes [LOGCXX-304](https://issues.apache.org/jira/browse/LOGCXX-304). | |
|  | DOMConfigurator does not set ErrorHandler. Fixes [LOGCXX-303](https://issues.apache.org/jira/browse/LOGCXX-303). | |
|  | ODBCAppender connection settings broken (or just have changed). Fixes [LOGCXX-300](https://issues.apache.org/jira/browse/LOGCXX-300). | |
@@ -290,8 +286,7 @@ Improvement
|  | Documented C (class) and M (method) log format keywords. | |
|  | LocationInfo for Borland C++ Builder and successors improved. | |
-<a name="0.10.0"/>
-### Release 0.10.0 - 2008-04-03
+## Release 0.10.0 - 2008-04-03 {#rel_10_0}
| | | |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -319,8 +314,8 @@ Improvement
|  | Drop src/performance Fixes [LOGCXX-232](https://issues.apache.org/jira/browse/LOGCXX-232). | |
|  | Deadlock in AsyncAppender Fixes [LOGCXX-231](https://issues.apache.org/jira/browse/LOGCXX-231). | |
|  | Align ant build options with automake Fixes [LOGCXX-230](https://issues.apache.org/jira/browse/LOGCXX-230). | |
-|  | Remove @author tags Fixes [LOGCXX-228](https://issues.apache.org/jira/browse/LOGCXX-228). | |
-|  | Remove @since tags Fixes [LOGCXX-227](https://issues.apache.org/jira/browse/LOGCXX-227). | |
+|  | Remove \@author tags Fixes [LOGCXX-228](https://issues.apache.org/jira/browse/LOGCXX-228). | |
+|  | Remove \@since tags Fixes [LOGCXX-227](https://issues.apache.org/jira/browse/LOGCXX-227). | |
|  | Default configurator uses \*.properties in preference to \*.xml Fixes [LOGCXX-226](https://issues.apache.org/jira/browse/LOGCXX-226). | |
|  | Migrate unit tests from LGPL'd CPPUNIT to an ASL'd testing framework Fixes [LOGCXX-225](https://issues.apache.org/jira/browse/LOGCXX-225). | |
|  | trunk compile error. Fixes [LOGCXX-222](https://issues.apache.org/jira/browse/LOGCXX-222). | |
@@ -501,8 +496,7 @@ Improvement
|  | Missing \#else Fixes [LOGCXX-3](https://issues.apache.org/jira/browse/LOGCXX-3). | |
|  | logger.h includes config.h Fixes [LOGCXX-2](https://issues.apache.org/jira/browse/LOGCXX-2). | |
-<a name="0.9.7"/>
-### Release 0.9.7 - 2004-05-10
+## Release 0.9.7 - 2004-05-10 {#rel_9_7}
| | | |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -517,8 +511,7 @@ Improvement
|  | Logging macros can be used without explicity declaring the use of log4cxx namespace. | |
|  | Fixed static library unresolved externals for msvc 6 and 7.1 | |
-<a name="0.9.6"/>
-### Release 0.9.6 - 2004-04-11
+## Release 0.9.6 - 2004-04-11 {#rel_9_6}
| | | |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -- |
@@ -532,8 +525,7 @@ Improvement
|  | Added TimeZone configuration to PatternLayout (bug 912563) | |
|  | Support of the DailyRollingFileAppender (feature request 842765) | |
-<a name="0.9.5"/>
-### Release 0.9.5 - 2004-02-04
+## Release 0.9.5 - 2004-02-04 {#rel_9_5}
| | | |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -553,8 +545,7 @@ Improvement
|  | Fixed compilations problems with unicode. | |
|  | Fixed SocketAppender bug concerning MDC and NDC. | |
-<a name="0.9.4"/>
-### Release 0.9.4 - 2003-10-25
+## Release 0.9.4 - 2003-10-25 {#rel_9_4}
| | | |
| ------------------------------------------------------------------- | --------------------------------------------------------- | -- |
@@ -565,8 +556,7 @@ Improvement
|  | Fixed threading configuration problems (bug 809125) | |
|  | Fixed miscellaneous MSVC and cygwin compilation problems. | |
-<a name="0.9.3"/>
-### Release 0.9.3 - 2003-09-19
+## Release 0.9.3 - 2003-09-19 {#rel_9_3}
| | | |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -- |
@@ -581,8 +571,7 @@ Improvement
|  | Added new tests | |
|  | Added benchmarks | |
-<a name="0.9.2"/>
-### Release 0.9.2 - 2003-08-10
+## Release 0.9.2 - 2003-08-10 {#rel_9_2}
| | | |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -- |
@@ -592,8 +581,7 @@ Improvement
|  | Long events (\> 1024 chars) are now supported in the class XMLSocketAppender. | |
|  | Carriage returns have been normalized in the class XMLLayout. | |
-<a name="0.9.1"/>
-### Release 0.9.1 - 2003-08-06
+## Release 0.9.1 - 2003-08-06 {#rel_9_1}
| | | |
| ------------------------------------------------------------------- | ------------------------------------------------------------ | -- |
@@ -603,8 +591,7 @@ Improvement
|  | Added MSVC 6.0 static libraty project. | |
|  | Default configuration for the SMTP options is "no". | |
-<a name="0.9.0"/>
-### Release 0.9.0 - 2003-08-06
+## Release 0.9.0 - 2003-08-06 {#rel_9_0}
| | | |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------- | -- |
@@ -619,8 +606,7 @@ Improvement
|  | Added MSVC 6.0 'Unicode Debug' and 'Unicode Release' targets | |
|  | Added Java like System class. | |
-<a name="0.1.1"/>
-### Release 0.1.1 - 2003-07-09
+## Release 0.1.1 - 2003-07-09 {#rel_1_1}
| | | |
| ---------------------------------------------------------------- | ------------------------------------------------------------------- | -- |
@@ -628,8 +614,7 @@ Improvement
|  | Fixed MSVC 6.0 compilation problems concerning the 'Release' target | |
|  | Added MSVC 6.0 tests projects | |
-<a name="0.1.0"/>
-### Release 0.1.0 - 2003-07-08
+## Release 0.1.0 - 2003-07-08 {#rel_1_0}
| | | |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -645,8 +630,7 @@ Improvement
|  | Port of the "Map Diagnostic Context" (MDC) class | |
|  | Added 13 tests (try make check) | |
-<a name="0.0.1"/>
-### Release 0.0.1 - 2003-05-31
+## Release 0.0.1 - 2003-05-31 {#rel_0_1}
| | | |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
diff --git a/src/site/markdown/development/build-cmake.md b/src/site/markdown/development/build-cmake.md
index b8837a5b..242430b9 100644
--- a/src/site/markdown/development/build-cmake.md
+++ b/src/site/markdown/development/build-cmake.md
@@ -43,19 +43,19 @@ $ sudo make install
Windows Example:
Building and testing Log4cxx on a Microsoft Windows with APR, Expat and APR-Util built from source
-extracted into apr-1.7.0, libexpat(from github) and apr-util-1.6.1 in %HOMEPATH%\Libraries.
+extracted into apr-1.7.0, libexpat(from github) and apr-util-1.6.1 in %HOMEPATH%/Libraries.
~~~
-$ cd %HOMEPATH%\Libraries
-$ cmake -S libexpat\expat -B buildtrees\expat -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
-$ cmake --build buildtrees\expat --target install --config Release
-$ cmake -S apr-1.7.0 -B buildtrees\apr -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
-$ cmake --build buildtrees\apr --target install --config Release
-$ set CMAKE_PREFIX_PATH=%HOMEPATH%\Libraries\installed
-$ cmake -S apr-util-1.6.1 -B buildtrees\apr-util -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
-$ cmake --build buildtrees\apr-util --target install --config Release
-$ cmake -S apache-Log4cxx-x.x.x -B buildtrees\Log4cxx -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
-$ cmake --build buildtrees\Log4cxx --target install --config Release
+$ cd %HOMEPATH%/Libraries
+$ cmake -S libexpat/expat -B buildtrees/expat -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed
+$ cmake --build buildtrees/expat --target install --config Release
+$ cmake -S apr-1.7.0 -B buildtrees/apr -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed
+$ cmake --build buildtrees/apr --target install --config Release
+$ set CMAKE_PREFIX_PATH=%HOMEPATH%/Libraries/installed
+$ cmake -S apr-util-1.6.1 -B buildtrees/apr-util -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed
+$ cmake --build buildtrees/apr-util --target install --config Release
+$ cmake -S apache-Log4cxx-x.x.x -B buildtrees/Log4cxx -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed
+$ cmake --build buildtrees/Log4cxx --target install --config Release
~~~
## ccmake options
@@ -136,7 +136,7 @@ The easiest way to get dependencies installed is to use vcpkg(for APR/expat), an
utilities(zip, grep, sed).
Msys2 can be downloaded from: https://www.msys2.org/
-By default, this will be installed under C:\msys2, so you can add that to the build PATH by setting
+By default, this will be installed under C:\\msys2, so you can add that to the build PATH by setting
LOG4CXX_TEST_PROGRAM_PATH=C:/msys64/usr/bin in your build settings.
For vcpkg, follow the directions at https://github.com/microsoft/vcpkg#quick-start-windows and then install
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index 2e9053b8..5a169ad1 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -1,4 +1,4 @@
-Usage {#usage}
+Loggers, Appenders and Layouts {#usage}
===
<!--
Note: License header cannot be first, as doxygen does not generate
@@ -22,14 +22,12 @@ Usage {#usage}
-->
[TOC]
-# Loggers {#loggers}
-
Log4cxx has three main components: *loggers*, *appenders* and *layouts*.
These three types of components work together to enable developers to
log messages according to message type and level, and to control at
runtime how these messages are formatted and where they are reported.
-## Hierarchy {#hierarchy}
+# Hierarchy {#hierarchy}
The first and foremost advantage of any logging API over plain
`std::cout` resides in its ability to disable certain log statements
@@ -89,7 +87,7 @@ Some of the basic methods in the Logger class are listed below.
#define LOG4CXX_FATAL(logger, expression) ...
~~~
-## Levels {#levels}
+# Levels {#levels}
Loggers *may* be assigned levels. The pre-defined levels: TRACE, DEBUG,
INFO, WARN, ERROR and FATAL are defined in the
@@ -162,7 +160,7 @@ In example 4, the loggers *root* and *X* and are assigned the levels
their level value from their nearest parent *X* having an assigned
level.
-## Requests {#requests}
+# Requests {#requests}
Logging requests are made by invoking a method of a logger instance,
preferrably through the use of LOG4CXX\_INFO or similar macros which
@@ -261,7 +259,7 @@ name the loggers as desired.
Nevertheless, naming loggers after the class where they are located
seems to be the best strategy known so far.
-# Appenders and Layouts {#appenders-and-layouts}
+# Appenders {#appenders}
The ability to selectively enable or disable logging requests based on
their logger is only part of the picture. Log4cxx allows logging
@@ -292,7 +290,7 @@ appender accumulation is no longer additive by
The rules governing appender additivity are summarized below.
-## Appender Additivity {#additivity}
+## Additivity {#appender-additivity}
The output of a log statement of logger *C* will go to all the appenders
in *C* and its ancestors. This is the meaning of the term "appender
@@ -416,7 +414,24 @@ is invoked on the first call to the com::foo::getLogger() function
and its destructor is automatically called during application exit.
\include com/foo/config1.cpp
-## Request Formatting {#formatting}
+## Default Initialization {#default-initialization}
+
+The Log4cxx library does not make any assumptions about its environment.
+In particular, when initially created the root [Logger](@ref log4cxx.Logger) has no appender.
+However the library will attempt automatic configuration.
+
+If the LoggerRepositoy is not yet configured on the first call to
+[getLogger](@ref log4cxx.LogManager.getLogger) of [LogManager](@ref log4cxx.LogManager),
+the [configure](@ref log4cxx.DefaultConfigurator.configure) method
+of [DefaultConfigurator](@ref log4cxx.DefaultConfigurator) is called
+via [ensureIsConfigured](@ref log4cxx.spi.LoggerRepository.ensureIsConfigured) method
+of [LoggerRepository](@ref log4cxx.spi.LoggerRepository).
+
+To use automatic configuration with a non-standard file name
+create and use your own wrapper for [getLogger](@ref log4cxx.LogManager.getLogger).
+A full example can be seen in the \ref UserLib/logmanager.cpp file.
+
+# Layouts {#layouts}
The invocation of the
[BasicConfigurator::configure](@ref log4cxx.BasicConfigurator.configure)
@@ -518,37 +533,6 @@ forwarded logging events to a remote Log4cxx server, which would log
according to local server policy, for example by forwarding the log
event to a second Log4cxx server.
-## Default Initialization {#default-initialization}
-
-The Log4cxx library does not make any assumptions about its environment.
-In particular, when initially created the root [Logger](@ref log4cxx.Logger) has no appender.
-However the library will attempt automatic configuration.
-
-If the LoggerRepositoy is not yet configured on the first call to
-[getLogger](@ref log4cxx.LogManager.getLogger) of [LogManager](@ref log4cxx.LogManager),
-the [configure](@ref log4cxx.DefaultConfigurator.configure) method
-of [DefaultConfigurator](@ref log4cxx.DefaultConfigurator) is called
-via [ensureIsConfigured](@ref log4cxx.spi.LoggerRepository.ensureIsConfigured) method
-of [LoggerRepository](@ref log4cxx.spi.LoggerRepository).
-
-To use automatic configuration with a non-standard file name
-create and use your own wrapper for [getLogger](@ref log4cxx.LogManager.getLogger).
-A full example can be seen in the \ref UserLib/logmanager.cpp file.
-
-# Internal Debugging {#internal-debugging}
-
-Because Log4cxx is a logging library, we can't use it to output errors from
-the library itself. There are several ways to activate internal logging:
-
-1. Configure the library directly by calling the
-[LogLog::setInternalDebugging](@ref log4cxx.helpers.LogLog.setInternalDebugging)
-method
-2. If using a properties file, set the value `log4j.debug=true` in your configuration file
-3. If using an XML file, set the attribute `internalDebug=true` in the root node
-4. From the environment: `LOG4CXX_DEBUG=true`
-
-All error and warning messages are sent to stderr.
-
# Nested Diagnostic Contexts {#nested-diagnostic-contexts}
Most real-world systems have to deal with multiple clients
@@ -617,7 +601,106 @@ Log4cxx releases support multiple hierarchy trees. This enhancement
allows each virtual host to possess its own copy of the logger
hierarchy.
-# Performance {#performance}
+# Logging Custom Types {#custom-types}
+
+Often, the data that needs to be logged is not just standard data types
+(such as int, string, etc), but amalgamations of those types in a data
+structure such as a class or struct. In order to log these custom types,
+simply override an `operator<<` function, the same as if you would
+print the custom type to `std::cout`. This can be accomplished by
+doing the following:
+
+~~~{.cpp}
+struct MyStruct {
+ int x;
+};
+
+std::ostream& operator<<( std::ostream& stream, const MyStruct& mystruct ){
+ stream << "[MyStruct x:" << mystruct.x << "]";
+ return stream;
+}
+
+void someMethod(){
+ MyStruct mine;
+ mine.x = 90;
+ LOG4CXX_INFO( logger, "Some important information: " << mine );
+}
+~~~
+
+This will output data similar to the following:
+
+~~~
+0 [0x7fd1eed63bc0] INFO root null - Some important information: [MyStruct x:90]
+~~~
+
+# Logging with {fmt} {#logging-with-fmt}
+
+One issue with utilizing Log4cxx and its ostream style of logging is that log
+statements can be very awkward if you need to precisely format something:
+
+~~~{.cpp}
+LOG4CXX_INFO( rootLogger, "Numbers can be formatted with excessive operator<<: "
+ << std::setprecision(3) << 22.456
+ << " And as hex: "
+ << std::setbase( 16 ) << 123 );
+~~~
+
+This leads to very awkward code to read and write, especially as iostreams don't
+support positional arguments at all.
+
+In order to get around this, one popular library(that has been standardized as
+part of C++20) is [{fmt}](https://fmt.dev/latest/index.html). Supporting
+positional arguments and printf-like formatting, it makes for much clearer
+code like the following:
+
+~~~{.cpp}
+LOG4CXX_INFO_FMT( rootLogger, "Numbers can be formatted with a format string {:.1f} and as hex: {:x}", 22.456, 123 );
+~~~
+
+Note that Log4cxx does not include a copy of {fmt}, so you must include the
+correct headers and linker flags in order to use the `LOG4CXX_[level]_FMT`
+family of macros.
+
+As with the standard logger macros, these macros will also be compiled out
+if the `LOG4CXX_THRESHOLD` macro is set to a level that will compile out
+the non-FMT macros.
+
+A full example can be seen in the \ref format-string.cpp file.
+
+# Filtering Messages {#filtering}
+
+When dealing with large amounts of logging information, it can be useful
+to filter on messages that we are interested in. This filtering only
+takes places after determining that the level of the current logger would
+log the message in the first place. When defining filters, note that
+they can only be defined on a per-appender basis, they do not globally
+affect anything.
+
+The filtering system is similar in concept to Linux iptables rules, in
+that there is a chain of filters that can accept a log message, deny the
+log message, or pass the message on to the next filter. Accepting a log
+message means that the message will be logged immediately without
+consulting other filters. Denying has the opposite affect, immediately
+dropping the log message and not consulting any other filters.
+
+See the documentation for [Filter](@ref log4cxx.spi.Filter) for some more
+information, or view a [configuration sample](@ref configuration-samples).
+
+# Internal Debugging {#internal-debugging}
+
+Because Log4cxx is a logging library, we can't use it to output errors from
+the library itself. There are several ways to activate internal logging:
+
+1. Configure the library directly by calling the
+[LogLog::setInternalDebugging](@ref log4cxx.helpers.LogLog.setInternalDebugging)
+method
+2. If using a properties file, set the value `log4j.debug=true` in your configuration file
+3. If using an XML file, set the attribute `internalDebug=true` in the root node
+4. From the environment: `LOG4CXX_DEBUG=true`
+
+All error and warning messages are sent to stderr.
+
+# Performance {#request-cost}
One of the often-cited arguments against logging is its computational
cost. This is a legitimate concern as even moderately sized applications
@@ -704,91 +787,6 @@ statements, define `LOG4CXX_DISABLE_LOCATION_INFO` in your build system. This
will allow log messages to still be created, but the location information
will be invalid.
-# Logging Custom Types {#custom-types}
-
-Often, the data that needs to be logged is not just standard data types
-(such as int, string, etc), but amalgamations of those types in a data
-structure such as a class or struct. In order to log these custom types,
-simply override an `operator<<` function, the same as if you would
-print the custom type to `std::cout`. This can be accomplished by
-doing the following:
-
-~~~{.cpp}
-struct MyStruct {
- int x;
-};
-
-std::ostream& operator<<( std::ostream& stream, const MyStruct& mystruct ){
- stream << "[MyStruct x:" << mystruct.x << "]";
- return stream;
-}
-
-void someMethod(){
- MyStruct mine;
- mine.x = 90;
- LOG4CXX_INFO( logger, "Some important information: " << mine );
-}
-~~~
-
-This will output data similar to the following:
-
-~~~
-0 [0x7fd1eed63bc0] INFO root null - Some important information: [MyStruct x:90]
-~~~
-
-# Logging with {fmt} {#logging-with-fmt}
-
-One issue with utilizing Log4cxx and its ostream style of logging is that log
-statements can be very awkward if you need to precisely format something:
-
-~~~{.cpp}
-LOG4CXX_INFO( rootLogger, "Numbers can be formatted with excessive operator<<: "
- << std::setprecision(3) << 22.456
- << " And as hex: "
- << std::setbase( 16 ) << 123 );
-~~~
-
-This leads to very awkward code to read and write, especially as iostreams don't
-support positional arguments at all.
-
-In order to get around this, one popular library(that has been standardized as
-part of C++20) is [{fmt}](https://fmt.dev/latest/index.html). Supporting
-positional arguments and printf-like formatting, it makes for much clearer
-code like the following:
-
-~~~{.cpp}
-LOG4CXX_INFO_FMT( rootLogger, "Numbers can be formatted with a format string {:.1f} and as hex: {:x}", 22.456, 123 );
-~~~
-
-Note that Log4cxx does not include a copy of {fmt}, so you must include the
-correct headers and linker flags in order to use the `LOG4CXX_[level]_FMT`
-family of macros.
-
-As with the standard logger macros, these macros will also be compiled out
-if the `LOG4CXX_THRESHOLD` macro is set to a level that will compile out
-the non-FMT macros.
-
-A full example can be seen in the \ref format-string.cpp file.
-
-# Filtering Messages {#filtering}
-
-When dealing with large amounts of logging information, it can be useful
-to filter on messages that we are interested in. This filtering only
-takes places after determining that the level of the current logger would
-log the message in the first place. When defining filters, note that
-they can only be defined on a per-appender basis, they do not globally
-affect anything.
-
-The filtering system is similar in concept to Linux iptables rules, in
-that there is a chain of filters that can accept a log message, deny the
-log message, or pass the message on to the next filter. Accepting a log
-message means that the message will be logged immediately without
-consulting other filters. Denying has the opposite affect, immediately
-dropping the log message and not consulting any other filters.
-
-See the documentation for [Filter](@ref log4cxx.spi.Filter) for some more
-information, or view a [configuration sample](@ref configuration-samples).
-
# Conclusions {#conclusions}
Apache Log4cxx is a popular logging package written in C++. One of its