Merge pull request #49 from rm5248/documentation-updates
Documentation updates
Moves website over to Doxygen, as well as adding a number of pieces of documentation in order to make it clearer how to use log4cxx.
diff --git a/.gitignore b/.gitignore
index dbaf83a..a845dd5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@
ar-lib
config**
+!configuration-samples.md
depcomp
install-sh
liblog4cxx.pc
diff --git a/CMakeLists.txt b/CMakeLists.txt
index b728ff7..63cbfe5 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -7,6 +7,8 @@
# (at least in the past it was project vesion: 0.a.b.c and the library so vesion a.b.c.0
set(LIBLOG4CXX_LIB_VERSION ${log4cxx_VERSION_MINOR}.${log4cxx_VERSION_PATCH}.${log4cxx_VERSION_TWEAK})
set(LIBLOG4CXX_LIB_SOVERSION ${log4cxx_VERSION_MINOR})
+# Set the 'release' version. This is the human-readable version
+set(LOG4CXX_RELEASE_VERSION ${log4cxx_VERSION_MAJOR}.${log4cxx_VERSION_MINOR}.${log4cxx_VERSION_PATCH})
# FindAPR and FindAPR-util are not provided by APR and APR-Util so source them locally
list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/src/cmake")
@@ -104,6 +106,25 @@
endforeach()
#
+# Package and sign if Apache maintainer
+#
+option(APACHE_MAINTAINER "Apache maintainer" OFF)
+if(APACHE_MAINTAINER)
+ set(CPACK_SOURCE_PACKAGE_FILE_NAME "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}")
+ set(CPACK_SOURCE_GENERATOR "TGZ;ZIP")
+ set(CPACK_SOURCE_IGNORE_FILES ".git/;build/;.vs/;out/")
+ include(CPack)
+
+ add_custom_target( dist
+ COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} -- package_source
+ COMMAND ${CMAKE_COMMAND} -E sha512sum "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz" > "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.sha512"
+ COMMAND ${CMAKE_COMMAND} -E sha512sum "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip" > "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.sha512"
+ COMMAND gpg -ab --yes "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz" > "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc"
+ COMMAND gpg -ab --yes "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip" > "apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.asc"
+ )
+endif()
+
+#
# Output configuration information
# Similar to APR CMake configuration
#
@@ -114,6 +135,7 @@
message(STATUS " Build shared library ............ : ${BUILD_SHARED_LIBS}")
message(STATUS " Build tests ..................... : ${BUILD_TESTING}")
+message(STATUS " Build site ...................... : ${BUILD_SITE}")
message(STATUS " Install prefix .................. : ${CMAKE_INSTALL_PREFIX}")
message(STATUS " C++ compiler .................... : ${CMAKE_CXX_COMPILER}")
message(STATUS " log4cxx char API ................ : ${LOG4CXX_CHAR}")
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index b1be4ee..283283c 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -14,3 +14,5 @@
add_subdirectory(test)
add_subdirectory(examples/cpp)
endif()
+
+add_subdirectory(site)
diff --git a/src/examples/cpp/CMakeLists.txt b/src/examples/cpp/CMakeLists.txt
index 05614b3..4677ebb 100644
--- a/src/examples/cpp/CMakeLists.txt
+++ b/src/examples/cpp/CMakeLists.txt
@@ -1,4 +1,4 @@
-set(ALL_LOG4CXX_EXAMPLES console delayedloop stream trivial)
+set(ALL_LOG4CXX_EXAMPLES console delayedloop stream trivial custom-appender)
foreach(exampleName IN LISTS ALL_LOG4CXX_EXAMPLES)
add_executable(${exampleName} ${exampleName}.cpp)
@@ -6,3 +6,7 @@
target_include_directories(${exampleName} PRIVATE ${CMAKE_CURRENT_LIST_DIR} $<TARGET_PROPERTY:log4cxx,INCLUDE_DIRECTORIES>)
target_link_libraries(${exampleName} PRIVATE log4cxx ${APR_UTIL_LIBRARIES} ${XMLLIB_LIBRARIES} ${APR_LIBRARIES} ${APR_SYSTEM_LIBS})
endforeach()
+
+configure_file( custom-appender.xml
+ ${CMAKE_CURRENT_BINARY_DIR}/custom-appender.xml
+ COPYONLY )
diff --git a/src/examples/cpp/custom-appender.cpp b/src/examples/cpp/custom-appender.cpp
new file mode 100644
index 0000000..5154090
--- /dev/null
+++ b/src/examples/cpp/custom-appender.cpp
@@ -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.
+ */
+
+#include <stdlib.h>
+#include <log4cxx/basicconfigurator.h>
+#include <log4cxx/helpers/object.h>
+#include <log4cxx/appenderskeleton.h>
+#include <log4cxx/helpers/stringhelper.h>
+#include <log4cxx/xml/domconfigurator.h>
+
+namespace log4cxx {
+
+class NullWriterAppender : public log4cxx::AppenderSkeleton {
+public:
+ DECLARE_LOG4CXX_OBJECT(NullWriterAppender)
+ BEGIN_LOG4CXX_CAST_MAP()
+ LOG4CXX_CAST_ENTRY(NullWriterAppender)
+ LOG4CXX_CAST_ENTRY_CHAIN(AppenderSkeleton)
+ END_LOG4CXX_CAST_MAP()
+
+ NullWriterAppender(){}
+
+ virtual void close(){}
+
+ virtual bool requiresLayout() const {
+ return false;
+ }
+
+ virtual void append(const spi::LoggingEventPtr& event, log4cxx::helpers::Pool& p){
+ // This gets called whenever there is a valid event for our appender.
+ }
+
+ virtual void activateOptions(log4cxx::helpers::Pool& /* pool */) {
+ // Given all of our options, do something useful(e.g. open a file)
+ }
+
+ virtual void setOption(const LogString& option, const LogString& value){
+ if (helpers::StringHelper::equalsIgnoreCase(option,
+ LOG4CXX_STR("SOMEVALUE"), LOG4CXX_STR("somevalue"))){
+ // Do something with the 'value' here.
+ }
+ }
+};
+
+IMPLEMENT_LOG4CXX_OBJECT(NullWriterAppender)
+
+}
+
+int main( int argc, char** argv ){
+ log4cxx::xml::DOMConfigurator::configure( "custom-appender.xml" );
+
+ log4cxx::LoggerPtr rootLogger = log4cxx::Logger::getRootLogger();
+ log4cxx::LoggerPtr nullLogger = log4cxx::Logger::getLogger( "NullLogger" );
+
+ LOG4CXX_INFO( rootLogger, "This is some root message" );
+ LOG4CXX_INFO( nullLogger, "This message will be discarded" );
+}
diff --git a/src/examples/cpp/custom-appender.xml b/src/examples/cpp/custom-appender.xml
new file mode 100644
index 0000000..f7b40e8
--- /dev/null
+++ b/src/examples/cpp/custom-appender.xml
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
+ <appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
+ <param name="Target" value="System.out"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%n"/>
+ </layout>
+ </appender>
+
+ <appender name="NullAppender" class="NullWriterAppender">
+ <param name="SomeValue" value="Nothing"/>
+ </appender>
+
+ <root>
+ <priority value="info" />
+ <appender-ref ref="ConsoleAppender"/>
+ </root>
+
+ <logger name="NullLogger" additivity="false">
+ <appender-ref ref="NullAppender"/>
+ </logger>
+</log4j:configuration>
diff --git a/src/site/CMakeLists.txt b/src/site/CMakeLists.txt
new file mode 100644
index 0000000..d83949e
--- /dev/null
+++ b/src/site/CMakeLists.txt
@@ -0,0 +1,15 @@
+option(BUILD_SITE "Build log4cxx website" OFF)
+if(BUILD_SITE)
+ find_package( Doxygen REQUIRED dot )
+ configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/doxy/Doxyfile.in
+ ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile )
+
+ configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/markdown/download.md.in
+ ${CMAKE_CURRENT_BINARY_DIR}/markdown/download.md )
+
+ add_custom_target( doc_doxygen ALL
+ COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Generate site with Doxygen"
+ VERBATIM )
+endif()
diff --git a/src/site/apt/building/cmake.apt b/src/site/apt/building/cmake.apt
deleted file mode 100644
index 9bfb794..0000000
--- a/src/site/apt/building/cmake.apt
+++ /dev/null
@@ -1,147 +0,0 @@
-~~ 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.
- ------
- Building Apache log4cxx with CMake
- ------
- ------
- ------
-
-Building Apache log4cxx with CMake
-
-* Quick start:
-
- Building and testing log4cxx on a Unix platform with packaged APR and APR-Util.
-
- Make sure cmake 3.13+, g++ and make are available, install or
- build apr 1.x, apr-util 1.x, gzip and zip.
-
-+------------+
-$ apt-get install build-essential libapr1-dev libaprutil1-dev gzip zip
-$ cd apache-log4cxx-x.x.x
-$ mkdir build
-$ cd build
-$ ccmake ..
-$ make
-$ sudo make install
-+------------+
-
-* ccmake options
-
-*------------------------+---------------------------------------------------------------------------------------------+
-| -DLOG4CXX_WCHAR_T=no | Enable wchar_t API methods, choice of yes (default), no. |
-*------------------------+---------------------------------------------------------------------------------------------+
-| -DLOG4CXX_UNICHAR=yes | Enable UniChar API methods, choice of yes, no (default). |
-*------------------------+---------------------------------------------------------------------------------------------+
-| -DLOG4CXX_CFSTRING=yes | Enable CFString API methods, requires Mac OS/X CoreFoundation, choice of yes, no (default). |
-*------------------------+---------------------------------------------------------------------------------------------+
-| -DBUILD_TESTING=off | Do not build tests. Tests are built by default |
-*------------------------+---------------------------------------------------------------------------------------------+
-| -DBUILD_SHARED_LIBS=off| Build log4cxx as a static library. A dynamically linked log4cxx library is built by default.|
-| | Any compilation unit that includes a log4cxx header must define LOG4CXX_STATIC. |
-*------------------------+---------------------------------------------------------------------------------------------+
-| -DAPU_STATIC=yes | Link to the APR-Util static library. By default, the log4cxx shared library is linked to the|
-| | APR-Util shared library. If BUILD_SHARED_LIBS=off, the static APR-Util library is used. |
-*------------------------+---------------------------------------------------------------------------------------------+
-| -DAPR_STATIC=yes | Link to the APR static library. By default, the log4cxx shared library is linked to the |
-| | APR shared library. If BUILD_SHARED_LIBS=off, the static APR library is always used. |
-*------------------------+---------------------------------------------------------------------------------------------+
-|-DLOG4CXX_TEST_PROGRAM_PATH=path| An extra path to prepend to the PATH for test programs. Log4cxx requires zip, |
-| | sed, and grep on the PATH in order for the tests to work properly. |
-*------------------------+---------------------------------------------------------------------------------------------+
-
- 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.
-
-+------------+
-$ 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
-+------------+
-
-* Platform specific notes:
-
-** Mac OS/X:
-
- APR and APR-Util are provided by the platform in Mac OS/X 10.5 and iODBC in 10.4.
-
- cmake can be installed by typing "brew install cmake".
-
-** Debian:
-
- APR, APR-Util, openssl, gzip and zip may be installed by:
-
-+----+
-$ sudo apt-get install libssl-dev libapr1-dev libaprutil1-dev gzip zip
-+----+
-
- CMake can be built from source by typing:
-
-+----+
-$ wget https://github.com/Kitware/CMake/releases/download/v3.16.4/cmake-3.16.4.tar.gz
-$ tar xf cmake-3.16.4.tar.gz
-$ cd cmake-3.16.4
-$ ./bootstrap
-$ make
-$ sudo make install
-+----+
-
-** FreeBSD:
-
- APR, APR-Util, gzip and zip may be installed from the ports collection by:
-
-+----+
-$ cd /usr/ports/archivers/zip
-$ make
-$ make install
-$ cd /usr/ports/archivers/gzip
-$ make
-$ make install
-$ cd /usr/ports/devel/apr
-$ make
-$ make install
-+----+
-
-** Windows:
-
-The easiest way to get dependencies installed is to use vcpkg(for APR/expat), and msys2 for the command-line
-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
-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
-the dependencies needed using `vcpkg install apr apr-util`.
-
-* Using log4cxx in a CMake build
-
- A log4cxxConfig.cmake and log4cxxConfigVersion.cmake is installed to allow use of find_package()
- in your CMakeLists.txt.
-
- Below are example cmake commands that compile and link "myApplication" with log4cxx.
-
-+----+
-find_package(log4cxx 0.11)
-add_executable(myApplication myMain.cpp)
-target_include_directories(myApplication PRIVATE $<TARGET_PROPERTY:log4cxx,INTERFACE_INCLUDE_DIRECTORIES>)
-target_link_libraries( myApplication PRIVATE log4cxx)
-+----+
diff --git a/src/site/apt/building/vcpkg.apt b/src/site/apt/building/vcpkg.apt
deleted file mode 100644
index 4c3bdec..0000000
--- a/src/site/apt/building/vcpkg.apt
+++ /dev/null
@@ -1,43 +0,0 @@
-~~ 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.
- ------
- Building Apache log4cxx with vcpkg
- ------
- ------
- ------
-
-Building Apache log4cxx with vcpkg
-
-*Preparation
-
-+----+
- > git clone https://github.com/Microsoft/vcpkg.git
- > cd vcpkg
-
- PS> .\bootstrap-vcpkg.bat
- Linux:~/$ ./bootstrap-vcpkg.sh
-
- Then, to hook up user-wide integration, run (note: requires admin on first use)
-
- PS> .\vcpkg integrate install
- Linux:~/$ ./vcpkg integrate install
-+----+
-
-*Building log4cxx.dll
-
-+----+
- PS> .\vcpkg install log4cxx
- Linux:~/$ ./vcpkg install log4cxx
-+----+
diff --git a/src/site/apt/community/issue-tracking.apt b/src/site/apt/community/issue-tracking.apt
deleted file mode 100644
index 745923b..0000000
--- a/src/site/apt/community/issue-tracking.apt
+++ /dev/null
@@ -1,48 +0,0 @@
-~~ 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.
- ------
-Issue Tracking
- ------
- ------
- ------
-
-Overview
-
- This project uses {{{https://www.atlassian.com/software/jira}JIRA}}, a J2EE-based issue tracking
- and project management application.
-
-Issue Tracking
-
- <<Bugs>> and <<feature requests>> should be submitted to the following issue tracking system
- for this project.
-
- {{{https://issues.apache.org/jira/browse/LOGCXX}https://issues.apache.org/jira/browse/LOGCXX}}
-
- <<Please don't just open bugs only because things don't work for you>>, some issues simply
- don't are bugs in the code base of the project or it's build tools, but may have a lot of
- different other reasons. If things don't work for you and you need some help, please subscribe
- to the {{{https://logging.apache.org/log4cxx/mail-lists.html}users mailing list}} and describe
- the issue you have, the more detailed the better. The mailing list is a far better place to
- discuss things than JIRA, besides that there are more users than developers of the project and
- issues created in JIRA are only forwarded to the latter. There's always the chance to create an
- issue in JIRA later, hopefully with a specific explanation of the problem and even a solution
- already.
-
- As a rule of thumb, if you already digged through the code and found a problem in it or its
- build tools, feel free to directly create a bug in {{{https://issues.apache.org/jira/browse/LOGCXX}JIRA}}.
- But if things really only don't work and you don't have any clue why, please use the {{{https://logging.apache.org/log4cxx/mail-lists.html}users mailing listt}}
- instead.
-
- Thanks!
\ No newline at end of file
diff --git a/src/site/apt/download.apt.vm b/src/site/apt/download.apt.vm
deleted file mode 100644
index 6b6bdeb..0000000
--- a/src/site/apt/download.apt.vm
+++ /dev/null
@@ -1,58 +0,0 @@
-~~ 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.
- ------
-Download Apache log4cxx ${releaseVersion}
- ------
- ------
- ------
-
-Download Apache log4cxx ${releaseVersion}
-
- Apache log4cxx ${releaseVersion} is distributed under the {{{https://www.apache.org/licenses/LICENSE-2.0.html} Apache License, version 2.0}}.
-
- The link in the Mirrors column should display a list of available mirrors with a
- default selection based on your inferred location. If you do not see that page,
- try a different browser. The checksum and signature are links to
- the originals on the main distribution server.
-
-*-------------------------+---------+----------+-----------+
-| | Mirrors | Checksum | Signature |
-*-------------------------+---------+----------+-----------+
-| Apache log4cxx ${releaseVersion} (tar.gz) | {{{https://www.apache.org/dyn/closer.cgi/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.tar.gz} ${releaseArtifactId}-${releaseVersion}.tar.gz}} | {{{https://www.apache.org/dist/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.tar.gz.sha512} ${releaseArtifactId}-${releaseVersion}.tar.gz.sha512}} | {{{https://www.apache.org/dist/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.tar.gz.asc} ${releaseArtifactId}-${releaseVersion}.tar.gz.asc}} |
-*-------------------------+---------+----------+-----------+
-| Apache log4cxx ${releaseVersion} (zip) | {{{https://www.apache.org/dyn/closer.cgi/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.zip} ${releaseArtifactId}-${releaseVersion}.zip}} | {{{https://www.apache.org/dist/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.zip.sha512} ${releaseArtifactId}-${releaseVersion}.zip.sha512}} | {{{https://www.apache.org/dist/logging/log4cxx/${releaseVersion}/${releaseArtifactId}-${releaseVersion}.zip.asc} ${releaseArtifactId}-${releaseVersion}.zip.asc}} |
-*-------------------------+---------+----------+-----------+
-
- It is essential that you verify the integrity of the downloaded files using the PGP or SHA512 signatures.
- Please read {{{https://httpd.apache.org/dev/verification.html}Verifying Apache HTTP Server Releases}} for more
- information on why you should verify our releases.
-
- The PGP signatures can be verified using PGP or GPG. First download the {{{https://www.apache.org/dist/logging/KEYS}KEYS}}
- as well as the asc signature file for the relevant distribution. Make sure you get these files from the
- {{{https://www.apache.org/dist/logging/}main distribution directory}}, rather than from a mirror. Then verify the signatures using:
-
----
-% gpg --import KEYS
-% gpg --verify ${releaseArtifactId}-${releaseVersion}.tar.gz.asc ${releaseArtifactId}-${releaseVersion}.tar.gz
----
-
- * ${releaseArtifactId}-${releaseVersion} is signed by ${releaseManager} (${releaseKey})
-
- Alternatively, you can verify the SHA512 signature on the files. A unix program called sha512 or sha512sum is included
- in many unix distributions.
-
-* Previous Releases
-
- All previous releases of Apache log4cxx can be found in the {{{https://archive.apache.org/dist/logging/log4cxx}archive repository}}.
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
deleted file mode 100644
index 4eb49dd..0000000
--- a/src/site/apt/index.apt
+++ /dev/null
@@ -1,45 +0,0 @@
-~~ 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.
- ------
-Short introduction to Apache log4cxx
- ------
- ------
- ------
-
-Short introduction to Apache log4cxx
-
- Apache log4cxx is a logging framework for C++ patterned after
- {{{https://logging.apache.org/log4j}Apache log4j}}, which uses
- {{{https://apr.apache.org}Apache Portable Runtime}} for most platform-specific code and should
- be usable on any platform supported by APR. Apache log4cxx is licensed under the
- {{{https://www.apache.org/licenses}Apache License}}, an open source license certified by the
- {{{https://www.opensource.org}Open Source Initiative}}.
-
- Almost every large application includes its own logging or tracing API. 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 is 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.
-
- Logging does have its drawbacks. It can slow down an application. If too verbose, it can cause
- scrolling blindness. To alleviate these concerns, log4cxx is designed to be reliable, fast and
- extensible. Since logging is rarely the main focus of an application, the log4cxx API strives
- to be simple to understand and to use.
diff --git a/src/site/doxy/Doxyfile.in b/src/site/doxy/Doxyfile.in
index 37c21f4..989a935 100644
--- a/src/site/doxy/Doxyfile.in
+++ b/src/site/doxy/Doxyfile.in
@@ -13,7 +13,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
#
-# Doxyfile 1.8.6
+# Doxyfile 1.8.13
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project.
@@ -53,7 +53,7 @@
# could be handy for archiving the generated documentation or if some version
# control system is used.
-PROJECT_NUMBER = "Version @version@"
+PROJECT_NUMBER = "Version ${LOG4CXX_RELEASE_VERSION}"
# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
@@ -61,10 +61,10 @@
PROJECT_BRIEF =
-# With the PROJECT_LOGO tag one can specify an logo or icon that is included in
-# the documentation. The maximum height of the logo should not exceed 55 pixels
-# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo
-# to the output directory.
+# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
+# in the documentation. The maximum height of the logo should not exceed 55
+# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
+# the logo to the output directory.
PROJECT_LOGO =
@@ -73,9 +73,9 @@
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
-OUTPUT_DIRECTORY = .
+OUTPUT_DIRECTORY =
-# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub-
+# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
# directories (in 2 levels) under the output directory of each output format and
# will distribute the generated files over these directories. Enabling this
# option can be useful when feeding doxygen a huge amount of source files, where
@@ -85,6 +85,14 @@
CREATE_SUBDIRS = NO
+# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII
+# characters to appear in the names of generated files. If set to NO, non-ASCII
+# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode
+# U+3044.
+# The default value is: NO.
+
+ALLOW_UNICODE_NAMES = NO
+
# The OUTPUT_LANGUAGE tag is used to specify the language in which all
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
@@ -100,14 +108,14 @@
OUTPUT_LANGUAGE = English
-# If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member
+# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member
# descriptions after the members that are listed in the file and class
# documentation (similar to Javadoc). Set to NO to disable this.
# The default value is: YES.
BRIEF_MEMBER_DESC = YES
-# If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief
+# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief
# description of a member or function before the detailed description
#
# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
@@ -125,7 +133,17 @@
# the entity):The $name class, The $name widget, The $name file, is, provides,
# specifies, contains, represents, a, an and the.
-ABBREVIATE_BRIEF =
+ABBREVIATE_BRIEF = "The $name class" \
+ "The $name widget" \
+ "The $name file" \
+ is \
+ provides \
+ specifies \
+ contains \
+ represents \
+ a \
+ an \
+ the
# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
# doxygen will generate a detailed section even if there is only a brief
@@ -142,7 +160,7 @@
INLINE_INHERITED_MEMB = NO
-# If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path
+# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path
# before files name in the file list and in the header files. If set to NO the
# shortest path that makes the file name unique will be used
# The default value is: YES.
@@ -212,9 +230,9 @@
INHERIT_DOCS = YES
-# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a
-# new page for each member. If set to NO, the documentation of a member will be
-# part of the file/class/namespace that contains it.
+# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new
+# page for each member. If set to NO, the documentation of a member will be part
+# of the file/class/namespace that contains it.
# The default value is: NO.
SEPARATE_MEMBER_PAGES = NO
@@ -276,11 +294,14 @@
# extension. Doxygen has a built-in mapping, but you can override or extend it
# using this tag. The format is ext=language, where ext is a file extension, and
# language is one of the parsers supported by doxygen: IDL, Java, Javascript,
-# C#, C, C++, D, PHP, Objective-C, Python, Fortran, VHDL. For instance to make
-# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C
-# (default is Fortran), use: inc=Fortran f=C.
+# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran:
+# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran:
+# Fortran. In the later case the parser tries to guess whether the code is fixed
+# or free formatted code, this is the default for Fortran type files), VHDL. For
+# instance to make doxygen treat .inc files as Fortran files (default is PHP),
+# and .f files as C (default is Fortran), use: inc=Fortran f=C.
#
-# Note For files without extension you can use no_extension as a placeholder.
+# Note: For files without extension you can use no_extension as a placeholder.
#
# Note that for custom extensions you also need to set FILE_PATTERNS otherwise
# the files are not read by doxygen.
@@ -297,10 +318,19 @@
MARKDOWN_SUPPORT = YES
+# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up
+# to that level are automatically included in the table of contents, even if
+# they do not have an id attribute.
+# Note: This feature currently applies only to Markdown headings.
+# Minimum value: 0, maximum value: 99, default value: 0.
+# This tag requires that the tag MARKDOWN_SUPPORT is set to YES.
+
+TOC_INCLUDE_HEADINGS = 0
+
# When enabled doxygen tries to link words that correspond to documented
# classes, or namespaces to their corresponding documentation. Such a link can
-# be prevented in individual cases by by putting a % sign in front of the word
-# or globally by setting AUTOLINK_SUPPORT to NO.
+# be prevented in individual cases by putting a % sign in front of the word or
+# globally by setting AUTOLINK_SUPPORT to NO.
# The default value is: YES.
AUTOLINK_SUPPORT = YES
@@ -313,7 +343,7 @@
# diagrams that involve STL classes more complete and accurate.
# The default value is: NO.
-BUILTIN_STL_SUPPORT = YES
+BUILTIN_STL_SUPPORT = NO
# If you use Microsoft's C++/CLI language, you should set this option to YES to
# enable parsing support.
@@ -340,13 +370,20 @@
IDL_PROPERTY_SUPPORT = YES
# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
-# tag is set to YES, then doxygen will reuse the documentation of the first
+# tag is set to YES then doxygen will reuse the documentation of the first
# member in the group (if any) for the other members of the group. By default
# all members of a group must be documented explicitly.
# The default value is: NO.
DISTRIBUTE_GROUP_DOC = NO
+# If one adds a struct or class to a group and this option is enabled, then also
+# any nested class or struct is added to the same group. By default this option
+# is disabled and one has to add nested compounds explicitly via \ingroup.
+# The default value is: NO.
+
+GROUP_NESTED_COMPOUNDS = NO
+
# Set the SUBGROUPING tag to YES to allow class member groups of the same type
# (for instance a group of public functions) to be put as a subgroup of that
# type (e.g. under the Public Functions section). Set it to NO to prevent
@@ -405,7 +442,7 @@
# Build related configuration options
#---------------------------------------------------------------------------
-# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
+# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in
# documentation are documented, even if no documentation was available. Private
# class members and static file members will be hidden unless the
# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
@@ -413,37 +450,37 @@
# normally produced when WARNINGS is set to YES.
# The default value is: NO.
-EXTRACT_ALL = YES
+EXTRACT_ALL = NO
-# If the EXTRACT_PRIVATE tag is set to YES all private members of a class will
+# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation.
# The default value is: NO.
EXTRACT_PRIVATE = NO
-# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal
+# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
# scope will be included in the documentation.
# The default value is: NO.
EXTRACT_PACKAGE = NO
-# If the EXTRACT_STATIC tag is set to YES all static members of a file will be
+# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be
# included in the documentation.
# The default value is: NO.
-EXTRACT_STATIC = YES
+EXTRACT_STATIC = NO
-# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined
-# locally in source files will be included in the documentation. If set to NO
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
+# locally in source files will be included in the documentation. If set to NO,
# only classes defined in header files are included. Does not have any effect
# for Java sources.
# The default value is: YES.
-EXTRACT_LOCAL_CLASSES = NO
+EXTRACT_LOCAL_CLASSES = YES
-# This flag is only useful for Objective-C code. When set to YES local methods,
+# This flag is only useful for Objective-C code. If set to YES, local methods,
# which are defined in the implementation section but not in the interface are
-# included in the documentation. If set to NO only methods in the interface are
+# included in the documentation. If set to NO, only methods in the interface are
# included.
# The default value is: NO.
@@ -468,21 +505,21 @@
# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
# undocumented classes that are normally visible in the class hierarchy. If set
-# to NO these classes will be included in the various overviews. This option has
-# no effect if EXTRACT_ALL is enabled.
+# to NO, these classes will be included in the various overviews. This option
+# has no effect if EXTRACT_ALL is enabled.
# The default value is: NO.
HIDE_UNDOC_CLASSES = NO
# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
-# (class|struct|union) declarations. If set to NO these declarations will be
+# (class|struct|union) declarations. If set to NO, these declarations will be
# included in the documentation.
# The default value is: NO.
HIDE_FRIEND_COMPOUNDS = NO
# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
-# documentation blocks found inside the body of a function. If set to NO these
+# documentation blocks found inside the body of a function. If set to NO, these
# blocks will be appended to the function's detailed documentation block.
# The default value is: NO.
@@ -496,26 +533,33 @@
INTERNAL_DOCS = NO
# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file
-# names in lower-case letters. If set to YES upper-case letters are also
+# names in lower-case letters. If set to YES, upper-case letters are also
# allowed. This is useful if you have classes or files whose names only differ
# in case and if your file system supports case sensitive file names. Windows
# and Mac users are advised to set this option to NO.
# The default value is: system dependent.
-CASE_SENSE_NAMES = NO
+CASE_SENSE_NAMES = YES
# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with
-# their full class and namespace scopes in the documentation. If set to YES the
+# their full class and namespace scopes in the documentation. If set to YES, the
# scope will be hidden.
# The default value is: NO.
-HIDE_SCOPE_NAMES = YES
+HIDE_SCOPE_NAMES = NO
+
+# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will
+# append additional text to a page's title, such as Class Reference. If set to
+# YES the compound reference will be hidden.
+# The default value is: NO.
+
+HIDE_COMPOUND_REFERENCE= NO
# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of
# the files that are included by a file in the documentation of that file.
# The default value is: YES.
-SHOW_INCLUDE_FILES = NO
+SHOW_INCLUDE_FILES = YES
# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
# grouped member an include statement to the documentation, telling the reader
@@ -538,14 +582,14 @@
# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
# (detailed) documentation of file and class members alphabetically by member
-# name. If set to NO the members will appear in declaration order.
+# name. If set to NO, the members will appear in declaration order.
# The default value is: YES.
SORT_MEMBER_DOCS = YES
# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
# descriptions of file, namespace and class members alphabetically by member
-# name. If set to NO the members will appear in declaration order. Note that
+# name. If set to NO, the members will appear in declaration order. Note that
# this will also influence the order of the classes in the class list.
# The default value is: NO.
@@ -590,32 +634,30 @@
STRICT_PROTO_MATCHING = NO
-# The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the
-# todo list. This list is created by putting \todo commands in the
-# documentation.
+# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo
+# list. This list is created by putting \todo commands in the documentation.
# The default value is: YES.
GENERATE_TODOLIST = YES
-# The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the
-# test list. This list is created by putting \test commands in the
-# documentation.
+# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
+# list. This list is created by putting \test commands in the documentation.
# The default value is: YES.
GENERATE_TESTLIST = YES
-# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug
+# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug
# list. This list is created by putting \bug commands in the documentation.
# The default value is: YES.
GENERATE_BUGLIST = YES
-# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO)
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)
# the deprecated list. This list is created by putting \deprecated commands in
# the documentation.
# The default value is: YES.
-GENERATE_DEPRECATEDLIST= NO
+GENERATE_DEPRECATEDLIST= YES
# The ENABLED_SECTIONS tag can be used to enable conditional documentation
# sections, marked by \if <section_label> ... \endif and \cond <section_label>
@@ -635,8 +677,8 @@
MAX_INITIALIZER_LINES = 30
# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at
-# the bottom of the documentation of classes and structs. If set to YES the list
-# will mention the files that were used to generate the documentation.
+# the bottom of the documentation of classes and structs. If set to YES, the
+# list will mention the files that were used to generate the documentation.
# The default value is: YES.
SHOW_USED_FILES = YES
@@ -676,7 +718,7 @@
# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
# tag is left empty.
-LAYOUT_FILE =
+LAYOUT_FILE = ${CMAKE_SOURCE_DIR}/src/site/doxy/DoxygenLayout.xml
# The CITE_BIB_FILES tag can be used to specify one or more bib files containing
# the reference definitions. This must be a list of .bib files. The .bib
@@ -684,8 +726,7 @@
# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info.
# For LaTeX the style of the bibliography can be controlled using
# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the
-# search path. Do not use file names with spaces, bibtex cannot handle them. See
-# also \cite for info how to create references.
+# search path. See also \cite for info how to create references.
CITE_BIB_FILES =
@@ -701,7 +742,7 @@
QUIET = NO
# The WARNINGS tag can be used to turn on/off the warning messages that are
-# generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES
+# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
# this implies that the warnings are on.
#
# Tip: Turn warnings on while writing the documentation.
@@ -709,12 +750,12 @@
WARNINGS = YES
-# If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate
+# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
# will automatically be disabled.
# The default value is: YES.
-WARN_IF_UNDOCUMENTED = NO
+WARN_IF_UNDOCUMENTED = YES
# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
# potential errors in the documentation, such as not documenting some parameters
@@ -726,12 +767,18 @@
# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
# are documented, but have no documentation for their parameters or return
-# value. If set to NO doxygen will only warn about wrong or incomplete parameter
-# documentation, but not about the absence of documentation.
+# value. If set to NO, doxygen will only warn about wrong or incomplete
+# parameter documentation, but not about the absence of documentation.
# The default value is: NO.
WARN_NO_PARAMDOC = NO
+# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
+# a warning is encountered.
+# The default value is: NO.
+
+WARN_AS_ERROR = NO
+
# The WARN_FORMAT tag determines the format of the warning messages that doxygen
# can produce. The string should contain the $file, $line, and $text tags, which
# will be replaced by the file and line number from which the warning originated
@@ -755,11 +802,12 @@
# The INPUT tag is used to specify the files and/or directories that contain
# documented source files. You may enter file names like myfile.cpp or
# directories like /usr/src/myproject. Separate the files or directories with
-# spaces.
+# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
-INPUT = @base_dir@/src/main/include \
- @base_dir@/target/mainpage.dox
+INPUT = ${CMAKE_SOURCE_DIR}/src/main/include \
+ ${CMAKE_SOURCE_DIR}/src/site/markdown \
+ ${CMAKE_BINARY_DIR}/src/site/markdown
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -772,14 +820,62 @@
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and
-# *.h) to filter out the source-files in the directories. If left blank the
-# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii,
-# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp,
-# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown,
-# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
-# *.qsf, *.as and *.js.
+# *.h) to filter out the source-files in the directories.
+#
+# Note that for custom extensions or not directly supported extensions you also
+# need to set EXTENSION_MAPPING for the extension otherwise the files are not
+# read by doxygen.
+#
+# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp,
+# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h,
+# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc,
+# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08,
+# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf.
-FILE_PATTERNS = *.h
+FILE_PATTERNS = *.c \
+ *.cc \
+ *.cxx \
+ *.cpp \
+ *.c++ \
+ *.java \
+ *.ii \
+ *.ixx \
+ *.ipp \
+ *.i++ \
+ *.inl \
+ *.idl \
+ *.ddl \
+ *.odl \
+ *.h \
+ *.hh \
+ *.hxx \
+ *.hpp \
+ *.h++ \
+ *.cs \
+ *.d \
+ *.php \
+ *.php4 \
+ *.php5 \
+ *.phtml \
+ *.inc \
+ *.m \
+ *.markdown \
+ *.md \
+ *.mm \
+ *.dox \
+ *.py \
+ *.pyw \
+ *.f90 \
+ *.f95 \
+ *.f03 \
+ *.f08 \
+ *.f \
+ *.for \
+ *.tcl \
+ *.vhd \
+ *.vhdl \
+ *.ucf \
+ *.qsf
# The RECURSIVE tag can be used to specify whether or not subdirectories should
# be searched for input files as well.
@@ -834,7 +930,7 @@
# *.h) to filter out the source-files in the directories. If left blank all
# files are included.
-EXAMPLE_PATTERNS =
+EXAMPLE_PATTERNS = *
# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
# searched for input files to be used with the \include or \dontinclude commands
@@ -847,7 +943,7 @@
# that contain images that are to be included in the documentation (see the
# \image command).
-IMAGE_PATH =
+IMAGE_PATH = ${CMAKE_SOURCE_DIR}/src/site/images
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
@@ -863,6 +959,10 @@
# Note that the filter must not add or remove lines; it is applied before the
# code is scanned, but not when the output code is generated. If lines are added
# or removed, the anchors will not be placed correctly.
+#
+# Note that for custom extensions or not directly supported extensions you also
+# need to set EXTENSION_MAPPING for the extension otherwise the files are not
+# properly processed by doxygen.
INPUT_FILTER =
@@ -872,11 +972,15 @@
# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how
# filters are used. If the FILTER_PATTERNS tag is empty or if none of the
# patterns match the file name, INPUT_FILTER is applied.
+#
+# Note that for custom extensions or not directly supported extensions you also
+# need to set EXTENSION_MAPPING for the extension otherwise the files are not
+# properly processed by doxygen.
FILTER_PATTERNS =
# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
-# INPUT_FILTER ) will also be used to filter the input files that are used for
+# INPUT_FILTER) will also be used to filter the input files that are used for
# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES).
# The default value is: NO.
@@ -895,7 +999,7 @@
# (index.html). This can be useful if you have a project on for instance GitHub
# and want to reuse the introduction page also for the doxygen output.
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = ${CMAKE_SOURCE_DIR}/src/site/markdown/index.md
#---------------------------------------------------------------------------
# Configuration options related to source browsing
@@ -936,7 +1040,7 @@
REFERENCES_RELATION = NO
# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set
-# to YES, then the hyperlinks from functions in REFERENCES_RELATION and
+# to YES then the hyperlinks from functions in REFERENCES_RELATION and
# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will
# link to the documentation.
# The default value is: YES.
@@ -981,15 +1085,15 @@
# See also: Section \class.
# The default value is: YES.
-VERBATIM_HEADERS = NO
+VERBATIM_HEADERS = YES
-# If the CLANG_ASSISTED_PARSING tag is set to YES, then doxygen will use the
-# clang parser (see: http://clang.llvm.org/) for more acurate parsing at the
+# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the
+# clang parser (see: http://clang.llvm.org/) for more accurate parsing at the
# cost of reduced performance. This can be particularly helpful with template
# rich C++ code for which doxygen's built-in parser lacks the necessary type
# information.
# Note: The availability of this option depends on whether or not doxygen was
-# compiled with the --with-libclang option.
+# generated with the -Duse-libclang=ON option for CMake.
# The default value is: NO.
CLANG_ASSISTED_PARSING = NO
@@ -1018,7 +1122,7 @@
# 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 = 2
+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
@@ -1032,7 +1136,7 @@
# Configuration options related to the HTML output
#---------------------------------------------------------------------------
-# If the GENERATE_HTML tag is set to YES doxygen will generate HTML output
+# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
# The default value is: YES.
GENERATE_HTML = YES
@@ -1043,7 +1147,7 @@
# The default directory is: html.
# This tag requires that the tag GENERATE_HTML is set to YES.
-HTML_OUTPUT = @manual_dest@
+HTML_OUTPUT = html
# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each
# generated HTML page (for example: .htm, .php, .asp).
@@ -1080,7 +1184,7 @@
# that doxygen normally uses.
# This tag requires that the tag GENERATE_HTML is set to YES.
-HTML_FOOTER = @base_dir@/src/site/doxy/license_notice_footer.txt
+HTML_FOOTER = ${CMAKE_SOURCE_DIR}/src/site/doxy/footer.html
# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
# sheet that is used by each HTML page. It can be used to fine-tune the look of
@@ -1094,16 +1198,18 @@
HTML_STYLESHEET =
-# The HTML_EXTRA_STYLESHEET tag can be used to specify an additional user-
-# defined cascading style sheet that is included after the standard style sheets
+# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined
+# cascading style sheets that are included after the standard style sheets
# created by doxygen. Using this option one can overrule certain style aspects.
# This is preferred over using HTML_STYLESHEET since it does not replace the
-# standard style sheet and is therefor more robust against future updates.
-# Doxygen will copy the style sheet file to the output directory. For an example
-# see the documentation.
+# standard style sheet and is therefore more robust against future updates.
+# Doxygen will copy the style sheet files to the output directory.
+# Note: The order of the extra style sheet files is of importance (e.g. the last
+# style sheet in the list overrules the setting of the previous ones in the
+# list). For an example see the documentation.
# This tag requires that the tag GENERATE_HTML is set to YES.
-HTML_EXTRA_STYLESHEET =
+HTML_EXTRA_STYLESHEET = ${CMAKE_SOURCE_DIR}/src/site/doxy/customdoxygen.css
# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the HTML output directory. Note
@@ -1116,7 +1222,7 @@
HTML_EXTRA_FILES =
# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen
-# will adjust the colors in the stylesheet and background images according to
+# will adjust the colors in the style sheet and background images according to
# this color. Hue is specified as an angle on a colorwheel, see
# http://en.wikipedia.org/wiki/Hue for more information. For instance the value
# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300
@@ -1147,8 +1253,9 @@
# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
# page will contain the date and time when the page was generated. Setting this
-# to NO can help when comparing the output of multiple runs.
-# The default value is: YES.
+# to YES can help to show when doxygen was last run and thus if the
+# documentation is up to date.
+# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
HTML_TIMESTAMP = NO
@@ -1244,28 +1351,29 @@
CHM_FILE =
# The HHC_LOCATION tag can be used to specify the location (absolute path
-# including file name) of the HTML help compiler ( hhc.exe). If non-empty
+# including file name) of the HTML help compiler (hhc.exe). If non-empty,
# doxygen will try to run the HTML help compiler on the generated index.hhp.
# The file has to be specified with full path.
# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
HHC_LOCATION =
-# The GENERATE_CHI flag controls if a separate .chi index file is generated (
-# YES) or that it should be included in the master .chm file ( NO).
+# The GENERATE_CHI flag controls if a separate .chi index file is generated
+# (YES) or that it should be included in the master .chm file (NO).
# The default value is: NO.
# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
GENERATE_CHI = NO
-# The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc)
+# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc)
# and project file content.
# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
CHM_INDEX_ENCODING =
-# The BINARY_TOC flag controls whether a binary table of contents is generated (
-# YES) or a normal table of contents ( NO) in the .chm file.
+# The BINARY_TOC flag controls whether a binary table of contents is generated
+# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it
+# enables the Previous and Next buttons.
# The default value is: NO.
# This tag requires that the tag GENERATE_HTMLHELP is set to YES.
@@ -1378,7 +1486,7 @@
# index structure (just like the one that is generated for HTML Help). For this
# to work a browser that supports JavaScript, DHTML, CSS and frames is required
# (i.e. any modern browser). Windows users are probably better off using the
-# HTML help feature. Via custom stylesheets (see HTML_EXTRA_STYLESHEET) one can
+# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can
# further fine-tune the look of the index. As an example, the default style
# sheet generated by doxygen has an example that shows how to put an image at
# the root of the tree instead of the PROJECT_NAME. Since the tree basically has
@@ -1406,7 +1514,7 @@
TREEVIEW_WIDTH = 250
-# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to
+# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to
# external symbols imported via tag files in a separate window.
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
@@ -1435,7 +1543,7 @@
# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see
# http://www.mathjax.org) which uses client side Javascript for the rendering
-# instead of using prerendered bitmaps. Use this if you do not have LaTeX
+# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX
# installed or if you want to formulas look prettier in the HTML output. When
# enabled you may also need to install MathJax separately and configure the path
# to it using the MATHJAX_RELPATH option.
@@ -1505,11 +1613,11 @@
# When the SERVER_BASED_SEARCH tag is enabled the search engine will be
# implemented using a web server instead of a web client using Javascript. There
-# are two flavours of web server based searching depending on the
-# EXTERNAL_SEARCH setting. When disabled, doxygen will generate a PHP script for
-# searching and an index file used by the script. When EXTERNAL_SEARCH is
-# enabled the indexing and searching needs to be provided by external tools. See
-# the section "External Indexing and Searching" for details.
+# are two flavors of web server based searching depending on the EXTERNAL_SEARCH
+# setting. When disabled, doxygen will generate a PHP script for searching and
+# an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing
+# and searching needs to be provided by external tools. See the section
+# "External Indexing and Searching" for details.
# The default value is: NO.
# This tag requires that the tag SEARCHENGINE is set to YES.
@@ -1521,7 +1629,7 @@
# external search engine pointed to by the SEARCHENGINE_URL option to obtain the
# search results.
#
-# Doxygen ships with an example indexer ( doxyindexer) and search engine
+# Doxygen ships with an example indexer (doxyindexer) and search engine
# (doxysearch.cgi) which are based on the open source search engine library
# Xapian (see: http://xapian.org/).
#
@@ -1534,7 +1642,7 @@
# The SEARCHENGINE_URL should point to a search engine hosted by a web server
# which will return the search results when EXTERNAL_SEARCH is enabled.
#
-# Doxygen ships with an example indexer ( doxyindexer) and search engine
+# Doxygen ships with an example indexer (doxyindexer) and search engine
# (doxysearch.cgi) which are based on the open source search engine library
# Xapian (see: http://xapian.org/). See the section "External Indexing and
# Searching" for details.
@@ -1572,7 +1680,7 @@
# Configuration options related to the LaTeX output
#---------------------------------------------------------------------------
-# If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output.
+# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
# The default value is: YES.
GENERATE_LATEX = NO
@@ -1603,7 +1711,7 @@
MAKEINDEX_CMD_NAME = makeindex
-# If the COMPACT_LATEX tag is set to YES doxygen generates more compact LaTeX
+# If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX
# documents. This may be useful for small projects and may help to save some
# trees in general.
# The default value is: NO.
@@ -1618,12 +1726,15 @@
# The default value is: a4.
# This tag requires that the tag GENERATE_LATEX is set to YES.
-PAPER_TYPE = a4wide
+PAPER_TYPE = a4
# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
-# that should be included in the LaTeX output. To get the times font for
-# instance you can specify
-# EXTRA_PACKAGES=times
+# that should be included in the LaTeX output. The package can be specified just
+# by its name or with the correct syntax as to be used with the LaTeX
+# \usepackage command. To get the times font for instance you can specify :
+# EXTRA_PACKAGES=times or EXTRA_PACKAGES={times}
+# To use the option intlimits with the amsmath package you can specify:
+# EXTRA_PACKAGES=[intlimits]{amsmath}
# If left blank no extra packages will be included.
# This tag requires that the tag GENERATE_LATEX is set to YES.
@@ -1637,23 +1748,36 @@
#
# Note: Only use a user-defined header if you know what you are doing! The
# following commands have a special meaning inside the header: $title,
-# $datetime, $date, $doxygenversion, $projectname, $projectnumber. Doxygen will
-# replace them by respectively the title of the page, the current date and time,
-# only the current date, the version number of doxygen, the project name (see
-# PROJECT_NAME), or the project number (see PROJECT_NUMBER).
+# $datetime, $date, $doxygenversion, $projectname, $projectnumber,
+# $projectbrief, $projectlogo. Doxygen will replace $title with the empty
+# string, for the replacement values of the other commands the user is referred
+# to HTML_HEADER.
# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_HEADER =
# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the
# generated LaTeX document. The footer should contain everything after the last
-# chapter. If it is left blank doxygen will generate a standard footer.
+# chapter. If it is left blank doxygen will generate a standard footer. See
+# LATEX_HEADER for more information on how to generate a default footer and what
+# special commands can be used inside the footer.
#
# Note: Only use a user-defined footer if you know what you are doing!
# This tag requires that the tag GENERATE_LATEX is set to YES.
LATEX_FOOTER =
+# The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined
+# LaTeX style sheets that are included after the standard style sheets created
+# by doxygen. Using this option one can overrule certain style aspects. Doxygen
+# will copy the style sheet files to the output directory.
+# Note: The order of the extra style sheet files is of importance (e.g. the last
+# style sheet in the list overrules the setting of the previous ones in the
+# list).
+# This tag requires that the tag GENERATE_LATEX is set to YES.
+
+LATEX_EXTRA_STYLESHEET =
+
# The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or
# other source files which should be copied to the LATEX_OUTPUT output
# directory. Note that the files will be copied as-is; there are no commands or
@@ -1669,15 +1793,15 @@
# The default value is: YES.
# This tag requires that the tag GENERATE_LATEX is set to YES.
-PDF_HYPERLINKS = NO
+PDF_HYPERLINKS = YES
-# If the LATEX_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate
-# the PDF file directly from the LaTeX files. Set this option to YES to get a
+# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate
+# the PDF file directly from the LaTeX files. Set this option to YES, to get a
# higher quality PDF documentation.
# The default value is: YES.
# This tag requires that the tag GENERATE_LATEX is set to YES.
-USE_PDFLATEX = NO
+USE_PDFLATEX = YES
# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode
# command to the generated LaTeX files. This will instruct LaTeX to keep running
@@ -1713,11 +1837,19 @@
LATEX_BIB_STYLE = plain
+# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated
+# page will contain the date and time when the page was generated. Setting this
+# to NO can help when comparing the output of multiple runs.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_LATEX is set to YES.
+
+LATEX_TIMESTAMP = NO
+
#---------------------------------------------------------------------------
# Configuration options related to the RTF output
#---------------------------------------------------------------------------
-# If the GENERATE_RTF tag is set to YES doxygen will generate RTF output. The
+# If the GENERATE_RTF tag is set to YES, doxygen will generate RTF output. The
# RTF output is optimized for Word 97 and may not look too pretty with other RTF
# readers/editors.
# The default value is: NO.
@@ -1732,7 +1864,7 @@
RTF_OUTPUT = rtf
-# If the COMPACT_RTF tag is set to YES doxygen generates more compact RTF
+# If the COMPACT_RTF tag is set to YES, doxygen generates more compact RTF
# documents. This may be useful for small projects and may help to save some
# trees in general.
# The default value is: NO.
@@ -1769,11 +1901,21 @@
RTF_EXTENSIONS_FILE =
+# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code
+# with syntax highlighting in the RTF output.
+#
+# Note that which sources are shown also depends on other settings such as
+# SOURCE_BROWSER.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_RTF is set to YES.
+
+RTF_SOURCE_CODE = NO
+
#---------------------------------------------------------------------------
# Configuration options related to the man page output
#---------------------------------------------------------------------------
-# If the GENERATE_MAN tag is set to YES doxygen will generate man pages for
+# If the GENERATE_MAN tag is set to YES, doxygen will generate man pages for
# classes and files.
# The default value is: NO.
@@ -1797,6 +1939,13 @@
MAN_EXTENSION = .3
+# The MAN_SUBDIR tag determines the name of the directory created within
+# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by
+# MAN_EXTENSION with the initial . removed.
+# This tag requires that the tag GENERATE_MAN is set to YES.
+
+MAN_SUBDIR =
+
# If the MAN_LINKS tag is set to YES and doxygen generates man output, then it
# will generate one additional man file for each entity documented in the real
# man page(s). These additional files only source the real man page, but without
@@ -1810,7 +1959,7 @@
# Configuration options related to the XML output
#---------------------------------------------------------------------------
-# If the GENERATE_XML tag is set to YES doxygen will generate an XML file that
+# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that
# captures the structure of the code including all documentation.
# The default value is: NO.
@@ -1824,7 +1973,7 @@
XML_OUTPUT = xml
-# If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program
+# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program
# listings (including syntax highlighting and cross-referencing information) to
# the XML output. Note that enabling this will significantly increase the size
# of the XML output.
@@ -1837,7 +1986,7 @@
# Configuration options related to the DOCBOOK output
#---------------------------------------------------------------------------
-# If the GENERATE_DOCBOOK tag is set to YES doxygen will generate Docbook files
+# If the GENERATE_DOCBOOK tag is set to YES, doxygen will generate Docbook files
# that can be used to generate PDF.
# The default value is: NO.
@@ -1851,14 +2000,23 @@
DOCBOOK_OUTPUT = docbook
+# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the
+# program listings (including syntax highlighting and cross-referencing
+# information) to the DOCBOOK output. Note that enabling this will significantly
+# increase the size of the DOCBOOK output.
+# The default value is: NO.
+# This tag requires that the tag GENERATE_DOCBOOK is set to YES.
+
+DOCBOOK_PROGRAMLISTING = NO
+
#---------------------------------------------------------------------------
# Configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
-# If the GENERATE_AUTOGEN_DEF tag is set to YES doxygen will generate an AutoGen
-# Definitions (see http://autogen.sf.net) file that captures the structure of
-# the code including all documentation. Note that this feature is still
-# experimental and incomplete at the moment.
+# If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an
+# AutoGen Definitions (see http://autogen.sf.net) file that captures the
+# structure of the code including all documentation. Note that this feature is
+# still experimental and incomplete at the moment.
# The default value is: NO.
GENERATE_AUTOGEN_DEF = NO
@@ -1867,7 +2025,7 @@
# Configuration options related to the Perl module output
#---------------------------------------------------------------------------
-# If the GENERATE_PERLMOD tag is set to YES doxygen will generate a Perl module
+# If the GENERATE_PERLMOD tag is set to YES, doxygen will generate a Perl module
# file that captures the structure of the code including all documentation.
#
# Note that this feature is still experimental and incomplete at the moment.
@@ -1875,7 +2033,7 @@
GENERATE_PERLMOD = NO
-# If the PERLMOD_LATEX tag is set to YES doxygen will generate the necessary
+# If the PERLMOD_LATEX tag is set to YES, doxygen will generate the necessary
# Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI
# output from the Perl module output.
# The default value is: NO.
@@ -1883,9 +2041,9 @@
PERLMOD_LATEX = NO
-# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be nicely
+# If the PERLMOD_PRETTY tag is set to YES, the Perl module output will be nicely
# formatted so it can be parsed by a human reader. This is useful if you want to
-# understand what is going on. On the other hand, if this tag is set to NO the
+# understand what is going on. On the other hand, if this tag is set to NO, the
# size of the Perl module output will be much smaller and Perl will parse it
# just the same.
# The default value is: YES.
@@ -1905,20 +2063,20 @@
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
-# If the ENABLE_PREPROCESSING tag is set to YES doxygen will evaluate all
+# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all
# C-preprocessor directives found in the sources and include files.
# The default value is: YES.
ENABLE_PREPROCESSING = YES
-# If the MACRO_EXPANSION tag is set to YES doxygen will expand all macro names
-# in the source code. If set to NO only conditional compilation will be
+# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
+# in the source code. If set to NO, only conditional compilation will be
# performed. Macro expansion can be done in a controlled way by setting
# EXPAND_ONLY_PREDEF to YES.
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
-MACRO_EXPANSION = YES
+MACRO_EXPANSION = NO
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -1928,7 +2086,7 @@
EXPAND_ONLY_PREDEF = NO
-# If the SEARCH_INCLUDES tag is set to YES the includes files in the
+# If the SEARCH_INCLUDES tag is set to YES, the include files in the
# INCLUDE_PATH will be searched if a #include is found.
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
@@ -1972,9 +2130,9 @@
EXPAND_AS_DEFINED =
# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
-# remove all refrences to function-like macros that are alone on a line, have an
-# all uppercase name, and do not end with a semicolon. Such function macros are
-# typically used for boiler-plate code, and will confuse the parser if not
+# remove all references to function-like macros that are alone on a line, have
+# an all uppercase name, and do not end with a semicolon. Such function macros
+# are typically used for boiler-plate code, and will confuse the parser if not
# removed.
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
@@ -1994,7 +2152,7 @@
# where loc1 and loc2 can be relative or absolute paths or URLs. See the
# section "Linking to external documentation" for more information about the use
# of tag files.
-# Note: Each tag file must have an unique name (where the name does NOT include
+# Note: Each tag file must have a unique name (where the name does NOT include
# the path). If a tag file is not located in the directory in which doxygen is
# run, you must also specify the path to the tagfile here.
@@ -2006,20 +2164,21 @@
GENERATE_TAGFILE =
-# If the ALLEXTERNALS tag is set to YES all external class will be listed in the
-# class index. If set to NO only the inherited external classes will be listed.
+# If the ALLEXTERNALS tag is set to YES, all external class will be listed in
+# the class index. If set to NO, only the inherited external classes will be
+# listed.
# The default value is: NO.
ALLEXTERNALS = NO
-# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed in
-# the modules index. If set to NO, only the current project's groups will be
+# If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will be
# listed.
# The default value is: YES.
EXTERNAL_GROUPS = YES
-# If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in
+# If the EXTERNAL_PAGES tag is set to YES, all external pages will be listed in
# the related pages index. If set to NO, only the current project's pages will
# be listed.
# The default value is: YES.
@@ -2036,7 +2195,7 @@
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
-# If the CLASS_DIAGRAMS tag is set to YES doxygen will generate a class diagram
+# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram
# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to
# NO turns the diagrams off. Note that this option also works with HAVE_DOT
# disabled, but it is recommended to install and use dot, since it yields more
@@ -2061,7 +2220,7 @@
DIA_PATH =
-# If set to YES, the inheritance and collaboration graphs will hide inheritance
+# If set to YES the inheritance and collaboration graphs will hide inheritance
# and usage relations if the target is undocumented or is not a class.
# The default value is: YES.
@@ -2072,7 +2231,7 @@
# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent
# Bell Labs. The other options in this section have no effect if this option is
# set to NO
-# The default value is: NO.
+# The default value is: YES.
HAVE_DOT = NO
@@ -2086,7 +2245,7 @@
DOT_NUM_THREADS = 0
-# When you want a differently looking font n the dot files that doxygen
+# When you want a differently looking font in the dot files that doxygen
# generates you can specify the font name using DOT_FONTNAME. You need to make
# sure dot is able to find the font, which can be done by putting it in a
# standard location or by setting the DOTFONTPATH environment variable or by
@@ -2134,7 +2293,7 @@
GROUP_GRAPHS = YES
-# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
+# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and
# collaboration diagrams in a style similar to the OMG's Unified Modeling
# Language.
# The default value is: NO.
@@ -2186,7 +2345,8 @@
#
# Note that enabling this option will significantly increase the time of a run.
# So in most cases it will be better to enable call graphs for selected
-# functions only using the \callgraph command.
+# functions only using the \callgraph command. Disabling a call graph can be
+# accomplished by means of the command \hidecallgraph.
# The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES.
@@ -2197,7 +2357,8 @@
#
# Note that enabling this option will significantly increase the time of a run.
# So in most cases it will be better to enable caller graphs for selected
-# functions only using the \callergraph command.
+# functions only using the \callergraph command. Disabling a caller graph can be
+# accomplished by means of the command \hidecallergraph.
# The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES.
@@ -2208,7 +2369,7 @@
# The default value is: YES.
# This tag requires that the tag HAVE_DOT is set to YES.
-GRAPHICAL_HIERARCHY = NO
+GRAPHICAL_HIERARCHY = YES
# If the DIRECTORY_GRAPH tag is set to YES then doxygen will show the
# dependencies a directory has on other directories in a graphical way. The
@@ -2220,11 +2381,17 @@
DIRECTORY_GRAPH = YES
# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
-# generated by dot.
+# generated by dot. For an explanation of the image formats see the section
+# output formats in the documentation of the dot tool (Graphviz (see:
+# http://www.graphviz.org/)).
# Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order
# to make the SVG files visible in IE 9+ (other browsers do not have this
# requirement).
-# Possible values are: png, jpg, gif and svg.
+# Possible values are: png, png:cairo, png:cairo:cairo, png:cairo:gd, png:gd,
+# png:gd:gd, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, gif, gif:cairo,
+# gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, png:cairo,
+# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and
+# png:gdiplus:gdiplus.
# The default value is: png.
# This tag requires that the tag HAVE_DOT is set to YES.
@@ -2267,6 +2434,24 @@
DIAFILE_DIRS =
+# When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the
+# path where java can find the plantuml.jar file. If left blank, it is assumed
+# PlantUML is not used or called during a preprocessing step. Doxygen will
+# generate a warning when it encounters a \startuml command in this case and
+# will not generate output for the diagram.
+
+PLANTUML_JAR_PATH =
+
+# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a
+# configuration file for plantuml.
+
+PLANTUML_CFG_FILE =
+
+# When using plantuml, the specified paths are searched for files specified by
+# the !include statement in a plantuml block.
+
+PLANTUML_INCLUDE_PATH =
+
# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes
# that will be shown in the graph. If the number of nodes in a graph becomes
# larger than this value, doxygen will truncate the graph, which is visualized
@@ -2303,7 +2488,7 @@
DOT_TRANSPARENT = NO
-# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
+# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output
# files in one run (i.e. multiple -o and -T options on the command line). This
# makes dot run faster, but since only newer versions of dot (>1.8.10) support
# this, this feature is disabled by default.
@@ -2320,7 +2505,7 @@
GENERATE_LEGEND = YES
-# If the DOT_CLEANUP tag is set to YES doxygen will remove the intermediate dot
+# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot
# files that are used to generate the various graphs.
# The default value is: YES.
# This tag requires that the tag HAVE_DOT is set to YES.
diff --git a/src/site/doxy/DoxygenLayout.xml b/src/site/doxy/DoxygenLayout.xml
new file mode 100644
index 0000000..b51cbac
--- /dev/null
+++ b/src/site/doxy/DoxygenLayout.xml
@@ -0,0 +1,197 @@
+<doxygenlayout version="1.0">
+ <!-- Generated by doxygen 1.8.13 -->
+ <!-- Navigation index tabs for HTML output -->
+ <navindex>
+ <tab type="mainpage" visible="yes" title=""/>
+ <tab type="pages" visible="yes" title="" intro=""/>
+ <tab type="modules" visible="yes" title="" intro=""/>
+ <tab type="namespaces" visible="yes" title="">
+ <tab type="namespacelist" visible="yes" title="" intro=""/>
+ <tab type="namespacemembers" visible="yes" title="" intro=""/>
+ </tab>
+ <tab type="classes" visible="yes" title="">
+ <tab type="classlist" visible="yes" title="" intro=""/>
+ <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
+ <tab type="hierarchy" visible="yes" title="" intro=""/>
+ <tab type="classmembers" visible="yes" title="" intro=""/>
+ </tab>
+ <tab type="files" visible="yes" title="">
+ <tab type="filelist" visible="yes" title="" intro=""/>
+ <tab type="globals" visible="yes" title="" intro=""/>
+ </tab>
+ <tab type="examples" visible="yes" title="" intro=""/>
+ <tab type="user" url="https://www.apache.org" title="Apache"/>
+ <tab type="user" url="https://logging.apache.org" title="Logging Services"/>
+ <tab type="user" url="https://github.com/apache/logging-log4cxx" title="Github"/>
+ </navindex>
+
+ <!-- Layout definition for a class page -->
+ <class>
+ <briefdescription visible="yes"/>
+ <includes visible="$SHOW_INCLUDE_FILES"/>
+ <inheritancegraph visible="$CLASS_GRAPH"/>
+ <collaborationgraph visible="$COLLABORATION_GRAPH"/>
+ <memberdecl>
+ <nestedclasses visible="yes" title=""/>
+ <publictypes title=""/>
+ <services title=""/>
+ <interfaces title=""/>
+ <publicslots title=""/>
+ <signals title=""/>
+ <publicmethods title=""/>
+ <publicstaticmethods title=""/>
+ <publicattributes title=""/>
+ <publicstaticattributes title=""/>
+ <protectedtypes title=""/>
+ <protectedslots title=""/>
+ <protectedmethods title=""/>
+ <protectedstaticmethods title=""/>
+ <protectedattributes title=""/>
+ <protectedstaticattributes title=""/>
+ <packagetypes title=""/>
+ <packagemethods title=""/>
+ <packagestaticmethods title=""/>
+ <packageattributes title=""/>
+ <packagestaticattributes title=""/>
+ <properties title=""/>
+ <events title=""/>
+ <privatetypes title=""/>
+ <privateslots title=""/>
+ <privatemethods title=""/>
+ <privatestaticmethods title=""/>
+ <privateattributes title=""/>
+ <privatestaticattributes title=""/>
+ <friends title=""/>
+ <related title="" subtitle=""/>
+ <membergroups visible="yes"/>
+ </memberdecl>
+ <detaileddescription title=""/>
+ <memberdef>
+ <inlineclasses title=""/>
+ <typedefs title=""/>
+ <enums title=""/>
+ <services title=""/>
+ <interfaces title=""/>
+ <constructors title=""/>
+ <functions title=""/>
+ <related title=""/>
+ <variables title=""/>
+ <properties title=""/>
+ <events title=""/>
+ </memberdef>
+ <allmemberslink visible="yes"/>
+ <usedfiles visible="$SHOW_USED_FILES"/>
+ <authorsection visible="yes"/>
+ </class>
+
+ <!-- Layout definition for a namespace page -->
+ <namespace>
+ <briefdescription visible="yes"/>
+ <memberdecl>
+ <nestednamespaces visible="yes" title=""/>
+ <constantgroups visible="yes" title=""/>
+ <classes visible="yes" title=""/>
+ <typedefs title=""/>
+ <enums title=""/>
+ <functions title=""/>
+ <variables title=""/>
+ <membergroups visible="yes"/>
+ </memberdecl>
+ <detaileddescription title=""/>
+ <memberdef>
+ <inlineclasses title=""/>
+ <typedefs title=""/>
+ <enums title=""/>
+ <functions title=""/>
+ <variables title=""/>
+ </memberdef>
+ <authorsection visible="yes"/>
+ </namespace>
+
+ <!-- Layout definition for a file page -->
+ <file>
+ <briefdescription visible="yes"/>
+ <includes visible="$SHOW_INCLUDE_FILES"/>
+ <includegraph visible="$INCLUDE_GRAPH"/>
+ <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+ <sourcelink visible="yes"/>
+ <memberdecl>
+ <classes visible="yes" title=""/>
+ <namespaces visible="yes" title=""/>
+ <constantgroups visible="yes" title=""/>
+ <defines title=""/>
+ <typedefs title=""/>
+ <enums title=""/>
+ <functions title=""/>
+ <variables title=""/>
+ <membergroups visible="yes"/>
+ </memberdecl>
+ <detaileddescription title=""/>
+ <memberdef>
+ <inlineclasses title=""/>
+ <defines title=""/>
+ <typedefs title=""/>
+ <enums title=""/>
+ <functions title=""/>
+ <variables title=""/>
+ </memberdef>
+ <authorsection/>
+ </file>
+
+ <!-- Layout definition for a group page -->
+ <group>
+ <briefdescription visible="yes"/>
+ <groupgraph visible="$GROUP_GRAPHS"/>
+ <memberdecl>
+ <nestedgroups visible="yes" title=""/>
+ <dirs visible="yes" title=""/>
+ <files visible="yes" title=""/>
+ <namespaces visible="yes" title=""/>
+ <classes visible="yes" title=""/>
+ <defines title=""/>
+ <typedefs title=""/>
+ <enums title=""/>
+ <enumvalues title=""/>
+ <functions title=""/>
+ <variables title=""/>
+ <signals title=""/>
+ <publicslots title=""/>
+ <protectedslots title=""/>
+ <privateslots title=""/>
+ <events title=""/>
+ <properties title=""/>
+ <friends title=""/>
+ <membergroups visible="yes"/>
+ </memberdecl>
+ <detaileddescription title=""/>
+ <memberdef>
+ <pagedocs/>
+ <inlineclasses title=""/>
+ <defines title=""/>
+ <typedefs title=""/>
+ <enums title=""/>
+ <enumvalues title=""/>
+ <functions title=""/>
+ <variables title=""/>
+ <signals title=""/>
+ <publicslots title=""/>
+ <protectedslots title=""/>
+ <privateslots title=""/>
+ <events title=""/>
+ <properties title=""/>
+ <friends title=""/>
+ </memberdef>
+ <authorsection visible="yes"/>
+ </group>
+
+ <!-- Layout definition for a directory page -->
+ <directory>
+ <briefdescription visible="yes"/>
+ <directorygraph visible="yes"/>
+ <memberdecl>
+ <dirs visible="yes"/>
+ <files visible="yes"/>
+ </memberdecl>
+ <detaileddescription title=""/>
+ </directory>
+</doxygenlayout>
diff --git a/src/site/doxy/customdoxygen.css b/src/site/doxy/customdoxygen.css
new file mode 100644
index 0000000..2109924
--- /dev/null
+++ b/src/site/doxy/customdoxygen.css
@@ -0,0 +1,22 @@
+.navpath li.center
+{
+ list-style-type:none;
+ float:none;
+ padding-left:10px;
+ padding-right:10px;
+ background-image:none;
+ background-repeat:no-repeat;
+ background-position:right;
+ color:#364D7C;
+ font-size: 8pt;
+ line-height: 100%;
+ text-align: center;
+}
+
+code
+{
+ border-radius: 3px;
+ padding: 3px 4px;
+ background-color: #f7f7f9;
+ border: 1px solid #e1e1e8;
+}
diff --git a/src/site/doxy/footer.html b/src/site/doxy/footer.html
new file mode 100644
index 0000000..2639b9a
--- /dev/null
+++ b/src/site/doxy/footer.html
@@ -0,0 +1,25 @@
+<!-- HTML footer for doxygen 1.8.13-->
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
+ <ul>
+ $navpath
+ <li class="footer">$generatedby
+ <a href="http://www.doxygen.org/index.html">
+ <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
+ <li class="center">
+Copyright © 2003-2020 <a href="https://www.apache.org/">Apache Software Foundation</a>. All Rights Reserved. <br/>
+Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.
+ </li>
+ </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<hr class="footer"/><address class="footer"><small>
+$generatedby  <a href="http://www.doxygen.org/index.html">
+<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
+</a> $doxygenversion
+</small></address>
+<!--END !GENERATE_TREEVIEW-->
+</body>
+</html>
diff --git a/src/site/images/add.gif b/src/site/images/add.gif
new file mode 100644
index 0000000..ac0bdcc
--- /dev/null
+++ b/src/site/images/add.gif
Binary files differ
diff --git a/src/site/images/fix.gif b/src/site/images/fix.gif
new file mode 100644
index 0000000..2585f13
--- /dev/null
+++ b/src/site/images/fix.gif
Binary files differ
diff --git a/src/site/images/update.gif b/src/site/images/update.gif
new file mode 100644
index 0000000..71ca225
--- /dev/null
+++ b/src/site/images/update.gif
Binary files differ
diff --git a/src/site/markdown/0-community.md b/src/site/markdown/0-community.md
new file mode 100644
index 0000000..0b819f1
--- /dev/null
+++ b/src/site/markdown/0-community.md
@@ -0,0 +1,27 @@
+Community {#community}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+See the following pages for community information:
+
+* @subpage issue-tracking
+* @subpage mailing-lists
diff --git a/src/site/markdown/1-usage.md b/src/site/markdown/1-usage.md
new file mode 100644
index 0000000..97ccaef
--- /dev/null
+++ b/src/site/markdown/1-usage.md
@@ -0,0 +1,29 @@
+Usage {#usage-overview}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+See the following pages for usage information:
+
+* @subpage usage
+* @subpage extending-log4cxx
+* @subpage faq
+* @subpage configuration-samples
diff --git a/src/site/markdown/2-get.md b/src/site/markdown/2-get.md
new file mode 100644
index 0000000..baac33b
--- /dev/null
+++ b/src/site/markdown/2-get.md
@@ -0,0 +1,26 @@
+Get {#get}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+* @subpage download
+* @subpage changelog
+* @subpage license
diff --git a/src/site/markdown/3-development.md b/src/site/markdown/3-development.md
new file mode 100644
index 0000000..c0e6c07
--- /dev/null
+++ b/src/site/markdown/3-development.md
@@ -0,0 +1,30 @@
+Development {#development-overview}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+See the following pages for development information:
+
+* @subpage source-repository
+* @subpage dependencies
+* @subpage building
+* @subpage build-cmake
+* @subpage build-vcpkg
diff --git a/src/site/markdown/change-report-gh.md b/src/site/markdown/change-report-gh.md
new file mode 100644
index 0000000..32c258b
--- /dev/null
+++ b/src/site/markdown/change-report-gh.md
@@ -0,0 +1,511 @@
+Changelog {#changelog}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+## Changes
+
+### Release History
+
+| | | |
+| -------------------------------------------------------------------------------------- | ---------- | -------------------- |
+| Version | Date | Description |
+| [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.11.0"/>
+### Release 0.11.0 - 2020-08-09
+
+| | | |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | cmake and autotools generate different versioned binaries Fixes [LOGCXX-512](https://issues.apache.org/jira/browse/LOGCXX-512). | |
+|  | CachedDateFormat reuses timestamps without updating milliseconds after formatting timestamp with ms == 654 Fixes [LOGCXX-506](https://issues.apache.org/jira/browse/LOGCXX-506). | |
+|  | Checksums/Signatures don't match for log4cxx binaries Fixes [LOGCXX-503](https://issues.apache.org/jira/browse/LOGCXX-503). | |
+|  | appenderattachable.h function doc formatted "incorrectly" Fixes [LOGCXX-502](https://issues.apache.org/jira/browse/LOGCXX-502). | |
+|  | Logging in Timing-Critical Applications Fixes [LOGCXX-500](https://issues.apache.org/jira/browse/LOGCXX-500). | |
+|  | Provide a windows build environment for the project by replacing the ant build with a CMake build Fixes [LOGCXX-494](https://issues.apache.org/jira/browse/LOGCXX-494). | |
+|  | Wrong usage of milli- vs. micro- and non- vs. milliseconds in some docs. Fixes [LOGCXX-493](https://issues.apache.org/jira/browse/LOGCXX-493). | |
+|  | conditional expression is constant Fixes [LOGCXX-490](https://issues.apache.org/jira/browse/LOGCXX-490). | |
+|  | Space after log level hides messages Fixes [LOGCXX-488](https://issues.apache.org/jira/browse/LOGCXX-488). | |
+|  | Spelling error s/excute/execute Fixes [LOGCXX-484](https://issues.apache.org/jira/browse/LOGCXX-484). | |
+|  | Not able to see hebrew values when logging in log4cxx Fixes [LOGCXX-483](https://issues.apache.org/jira/browse/LOGCXX-483). | |
+|  | Build failure with GCC-6 Fixes [LOGCXX-482](https://issues.apache.org/jira/browse/LOGCXX-482). | |
+|  | TimeBasedRollingPolicy should append as configured on rollover Fixes [LOGCXX-464](https://issues.apache.org/jira/browse/LOGCXX-464). | |
+|  | LogLog::setQuietMode(true) does not suppress exception reporting Fixes [LOGCXX-455](https://issues.apache.org/jira/browse/LOGCXX-455). | |
+|  | make install fails, trying to overwrite header files Fixes [LOGCXX-446](https://issues.apache.org/jira/browse/LOGCXX-446). | |
+|  | Return by const reference in Logger::getName() Fixes [LOGCXX-443](https://issues.apache.org/jira/browse/LOGCXX-443). | |
+|  | Autoconf 2.69 needs 'ACLOCAL\_AMFLAGS= -I .' Fixes [LOGCXX-433](https://issues.apache.org/jira/browse/LOGCXX-433). | |
+|  | Wildcards in Makefile.am break either VPATH or non-VPATH installs Fixes [LOGCXX-428](https://issues.apache.org/jira/browse/LOGCXX-428). | |
+|  | exceptions in CachedDateFormatTestCase after LOGCXX-420 Fixes [LOGCXX-425](https://issues.apache.org/jira/browse/LOGCXX-425). | |
+|  | liblog4cxx.pc.in should reflect dependency on apr-1, apr-1-util Fixes [LOGCXX-424](https://issues.apache.org/jira/browse/LOGCXX-424). | |
+|  | Repair autogen script warnings Fixes [LOGCXX-423](https://issues.apache.org/jira/browse/LOGCXX-423). | |
+|  | Regression of LOGCXX-420 Fixes [LOGCXX-422](https://issues.apache.org/jira/browse/LOGCXX-422). | |
+|  | Possible out\_of\_range exception for millisecond formats in CachedDateFormat Fixes [LOGCXX-420](https://issues.apache.org/jira/browse/LOGCXX-420). | |
+|  | atoi undefined on Mac OS 10.9 compiling stringhelper.cpp Fixes [LOGCXX-417](https://issues.apache.org/jira/browse/LOGCXX-417). | |
+|  | Configure and watch could crash on app exit with static linking Fixes [LOGCXX-416](https://issues.apache.org/jira/browse/LOGCXX-416). | |
+|  | Empty XML configuration file causes crash Fixes [LOGCXX-415](https://issues.apache.org/jira/browse/LOGCXX-415). | |
+|  | possibly wrong use of autotools docdir (due to Alex Zbarcea) Fixes [LOGCXX-414](https://issues.apache.org/jira/browse/LOGCXX-414). | |
+|  | log4cxx doesn't compile on openembedded (due to Alex Zbarcea) Fixes [LOGCXX-413](https://issues.apache.org/jira/browse/LOGCXX-413). | |
+|  | Log4cxx doesn't roll normally when working under multiple processes environment Fixes [LOGCXX-412](https://issues.apache.org/jira/browse/LOGCXX-412). | |
+|  | Crash when logging on multiple threads. Fixes [LOGCXX-411](https://issues.apache.org/jira/browse/LOGCXX-411). | |
+|  | C++11 does not allow char literals with highest bit set unless cast Fixes [LOGCXX-400](https://issues.apache.org/jira/browse/LOGCXX-400). | |
+|  | Non-ascii character output wrong. Fixes [LOGCXX-399](https://issues.apache.org/jira/browse/LOGCXX-399). | |
+|  | Infinite loop in Transcoder::encode(const LogString& src, std::wstring& dst) Fixes [LOGCXX-398](https://issues.apache.org/jira/browse/LOGCXX-398). | |
+|  | Levels are not thread safe Fixes [LOGCXX-394](https://issues.apache.org/jira/browse/LOGCXX-394). | |
+|  | Hierarchy::updateParents loops forever on illegal logger-name like '.logger1' Fixes [LOGCXX-388](https://issues.apache.org/jira/browse/LOGCXX-388). | |
+|  | Mingw build type conversion error Fixes [LOGCXX-382](https://issues.apache.org/jira/browse/LOGCXX-382). | |
+|  | Pkgconfig can't find dependencies properly if log4cxx built statically Fixes [LOGCXX-381](https://issues.apache.org/jira/browse/LOGCXX-381). | |
+|  | Load Properties File Fails When There Are multibyte Characters in the Path Fixes [LOGCXX-369](https://issues.apache.org/jira/browse/LOGCXX-369). | |
+|  | method and class name functions not properly implemented Fixes [LOGCXX-368](https://issues.apache.org/jira/browse/LOGCXX-368). | |
+|  | Build fails on Linux with g++ 4.4 Fixes [LOGCXX-367](https://issues.apache.org/jira/browse/LOGCXX-367). | |
+|  | Errors when compile log4cxx 0.10.0 under Win7 x64 with Visual Studio 2010 (due to Christian Boos and Feng Nan) Fixes [LOGCXX-366](https://issues.apache.org/jira/browse/LOGCXX-366). | |
+|  | Unit tests fail on system dates later than 2009-12-31. Fixes [LOGCXX-365](https://issues.apache.org/jira/browse/LOGCXX-365). | |
+|  | SMTPAppender generating Emails with an empty body Fixes [LOGCXX-358](https://issues.apache.org/jira/browse/LOGCXX-358). | |
+|  | apache-log4cxx-0.10.0\\src\\main\\include\\log4cxx\\spi\\configurator.h(57) : warning C4231: nonstandard extension used : 'extern' before template explicit instantiation Fixes [LOGCXX-356](https://issues.apache.org/jira/browse/LOGCXX-356). | |
+|  | When a client disconnects the SocketHubAppender crashes on the next log message Fixes [LOGCXX-353](https://issues.apache.org/jira/browse/LOGCXX-353). | |
+|  | Download page does not have link to KEYS file Fixes [LOGCXX-351](https://issues.apache.org/jira/browse/LOGCXX-351). | |
+|  | Transcoder::encodeCharsetName bungles encoding Fixes [LOGCXX-340](https://issues.apache.org/jira/browse/LOGCXX-340). | |
+|  | Child thread does not inherit a copy of the mapped diagnostic context of its parent Fixes [LOGCXX-339](https://issues.apache.org/jira/browse/LOGCXX-339). | |
+|  | Suggested fix for socketappender not reconnecting multiple times Fixes [LOGCXX-337](https://issues.apache.org/jira/browse/LOGCXX-337). | |
+|  | Test compilation fails: Overloading ambiguity Fixes [LOGCXX-336](https://issues.apache.org/jira/browse/LOGCXX-336). | |
+|  | DailyRollingFileAppender should roll if program doesn't run at rolling time Fixes [LOGCXX-331](https://issues.apache.org/jira/browse/LOGCXX-331). | |
+|  | TLS memory of APR is not freed in destructor of APRInitializer Fixes [LOGCXX-320](https://issues.apache.org/jira/browse/LOGCXX-320). | |
+|  | 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). | |
+|  | 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). | |
+|  | odbcappender.cpp does not compile with unixODBC on linux. Fixes [LOGCXX-299](https://issues.apache.org/jira/browse/LOGCXX-299). | |
+|  | SMTPAppender does not build properly with autotools. Fixes [LOGCXX-298](https://issues.apache.org/jira/browse/LOGCXX-298). | |
+|  | Escape sequences not recognized in property files. Fixes [LOGCXX-293](https://issues.apache.org/jira/browse/LOGCXX-293). | |
+|  | Value continuation does not properly handle CRLF in property files. Fixes [LOGCXX-292](https://issues.apache.org/jira/browse/LOGCXX-292). | |
+|  | Tab characters are not recognized in property files. Fixes [LOGCXX-291](https://issues.apache.org/jira/browse/LOGCXX-291). | |
+|  | Unnecessary trailing semi-colons after LOG4CXX\_INFO et al in docs, examples and tests. Fixes [LOGCXX-288](https://issues.apache.org/jira/browse/LOGCXX-288). | |
+|  | gcc 4.3 requires \#include \<cstring\> when using memcpy and related. Fixes [LOGCXX-286](https://issues.apache.org/jira/browse/LOGCXX-286). | |
+|  | LevelRangeFilter has default value for acceptOnMatch that is different from log4j Fixes [LOGCXX-285](https://issues.apache.org/jira/browse/LOGCXX-285). | |
+|  | Unit tests fail to compile with xlc\_r on AIX Fixes [LOGCXX-284](https://issues.apache.org/jira/browse/LOGCXX-284). | |
+|  | Suspicious, but harmless, reuse of LOCAL1 in SyslogAppender Fixes [LOGCXX-283](https://issues.apache.org/jira/browse/LOGCXX-283). | |
+|  | Thread::sleep not affected by Thread::interrupt. Fixes [LOGCXX-282](https://issues.apache.org/jira/browse/LOGCXX-282). | |
+|  | Sun Studio 11 reports function hides base virtual function warning Fixes [LOGCXX-281](https://issues.apache.org/jira/browse/LOGCXX-281). | |
+|  | tests and sample code unnecessarily compiled during default make target Fixes [LOGCXX-280](https://issues.apache.org/jira/browse/LOGCXX-280). | |
+|  | Threads for reconnecting sockets do not end cleanly when program exits Fixes [LOGCXX-278](https://issues.apache.org/jira/browse/LOGCXX-278). | |
+|  | Reconnection not working for sockets Fixes [LOGCXX-277](https://issues.apache.org/jira/browse/LOGCXX-277). | |
+|  | AndFilter and others defined but not implemented Fixes [LOGCXX-276](https://issues.apache.org/jira/browse/LOGCXX-276). | |
+|  | Headers cannot be included with very strict warning settings Fixes [LOGCXX-275](https://issues.apache.org/jira/browse/LOGCXX-275). | |
+|  | Prevent filenamepatterntestcase from failing in some timezones Fixes [LOGCXX-273](https://issues.apache.org/jira/browse/LOGCXX-273). | |
+|  | Apache log4cxx 0.11.0 release Fixes [LOGCXX-272](https://issues.apache.org/jira/browse/LOGCXX-272). | |
+|  | MDC::put will not overwrite existing key value pair Fixes [LOGCXX-271](https://issues.apache.org/jira/browse/LOGCXX-271). | |
+|  | Add ability to compile out logging by logging level. Fixes [LOGCXX-270](https://issues.apache.org/jira/browse/LOGCXX-270). | |
+|  | Local variables hide member variables Fixes [LOGCXX-267](https://issues.apache.org/jira/browse/LOGCXX-267). | |
+|  | Eliminate Extra ";" ignored warnings Fixes [LOGCXX-266](https://issues.apache.org/jira/browse/LOGCXX-266). | |
+|  | Eliminate anachronism warnings Fixes [LOGCXX-265](https://issues.apache.org/jira/browse/LOGCXX-265). | |
+|  | Bad link to log4cxx-dev archive Fixes [LOGCXX-263](https://issues.apache.org/jira/browse/LOGCXX-263). | |
+|  | socketappendertestcase and xmlsocketappendertestcase not run Fixes [LOGCXX-262](https://issues.apache.org/jira/browse/LOGCXX-262). | |
+|  | Console appender crashes if layout is not set Fixes [LOGCXX-249](https://issues.apache.org/jira/browse/LOGCXX-249). | |
+|  | Set SONAME in cmake like autotools based buildsystem would do. Fixes [32](https://github.com/apache/logging-log4cxx/pull/32). | |
+|  | Implementation of map-based filter. Fixes [24](https://github.com/apache/logging-log4cxx/pull/24). | |
+|  | Added support for building log4cxx as a statically linked library on Windows. Fixes [21](https://github.com/apache/logging-log4cxx/pull/21). | |
+|  | Replaced ant build with cmake. Fixes [14](https://github.com/apache/logging-log4cxx/pull/14). | |
+|  | JSONLayout Fixes [13](https://github.com/apache/logging-log4cxx/pull/13). | |
+|  | Behavior of StringHelper::startsWith and endsWith synced. | |
+|  | 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
+
+| | | |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | Several appenders fail to compile in Visual Studio 2008 Fixes [LOGCXX-259](https://issues.apache.org/jira/browse/LOGCXX-259). | |
+|  | unable to build from make dist package due to missing doxygen file Fixes [LOGCXX-258](https://issues.apache.org/jira/browse/LOGCXX-258). | |
+|  | ServerSocket::accept hangs on Unix Fixes [LOGCXX-257](https://issues.apache.org/jira/browse/LOGCXX-257). | |
+|  | SocketHubAppender fails after accepting connection Fixes [LOGCXX-256](https://issues.apache.org/jira/browse/LOGCXX-256). | |
+|  | Add build option for static C RTL Fixes [LOGCXX-254](https://issues.apache.org/jira/browse/LOGCXX-254). | |
+|  | Transcoder compilation error with utf-8 charset Fixes [LOGCXX-253](https://issues.apache.org/jira/browse/LOGCXX-253). | |
+|  | Add documentation for use of operator\<\< in logging requests Fixes [LOGCXX-252](https://issues.apache.org/jira/browse/LOGCXX-252). | |
+|  | NDC::cloneStack and NDC::inherit missing in 0.10.0 RC2 Fixes [LOGCXX-251](https://issues.apache.org/jira/browse/LOGCXX-251). | |
+|  | ODBCAppender has unicode issues Fixes [LOGCXX-248](https://issues.apache.org/jira/browse/LOGCXX-248). | |
+|  | MSVC project has wrong additional include directories Fixes [LOGCXX-247](https://issues.apache.org/jira/browse/LOGCXX-247). | |
+|  | Config refresh hangs a client application that uses TelnetAppender Fixes [LOGCXX-246](https://issues.apache.org/jira/browse/LOGCXX-246). | |
+|  | Problem Compile in Doxy Fixes [LOGCXX-243](https://issues.apache.org/jira/browse/LOGCXX-243). | |
+|  | Eliminate log4cxx proxies for APR types Fixes [LOGCXX-242](https://issues.apache.org/jira/browse/LOGCXX-242). | |
+|  | Non-ascii named files have names mangled Fixes [LOGCXX-241](https://issues.apache.org/jira/browse/LOGCXX-241). | |
+|  | Inconsistent const qualification on logging methods. Fixes [LOGCXX-239](https://issues.apache.org/jira/browse/LOGCXX-239). | |
+|  | Include missing headers Fixes [LOGCXX-237](https://issues.apache.org/jira/browse/LOGCXX-237). | |
+|  | Re-order constructor initialiser lists to match declaration order Fixes [LOGCXX-236](https://issues.apache.org/jira/browse/LOGCXX-236). | |
+|  | Add ObjectPtrT::exchange Fixes [LOGCXX-235](https://issues.apache.org/jira/browse/LOGCXX-235). | |
+|  | Assignment operator removes const qualifier Fixes [LOGCXX-234](https://issues.apache.org/jira/browse/LOGCXX-234). | |
+|  | Unnecessary casts in ObjectPtrT Fixes [LOGCXX-233](https://issues.apache.org/jira/browse/LOGCXX-233). | |
+|  | 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). | |
+|  | 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). | |
+|  | ThreadID layout does not match debugger Fixes [LOGCXX-221](https://issues.apache.org/jira/browse/LOGCXX-221). | |
+|  | Memory leaks when using MFC Fixes [LOGCXX-220](https://issues.apache.org/jira/browse/LOGCXX-220). | |
+|  | suspicious warnings Fixes [LOGCXX-219](https://issues.apache.org/jira/browse/LOGCXX-219). | |
+|  | Visual Studio 8 build Fixes [LOGCXX-218](https://issues.apache.org/jira/browse/LOGCXX-218). | |
+|  | Not initialized LoggerPtr segfault program. Fixes [LOGCXX-217](https://issues.apache.org/jira/browse/LOGCXX-217). | |
+|  | crash on program exit Fixes [LOGCXX-216](https://issues.apache.org/jira/browse/LOGCXX-216). | |
+|  | Eliminate sqlext.h from odbcappender.h Fixes [LOGCXX-215](https://issues.apache.org/jira/browse/LOGCXX-215). | |
+|  | Possible memory leak due to fault in build process (via make) Fixes [LOGCXX-214](https://issues.apache.org/jira/browse/LOGCXX-214). | |
+|  | trace method implementation is missing Fixes [LOGCXX-213](https://issues.apache.org/jira/browse/LOGCXX-213). | |
+|  | unittest failed Fixes [LOGCXX-212](https://issues.apache.org/jira/browse/LOGCXX-212). | |
+|  | Crash(Segmentation Fault) in DailyRollingFileAppender when file change Fixes [LOGCXX-211](https://issues.apache.org/jira/browse/LOGCXX-211). | |
+|  | HTMLLayout NDC null check Fixes [LOGCXX-210](https://issues.apache.org/jira/browse/LOGCXX-210). | |
+|  | A message of type wchar\_t\* is not beeing written correctly to the internal message buffer (Revision: 592627) Fixes [LOGCXX-209](https://issues.apache.org/jira/browse/LOGCXX-209). | |
+|  | isTraceEnabled implemenation missing in logger.cpp (Revision: 592627) Fixes [LOGCXX-208](https://issues.apache.org/jira/browse/LOGCXX-208). | |
+|  | PatternParserTestCase and FileNamePatternTestCase fail only with VC6 Fixes [LOGCXX-204](https://issues.apache.org/jira/browse/LOGCXX-204). | |
+|  | ObjectPtrT has inconsistent const-ness on accessors Fixes [LOGCXX-202](https://issues.apache.org/jira/browse/LOGCXX-202). | |
+|  | Visual Studio 6 build Fixes [LOGCXX-201](https://issues.apache.org/jira/browse/LOGCXX-201). | |
+|  | Implement compression for RollingFileAppender Fixes [LOGCXX-200](https://issues.apache.org/jira/browse/LOGCXX-200). | |
+|  | ant can't generate vc6 project Fixes [LOGCXX-197](https://issues.apache.org/jira/browse/LOGCXX-197). | |
+|  | Syslog appender destructor can cause core Fixes [LOGCXX-196](https://issues.apache.org/jira/browse/LOGCXX-196). | |
+|  | Syslog appender adds characters to output. Fixes [LOGCXX-195](https://issues.apache.org/jira/browse/LOGCXX-195). | |
+|  | Garbage in log files when appenders are defined in multiple levels of the logger hierarchy Fixes [LOGCXX-194](https://issues.apache.org/jira/browse/LOGCXX-194). | |
+|  | Please rename or remove new local variable "buf" in Logger.h macros Fixes [LOGCXX-193](https://issues.apache.org/jira/browse/LOGCXX-193). | |
+|  | Suggested improvements to log4cxx webpages Fixes [LOGCXX-192](https://issues.apache.org/jira/browse/LOGCXX-192). | |
+|  | Application cores when syslog appender is given an unreachable host/ip. Fixes [LOGCXX-191](https://issues.apache.org/jira/browse/LOGCXX-191). | |
+|  | The 'logger.h' header includes itself. Fixes [LOGCXX-190](https://issues.apache.org/jira/browse/LOGCXX-190). | |
+|  | Migrate to Maven 2.0 for documentation and packaging Fixes [LOGCXX-189](https://issues.apache.org/jira/browse/LOGCXX-189). | |
+|  | Upgrade to apr 1.2.9 and apr-util 1.2.8 Fixes [LOGCXX-188](https://issues.apache.org/jira/browse/LOGCXX-188). | |
+|  | LogLog::emit() could potentially interleave messages Fixes [LOGCXX-187](https://issues.apache.org/jira/browse/LOGCXX-187). | |
+|  | Garbage characters in log files when log requests from multiple threads with hyperthreading enabled Fixes [LOGCXX-186](https://issues.apache.org/jira/browse/LOGCXX-186). | |
+|  | Crash when log level set to 'inherited' Fixes [LOGCXX-184](https://issues.apache.org/jira/browse/LOGCXX-184). | |
+|  | Compiler warning: dereferencing type-punned pointer will break strict-aliasing rules Fixes [LOGCXX-183](https://issues.apache.org/jira/browse/LOGCXX-183). | |
+|  | missing man page for simplesocketserver Fixes [LOGCXX-182](https://issues.apache.org/jira/browse/LOGCXX-182). | |
+|  | Level::DEBUG and other non-local statics cause crash on app shutdown on AIX Fixes [LOGCXX-181](https://issues.apache.org/jira/browse/LOGCXX-181). | |
+|  | Build fails at domconfigurator.h Fixes [LOGCXX-180](https://issues.apache.org/jira/browse/LOGCXX-180). | |
+|  | example applications do SIGABRT on aix 5.2 Fixes [LOGCXX-179](https://issues.apache.org/jira/browse/LOGCXX-179). | |
+|  | Link failure if wchar\_t cannot be determined as UTF-16 or UTF-32 Fixes [LOGCXX-178](https://issues.apache.org/jira/browse/LOGCXX-178). | |
+|  | SocketImpl::accept uses private APR function: apr\_wait\_for\_io\_or\_timeout Fixes [LOGCXX-177](https://issues.apache.org/jira/browse/LOGCXX-177). | |
+|  | APRCharsetEncoder is not thread safe Fixes [LOGCXX-175](https://issues.apache.org/jira/browse/LOGCXX-175). | |
+|  | configure fail with ".infig.status: error: cannot find input file:" Fixes [LOGCXX-172](https://issues.apache.org/jira/browse/LOGCXX-172). | |
+|  | Add project description file for projects.apache.org Fixes [LOGCXX-171](https://issues.apache.org/jira/browse/LOGCXX-171). | |
+|  | XMLLayoutTestCase fails on compilers that do not provide location info Fixes [LOGCXX-169](https://issues.apache.org/jira/browse/LOGCXX-169). | |
+|  | log4j.dtd does not contain rollingPolicy and other o.a.l.r.RFA elements Fixes [LOGCXX-168](https://issues.apache.org/jira/browse/LOGCXX-168). | |
+|  | system locale charmap is not determined properly on Fedora Core 6 Fixes [LOGCXX-167](https://issues.apache.org/jira/browse/LOGCXX-167). | |
+|  | XMLSocketAppender may generate erroneous output due to mismatched encoding Fixes [LOGCXX-165](https://issues.apache.org/jira/browse/LOGCXX-165). | |
+|  | XMLSocketAppender is disabled Fixes [LOGCXX-164](https://issues.apache.org/jira/browse/LOGCXX-164). | |
+|  | liblog4cxx (svn 480882) does not link on Mac OS X 10.4 Fixes [LOGCXX-163](https://issues.apache.org/jira/browse/LOGCXX-163). | |
+|  | Problem printing string with embedded NULL character Fixes [LOGCXX-162](https://issues.apache.org/jira/browse/LOGCXX-162). | |
+|  | Using RollingFileAppender increases the working set with each rollover Fixes [LOGCXX-161](https://issues.apache.org/jira/browse/LOGCXX-161). | |
+|  | helpers/object.h: DECLARE\_LOG4CXX\_OBJECT macro definition is missing virtual destructor declaration Fixes [LOGCXX-160](https://issues.apache.org/jira/browse/LOGCXX-160). | |
+|  | Initialization of local static objects out of order on Linux Fixes [LOGCXX-159](https://issues.apache.org/jira/browse/LOGCXX-159). | |
+|  | tolower not defined in stringhelper.cpp Fixes [LOGCXX-158](https://issues.apache.org/jira/browse/LOGCXX-158). | |
+|  | make install fails since @manual\_dest@ replacement is missing in Makefiles Fixes [LOGCXX-157](https://issues.apache.org/jira/browse/LOGCXX-157). | |
+|  | immediate flush in console appender Fixes [LOGCXX-156](https://issues.apache.org/jira/browse/LOGCXX-156). | |
+|  | Update source headers per new ASF header policy Fixes [LOGCXX-155](https://issues.apache.org/jira/browse/LOGCXX-155). | |
+|  | Automate log4cxx site and doxygen generation and deployment Fixes [LOGCXX-153](https://issues.apache.org/jira/browse/LOGCXX-153). | |
+|  | gcc warning about cast from \`const void\*' to \`log4cxx::helpers::Object\*' discards qualifiers from pointer target typ Fixes [LOGCXX-152](https://issues.apache.org/jira/browse/LOGCXX-152). | |
+|  | Umlauts as literal in patternlayout won't be logged correct Fixes [LOGCXX-151](https://issues.apache.org/jira/browse/LOGCXX-151). | |
+|  | logstream's operator\<\< declared in the wrong namespace Fixes [LOGCXX-150](https://issues.apache.org/jira/browse/LOGCXX-150). | |
+|  | make dist does not work Fixes [LOGCXX-149](https://issues.apache.org/jira/browse/LOGCXX-149). | |
+|  | DailyRollingFileAppender::~DailyRollingFileAppender must call finalize Fixes [LOGCXX-146](https://issues.apache.org/jira/browse/LOGCXX-146). | |
+|  | \-xarch=v8plus should be removed from Makefile.in Fixes [LOGCXX-143](https://issues.apache.org/jira/browse/LOGCXX-143). | |
+|  | socketservertestcase.cpp does not compile with Sun Studio 11 on Solaris Fixes [LOGCXX-142](https://issues.apache.org/jira/browse/LOGCXX-142). | |
+|  | Upgrade to APR 1.2.7 or later Fixes [LOGCXX-141](https://issues.apache.org/jira/browse/LOGCXX-141). | |
+|  | Handle leak with LoggingEvent::getCurrentThreadName Fixes [LOGCXX-140](https://issues.apache.org/jira/browse/LOGCXX-140). | |
+|  | XMLLayoutTestCase uses inadequate filters for 64 bit platforms Fixes [LOGCXX-139](https://issues.apache.org/jira/browse/LOGCXX-139). | |
+|  | XMLLayoutTestCase output and filtered output gets overwritten Fixes [LOGCXX-138](https://issues.apache.org/jira/browse/LOGCXX-138). | |
+|  | DailyRollingFileAppender not using Property options Fixes [LOGCXX-136](https://issues.apache.org/jira/browse/LOGCXX-136). | |
+|  | Use std::string with logstream Fixes [LOGCXX-135](https://issues.apache.org/jira/browse/LOGCXX-135). | |
+|  | FileAppender could create missing directories Fixes [LOGCXX-134](https://issues.apache.org/jira/browse/LOGCXX-134). | |
+|  | Missing parenthesis in LOG4CXX\_ASSERT Fixes [LOGCXX-133](https://issues.apache.org/jira/browse/LOGCXX-133). | |
+|  | various segmentation faults in multithreaded application Fixes [LOGCXX-132](https://issues.apache.org/jira/browse/LOGCXX-132). | |
+|  | TimeBasedRollingPolicy is declared "abstract" Fixes [LOGCXX-131](https://issues.apache.org/jira/browse/LOGCXX-131). | |
+|  | Compile fails on gcc4.1 Fixes [LOGCXX-130](https://issues.apache.org/jira/browse/LOGCXX-130). | |
+|  | Asyncappender is full of race conditions (improper use of condition variables) Fixes [LOGCXX-129](https://issues.apache.org/jira/browse/LOGCXX-129). | |
+|  | Main build.xml not referencing "env" properly. Fixes [LOGCXX-127](https://issues.apache.org/jira/browse/LOGCXX-127). | |
+|  | std::cout stops working if log4cxx is first to output Fixes [LOGCXX-126](https://issues.apache.org/jira/browse/LOGCXX-126). | |
+|  | L7dTestCase is stubbed out Fixes [LOGCXX-125](https://issues.apache.org/jira/browse/LOGCXX-125). | |
+|  | wchar\_t constructor missing in class NDC Fixes [LOGCXX-124](https://issues.apache.org/jira/browse/LOGCXX-124). | |
+|  | UTF-8 build fails on Linux Fixes [LOGCXX-123](https://issues.apache.org/jira/browse/LOGCXX-123). | |
+|  | Wrong parameter description in Patternlayout Fixes [LOGCXX-120](https://issues.apache.org/jira/browse/LOGCXX-120). | |
+|  | ndctestcase not working Fixes [LOGCXX-119](https://issues.apache.org/jira/browse/LOGCXX-119). | |
+|  | Hierarchy corrupts with PropertyConfigurator Fixes [LOGCXX-118](https://issues.apache.org/jira/browse/LOGCXX-118). | |
+|  | Memory leak with ThreadSpecificData on Win32 Fixes [LOGCXX-117](https://issues.apache.org/jira/browse/LOGCXX-117). | |
+|  | SVN head does not compiler with MinGW compiler Fixes [LOGCXX-116](https://issues.apache.org/jira/browse/LOGCXX-116). | |
+|  | SVN head does not compile with Borland C++ compiler Fixes [LOGCXX-115](https://issues.apache.org/jira/browse/LOGCXX-115). | |
+|  | Upgrade APR to 1.2.2 from 1.1.0 Fixes [LOGCXX-114](https://issues.apache.org/jira/browse/LOGCXX-114). | |
+|  | separate apr detection m4 codes from aclocal.m4 Fixes [LOGCXX-113](https://issues.apache.org/jira/browse/LOGCXX-113). | |
+|  | change "static" to "auto" for Transcoder::decode() decoder and CharsetDecoder::getDefaultDecoder() decoder Fixes [LOGCXX-112](https://issues.apache.org/jira/browse/LOGCXX-112). | |
+|  | make Logger cache a LoggerRepositoryPtr instead of a "blind" pointer Fixes [LOGCXX-111](https://issues.apache.org/jira/browse/LOGCXX-111). | |
+|  | try fix 64bit log4cxx\_intptr\_t Fixes [LOGCXX-110](https://issues.apache.org/jira/browse/LOGCXX-110). | |
+|  | Can't compile log4cxx in ascii on Windows Fixes [LOGCXX-107](https://issues.apache.org/jira/browse/LOGCXX-107). | |
+|  | maxFileSize has bad type in SizeBasedTriggeringPolicy file Fixes [LOGCXX-106](https://issues.apache.org/jira/browse/LOGCXX-106). | |
+|  | Infinite loop in string replacing Fixes [LOGCXX-105](https://issues.apache.org/jira/browse/LOGCXX-105). | |
+|  | ODBCAppender::close does not check if appender is already closed Fixes [LOGCXX-104](https://issues.apache.org/jira/browse/LOGCXX-104). | |
+|  | Much of CVS HEAD seems \#if 0 out, especially ResourceBundle stuff Fixes [LOGCXX-103](https://issues.apache.org/jira/browse/LOGCXX-103). | |
+|  | Fixes for ODBCAppender Fixes [LOGCXX-100](https://issues.apache.org/jira/browse/LOGCXX-100). | |
+|  | Gump build fails for log4cxx-ant-no-wchar-t target Fixes [LOGCXX-98](https://issues.apache.org/jira/browse/LOGCXX-98). | |
+|  | simplesocketserver.cpp should use LOG4CXX\_STR("...") not L"..." Fixes [LOGCXX-94](https://issues.apache.org/jira/browse/LOGCXX-94). | |
+|  | Explore use of security-enhanced CRT methods Fixes [LOGCXX-88](https://issues.apache.org/jira/browse/LOGCXX-88). | |
+|  | Remove remaining uses of Category and Priority Fixes [LOGCXX-87](https://issues.apache.org/jira/browse/LOGCXX-87). | |
+|  | Add TRACE level Fixes [LOGCXX-86](https://issues.apache.org/jira/browse/LOGCXX-86). | |
+|  | Mac OS/X fixes and enhancements Fixes [LOGCXX-85](https://issues.apache.org/jira/browse/LOGCXX-85). | |
+|  | Problems with stream logging in UTF8, no WCHAR\_T build Fixes [LOGCXX-84](https://issues.apache.org/jira/browse/LOGCXX-84). | |
+|  | log4cxx::Level::ERROR fails to compile when GDI enabled Fixes [LOGCXX-83](https://issues.apache.org/jira/browse/LOGCXX-83). | |
+|  | Compiling with stream.h in multiple object files errors Fixes [LOGCXX-82](https://issues.apache.org/jira/browse/LOGCXX-82). | |
+|  | SimpleDateFormat does not compile on Solaris 2.95.2 gcc Fixes [LOGCXX-81](https://issues.apache.org/jira/browse/LOGCXX-81). | |
+|  | Migrated network appenders to APR network IO Fixes [LOGCXX-80](https://issues.apache.org/jira/browse/LOGCXX-80). | |
+|  | configure check for apr-util Fixes [LOGCXX-79](https://issues.apache.org/jira/browse/LOGCXX-79). | |
+|  | Static builds broken Fixes [LOGCXX-77](https://issues.apache.org/jira/browse/LOGCXX-77). | |
+|  | user.home, user.dir, java.io.tmpdir available within configuration files Fixes [LOGCXX-76](https://issues.apache.org/jira/browse/LOGCXX-76). | |
+|  | Cygwin build Fixes [LOGCXX-75](https://issues.apache.org/jira/browse/LOGCXX-75). | |
+|  | MinGW build Fixes [LOGCXX-74](https://issues.apache.org/jira/browse/LOGCXX-74). | |
+|  | Not loading configuration from log4cxx.properties or log4cxx.xml Fixes [LOGCXX-73](https://issues.apache.org/jira/browse/LOGCXX-73). | |
+|  | INSTALL out of date Fixes [LOGCXX-72](https://issues.apache.org/jira/browse/LOGCXX-72). | |
+|  | Update performance page on web site Fixes [LOGCXX-71](https://issues.apache.org/jira/browse/LOGCXX-71). | |
+|  | Logic flaws in StringHelper::startsWith and StringHelper::endsWith Fixes [LOGCXX-70](https://issues.apache.org/jira/browse/LOGCXX-70). | |
+|  | NTEventLogAppender always uses RPC method for logging and has inadequate error handling. Fixes [LOGCXX-67](https://issues.apache.org/jira/browse/LOGCXX-67). | |
+|  | SyslogAppender append method currently stubbed out Fixes [LOGCXX-66](https://issues.apache.org/jira/browse/LOGCXX-66). | |
+|  | Migrate to APR network IO Fixes [LOGCXX-64](https://issues.apache.org/jira/browse/LOGCXX-64). | |
+|  | Platform appropriate line-feed convention Fixes [LOGCXX-63](https://issues.apache.org/jira/browse/LOGCXX-63). | |
+|  | log4cxx 0.10.0 release Fixes [LOGCXX-62](https://issues.apache.org/jira/browse/LOGCXX-62). | |
+|  | XML layout can be mismatched with document encoding Fixes [LOGCXX-60](https://issues.apache.org/jira/browse/LOGCXX-60). | |
+|  | Implement encoding support for Writer appender Fixes [LOGCXX-59](https://issues.apache.org/jira/browse/LOGCXX-59). | |
+|  | ImmediateFlush'd FileAppenders extremely slow on Windows Fixes [LOGCXX-58](https://issues.apache.org/jira/browse/LOGCXX-58). | |
+|  | Port log4j performance test Fixes [LOGCXX-57](https://issues.apache.org/jira/browse/LOGCXX-57). | |
+|  | BasicConfiguration is unreliable Fixes [LOGCXX-56](https://issues.apache.org/jira/browse/LOGCXX-56). | |
+|  | DailyRolling File Appender Fixes [LOGCXX-55](https://issues.apache.org/jira/browse/LOGCXX-55). | |
+|  | Eliminate use of boost-regex in unit tests Fixes [LOGCXX-54](https://issues.apache.org/jira/browse/LOGCXX-54). | |
+|  | Problems compiling with MsDev 6.0 (space in paths) Fixes [LOGCXX-53](https://issues.apache.org/jira/browse/LOGCXX-53). | |
+|  | Migrate log4j 1.3 RollingFileAppender Fixes [LOGCXX-52](https://issues.apache.org/jira/browse/LOGCXX-52). | |
+|  | variable name clash in macro Fixes [LOGCXX-50](https://issues.apache.org/jira/browse/LOGCXX-50). | |
+|  | Move timezone specification into pattern, remove locale specification Fixes [LOGCXX-49](https://issues.apache.org/jira/browse/LOGCXX-49). | |
+|  | Use hex representation for thread identifier Fixes [LOGCXX-48](https://issues.apache.org/jira/browse/LOGCXX-48). | |
+|  | Check headers for missing declarations and Effective C++ violations Fixes [LOGCXX-47](https://issues.apache.org/jira/browse/LOGCXX-47). | |
+|  | Extra semicolon after namespace closing paren Fixes [LOGCXX-46](https://issues.apache.org/jira/browse/LOGCXX-46). | |
+|  | \_T causes error : 1048576 cannot be used as a function Fixes [LOGCXX-45](https://issues.apache.org/jira/browse/LOGCXX-45). | |
+|  | GUMP integation Fixes [LOGCXX-44](https://issues.apache.org/jira/browse/LOGCXX-44). | |
+|  | configure/make help needed Fixes [LOGCXX-43](https://issues.apache.org/jira/browse/LOGCXX-43). | |
+|  | Layout timestamp doesn't seem to adjust for daylight saving Fixes [LOGCXX-41](https://issues.apache.org/jira/browse/LOGCXX-41). | |
+|  | PatternLayout does not support Java date format specifiers Fixes [LOGCXX-40](https://issues.apache.org/jira/browse/LOGCXX-40). | |
+|  | Remove DailyRollingFileAppender Fixes [LOGCXX-39](https://issues.apache.org/jira/browse/LOGCXX-39). | |
+|  | Unable to build log4cxx under Borland C++ Fixes [LOGCXX-37](https://issues.apache.org/jira/browse/LOGCXX-37). | |
+|  | Migrate to Apache Portable Runtime threads Fixes [LOGCXX-36](https://issues.apache.org/jira/browse/LOGCXX-36). | |
+|  | Avoid use of MSXML Fixes [LOGCXX-35](https://issues.apache.org/jira/browse/LOGCXX-35). | |
+|  | Visual Studio 6 CVS build broken Fixes [LOGCXX-34](https://issues.apache.org/jira/browse/LOGCXX-34). | |
+|  | log4cxx::Exception is not derived from std::exception Fixes [LOGCXX-33](https://issues.apache.org/jira/browse/LOGCXX-33). | |
+|  | Missing copy constructors and assignment operators Fixes [LOGCXX-32](https://issues.apache.org/jira/browse/LOGCXX-32). | |
+|  | Missing const qualifiers, Exception::getMessage() in particular. Fixes [LOGCXX-31](https://issues.apache.org/jira/browse/LOGCXX-31). | |
+|  | StringTokenizer uses evil strtok and wcstok functions Fixes [LOGCXX-30](https://issues.apache.org/jira/browse/LOGCXX-30). | |
+|  | Appender attributes are not passed passed to setOption correctly. Fixes [LOGCXX-29](https://issues.apache.org/jira/browse/LOGCXX-29). | |
+|  | Appender threshold cannot be set in configuration files Fixes [LOGCXX-28](https://issues.apache.org/jira/browse/LOGCXX-28). | |
+|  | Appender threshold cannot be set in configuration files Fixes [LOGCXX-27](https://issues.apache.org/jira/browse/LOGCXX-27). | |
+|  | Default initialization is broken Fixes [LOGCXX-26](https://issues.apache.org/jira/browse/LOGCXX-26). | |
+|  | Add Ant+cpptasks build file Fixes [LOGCXX-25](https://issues.apache.org/jira/browse/LOGCXX-25). | |
+|  | Class and module name not available in LogEvent Fixes [LOGCXX-24](https://issues.apache.org/jira/browse/LOGCXX-24). | |
+|  | Unit tests have become stale Fixes [LOGCXX-23](https://issues.apache.org/jira/browse/LOGCXX-23). | |
+|  | Backslashes in filenames in XML config of FileAppender broken Fixes [LOGCXX-22](https://issues.apache.org/jira/browse/LOGCXX-22). | |
+|  | Add check that libxml2 not libxml has been included Fixes [LOGCXX-21](https://issues.apache.org/jira/browse/LOGCXX-21). | |
+|  | Add .cvsignore's to ignore generated files Fixes [LOGCXX-19](https://issues.apache.org/jira/browse/LOGCXX-19). | |
+|  | LoggerStream Feature Fixes [LOGCXX-18](https://issues.apache.org/jira/browse/LOGCXX-18). | |
+|  | Use of non reentrant time functions Fixes [LOGCXX-17](https://issues.apache.org/jira/browse/LOGCXX-17). | |
+|  | Misleading statements in Introduction to log4cxx Fixes [LOGCXX-16](https://issues.apache.org/jira/browse/LOGCXX-16). | |
+|  | PatternLayout don't use locale time zone,it's use GMT tome zone Fixes [LOGCXX-15](https://issues.apache.org/jira/browse/LOGCXX-15). | |
+|  | add -Wall to compile log4cxx will get many warning Fixes [LOGCXX-14](https://issues.apache.org/jira/browse/LOGCXX-14). | |
+|  | Add branch optimization hint to LOG4CXX\_DEBUG macro Fixes [LOGCXX-13](https://issues.apache.org/jira/browse/LOGCXX-13). | |
+|  | the threshold of ApenderSkeleton can not be set by calling setOption. Fixes [LOGCXX-12](https://issues.apache.org/jira/browse/LOGCXX-12). | |
+|  | Timezone may have side-effects Fixes [LOGCXX-11](https://issues.apache.org/jira/browse/LOGCXX-11). | |
+|  | Conflicting definitions of tchar.h/simulatenous Unicode+MBCS Fixes [LOGCXX-10](https://issues.apache.org/jira/browse/LOGCXX-10). | |
+|  | Compilation problems using VC5 or VC6 with later Platform SDKs Fixes [LOGCXX-8](https://issues.apache.org/jira/browse/LOGCXX-8). | |
+|  | SocketAppender binary format not compatible with Chainsaw Fixes [LOGCXX-7](https://issues.apache.org/jira/browse/LOGCXX-7). | |
+|  | Win32 OutputDebugString Fixes [LOGCXX-6](https://issues.apache.org/jira/browse/LOGCXX-6). | |
+|  | Preprocessor macro WIN32 used instead of \_WIN32 Fixes [LOGCXX-5](https://issues.apache.org/jira/browse/LOGCXX-5). | |
+|  | initialization not working on many OS's Fixes [LOGCXX-4](https://issues.apache.org/jira/browse/LOGCXX-4). | |
+|  | 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
+
+| | | |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | Fixed examples source code in the "Short introduction to log4cxx". | |
+|  | Fixed, in the renaming algorithm of RollingFileAppender and DailyRollingFileAppender, a problem specific to Unicode. | |
+|  | Fixed conflict with Windows macros "min" and "max", by renaming StrictMath::min and StrictMath::max to StrictMath::minimum and StrictMath::maximum. | |
+|  | Port to HPUX 11.0. | |
+|  | Fixed segmentation fault in PropertyConfigurator. | |
+|  | Port to Solaris. | |
+|  | Fixed MutexException thrown while destroying RollingFileAppender. | |
+|  | 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
+
+| | | |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | Timezone management has been optimized through the class TimeZone | |
+|  | Inter-thread synchronization and reference counting has been optimized | |
+|  | Reference counting now uses gcc atomic functions (bug 929078) | |
+|  | Use of StringBuffer has been optimized. | |
+|  | Support of localisation throug resourceBundles | |
+|  | SyslogAppender now uses the system function 'syslog' to log on the local host. (only for POSIX systems) | |
+|  | 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
+
+| | | |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | Port of log4j Jnuit tests with Cppunit and Boost Regex. | |
+|  | Added explicit exports for MSDEV 6 and MSDEV 7 (no further need of .def files) | |
+|  | Custom levels can be configured through the DOMConfigurator and PropertyConfigurator classes (Level inherites from Object) | |
+|  | Added a reference counter to LoggingEvent to avoid useless copies (LoggingEvent inherites from Object) | |
+|  | The file log4j.xml as well as the file log4j.properties are now search for, in log4cxx initialization. | |
+|  | The root logger can be assigned the "OFF" level. | |
+|  | Added MSVC6 project missing files mutext.cpp and condition.cpp (bug 847397) | |
+|  | condition.cpp now compiles with MSVC6 (bug 847417) | |
+|  | fixed pure virtual function call in PropertyConfigurator::configureAndWatch (bug 848521) | |
+|  | XMLAppender now displays correct timestamp with MSVC 6 (bug 852836) | |
+|  | SRLPORT 4.6 support. | |
+|  | Fixed an infinite loop in class Properties. | |
+|  | Fixed compilations problems with unicode. | |
+|  | Fixed SocketAppender bug concerning MDC and NDC. | |
+
+<a name="0.9.4"/>
+### Release 0.9.4 - 2003-10-25
+
+| | | |
+| ------------------------------------------------------------------- | --------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | StringBuffer has been optimized. | |
+|  | Fixed miscellaneous threading problems. | |
+|  | Added TimeZone support in PatternLayout (bug 796894) | |
+|  | 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
+
+| | | |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | Changed tstring to log4cxx::String and tostringstream to log4cxx::StringBuffer. | |
+|  | Fixed MSVC 2003 compilation erros and warnings. | |
+|  | Added helpers for NDC and MDC. | |
+|  | Added TimeZone support in TTCCLayout. | |
+|  | Fixed compilation problems with logger macros (LOG4CXX\_...) | |
+|  | Fixed milliseconds formatting problem with MSVC 6.0 and 2003 | |
+|  | Fixed AsyncAppender crash | |
+|  | Added new tests | |
+|  | Added benchmarks | |
+
+<a name="0.9.2"/>
+### Release 0.9.2 - 2003-08-10
+
+| | | |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | Fixed FreeBSD compilation problem with pthread mutex (class CriticalSection). | |
+|  | Fixed milliseconds formatting problem (class DateFormat). | |
+|  | 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
+
+| | | |
+| ------------------------------------------------------------------- | ------------------------------------------------------------ | -- |
+| Type | Changes | By |
+|  | Fixed deadlock problems in classes Logger and AsyncAppender. | |
+|  | Fixed MSVC 6.0 compilation problems. | |
+|  | 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
+
+| | | |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | Added ODBCAppender (matching log4j JDBCAppender) | |
+|  | Added SyslogAppender | |
+|  | Added SMTPAppender (only for Linux/FreeBSD) | |
+|  | Added BasicConfigurator | |
+|  | Added a FileWatchDog in PropertyConfigurator and DOMConfigurator | |
+|  | Possibility to load a custom LoggerFactory through the DOMConfigurator | |
+|  | Changed time precision from seconds to milliseconds | |
+|  | 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
+
+| | | |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | 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
+
+| | | |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | FreeBSD Autotools/Compilation support | |
+|  | Fixed TelnetAppender crash when a socket bind exception occured. | |
+|  | Added log4j DTD support to XMLLayout and DOMConfigurator | |
+|  | Can now send events in XML format over TCP (class XMLSocketAppender) for the log4j Chainsaw UI | |
+|  | Now compiles with 'configure --enable-unicode' (UTF16 Unicode support) | |
+|  | Added Java like Properties class. It's a helper for the PropertyConfigurator | |
+|  | Added Java like objects with dynamic cast and instanciation. Custom objects can be configured through the DOMConfigurator and PropertyConfigurator classes | |
+|  | Port of the PropertyConfigurator class | |
+|  | 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
+
+| | | |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
+| Type | Changes | By |
+|  | Loggers, Hierarchy, Filters, Appenders, Layouts, NDC | |
+|  | Appenders: AsyncAppender, ConsoleAppender, FileAppender, NTEventLogAppender, RollingFileAppender, SocketAppender, SocketHubAappender, TelnetAppender | |
+|  | Layouts: HTMLLayout, PatternLayout, SimpleLayout, TTCCLayout, XMLLayout | |
+|  | Filters: DenyAllFilter, LevelMatchFilter, LevelRangeFilter, StringMatchFilter | |
+|  | Configurators: DOMConfigurator | |
diff --git a/src/site/markdown/community/issue-tracking.md b/src/site/markdown/community/issue-tracking.md
new file mode 100644
index 0000000..ae2c1b3
--- /dev/null
+++ b/src/site/markdown/community/issue-tracking.md
@@ -0,0 +1,52 @@
+Issue Tracking {#issue-tracking}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+# Overview
+
+This project uses [JIRA](https://www.atlassian.com/software/jira), a J2EE-based issue tracking
+and project management application.
+
+# Issue Tracking
+
+*Bugs* and *feature requests* should be submitted to the following issue tracking system
+for this project.
+
+https://issues.apache.org/jira/browse/LOGCXX
+
+*Please don't just open bugs only because things don't work for you*, some issues simply
+aren't bugs in the code base of the project or it's build tools, but may have a lot of
+different other reasons. If things don't work for you and you need some help, please subscribe
+to the [users mailing list] and describe
+the issue you have, the more detailed the better. The mailing list is a far better place to
+discuss things than JIRA, besides that there are more users than developers of the project and
+issues created in JIRA are only forwarded to the latter. There's always the chance to create an
+issue in JIRA later, hopefully with a specific explanation of the problem and even a solution
+already.
+
+As a rule of thumb, if you already digged through the code and found a problem in it or its
+build tools, feel free to directly create a bug in [JIRA](https://issues.apache.org/jira/browse/LOGCXX).
+But if things really only don't work and you don't have any clue why, please use the [users mailing list]
+instead.
+
+Thanks!
+
+[users mailing list]:@ref mailing-lists
diff --git a/src/site/markdown/community/mailing-lists.md b/src/site/markdown/community/mailing-lists.md
new file mode 100644
index 0000000..81b8552
--- /dev/null
+++ b/src/site/markdown/community/mailing-lists.md
@@ -0,0 +1,38 @@
+Mailing Lists {#mailing-lists}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+These are the mailing lists that have been established for
+this project. For each list, there is a subscribe, unsubscribe, and an
+archive link.
+| | | | | | |
+| -------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| Name | Subscribe | Unsubscribe | Post | Archive | Other Archives |
+| log4cxx usage | [Subscribe](mailto:log4cxx-user-subscribe@logging.apache.org) | [Unsubscribe](mailto:log4cxx-user-unsubscribe@logging.apache.org) | [Post](mailto:log4cxx-user@logging.apache.org) | [mail-archives.apache.org](http://mail-archives.apache.org/mod_mbox/logging-log4cxx-user/) | [markmail.org](http://markmail.org/search/list:org.apache.logging.log4cxx-user) |
+| \- | \- | \- | \- | \- | [marc.info](http://marc.info/?l=log4cxx-user) |
+| \- | \- | \- | \- | \- | [dir.gmane.org](http://dir.gmane.org/gmane.comp.apache.logging.log4cxx.user) |
+| log4cxx development | [Subscribe](mailto:dev-subscribe@logging.apache.org) | [Unsubscribe](mailto:dev-unsubscribe@logging.apache.org) | [Post](mailto:dev@logging.apache.org) | [mail-archives.apache.org](http://mail-archives.apache.org/mod_mbox/logging-dev/) | [markmail.org](http://markmail.org/search/list:org.apache.logging.dev) |
+| \- | \- | \- | \- | \- | [marc.info](http://marc.info/?l=dev) |
+| \- | \- | \- | \- | \- | [dir.gmane.org](http://dir.gmane.org/gmane.comp.apache.logging.devel) |
+| Old log4cxx development (NOT USED ANYMORE\!) | [Subscribe](mailto:log4cxx-dev-subscribe@logging.apache.org) | [Unsubscribe](mailto:log4cxx-dev-unsubscribe@logging.apache.org) | [Post](mailto:log4cxx-dev@logging.apache.org) | [mail-archives.apache.org](http://mail-archives.apache.org/mod_mbox/logging-log4cxx-dev/) | [markmail.org](http://markmail.org/search/list:org.apache.logging.log4cxx-dev) |
+| \- | \- | \- | \- | \- | [marc.info](http://marc.info/?l=log4cxx-dev) |
+| \- | \- | \- | \- | \- | [dir.gmane.org](http://dir.gmane.org/gmane.comp.apache.logging.log4cxx.devel) |
+
diff --git a/src/site/markdown/configuration-samples.md b/src/site/markdown/configuration-samples.md
new file mode 100644
index 0000000..611ac81
--- /dev/null
+++ b/src/site/markdown/configuration-samples.md
@@ -0,0 +1,214 @@
+Configuration Samples {#configuration-samples}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+The following snippets show various ways of configuring log4cxx.
+
+[TOC]
+
+# Patterns {#patterns}
+
+The basic way of outputing messages is by using a [PatternLayout](@ref log4cxx.PatternLayout),
+and then sending the messages to stderr/stdout/file. The following
+examples show how you might configure the PatternLayout in order to
+achieve the results shown.
+
+Each example has two blocks of code: the layout for the PatternLayout,
+and a sample output message.
+
+## Pattern 1 {#pattern1}
+
+This pattern contains the date in an ISO-8601 format(without fractional seconds),
+followed by the logger name, the level, and then the message.
+
+~~~
+[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%n
+~~~
+
+~~~
+[2020-12-24 15:31:46] root INFO - Hello there!
+~~~
+
+## Pattern 2 {#pattern2}
+
+Similar to Pattern 1, except using ISO-8601 with fractional seconds
+
+~~~
+[%d] %c %-5p - %m%n
+~~~
+
+~~~
+[2020-12-24 15:35:39,225] root INFO - Hello there!
+~~~
+
+## Pattern 3 {#pattern3}
+
+Prints out the number of milliseconds since the start of the application,
+followed by the level(5 character width), followed by the logger name
+(20 character width), followed by the message.
+
+~~~
+%r %-5p %-20c %m%n
+~~~
+
+~~~
+0 INFO root Hello there!
+~~~
+
+# XML Files {#xmlfiles}
+
+One way of configuring log4cxx is with XML files. The following are some examples
+on various ways of using an XML file to configure the logging.
+
+## XML Example 1 {#xml-example-1}
+
+This simple example simply writes messages to stdout.
+If you want to send messages to stderr instead, simply change the 'Target' value
+to `System.err`.
+
+~~~{.xml}
+<?xml version="1.0" encoding="UTF-8" ?>
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
+
+ <appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
+ <param name="Target" value="System.out"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%m%n"/>
+ </layout>
+ </appender>
+
+ <root>
+ <priority value="info" />
+ <appender-ref ref="ConsoleAppender"/>
+ </root>
+
+</log4j:configuration>
+~~~
+
+Sample output:
+~~~
+Hello there!
+~~~
+
+## XML Example 2 {#xml-example-2}
+
+This example sends data to both stdout, as well as to a file. In this case,
+the file will be in our working directory. The pattern has also been updated
+to match with pattern example 1
+
+~~~{.xml}
+<?xml version="1.0" encoding="UTF-8" ?>
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
+
+ <appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
+ <param name="Target" value="System.out"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%n"/>
+ </layout>
+ </appender>
+
+ <appender name="FileAppender" class="org.apache.log4j.FileAppender">
+ <param name="file" value="example.log" />
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%n" />
+ </layout>
+ </appender>
+
+ <root>
+ <priority value="info" />
+ <appender-ref ref="ConsoleAppender"/>
+ <appender-ref ref="FileAppender"/>
+ </root>
+
+</log4j:configuration>
+~~~
+
+Sample output:
+~~~
+[2020-12-24 15:57:35] root INFO - Hello there!
+~~~
+
+## XML Example 3 {#xml-example-3}
+
+This example shows how you can configure logging for a particular category.
+
+Assume that our loggers are in our code as such:
+
+~~~{.cpp}
+ log4cxx::LoggerPtr root = log4cxx::Logger::getRootLogger();
+ log4cxx::LoggerPtr com = log4cxx::Logger::getLogger( "com" );
+ log4cxx::LoggerPtr com_example = log4cxx::Logger::getLogger( "com.example" );
+
+ LOG4CXX_INFO( root, "Hello there!" );
+ LOG4CXX_DEBUG( com, "com logger debug" );
+ LOG4CXX_DEBUG( com_example, "com.example debug message" );
+ LOG4CXX_TRACE( com, "com debug message" );
+ LOG4CXX_TRACE( com_example, "com.example trace message" );
+~~~
+
+For this configuration, we have set any logger that is at the `com` level or below
+to be debug. However, we have also set the logger `com.example` to have a more
+verbose `trace` level to see more information from that particular logger.
+
+~~~{.xml}
+<?xml version="1.0" encoding="UTF-8" ?>
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
+
+ <appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
+ <param name="Target" value="System.out"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%n"/>
+ </layout>
+ </appender>
+
+ <appender name="FileAppender" class="org.apache.log4j.FileAppender">
+ <param name="file" value="example.log" />
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%n" />
+ </layout>
+ </appender>
+
+ <root>
+ <priority value="info" />
+ <appender-ref ref="ConsoleAppender"/>
+ <appender-ref ref="FileAppender"/>
+ </root>
+
+ <logger name="com" >
+ <priority value="debug"/>
+ </logger>
+
+ <logger name="com.example" >
+ <priority value="trace"/>
+ </logger>
+
+</log4j:configuration>
+~~~
+
+Sample output:
+
+~~~
+[2020-12-24 16:05:48] root INFO - Hello there!
+[2020-12-24 16:05:48] com DEBUG - com logger debug
+[2020-12-24 16:05:48] com.example DEBUG - com.example debug message
+[2020-12-24 16:05:48] com.example TRACE - com.example trace message
+~~~
diff --git a/src/site/apt/building/autotools.apt b/src/site/markdown/development/autotools.apt
similarity index 100%
rename from src/site/apt/building/autotools.apt
rename to src/site/markdown/development/autotools.apt
diff --git a/src/site/markdown/development/build-cmake.md b/src/site/markdown/development/build-cmake.md
new file mode 100644
index 0000000..fc7e43f
--- /dev/null
+++ b/src/site/markdown/development/build-cmake.md
@@ -0,0 +1,140 @@
+Build with CMake {#build-cmake}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+# Building Apache log4cxx with CMake
+
+* Quick start:
+
+ Building and testing log4cxx on a Unix platform with packaged APR and APR-Util.
+
+ Make sure cmake 3.13+, g++ and make are available, install or
+ build apr 1.x, apr-util 1.x, gzip and zip.
+
+~~~
+$ apt-get install build-essential libapr1-dev libaprutil1-dev gzip zip
+$ cd apache-log4cxx-x.x.x
+$ mkdir build
+$ cd build
+$ ccmake ..
+$ make
+$ sudo make install
+~~~
+
+* ccmake options
+
+| Option | Usage |
+|------------------------|-------|
+| -DLOG4CXX_WCHAR_T=no | Enable wchar_t API methods, choice of yes (default), no. |
+| -DLOG4CXX_UNICHAR=yes | Enable UniChar API methods, choice of yes, no (default). |
+| -DLOG4CXX_CFSTRING=yes | Enable CFString API methods, requires Mac OS/X CoreFoundation, choice of yes, no (default). |
+| -DBUILD_TESTING=off | Do not build tests. Tests are built by default |
+| -DBUILD_SHARED_LIBS=off| Build log4cxx as a static library. A dynamically linked log4cxx library is built by default. Any compilation unit that includes a log4cxx header must define LOG4CXX_STATIC. |
+| -DAPU_STATIC=yes | Link to the APR-Util static library. By default, the log4cxx shared library is linked to the APR-Util shared library. If BUILD_SHARED_LIBS=off, the static APR-Util library is used. |
+| -DAPR_STATIC=yes | Link to the APR static library. By default, the log4cxx shared library is linked to the APR shared library. If BUILD_SHARED_LIBS=off, the static APR library is always used. |
+|-DLOG4CXX_TEST_PROGRAM_PATH=path| An extra path to prepend to the PATH for test programs. Log4cxx requires zip, sed, and grep on the PATH in order for the tests to work properly. |
+
+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.
+
+~~~
+$ 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
+~~~
+
+# Platform specific notes:
+
+## Mac OS/X:
+
+APR and APR-Util are provided by the platform in Mac OS/X 10.5 and iODBC in 10.4.
+
+cmake can be installed by typing "brew install cmake".
+
+## Debian:
+
+APR, APR-Util, openssl, gzip and zip may be installed by:
+
+~~~
+$ sudo apt-get install libssl-dev libapr1-dev libaprutil1-dev gzip zip
+~~~
+
+CMake can be built from source by typing:
+
+~~~
+$ wget https://github.com/Kitware/CMake/releases/download/v3.16.4/cmake-3.16.4.tar.gz
+$ tar xf cmake-3.16.4.tar.gz
+$ cd cmake-3.16.4
+$ ./bootstrap
+$ make
+$ sudo make install
+~~~
+
+## FreeBSD:
+
+APR, APR-Util, gzip and zip may be installed from the ports collection by:
+
+~~~
+$ cd /usr/ports/archivers/zip
+$ make
+$ make install
+$ cd /usr/ports/archivers/gzip
+$ make
+$ make install
+$ cd /usr/ports/devel/apr
+$ make
+$ make install
+~~~
+
+## Windows:
+
+The easiest way to get dependencies installed is to use vcpkg(for APR/expat), and msys2 for the command-line
+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
+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
+the dependencies needed using `vcpkg install apr apr-util`.
+
+# Using log4cxx in a CMake build
+
+A log4cxxConfig.cmake and log4cxxConfigVersion.cmake is installed to allow use of find_package()
+in your CMakeLists.txt.
+
+Below are example cmake commands that compile and link "myApplication" with log4cxx.
+
+~~~
+find_package(log4cxx 0.11)
+add_executable(myApplication myMain.cpp)
+target_include_directories(myApplication PRIVATE $<TARGET_PROPERTY:log4cxx,INTERFACE_INCLUDE_DIRECTORIES>)
+target_link_libraries( myApplication PRIVATE log4cxx)
+~~~
+
diff --git a/src/site/markdown/development/build-vcpkg.md b/src/site/markdown/development/build-vcpkg.md
new file mode 100644
index 0000000..1dfba51
--- /dev/null
+++ b/src/site/markdown/development/build-vcpkg.md
@@ -0,0 +1,56 @@
+Building with vcpkg {#build-vcpkg}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+# Building Apache log4cxx with vcpkg
+
+## Preparation
+
+Windows:
+~~~
+> git clone https://github.com/Microsoft/vcpkg.git
+> cd vcpkg
+> .\bootstrap-vcpkg.bat
+# Then, to hook up user-wide integration, run (note: requires admin on first use)
+> .\vcpkg integrate install
+~~~
+
+Linux:
+~~~
+$ git clone https://github.com/Microsoft/vcpkg.git
+$ cd vcpkg
+$ ./bootstrap-vcpkg.sh
+$ ./vcpkg integrate install
+~~~
+
+## Building log4cxx.dll
+
+Windows:
+~~~
+PS> .\vcpkg install log4cxx
+~~~
+
+Linux:
+~~~
+$ ./vcpkg install log4cxx
+~~~
+
diff --git a/src/site/markdown/development/building.md b/src/site/markdown/development/building.md
new file mode 100644
index 0000000..b348e39
--- /dev/null
+++ b/src/site/markdown/development/building.md
@@ -0,0 +1,51 @@
+Building {#building}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+# Building Apache log4cxx
+
+The project supports different build tools on different platforms, have a
+look at the menu to find the platform you need. If your environment is not
+covered already, feel free to ask about it on one of the Mailing Lists or
+leave a bug in our Issue Tracker. In this case it would be very helpful of
+course if you could already provide some patches to support your environment
+or at least provide some technical details about the build tools, compiler
+etc. you use.
+
+## Covered by the team
+
+The following list provides an overview about the environments some of the
+team members have access to and therefore normally should work out of the box
+or at least were used sometimes in the past. This list by no means tells
+something about how good the support on each platform is, it's just a guide.
+
+The following platforms/compilers are expected to work correctly:
+
+* Windows 10(32 and 64-bit) - MSVC
+* Windows 10(32-bit) - Embarcadero C++ Builder XE 4
+* Debian 10(32 and 64-bit) - gcc 8.3.0, clang-7
+* Ubuntu 20.04(32 and 64-bit) - gcc, clang
+* Mac OSX - clang
+
+Various Linux distributions already have log4cxx as part of their package
+managers - consult the documentation for your distribution to determine
+if a package already exists.
diff --git a/src/site/markdown/dependencies.md b/src/site/markdown/development/dependencies.md
similarity index 94%
rename from src/site/markdown/dependencies.md
rename to src/site/markdown/development/dependencies.md
index 49a21ec..5cfe28f 100644
--- a/src/site/markdown/dependencies.md
+++ b/src/site/markdown/development/dependencies.md
@@ -1,3 +1,9 @@
+Dependencies {#dependencies}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
@@ -15,6 +21,7 @@
limitations under the License.
-->
+
# LOG4CXX Dependencies
log4cxx requires the following software to build and/or run correctly:
diff --git a/src/site/apt/building/maven.apt b/src/site/markdown/development/maven.apt
similarity index 100%
rename from src/site/apt/building/maven.apt
rename to src/site/markdown/development/maven.apt
diff --git a/src/site/markdown/development/source-repository.md b/src/site/markdown/development/source-repository.md
new file mode 100644
index 0000000..879f02b
--- /dev/null
+++ b/src/site/markdown/development/source-repository.md
@@ -0,0 +1,48 @@
+Source Repository {#source-repository}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+# Overview
+
+Log4cxx uses GIT to manage its source code. Instructions on GIT use can be found at http://git-scm.com/documentation.
+
+## Web Access
+
+The default repository can be seen on gitbox at:
+
+* https://gitbox.apache.org/repos/asf?p=logging-log4cxx.git
+
+This repository is mirrored to GitHub at the following location:
+
+* https://github.com/apache/logging-log4cxx
+
+## Anonymous access
+
+The source can be checked out anonymously from GIT with this command (See http://git-scm.com/docs/git-clone):
+
+~~~
+ $ git clone http://gitbox.apache.org/repos/asf/logging-log4cxx.git
+~~~
+
+## Pull Requests
+
+Pull requests may be submitted through GitHub.
diff --git a/src/site/markdown/download.md.in b/src/site/markdown/download.md.in
new file mode 100644
index 0000000..cb2d4c9
--- /dev/null
+++ b/src/site/markdown/download.md.in
@@ -0,0 +1,64 @@
+Download {#download}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+# Download Apache log4cxx ${LOG4CXX_RELEASE_VERSION}
+
+ Apache log4cxx ${LOG4CXX_RELEASE_VERSION} is distributed under the [Apache License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
+
+ The link in the Mirrors column should display a list of available mirrors with a
+ default selection based on your inferred location. If you do not see that page,
+ try a different browser. The checksum and signature are links to
+ the originals on the main distribution server.
+
+| | Mirrors | Checksum | Signature |
+|-------------------------|---------|----------|-----------|
+| Apache log4cxx ${LOG4CXX_RELEASE_VERSION} (tar.gz) | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz] | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.sha512] | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc] |
+| Apache log4cxx ${LOG4CXX_RELEASE_VERSION} (zip) | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip] | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.sha512] | [apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.asc] |
+
+It is essential that you verify the integrity of the downloaded files using the PGP or SHA512 signatures.
+Please read [Verifying Apache HTTP Server Releases](https://httpd.apache.org/dev/verification.html) for more
+information on why you should verify our releases.
+
+The PGP signatures can be verified using PGP or GPG. First download the [KEYS](https://www.apache.org/dist/logging/KEYS)
+as well as the asc signature file for the relevant distribution. Make sure you get these files from the
+[main distribution directory](https://www.apache.org/dist/logging/), rather than from a mirror. Then verify the signatures using:
+
+~~~
+% gpg --import KEYS
+% gpg --verify apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz
+~~~
+
+* apache-log4cxx-${LOG4CXX_RELEASE_VERSION} is signed by ${releaseManager} (${releaseKey})
+
+Alternatively, you can verify the SHA512 signature on the files. A unix program called sha512 or sha512sum is included
+in many unix distributions.
+
+## Previous Releases
+
+All previous releases of Apache log4cxx can be found in the [archive repository](https://archive.apache.org/dist/logging/log4cxx).
+
+[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz]:https://www.apache.org/dyn/closer.cgi/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz
+[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.sha512]:https://www.apache.org/dist/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.sha512
+[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc]:https://www.apache.org/dist/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.tar.gz.asc
+[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip]:https://www.apache.org/dyn/closer.cgi/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip
+[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.sha512]:https://www.apache.org/dist/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.sha512
+[apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.asc]:https://www.apache.org/dist/logging/log4cxx/${LOG4CXX_RELEASE_VERSION}/apache-log4cxx-${LOG4CXX_RELEASE_VERSION}.zip.asc
diff --git a/src/site/markdown/extending.md b/src/site/markdown/extending.md
new file mode 100644
index 0000000..ede583f
--- /dev/null
+++ b/src/site/markdown/extending.md
@@ -0,0 +1,141 @@
+Extending Log4cxx {#extending-log4cxx}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+Sometimes, you may want to extend log4cxx, for example by creating
+a new appender to write out data in a new format. The following
+guide shows how you can extend log4cxx in order to add a new appender.
+
+The full sample application can be found in the src/examples/cpp
+directory.
+
+The first thing for our example is to create a class that extends
+log4cxx.AppenderSkeleton so that we don't need to implement all of
+the virtual methods that are defined in log4cxx.Appender:
+
+~~~{.cpp}
+namespace log4cxx {
+
+class NullWriterAppender : public log4cxx::AppenderSkeleton {
+};
+
+}
+~~~
+
+Next, we need to add in a few macros in order to properly register
+our new appender with log4cxx:
+
+~~~{.cpp}
+namespace log4cxx {
+
+class NullWriterAppender : public log4cxx::AppenderSkeleton {
+public:
+ DECLARE_LOG4CXX_OBJECT(NullWriterAppender)
+ BEGIN_LOG4CXX_CAST_MAP()
+ LOG4CXX_CAST_ENTRY(NullWriterAppender)
+ LOG4CXX_CAST_ENTRY_CHAIN(AppenderSkeleton)
+ END_LOG4CXX_CAST_MAP()
+
+};
+
+IMPLEMENT_LOG4CXX_OBJECT(NullWriterAppender)
+
+}
+~~~
+
+These macros tell log4cxx what the name of our class is, as well as giving
+log4cxx a way of instansiating our class. Without these macros, the custom
+class will not work.
+
+Now, let's add some basic functionality to our class. As the name of
+our class implies, we are going to do nothing with our appender here, as
+this is just an example. To that end, we need to implement the following:
+1. Default constructor
+2. `close` method
+3. `requiresLayout` method
+4. `append` method, which does the actual writing of the log event
+5. `activateOptions`, which causes the class to reconfigure itself
+6. `setOption`, which gets called whenever we get an option in a config file
+
+These are basically stub methods, with a few comments on their use:
+
+~~~{.cpp}
+ NullWriterAppender(){}
+
+ virtual void close(){}
+
+ virtual bool requiresLayout() const {
+ return false;
+ }
+
+ virtual void append(const spi::LoggingEventPtr& event, log4cxx::helpers::Pool& p){
+ // This gets called whenever there is a valid event for our appender.
+ }
+
+ virtual void activateOptions(log4cxx::helpers::Pool& /* pool */) {
+ // Given all of our options, do something useful(e.g. open a file)
+ }
+
+ virtual void setOption(const LogString& option, const LogString& value){
+ if (helpers::StringHelper::equalsIgnoreCase(option,
+ LOG4CXX_STR("SOMEVALUE"), LOG4CXX_STR("somevalue"))){
+ // Do something with the 'value' here.
+ }
+ }
+~~~
+
+At this point, we now have a fully functioning(if useless) custom appender. We can now
+refer to this appender in our configuration file like so:
+
+~~~{.xml}
+<?xml version="1.0" encoding="UTF-8" ?>
+<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
+ <appender name="ConsoleAppender" class="org.apache.log4j.ConsoleAppender">
+ <param name="Target" value="System.out"/>
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="[%d{yyyy-MM-dd HH:mm:ss}] %c %-5p - %m%n"/>
+ </layout>
+ </appender>
+
+ <appender name="NullAppender" class="NullWriterAppender">
+ <param name="SomeValue" value="Nothing"/>
+ </appender>
+
+ <root>
+ <priority value="info" />
+ <appender-ref ref="ConsoleAppender"/>
+ </root>
+
+ <logger name="NullLogger" additivity="false">
+ <appender-ref ref="NullAppender"/>
+ </logger>
+</log4j:configuration>
+~~~
+
+When log4cxx is configured, any messages that go to the `NullLogger` will
+then be forwarded on to the `NullWriterAppender`.
+
+This same technique can be used to add new classes of many different kinds
+to log4cxx, including(but not limited to):
+* [Appenders](@ref log4cxx.Appender)
+* [Layouts](@ref log4cxx.Layout)
+* [Filters](@ref log4cxx.spi.Filter)
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 190ff4d..b1c7ce6 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -1,3 +1,9 @@
+FAQ {#faq}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
new file mode 100644
index 0000000..7d6d9c7
--- /dev/null
+++ b/src/site/markdown/index.md
@@ -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.
+-->
+
+# Short introduction to Apache log4cxx
+
+Apache log4cxx is a logging framework for C++ patterned after [Apache log4j],
+which uses [Apache Portable Runtime] for most platform-specific code and should
+be usable on any platform supported by APR. Apache log4cxx is licensed under
+the [Apache License], an open source license certified by the [Open Source Initiative].
+
+Almost every large application includes its own logging or tracing API.
+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 is 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.
+
+Logging does have its drawbacks. It can slow down an application. If too verbose,
+it can cause scrolling blindness. To alleviate these concerns, log4cxx is
+designed to be reliable, fast and extensible. Since logging is rarely the
+main focus of an application, the log4cxx API strives to be simple to
+understand and to use.
+
+[Apache log4j]:https://logging.apache.org/log4j/2.x/
+[Apache Portable Runtime]:https://apr.apache.org/
+[Apache License]:https://www.apache.org/licenses/
+[Open Source Initiative]:https://opensource.org/
diff --git a/src/site/markdown/license.md b/src/site/markdown/license.md
new file mode 100644
index 0000000..233f889
--- /dev/null
+++ b/src/site/markdown/license.md
@@ -0,0 +1,232 @@
+License {#license}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+
+# Overview
+
+Typically the licenses listed for the project are that of the project itself, and not of dependencies.
+
+## Project License
+Apache License, Version 2.0
+~~~
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed 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.
+~~~
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
new file mode 100644
index 0000000..84dbd77
--- /dev/null
+++ b/src/site/markdown/usage.md
@@ -0,0 +1,813 @@
+Usage {#usage}
+===
+<!--
+ Note: License header cannot be first, as doxygen does not generate
+ cleanly if it before the '==='
+-->
+<!--
+ 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.
+-->
+[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}
+
+The first and foremost advantage of any logging API over plain
+`std::cout` resides in its ability to disable certain log statements
+while allowing others to print unhindered. This capability assumes that
+the logging space, that is, the space of all possible logging
+statements, is categorized according to some developer-chosen criteria.
+
+Loggers are named entities. Logger names are case-sensitive and they
+follow the hierarchical naming rule:
+
+**Named Hierarchy**
+
+A logger is said to be an *ancestor* of another logger if its name
+followed by a dot is a prefix of the *descendant* logger name. A logger
+is said to be a *parent* of a *child* logger if there are no ancestors
+between itself and the descendant logger.
+
+For example, the logger named `com.foo` is a parent of the logger
+named `com.foo.Bar`. Similarly, `java` is a parent of `java.util`
+and an ancestor of `java.util.Vector`. This naming scheme should be
+familiar to most developers.
+
+The root logger resides at the top of the logger hierarchy. It is
+exceptional in two ways:
+
+1. it always exists,
+2. it cannot be retrieved by name.
+
+Invoking the class static
+log4cxx::Logger::getRootLogger method retrieves it. All other loggers are instantiated and retrieved
+with the class static log4cxx::Logger::getLogger
+method. This method takes the name of the desired logger as a parameter.
+Some of the basic methods in the Logger class are listed below.
+
+~~~{.cpp}
+ namespace log4cxx {
+ class Logger {
+ public:
+ // Creation & retrieval methods:
+ static LoggerPtr getRootLogger();
+ static LoggerPtr getLogger(const std::string& name);
+ static LoggerPtr getLogger(const std::wstring& name);
+ }
+ }
+
+ //
+ // Use these macros instead of calling Logger methods directly.
+ // Macros will handle char or wchar_t pointers or strings
+ // or most right-hand side expressions of an
+ // std::basic_string::operator<<.
+ //
+ #define LOG4CXX_TRACE(logger, expression) ...
+ #define LOG4CXX_DEBUG(logger, expression) ...
+ #define LOG4CXX_INFO(logger, expression) ...
+ #define LOG4CXX_WARN(logger, expression) ...
+ #define LOG4CXX_ERROR(logger, expression) ...
+ #define LOG4CXX_FATAL(logger, expression) ...
+~~~
+
+## Levels {#levels}
+
+Loggers *may* be assigned levels. The pre-defined levels: TRACE, DEBUG,
+INFO, WARN, ERROR and FATAL are defined in the
+log4cxx::Level class which provides accessor functions.
+
+If a given logger is not assigned a level, then it inherits one from its
+closest ancestor with an assigned level. More formally:
+
+**Level Inheritance**
+
+The *inherited level* for a given logger *C*, is equal to the first
+non-null level in the logger hierarchy, starting at *C* and proceeding
+upwards in the hierarchy towards the *root* logger.
+
+To ensure that all loggers can eventually inherit a level, the root
+logger always has an assigned level.
+
+Below are four tables with various assigned level values and the
+resulting inherited levels according to the above rule.
+
+| Logger name | Assigned level | Inherited level |
+| ----------- | -------------- | --------------- |
+| root | Proot | Proot |
+| X | none | Proot |
+| X.Y | none | Proot |
+| X.Y.Z | none | Proot |
+
+Example 1
+
+In example 1 above, only the root logger is assigned a level. This level
+value, *Proot*, is inherited by the other loggers *X*, *X.Y* and
+*X.Y.Z*.
+
+| Logger name | Assigned level | Inherited level |
+| ----------- | -------------- | --------------- |
+| root | Proot | Proot |
+| X | Px | Px |
+| X.Y | Pxy | Pxy |
+| X.Y.Z | Pxyz | Pxyz |
+
+Example 2
+
+In example 2, all loggers have an assigned level value. There is no need
+for level inheritence.
+
+| Logger name | Assigned level | Inherited level |
+| ----------- | -------------- | --------------- |
+| root | Proot | Proot |
+| X | Px | Px |
+| X.Y | none | Px |
+| X.Y.Z | Pxyz | Pxyz |
+
+Example 3
+
+In example 3, the loggers *root*, *X* and *X.Y.Z* are assigned the
+levels *Proot*, *Px* and *Pxyz* respectively. The logger *X.Y* inherits
+its level value from its parent *X*.
+
+| Logger name | Assigned level | Inherited level |
+| ----------- | -------------- | --------------- |
+| root | Proot | Proot |
+| X | Px | Px |
+| X.Y | none | Px |
+| X.Y.Z | none | Px |
+
+Example 4
+
+In example 4, the loggers *root* and *X* and are assigned the levels
+*Proot* and *Px* respectively. The loggers *X.Y* and *X.Y.Z* inherits
+their level value from their nearest parent *X* having an assigned
+level.
+
+## 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
+support short-circuiting if the threshold is not satisfied and use of
+the insertion operator (\<\<) in the message parameter.
+
+~~~{.cpp}
+ log4cxx::LoggerPtr logger(log4cxx::Logger::getLogger("com.foo"));
+ const char* region = "World";
+ LOG4CXX_INFO(logger, "Simple message text.")
+ LOG4CXX_INFO(logger, "Hello, " << region)
+ LOG4CXX_DEBUG(logger, L"Iteration " << i)
+ LOG4CXX_DEBUG(logger, "e^10 = " << std::scientific << exp(10.0))
+ //
+ // Use a wchar_t first operand to force use of wchar_t based stream.
+ //
+ LOG4CXX_WARN(logger, L"" << i << L" is the number of the iteration.")
+~~~
+
+A logging request is said to be *enabled* if its level is higher than or
+equal to the level of its logger. Otherwise, the request is said to be
+*disabled*. A logger without an assigned level will inherit one from the
+hierarchy. This rule is summarized below.
+
+**Basic Selection Rule**
+
+A log request of level *p* in a logger with (either assigned or
+inherited, whichever is appropriate) level *q*, is enabled if *p \>= q*.
+
+This rule is at the heart of log4cxx. It assumes that levels are
+ordered. For the standard levels, we have *TRACE \< DEBUG \< INFO \<
+WARN \< ERROR \< FATAL*.
+
+Here is an example of this rule.
+
+~~~{.cpp}
+ // get a logger instance named "com.foo"
+ log4cxx::LoggerPtr logger(log4cxx::Logger::getLogger("com.foo"));
+
+ // Now set its level. Normally you do not need to set the
+ // level of a logger programmatically. This is usually done
+ // in configuration files.
+ logger->setLevel(log4cxx::Level::getInfo());
+
+ log4cxx::LoggerPtr barlogger(log4cxx::Logger::getLogger("com.foo.Bar"));
+
+ // This request is enabled, because WARN >= INFO.
+ LOG4CXX_WARN(logger, "Low fuel level.")
+
+ // This request is disabled, because DEBUG < INFO.
+ LOG4CXX_DEBUG(logger, "Starting search for nearest gas station.")
+
+ // The logger instance barlogger, named "com.foo.Bar",
+ // will inherit its level from the logger named
+ // "com.foo" Thus, the following request is enabled
+ // because INFO >= INFO.
+ LOG4CXX_INFO(barlogger. "Located nearest gas station.")
+
+ // This request is disabled, because DEBUG < INFO.
+ LOG4CXX_DEBUG(barlogger, "Exiting gas station search")
+~~~
+
+Calling the *getLogger* method with the same name will always return a
+reference to the exact same logger object.
+
+For example, in
+
+~~~{.cpp}
+ log4cxx::LoggerPtr x = log4cxx::Logger::getLogger("wombat");
+ log4cxx::LoggerPtr y = log4cxx::Logger::getLogger("wombat");
+~~~
+
+*x* and *y* refer to *exactly* the same logger object.
+
+Thus, it is possible to configure a logger and then to retrieve the same
+instance somewhere else in the code without passing around references.
+In fundamental contradiction to biological parenthood, where parents
+always preceed their children, log4cxx loggers can be created and
+configured in any order. In particular, a "parent" logger will find and
+link to its descendants even if it is instantiated after them.
+
+Configuration of the log4cxx environment is typically done at
+application initialization. The preferred way is by reading a
+configuration file. This approach will be discussed shortly.
+
+Log4cxx makes it easy to name loggers by *software component*. This can
+be accomplished by statically instantiating a logger in each class, with
+the logger name equal to the fully qualified name of the class. This is
+a useful and straightforward method of defining loggers. As the log
+output bears the name of the generating logger, this naming strategy
+makes it easy to identify the origin of a log message. However, this is
+only one possible, albeit common, strategy for naming loggers. Log4cxx
+does not restrict the possible set of loggers. The developer is free to
+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}
+
+The ability to selectively enable or disable logging requests based on
+their logger is only part of the picture. Log4cxx allows logging
+requests to print to multiple destinations. In log4cxx speak, an output
+destination is called an *appender*. Currently, appenders exist for the
+[console](@ref log4cxx.ConsoleAppender), [files](@ref log4cxx.FileAppender),
+GUI components, [remote socket](@ref log4cxx.net.SocketAppender)
+servers, [NT Event Loggers](@ref log4cxx.nt.NTEventLogAppender),
+and remote UNIX [Syslog](@ref log4cxx.net.SyslogAppender)
+daemons. It is also possible to log
+[asynchronously](@ref log4cxx.AsyncAppender).
+
+More than one appender can be attached to a logger.
+
+The
+[addAppender](@ref log4cxx.Logger.addAppender)
+method adds an appender to a given logger. *Each enabled logging
+request for a given logger will be forwarded to all the appenders in
+that logger as well as the appenders higher in the hierarchy.* In other
+words, appenders are inherited additively from the logger hierarchy. For
+example, if a console appender is added to the root logger, then all
+enabled logging requests will at least print on the console. If in
+addition a file appender is added to a logger, say *C*, then enabled
+logging requests for *C* and *C*'s children will print on a file *and*
+on the console. It is possible to override this default behavior so that
+appender accumulation is no longer additive by
+[setting the additivity flag](@ref log4cxx.Logger.setAdditivity) to `false`.
+
+The rules governing appender additivity are summarized below.
+
+**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
+additivity". However, if an ancestor of logger *C*, say *P*, has the
+additivity flag set to *false*, then *C*'s output will be directed to
+all the appenders in *C* and it's ancestors up to and including *P* but,
+not the appenders in any of the ancestors of *P*.
+
+Loggers have their additivity flag set to *true* by default.
+
+The table below shows an
+example:
+
+| Logger Name | Added Appenders | Additivity Flag | Output Targets | Comment |
+| --------------- | --------------- | --------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| root | A1 | not applicable | A1 | The root logger is anonymous but can be accessed with the log4cxx::Logger::getRootLogger() method. There is no default appender attached to root. |
+| x | A-x1, A-x2 | true | A1, A-x1, A-x2 | Appenders of "x" and root. |
+| x.y | none | true | A1, A-x1, A-x2 | Appenders of "x" and root. |
+| x.y.z | A-xyz1 | true | A1, A-x1, A-x2, A-xyz1 | Appenders in "x.y.z", "x" and root. |
+| security | A-sec | false | A-sec | No appender accumulation since the additivity flag is set to *false*. |
+| security.access | none | true | A-sec | Only appenders of "security" because the additivity flag in "security" is set to *false*. |
+
+More often than not, users wish to customize not only the output
+destination but also the output format. This is accomplished by
+associating a *layout* with an appender. The layout is responsible for
+formatting the logging request according to the user's wishes, whereas
+an appender takes care of sending the formatted output to its
+destination.
+
+The [PatternLayout](@ref log4cxx.PatternLayout),
+part of the standard log4cxx distribution, lets the user specify the
+output format according to conversion patterns similar to the C language
+*printf* function.
+
+For example, the PatternLayout with the conversion pattern `%%r [%%t]
+%%-5p %%c - %%m%%n` will output something akin to:
+
+~~~
+176 [main] INFO org.foo.Bar - Located nearest gas station.
+~~~
+
+The first field is the number of milliseconds elapsed since the start of
+the program. The second field is the thread making the log request. The
+third field is the level of the log statement. The fourth field is the
+name of the logger associated with the log request. The text after the
+'-' is the message of the statement.
+
+# Configuration {#configuration}
+
+Inserting log requests into the application code requires a fair amount
+of planning and effort. Observation shows that approximately 4 percent
+of code is dedicated to logging. Consequently, even moderately sized
+applications will have thousands of logging statements embedded within
+their code. Given their number, it becomes imperative to manage these
+log statements without the need to modify them manually.
+
+The log4cxx environment is fully configurable programmatically. However,
+it is far more flexible to configure log4cxx using configuration files.
+Currently, configuration files can be written in XML or in Java
+properties (key=value) format.
+
+Let us give a taste of how this is done with the help of an imaginary
+application *MyApp* that uses log4cxx.
+
+~~~{.cpp}
+ #include "com/foo/bar.h"
+ using namespace com::foo;
+
+ // include log4cxx header files.
+ #include "log4cxx/logger.h"
+ #include "log4cxx/basicconfigurator.h"
+ #include "log4cxx/helpers/exception.h"
+
+ using namespace log4cxx;
+ using namespace log4cxx::helpers;
+
+ LoggerPtr logger(Logger::getLogger("MyApp"));
+
+ int main(int argc, char **argv)
+ {
+ int result = EXIT_SUCCESS;
+ try
+ {
+ // Set up a simple configuration that logs on the console.
+ BasicConfigurator::configure();
+
+ LOG4CXX_INFO(logger, "Entering application.")
+ Bar bar;
+ bar.doIt();
+ LOG4CXX_INFO(logger, "Exiting application.")
+ }
+ catch(Exception&)
+ {
+ result = EXIT_FAILURE;
+ }
+
+ return result;
+ }
+~~~
+
+*MyApp* begins by including log4cxx headers. It then defines a static
+logger variable with the name *MyApp* which happens to be the fully
+qualified name of the class.
+
+*MyApp* uses the *Bar* class defined in header file *com/foo/bar.h*.
+
+~~~{.cpp}
+ // file com/foo/bar.h
+ #include "log4cxx/logger.h"
+
+ namespace com {
+ namespace foo {
+ class Bar {
+ static log4cxx::LoggerPtr logger;
+
+ public:
+ void doIt();
+ }
+ }
+ }
+~~~
+
+~~~{.cpp}
+ // file bar.cpp
+ #include "com/foo/bar.h"
+
+ using namespace com::foo;
+ using namespace log4cxx;
+
+ LoggerPtr Bar::logger(Logger::getLogger("com.foo.bar"));
+
+ void Bar::doIt() {
+ LOG4CXX_DEBUG(logger, "Did it again!")
+ }
+~~~
+
+The invocation of the
+[BasicConfigurator::configure](@ref log4cxx.BasicConfigurator.configure)
+method creates a rather simple log4cxx setup. This method is hardwired
+to add to the root logger a [ConsoleAppender](@ref log4cxx.ConsoleAppender).
+The output will be formatted using a
+[PatternLayout](@ref log4cxx.PatternLayout)
+set to the pattern `%%-4r [%%t] %%-5p %%c %%x - %%m%%n`.
+
+Note that by default, the root logger is assigned to
+*Level::getDebug()*.
+
+The output of MyApp is:
+
+~~~
+ 0 [12345] INFO MyApp - Entering application.
+ 36 [12345] DEBUG com.foo.Bar - Did it again!
+ 51 [12345] INFO MyApp - Exiting application.
+~~~
+
+The previous example always outputs the same log information.
+Fortunately, it is easy to modify *MyApp* so that the log output can be
+controlled at run-time. Here is a slightly modified version.
+
+~~~{.cpp}
+ // file MyApp2.cpp
+
+ #include "com/foo/bar.h"
+ using namespace com::foo;
+
+ // include log4cxx header files.
+ #include "log4cxx/logger.h"
+ #include "log4cxx/basicconfigurator.h"
+ #include "log4cxx/propertyconfigurator.h"
+ #include "log4cxx/helpers/exception.h"
+
+ using namespace log4cxx;
+ using namespace log4cxx::helpers;
+ // Define a static logger variable so that it references the
+ // Logger instance named "MyApp".
+ LoggerPtr logger(Logger::getLogger("MyApp"));
+
+ int main(int argc, char **argv)
+ {
+ int result = EXIT_SUCCESS;
+ try
+ {
+ if (argc > 1)
+ {
+ // BasicConfigurator replaced with PropertyConfigurator.
+ PropertyConfigurator::configure(argv[1]);
+ }
+ else
+ {
+ BasicConfigurator::configure();
+ }
+
+ LOG4CXX_INFO(logger, "Entering application.")
+ Bar bar
+ bar.doIt();
+ LOG4CXX_INFO(logger, "Exiting application.")
+ }
+ catch(Exception&)
+ {
+ result = EXIT_FAILURE;
+ }
+
+ return result;
+ }
+~~~
+
+This version of *MyApp* instructs *PropertyConfigurator* to parse a
+configuration file and set up logging accordingly.
+
+Here is a sample configuration file that results in exactly same output
+as the previous *BasicConfigurator* based example.
+
+~~~
+ # Set root logger level to DEBUG and its only appender to A1.
+ log4j.rootLogger=DEBUG, A1
+
+ # A1 is set to be a ConsoleAppender.
+ log4j.appender.A1=org.apache.log4j.ConsoleAppender
+
+ # A1 uses PatternLayout.
+ log4j.appender.A1.layout=org.apache.log4j.PatternLayout
+ log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
+~~~
+
+It can be noticed that the PropertyConfigurator file format is the same
+as log4j.
+
+Suppose we are no longer interested in seeing the output of any
+component belonging to the *com::foo* package. The following
+configuration file shows one possible way of achieving this.
+
+~~~
+ log4j.rootLogger=DEBUG, A1
+ log4j.appender.A1=org.apache.log4j.ConsoleAppender
+ log4j.appender.A1.layout=org.apache.log4j.PatternLayout
+
+ # Print the date in ISO 8601 format
+ log4j.appender.A1.layout.ConversionPattern=%d [%t] %-5p %c - %m%n
+
+ # Print only messages of level WARN or above in the package com.foo.
+ log4j.logger.com.foo=WARN
+~~~
+
+The output of *MyApp* configured with this file is shown below.
+
+~~~
+ 2000-09-07 14:07:41,508 [12345] INFO MyApp - Entering application.
+ 2000-09-07 14:07:41,529 [12345] INFO MyApp - Exiting application.
+~~~
+
+As the logger *com.foo.Bar* does not have an assigned level, it inherits
+its level from *com.foo*, which was set to WARN in the configuration
+file. The log statement from the *Bar::doIt* method has the level DEBUG,
+lower than the logger level WARN. Consequently, *doIt()* method's log
+request is suppressed.
+
+Here is another configuration file that uses multiple appenders.
+
+~~~
+ log4j.rootLogger=debug, stdout, R
+
+ log4j.appender.stdout=org.apache.log4j.ConsoleAppender
+ log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
+
+ # Pattern to output the caller's file name and line number.
+ log4j.appender.stdout.layout.ConversionPattern=%5p [%t] (%F:%L) - %m%n
+
+ log4j.appender.R=org.apache.log4j.RollingFileAppender
+ log4j.appender.R.File=example.log
+
+ log4j.appender.R.MaxFileSize=100KB
+ # Keep one backup file
+ log4j.appender.R.MaxBackupIndex=1
+
+ log4j.appender.R.layout=org.apache.log4j.PatternLayout
+ log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n
+~~~
+
+Calling the enhanced MyApp with the this configuration file will output
+the following on the console.
+
+~~~
+ INFO [12345] (MyApp2.cpp:31) - Entering application.
+ DEBUG [12345] (Bar.h:16) - Doing it again!
+ INFO [12345] (MyApp2.cpp:34) - Exiting application.
+~~~
+
+In addition, as the root logger has been allocated a second appender,
+output will also be directed to the *example.log* file. This file will
+be rolled over when it reaches 100KB. When roll-over occurs, the old
+version of *example.log* is automatically moved to *example.log.1*.
+
+Note that to obtain these different logging behaviors we did not need to
+recompile code. We could just as easily have logged to a UNIX Syslog
+daemon, redirected all *com.foo* output to an NT Event logger, or
+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 Procedure {#default-initialization-procedure}
+
+The log4cxx library does not make any assumptions about its environment.
+In particular, there are no default log4cxx appenders. Under certain
+well-defined circumstances however, the static inializer of the *Logger*
+class will attempt to automatically configure log4cxx.
+
+The exact default initialization algorithm is defined as follows:
+
+1. Set the configurationOptionStr string variable to the value of the
+ **LOG4CXX\_CONFIGURATION** environment variable if set, otherwise
+ the value of the **log4j.configuration** environment variable if
+ set, otherwise the first of the following file names which exist in
+ the current working directory, "log4cxx.xml", "log4cxx.properties",
+ "log4j.xml" and "log4j.properties". If configurationOptionStr has
+ not been set, then disable logging.
+2. Unless a custom configurator is specified using the
+ **LOG4CXX\_CONFIGURATOR\_CLASS** or **log4j.configuratorClass**
+ environment variable, the PropertyConfigurator will be used to
+ configure log4cxx unless the file name ends with the ".xml"
+ extension, in which case the DOMConfigurator will be used. If a
+ custom configurator is specified, the environment variable should
+ contain a fully qualified class name of a class that implements the
+ Configurator interface.
+
+# Nested Diagnostic Contexts {#nested-diagnostic-contexts}
+
+Most real-world systems have to deal with multiple clients
+simultaneously. In a typical multithreaded implementation of such a
+system, different threads will handle different clients. Logging is
+especially well suited to trace and debug complex distributed
+applications. A common approach to differentiate the logging output of
+one client from another is to instantiate a new separate logger for each
+client. This promotes the proliferation of loggers and increases the
+management overhead of logging.
+
+A lighter technique is to uniquely stamp each log request initiated from
+the same client interaction. Neil Harrison described this method in the
+book "Patterns for Logging Diagnostic Messages," in *Pattern Languages
+of Program Design 3*, edited by R. Martin, D. Riehle, and F. Buschmann
+(Addison-Wesley, 1997).
+
+To uniquely stamp each request, the user pushes contextual information
+into the NDC, the abbreviation of *Nested Diagnostic Context*. The NDC
+class is shown below.
+
+~~~{.cpp}
+ namespace log4cxx {
+ class NDC {
+ public:
+ // pushes the value on construction and pops on destruction.
+ NDC(const std::string& value);
+ NDC(const std::wstring& value);
+
+ // Remove the top of the context from the NDC.
+ static LogString pop();
+
+ // Add diagnostic context for the current thread.
+ static void push(const std::string& message);
+ static void push(const std::wstring& message);
+ }
+ }
+~~~
+
+The NDC is managed per thread as a *stack* of contextual information.
+Note that all methods of the *log4cxx::NDC* class are static. Assuming
+that NDC printing is turned on, every time a log request is made, the
+appropriate log4cxx component will include the *entire* NDC stack for
+the current thread in the log output. This is done without the
+intervention of the user, who is responsible only for placing the
+correct information in the NDC by using the *push* and *pop* methods at
+a few well-defined points in the code. In contrast, the per-client
+logger approach commands extensive changes in the code.
+
+To illustrate this point, let us take the example of a servlet
+delivering content to numerous clients. The servlet can build the NDC at
+the very beginning of the request before executing other code. The
+contextual information can be the client's host name and other
+information inherent to the request, typically information contained in
+cookies. Hence, even if the servlet is serving multiple clients
+simultaneously, the logs initiated by the same code, i.e. belonging to
+the same logger, can still be distinguished because each client request
+will have a different NDC stack. Contrast this with the complexity of
+passing a freshly instantiated logger to all code exercised during the
+client's request.
+
+Nevertheless, some sophisticated applications, such as virtual hosting
+web servers, must log differently depending on the virtual host context
+and also depending on the software component issuing the request. Recent
+log4cxx releases support multiple hierarchy trees. This enhancement
+allows each virtual host to possess its own copy of the logger
+hierarchy.
+
+# Performance {#performance}
+
+One of the often-cited arguments against logging is its computational
+cost. This is a legitimate concern as even moderately sized applications
+can generate thousands of log requests. Much effort was spent measuring
+and tweaking logging performance. Log4cxx claims to be fast and
+flexible: speed first, flexibility second.
+
+The user should be aware of the following performance issues.
+
+1. **Logging performance when logging is turned off.**
+
+ When logging is turned off entirely or just for a set of levels, the
+ cost of a log request consists of a method invocation plus an
+ integer comparison. The LOG4CXX\_DEBUG and similar macros suppress
+ unnecessary expression evaluation if the request is not enabled.
+
+2. **The performance of deciding whether to log or not to log when
+ logging is turned on.**
+
+ This is essentially the performance of walking the logger hierarchy.
+ When logging is turned on, log4cxx still needs to compare the level
+ of the log request with the level of the request logger. However,
+ loggers may not have an assigned level; they can inherit them from
+ the logger hierarchy. Thus, before inheriting a level, the logger
+ may need to search its ancestors.
+
+ There has been a serious effort to make this hierarchy walk to be as
+ fast as possible. For example, child loggers link only to their
+ existing ancestors. In the *BasicConfigurator* example shown
+ earlier, the logger named *com.foo.Bar* is linked directly to the
+ root logger, thereby circumventing the nonexistent *com* or
+ *com.foo* loggers. This significantly improves the speed of the
+ walk, especially in "sparse" hierarchies.
+
+ The cost of walking the hierarchy is typically 3 times slower than
+ when logging is turned off entirely.
+
+3. **Actually outputting log messages**
+
+ This is the cost of formatting the log output and sending it to its
+ target destination. Here again, a serious effort was made to make
+ layouts (formatters) perform as quickly as possible. The same is
+ true for appenders.
+
+# Removing log statements {#removing-log-statements}
+
+Sometimes, you may want to remove all log statements from your program,
+either for speed purposes or to remove sensitive information. This can easily
+be accomplished at build-time when using the standard `LOG4CXX_[level]` macros
+(`LOG4CXX_TRACE`, `LOG4CXX_DEBUG`, `LOG4CXX_INFO`, `LOG4CXX_WARN`,
+`LOG4CXX_ERROR`, `LOG4CXX_FATAL`).
+
+Log statements can be removed either above a certain level, or they
+can be disabled entirely.
+
+For example, if we want to remove all log statements within our program
+that use the `LOG4CXX_[level]` family of macros, add a preprocessor
+definition `LOG4CXX_THRESHOLD` set to 50001
+or greater. This will ensure that any log statement that uses the
+`LOG4CXX_[level]`-macro will be compiled out of the program. To remove
+all log statements at `DEBUG` or below, set `LOG4CXX_THRESHOLD` to a
+value between 10001-20000.
+
+The levels are set as follows:
+
+|Logger Level|Integer Value|
+|------------|-------------|
+|TRACE |5000 |
+|DEBUG |10000 |
+|INFO |20000 |
+|WARN |30000 |
+|ERROR(1) |40000 |
+|FATAL |50000 |
+
+(1) The `LOG4CXX_ASSERT` macro is the same level as `LOG4CXX_ERROR`
+
+Note that this has no effect on other macros, such as using the
+`LOG4CXX_LOG`, `LOG4CXX_LOGLS`, or `LOG4CXX_L7DLOG` family of macros.
+
+# 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]
+~~~
+
+# Conclusions {#conclusions}
+
+Apache Log4cxx is a popular logging package written in C++. One of its
+distinctive features is the notion of inheritance in loggers. Using a
+logger hierarchy it is possible to control which log statements are
+output at arbitrary granularity. This helps reduce the volume of logged
+output and minimize the cost of logging.
+
+One of the advantages of the log4cxx API is its manageability. Once the
+log statements have been inserted into the code, they can be controlled
+with configuration files. They can be selectively enabled or disabled,
+and sent to different and multiple output targets in user-chosen
+formats. The log4cxx package is designed so that log statements can
+remain in shipped code without incurring a heavy performance cost.
diff --git a/src/site/xdoc/usage.xml b/src/site/xdoc/usage.xml
deleted file mode 100644
index ad272ca..0000000
--- a/src/site/xdoc/usage.xml
+++ /dev/null
@@ -1,1062 +0,0 @@
-<!--
- 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.
-
--->
-<document>
- <properties>
- <title>How to use Apache log4cxx</title>
- </properties>
-
- <body>
- <section name="Loggers">
- <p>
- Log4cxx has three main components: <em>loggers</em>,
- <em>appenders</em> and <em>layouts</em>. 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.
- </p>
-
- <subsection name="Hierarchy">
- <p>
- The first and foremost advantage of any logging API over plain
- <code>std::cout</code> resides in its ability to disable
- certain log statements while allowing others to print unhindered. This
- capability assumes that the logging space, that is, the space of all
- possible logging statements, is categorized according to some
- developer-chosen criteria.
- </p>
-
- <p>
- Loggers are named entities. Logger names are case-sensitive and
- they follow the hierarchical naming rule:
- </p>
-
- <dl>
- <dt><strong>Named Hierarchy</strong></dt>
- <dd>
- A logger is said to be an <em>ancestor</em> of another
- logger if its name followed by a dot is a prefix of the
- <em>descendant</em> logger name. A logger is said to be a
- <em>parent</em> of a <em>child</em> logger if there are no
- ancestors between itself and the descendant logger.
- </dd>
- </dl>
-
- <p>
- For example, the logger named <code>"com.foo"</code> is a parent
- of the logger named <code>"com.foo.Bar"</code>. Similarly,
- <code>"java"</code> is a parent of <code>"java.util"</code> and an
- ancestor of <code>"java.util.Vector"</code>. This naming scheme
- should be familiar to most developers.
- </p>
-
- <p>
- The root logger resides at the top of the logger hierarchy. It
- is exceptional in two ways:
- </p>
-
- <ol>
- <li> it always exists,</li>
- <li> it cannot be retrieved by name.</li>
- </ol>
-
- <p>
- Invoking the class static <a href="apidocs/classlog4cxx_1_1_logger.html#afc0e4d99cab7c38a2851d41e6edc1dee">log4cxx::Logger::getRootLogger</a>
- method retrieves it. All other loggers are instantiated and retrieved with the class static
- <a href="apidocs/classlog4cxx_1_1_logger.html#a76017df17da02bc11bfe50e47de703a3">log4cxx::Logger::getLogger</a>
- method. This method takes the name of the desired logger as a parameter. Some of the basic methods in the Logger
- class are listed below.
- </p>
-
- <pre class="prettyprint linenums">
-namespace log4cxx {
- class <strong>Logger</strong> {
- public:
- // Creation & retrieval methods:
- static LoggerPtr getRootLogger();
- static LoggerPtr getLogger(const std::string& name);
- static LoggerPtr getLogger(const std::wstring& name);
- }
-}
-
-//
-// Use these macros instead of calling Logger methods directly.
-// Macros will handle char or wchar_t pointers or strings
-// or most right-hand side expressions of an
-// std::basic_string::operator<<.
-//
-#define LOG4CXX_TRACE(logger, expression) ...
-#define LOG4CXX_DEBUG(logger, expression) ...
-#define LOG4CXX_INFO(logger, expression) ...
-#define LOG4CXX_WARN(logger, expression) ...
-#define LOG4CXX_ERROR(logger, expression) ...
-#define LOG4CXX_FATAL(logger, expression) ...</pre>
- </subsection>
-
- <subsection name="Levels">
- <p>
- Loggers <em>may</em> be assigned levels. The pre-defined
- levels: TRACE, DEBUG, INFO, WARN, ERROR and FATAL are defined in the
- <code><a href="apidocs/classlog4cxx_1_1_level.html">log4cxx::Level</a></code>
- class which provides accessor functions.
- </p>
-
- <p>
- If a given logger is not assigned a level, then it inherits
- one from its closest ancestor with an assigned level. More
- formally:
- </p>
-
- <dl>
- <dt><strong>Level Inheritance</strong></dt>
-
- <dd>
- The <em>inherited level</em> for a given logger <i>C</i>, is equal to the
- first non-null level in the logger hierarchy, starting at <i>C</i> and
- proceeding upwards in the hierarchy towards the <code>root</code> logger.
- </dd>
- </dl>
-
- <p>
- To ensure that all loggers can eventually inherit a level,
- the root logger always has an assigned level.
- </p>
-
- <p>
- Below are four tables with various assigned level values and the
- resulting inherited levels according to the above rule.
- </p>
-
- <table border="1">
- <tr>
- <th>Logger name</th>
- <th>Assigned level</th>
- <th>Inherited level</th>
- </tr>
- <tr align="left">
- <td>root</td>
- <td>Proot</td>
- <td>Proot</td>
- </tr>
- <tr align="left">
- <td>X </td>
- <td>none</td>
- <td>Proot</td>
- </tr>
- <tr align="left">
- <td>X.Y </td>
- <td>none</td>
- <td>Proot</td>
- </tr>
- <tr align="left">
- <td>X.Y.Z</td>
- <td>none</td>
- <td>Proot</td>
- </tr>
- <caption align="bottom">Example 1</caption>
- </table>
-
- <p>
- In example 1 above, only the root logger is assigned a
- level. This level value, <code>Proot</code>, is inherited by the
- other loggers <code>X</code>, <code>X.Y</code> and
- <code>X.Y.Z</code>.
- </p>
-
- <table border="1">
- <tr>
- <th>Logger name</th>
- <th>Assigned level</th>
- <th>Inherited level</th>
- </tr>
- <tr align="left">
- <td>root</td>
- <td>Proot</td>
- <td>Proot</td>
- </tr>
- <tr align="left">
- <td>X </td>
- <td>Px</td>
- <td>Px</td>
- </tr>
- <tr align="left">
- <td>X.Y </td>
- <td>Pxy</td>
- <td>Pxy</td>
- </tr>
- <tr align="left">
- <td>X.Y.Z</td>
- <td>Pxyz</td>
- <td>Pxyz</td>
- </tr>
- <caption align="bottom">Example 2</caption>
- </table>
-
- <p>
- In example 2, all loggers have an assigned level value. There
- is no need for level inheritence.
- </p>
-
- <table border="1">
- <tr>
- <th>Logger name</th>
- <th>Assigned level</th>
- <th>Inherited level</th>
- </tr>
- <tr align="left">
- <td>root</td>
- <td>Proot</td>
- <td>Proot</td>
- </tr>
- <tr align="left">
- <td>X </td>
- <td>Px</td>
- <td>Px</td>
- </tr>
- <tr align="left">
- <td>X.Y </td>
- <td>none</td>
- <td>Px</td>
- </tr>
- <tr align="left">
- <td>X.Y.Z</td>
- <td>Pxyz</td>
- <td>Pxyz</td>
- </tr>
- <caption align="bottom">Example 3</caption>
- </table>
-
- <p>
- In example 3, the loggers <code>root</code>, <code>X</code> and
- <code>X.Y.Z</code> are assigned the levels <code>Proot</code>,
- <code>Px</code> and <code>Pxyz</code> respectively. The logger
- <code>X.Y</code> inherits its level value from its parent
- <code>X</code>.
- </p>
-
- <table border="1">
- <tr>
- <th>Logger name</th>
- <th>Assigned level</th>
- <th>Inherited level</th>
- </tr>
- <tr align="left">
- <td>root</td>
- <td>Proot</td>
- <td>Proot</td>
- </tr>
- <tr align="left">
- <td>X </td>
- <td>Px</td>
- <td>Px</td>
- </tr>
- <tr align="left">
- <td>X.Y </td>
- <td>none</td>
- <td>Px</td>
- </tr>
- <tr align="left">
- <td>X.Y.Z</td>
- <td>none</td>
- <td>Px</td>
- </tr>
- <caption align="bottom">Example 4</caption>
- </table>
-
- <p>
- In example 4, the loggers <code>root</code> and <code>X</code>
- and are assigned the levels <code>Proot</code> and <code>Px</code>
- respectively. The loggers <code>X.Y</code> and <code>X.Y.Z</code>
- inherits their level value from their nearest parent <code>X</code>
- having an assigned level.
- </p>
- </subsection>
-
- <subsection name="Requests">
- <p>
- Logging requests are made by invoking a method of
- a logger instance, preferrably through the use of LOG4CXX_INFO or similar
- macros which support short-circuiting if the threshold is not satisfied
- and use of the insertion operator (<<) in the message parameter.
- </p>
-
- <pre class="prettyprint linenums">
-log4cxx::LoggerPtr logger(log4cxx::Logger::getLogger(<strong>"com.foo"</strong>));
-const char* region = "World";
-LOG4CXX_INFO(logger, "Simple message text.")
-LOG4CXX_INFO(logger, "Hello, " << region)
-LOG4CXX_DEBUG(logger, L"Iteration " << i)
-LOG4CXX_DEBUG(logger, "e^10 = " << std::scientific << exp(10.0))
-//
-// Use a wchar_t first operand to force use of wchar_t based stream.
-//
-LOG4CXX_WARN(logger, L"" << i << L" is the number of the iteration.")</pre>
-
- <p>
- A logging request is said to be <em>enabled</em> if its level is
- higher than or equal to the level of its logger. Otherwise, the
- request is said to be <em>disabled</em>. A logger without an
- assigned level will inherit one from the hierarchy. This rule is
- summarized below.
- </p>
-
- <dl>
- <dt><strong>Basic Selection Rule</strong></dt>
-
- <dd>
- A log request of level <i>p</i> in a logger with (either assigned or
- inherited, whichever is appropriate) level <i>q</i>, is enabled if
- <i>p >= q</i>.
- </dd>
- </dl>
-
- <p>
- This rule is at the heart of log4cxx. It assumes that levels are
- ordered. For the standard levels, we have <code>TRACE < DEBUG < INFO
- < WARN < ERROR < FATAL</code>.
- </p>
-
- <p>
- Here is an example of this rule.
- </p>
-
- <pre class="prettyprint linenums">
-// get a logger instance named "com.foo"
-log4cxx::LoggerPtr logger(log4cxx::Logger::getLogger(<strong>"com.foo"</strong>));
-
-// Now set its level. Normally you do not need to set the
-// level of a logger programmatically. This is usually done
-// in configuration files.
-<strong>logger</strong>->setLevel(<strong class="set-level-highlight">log4cxx::Level::getInfo()</strong>);
-
-log4cxx::LoggerPtr barlogger(log4cxx::Logger::getLogger(<strong>"com.foo.Bar"</strong>));
-
-// This request is enabled, because <strong class="log-level compare-a">WARN</strong> >= <strong class="log-level compare-b">INFO</strong>.
-LOG4CXX_WARN(logger, "Low fuel level.")
-
-// This request is disabled, because <strong class="log-level compare-a">DEBUG</strong> < <strong class="log-level compare-b">INFO</strong>.
-LOG4CXX_DEBUG(logger, "Starting search for nearest gas station.")
-
-// The logger instance barlogger, named "com.foo.Bar",
-// will inherit its level from the logger named
-// "com.foo" Thus, the following request is enabled
-// because <strong class="log-level compare-a">INFO</strong> >= <strong class="log-level compare-b">INFO</strong>.
-LOG4CXX_INFO(barlogger. "Located nearest gas station.")
-
-// This request is disabled, because <strong class="log-level compare-a">DEBUG</strong> < <strong class="log-level compare-b">INFO</strong>.
-LOG4CXX_DEBUG(barlogger, "Exiting gas station search")</pre>
-
- <p>
- Calling the <code>getLogger</code> method with the same name will
- always return a reference to the exact same logger object.
- </p>
-
- <p>
- For example, in
- </p>
-
- <pre class="prettyprint linenums">
-log4cxx::LoggerPtr x = log4cxx::Logger::getLogger("wombat");
-log4cxx::LoggerPtr y = log4cxx::Logger::getLogger("wombat");</pre>
- <p>
- <code>x</code> and <code>y</code> refer to <em>exactly</em> the same logger object.
- </p>
-
- <p>
- Thus, it is possible to configure a logger and then to retrieve
- the same instance somewhere else in the code without passing around
- references. In fundamental contradiction to biological parenthood,
- where parents always preceed their children, log4cxx loggers can be
- created and configured in any order. In particular, a "parent"
- logger will find and link to its descendants even if it is
- instantiated after them.
- </p>
-
- <p>
- Configuration of the log4cxx environment is typically done at
- application initialization. The preferred way is by reading a
- configuration file. This approach will be discussed shortly.
- </p>
-
- <p>
- Log4cxx makes it easy to name loggers by <em>software
- component</em>. This can be accomplished by statically instantiating
- a logger in each class, with the logger name equal to the fully
- qualified name of the class. This is a useful and straightforward
- method of defining loggers. As the log output bears the name of the
- generating logger, this naming strategy makes it easy to identify
- the origin of a log message. However, this is only one possible,
- albeit common, strategy for naming loggers. Log4cxx does not restrict
- the possible set of loggers. The developer is free to name the
- loggers as desired.
- </p>
-
- <p>
- Nevertheless, naming loggers after the class where they are
- located seems to be the best strategy known so far.
- </p>
- </subsection>
- </section>
-
- <section name="Appenders and Layouts">
- <p>
- The ability to selectively enable or disable logging requests based
- on their logger is only part of the picture. Log4cxx allows logging
- requests to print to multiple destinations. In log4cxx speak, an output
- destination is called an <em>appender</em>. Currently, appenders exist
- for the <a href="apidocs/classlog4cxx_1_1_console_appender.html">console</a>,
- <a href="apidocs/classlog4cxx_1_1_file_appender.html">files</a>, GUI
- components, <a href="apidocs/classlog4cxx_1_1net_1_1_socket_appender.html">remote socket</a>
- servers, <a href="apidocs/classlog4cxx_1_1nt_1_1_n_t_event_log_appender.html"> NT Event Loggers</a>, and remote UNIX
- <a href="apidocs/classlog4cxx_1_1net_1_1_syslog_appender.html">Syslog</a>
- daemons. It is also possible to log <a href="apidocs/classlog4cxx_1_1_async_appender.html">asynchronously</a>.
- </p>
-
- <p>More than one appender can be attached to a logger.</p>
-
- <p>
- The <a href="apidocs/classlog4cxx_1_1_logger.html#a7c0629acee8dbd1251474bea15d7c9e2">addAppender</a>
- method adds an appender to a given logger.
-
- <strong>
- Each enabled logging request for a given logger will be forwarded to all the
- appenders in that logger as well as the appenders higher in the hierarchy.
- </strong>
- In other words, appenders are inherited additively from the logger hierarchy.
- For example, if a console appender is added to the root logger, then all enabled
- logging requests will at least print on the console. If in addition a file appender
- is added to a logger, say <em>C</em>, then enabled logging requests for <em>C</em> and
- <em>C</em>'s children will print on a file <em>and</em> on the console. It is possible
- to override this default behavior so that appender accumulation is no longer additive
- by <a href="apidocs/classlog4cxx_1_1_logger.html#a80f9397947dba9071ad485f178257c17">setting the additivity flag</a> to
- <code>false</code>.
- </p>
-
- <p>The rules governing appender additivity are summarized below.</p>
-
- <dl>
- <dt><strong>Appender Additivity</strong></dt>
-
- <dd>
- The output of a log statement of logger <i>C</i> will go to all the appenders
- in <i>C</i> and its ancestors. This is the meaning of the term "appender
- additivity". However, if an ancestor of logger <i>C</i>, say <i>P</i>, has the
- additivity flag set to <code>false</code>, then <i>C</i>'s output will be
- directed to all the appenders in <i>C</i> and it's ancestors up to and
- including <i>P</i> but, not the appenders in any of the ancestors of <i>P</i>.
- <br /><br />
- Loggers have their additivity flag set to <code>true</code> by default.
- </dd>
- </dl>
-
- <p>The table below shows an example:</p>
-
- <table align="center" border="3" cellpadding="10">
- <tr rowspan="2">
- <th>Logger Name </th>
- <th>Added Appenders</th>
- <th>Additivity Flag</th>
- <th>Output Targets</th>
- <th>Comment</th>
- </tr>
- <tr>
- <td>root</td>
- <td>A1</td>
- <td>not applicable</td>
- <td>A1</td>
- <td>
- The root logger is anonymous but can be accessed with the
- log4cxx::Logger::getRootLogger() method. There is no default appender
- attached to root.
- </td>
- </tr>
- <tr>
- <td>x</td>
- <td>A-x1, A-x2</td>
- <td>true</td>
- <td>A1, A-x1, A-x2</td>
- <td>Appenders of "x" and root.</td>
- </tr>
- <tr>
- <td>x.y</td>
- <td>none</td>
- <td>true</td>
- <td>A1, A-x1, A-x2</td>
- <td>Appenders of "x" and root.</td>
- </tr>
- <tr>
- <td>x.y.z</td>
- <td>A-xyz1</td>
- <td>true</td>
- <td>A1, A-x1, A-x2, A-xyz1</td>
- <td>Appenders in "x.y.z", "x" and root.</td>
- </tr>
- <tr>
- <td>security</td>
- <td>A-sec</td>
- <td>
- <span class="activity-flag-highlight">false</span>
- </td>
- <td>A-sec</td>
- <td>
- No appender accumulation since the additivity flag is set to <code>false</code>.
- </td>
- </tr>
- <tr>
- <td>security.access</td>
- <td>none</td>
- <td>true</td>
- <td>A-sec</td>
- <td>
- Only appenders of "security" because the additivity flag in "security" is
- set to <code>false</code>.
- </td>
- </tr>
- </table>
-
- <p>
- More often than not, users wish to customize not only the output
- destination but also the output format. This is accomplished by
- associating a <em>layout</em> with an appender. The layout is
- responsible for formatting the logging request according to the user's
- wishes, whereas an appender takes care of sending the formatted output
- to its destination.
- </p>
-
- <p>
- The <a href="apidocs/classlog4cxx_1_1_pattern_layout.html">PatternLayout</a>, part
- of the standard log4cxx distribution, lets the user specify the output
- format according to conversion patterns similar to the C language
- <code>printf</code> function.
- </p>
-
- <p>
- For example, the PatternLayout with the conversion pattern "%r [%t]
- %-5p %c - %m%n" will output something akin to:
- </p>
-
- <pre class="prettyprint linenums">
-176 [main] INFO org.foo.Bar - Located nearest gas station.</pre>
-
- <p>
- The first field is the number of milliseconds elapsed since the
- start of the program. The second field is the thread making the log
- request. The third field is the level of the log statement. The
- fourth field is the name of the logger associated with the log
- request. The text after the '-' is the message of the statement.
- </p>
- </section>
-
- <section name="Configuration">
- <p>
- Inserting log requests into the application code requires a fair
- amount of planning and effort. Observation shows that approximately 4
- percent of code is dedicated to logging. Consequently, even moderately
- sized applications will have thousands of logging statements embedded
- within their code. Given their number, it becomes imperative to
- manage these log statements without the need to modify them manually.
- </p>
-
- <p>
- The log4cxx environment is fully configurable programmatically.
- However, it is far more flexible to configure log4cxx using
- configuration files. Currently, configuration files can be written in
- XML or in Java properties (key=value) format.
- </p>
-
- <p>
- Let us give a taste of how this is done with the help of an
- imaginary application <code>MyApp</code> that uses log4cxx.
- </p>
-
- <pre class="prettyprint linenums">
-#include "com/foo/bar.h"
-using namespace com::foo;
-
-// include log4cxx header files.
-#include "log4cxx/logger.h"
-#include "log4cxx/basicconfigurator.h"
-#include "log4cxx/helpers/exception.h"
-
-using namespace log4cxx;
-using namespace log4cxx::helpers;
-
-LoggerPtr logger(Logger::getLogger("MyApp"));
-
-int main(int argc, char **argv)
-{
- int result = EXIT_SUCCESS;
- try
- {
- // Set up a simple configuration that logs on the console.
- BasicConfigurator::configure();
-
- LOG4CXX_INFO(logger, "Entering application.")
- Bar bar;
- bar.doIt();
- LOG4CXX_INFO(logger, "Exiting application.")
- }
- catch(Exception&)
- {
- result = EXIT_FAILURE;
- }
-
- return result;
-}</pre>
-
- <p>
- <code>MyApp</code> begins by including log4cxx headers. It
- then defines a static logger variable with the name <code>MyApp</code>
- which happens to be the fully qualified name of the
- class.
- </p>
-
- <p>
- <code>MyApp</code> uses the <code>Bar</code> class defined in header
- file <code>com/foo/bar.h</code>.
- </p>
-
- <pre class="prettyprint linenums">
-// file com/foo/bar.h
-#include "log4cxx/logger.h"
-
-namespace com {
- namespace foo {
- class Bar {
- static log4cxx::LoggerPtr logger;
-
- public:
- void doIt();
- }
- }
-}</pre>
-
- <pre class="prettyprint linenums">
-// file bar.cpp
-#include "com/foo/bar.h"
-
-using namespace com::foo;
-using namespace log4cxx;
-
-LoggerPtr Bar::logger(Logger::getLogger("com.foo.bar"));
-
-void Bar::doIt() {
- LOG4CXX_DEBUG(logger, "Did it again!")
-}</pre>
-
- <p>
- The invocation of the <a href="apidocs/classlog4cxx_1_1_basic_configurator.html#a4f96a09e1372664e3556ce94ace4a70c">BasicConfigurator::configure</a>
- method creates a rather simple log4cxx setup. This method is hardwired
- to add to the root logger a <a href="apidocs/classlog4cxx_1_1_console_appender.html">
- ConsoleAppender</a>. The output will be formatted using a
- <a href="apidocs/classlog4cxx_1_1_pattern_layout.html">PatternLayout</a> set
- to the pattern "%-4r [%t] %-5p %c %x - %m%n".
- </p>
-
- <p>
- Note that by default, the root logger is assigned to
- <code>Level::getDebug()</code>.
- </p>
-
- <p>
- The output of MyApp is:
- </p>
-
- <pre class="prettyprint linenums">
-0 [12345] INFO MyApp - Entering application.
-36 [12345] DEBUG com.foo.Bar - Did it again!
-51 [12345] INFO MyApp - Exiting application.</pre>
-
- <p>
- The previous example always outputs the same log information.
- Fortunately, it is easy to modify <code>MyApp</code> so that the log
- output can be controlled at run-time. Here is a slightly modified
- version.
- </p>
-
- <pre class="prettyprint linenums">
-// file MyApp2.cpp
-
-#include "com/foo/bar.h"
-using namespace com::foo;
-
-// include log4cxx header files.
-#include "log4cxx/logger.h"
-#include "log4cxx/basicconfigurator.h"
-#include "log4cxx/propertyconfigurator.h"
-#include "log4cxx/helpers/exception.h"
-
-using namespace log4cxx;
-using namespace log4cxx::helpers;
-// Define a static logger variable so that it references the
-// Logger instance named "MyApp".
-LoggerPtr logger(Logger::getLogger("MyApp"));
-
-int main(int argc, char **argv)
-{
- int result = EXIT_SUCCESS;
- try
- {
- if (argc > 1)
- {
- // BasicConfigurator replaced with PropertyConfigurator.
- PropertyConfigurator::configure(argv[1]);
- }
- else
- {
- BasicConfigurator::configure();
- }
-
- LOG4CXX_INFO(logger, "Entering application.")
- Bar bar
- bar.doIt();
- LOG4CXX_INFO(logger, "Exiting application.")
- }
- catch(Exception&)
- {
- result = EXIT_FAILURE;
- }
-
- return result;
-}</pre>
-
- <p>
- This version of <code>MyApp</code> instructs
- <code>PropertyConfigurator</code> to parse a configuration file and
- set up logging accordingly.
- </p>
-
- <p>
- Here is a sample configuration file that results in exactly same
- output as the previous <code>BasicConfigurator</code> based example.
- </p>
-
- <pre class="prettyprint linenums">
-# Set root logger level to DEBUG and its only appender to A1.
-log4j.rootLogger=DEBUG, A1
-
-# A1 is set to be a ConsoleAppender.
-log4j.appender.A1=org.apache.log4j.ConsoleAppender
-
-# A1 uses PatternLayout.
-log4j.appender.A1.layout=org.apache.log4j.PatternLayout
-log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n</pre>
-
- <p>
- It can be noticed that the PropertyConfigurator file format is the same as log4j.
- </p>
-
- <p>
- Suppose we are no longer interested in seeing the output of any
- component belonging to the <code>com::foo</code> package. The following
- configuration file shows one possible way of achieving this.
- </p>
-
- <pre class="prettyprint linenums">
-log4j.rootLogger=DEBUG, A1
-log4j.appender.A1=org.apache.log4j.ConsoleAppender
-log4j.appender.A1.layout=org.apache.log4j.PatternLayout
-
-# <strong>Print the date in ISO 8601 format</strong>
-log4j.appender.A1.layout.ConversionPattern=<strong>%d</strong> [%t] %-5p %c - %m%n
-
-# Print only messages of level WARN or above in the package com.foo.
-<strong>log4j.logger.com.foo=WARN</strong></pre>
-
- <p>
- The output of <code>MyApp</code> configured with this file is shown below.
- </p>
-
- <pre class="prettyprint linenums">
-<strong>2000-09-07 14:07:41,508</strong> [12345] INFO MyApp - Entering application.
-<strong>2000-09-07 14:07:41,529</strong> [12345] INFO MyApp - Exiting application.</pre>
-
- <p>
- As the logger <code>com.foo.Bar</code> does not have an assigned
- level, it inherits its level from <code>com.foo</code>, which
- was set to WARN in the configuration file. The log statement from the
- <code>Bar::doIt</code> method has the level DEBUG, lower than the
- logger level WARN. Consequently, <code>doIt()</code> method's log
- request is suppressed.
- </p>
-
- <p>
- Here is another configuration file that uses multiple appenders.
- </p>
-
- <pre class="prettyprint linenums">
-log4j.rootLogger=debug, <strong>stdout, R</strong>
-
-log4j.appender.<strong>stdout</strong>=org.apache.log4j.ConsoleAppender
-log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
-
-# Pattern to output the caller's file name and line number.
-log4j.appender.stdout.layout.ConversionPattern=%5p [%t] <strong>(%F:%L)</strong> - %m%n
-
-log4j.appender.<strong>R</strong>=org.apache.log4j.RollingFileAppender
-log4j.appender.R.File=example.log
-
-log4j.appender.R.MaxFileSize=<strong>100KB</strong>
-# Keep one backup file
-log4j.appender.R.MaxBackupIndex=1
-
-log4j.appender.R.layout=org.apache.log4j.PatternLayout
-log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n</pre>
-
- <p>
- Calling the enhanced MyApp with the this configuration file will
- output the following on the console.
- </p>
-
- <pre class="prettyprint linenums">
-INFO [12345] <strong>(MyApp2.cpp:31)</strong> - Entering application.
-DEBUG [12345] (Bar.h:16) - Doing it again!
-INFO [12345] (MyApp2.cpp:34) - Exiting application.</pre>
-
- <p>
- In addition, as the root logger has been allocated a second
- appender, output will also be directed to the <code>example.log</code>
- file. This file will be rolled over when it reaches 100KB. When
- roll-over occurs, the old version of <code>example.log</code> is
- automatically moved to <code>example.log.1</code>.
- </p>
-
- <p>
- Note that to obtain these different logging behaviors we did not
- need to recompile code. We could just as easily have logged to a UNIX
- Syslog daemon, redirected all <code>com.foo</code> output to an NT
- Event logger, or 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.
- </p>
- </section>
-
- <section name="Default Initialization Procedure">
- <p>
- The log4cxx library does not make any assumptions about its
- environment. In particular, there are no default log4cxx
- appenders. Under certain well-defined circumstances however, the
- static inializer of the <code>Logger</code> class will attempt to
- automatically configure log4cxx.
- </p>
-
- <p>
- The exact default initialization algorithm is defined as follows:
- </p>
-
- <ol>
- <li>
- <p>
- Set the configurationOptionStr string variable to the value of the
- <strong>LOG4CXX_CONFIGURATION</strong> environment variable if set, otherwise
- the value of the <strong>log4j.configuration</strong> environment variable
- if set, otherwise the first of the following file names which exist in the
- current working directory, "log4cxx.xml", "log4cxx.properties",
- "log4j.xml" and "log4j.properties". If configurationOptionStr has not been
- set, then disable logging.
- </p>
- </li>
- <li>
- <p>
- Unless a custom configurator is specified using the
- <strong>LOG4CXX_CONFIGURATOR_CLASS</strong> or <strong>log4j.configuratorClass</strong>
- environment variable, the PropertyConfigurator will be used to configure
- log4cxx unless the file name ends with the ".xml" extension,
- in which case the DOMConfigurator will be used.
- If a custom configurator is specified, the environment variable
- should contain a fully qualified class name of a class that
- implements the Configurator interface.
- </p>
- </li>
- </ol>
- </section>
-
- <section name="Nested Diagnostic Contexts">
- <p>
- Most real-world systems have to deal with multiple clients
- simultaneously. In a typical multithreaded implementation of such a
- system, different threads will handle different clients. Logging is
- especially well suited to trace and debug complex distributed
- applications. A common approach to differentiate the logging output of
- one client from another is to instantiate a new separate logger for
- each client. This promotes the proliferation of loggers and
- increases the management overhead of logging.
- </p>
-
- <p>
- A lighter technique is to uniquely stamp each log request initiated
- from the same client interaction. Neil Harrison described this method
- in the book "Patterns for Logging Diagnostic Messages," in <em>Pattern
- Languages of Program Design 3</em>, edited by R. Martin, D. Riehle,
- and F. Buschmann (Addison-Wesley, 1997).
- </p>
-
- <p>
- To uniquely stamp each request, the
- user pushes contextual information into the NDC, the abbreviation of
- <em>Nested Diagnostic Context</em>. The NDC class is shown below.
- </p>
-
- <pre class="prettyprint linenums">
-namespace log4cxx {
- class NDC {
- public:
- // pushes the value on construction and pops on destruction.
- NDC(const std::string& value);
- NDC(const std::wstring& value);
-
- // Remove the top of the context from the NDC.
- <strong>static</strong> LogString pop();
-
- // Add diagnostic context for the current thread.
- <strong>static</strong> void push(const std::string& message);
- <strong>static</strong> void push(const std::wstring& message);
- }
-}</pre>
-
- <p>
- The NDC is managed per thread as a <em>stack</em> of contextual
- information. Note that all methods of the <code>log4cxx::NDC</code>
- class are static. Assuming that NDC printing is turned on, every time
- a log request is made, the appropriate log4cxx component will include
- the <em>entire</em> NDC stack for the current thread in the log
- output. This is done without the intervention of the user, who is
- responsible only for placing the correct information in the NDC by
- using the <code>push</code> and <code>pop</code> methods at a few
- well-defined points in the code. In contrast, the per-client logger
- approach commands extensive changes in the code.
- </p>
-
- <p>
- To illustrate this point, let us take the example of a servlet
- delivering content to numerous clients. The servlet can build the NDC
- at the very beginning of the request before executing other code. The
- contextual information can be the client's host name and other
- information inherent to the request, typically information contained
- in cookies. Hence, even if the servlet is serving multiple clients
- simultaneously, the logs initiated by the same code, i.e. belonging to
- the same logger, can still be distinguished because each client
- request will have a different NDC stack. Contrast this with the
- complexity of passing a freshly instantiated logger to all code
- exercised during the client's request.
- </p>
-
- <p>
- Nevertheless, some sophisticated applications, such as virtual
- hosting web servers, must log differently depending on the virtual
- host context and also depending on the software component issuing the
- request. Recent log4cxx releases support multiple hierarchy trees. This
- enhancement allows each virtual host to possess its own copy of the
- logger hierarchy.
- </p>
- </section>
-
- <section name="Performance">
- <p>
- One of the often-cited arguments against logging is its
- computational cost. This is a legitimate concern as even moderately
- sized applications can generate thousands of log requests. Much
- effort was spent measuring and tweaking logging performance. Log4cxx
- claims to be fast and flexible: speed first, flexibility second.
- </p>
-
- <p>
- The user should be aware of the following performance issues.
- </p>
-
- <ol>
- <li>
- <p>
- <strong>Logging performance when logging is turned off.</strong>
- </p>
-
- <p>
- When logging is turned off entirely or just for a set
- of levels, the cost of a log request consists of a method
- invocation plus an integer comparison. The LOG4CXX_DEBUG and similar
- macros suppress unnecessary expression evaluation if the
- request is not enabled.
- </p>
- </li>
-
- <li>
- <p>
- <strong>The performance of deciding whether to log or not to log when logging is turned on.</strong>
- </p>
-
- <p>
- This is essentially the performance of walking the logger
- hierarchy. When logging is turned on, log4cxx still needs to compare
- the level of the log request with the level of the request
- logger. However, loggers may not have an assigned
- level; they can inherit them from the logger hierarchy. Thus,
- before inheriting a level, the logger may need to search its
- ancestors.
- </p>
-
- <p>
- There has been a serious effort to make this hierarchy walk to
- be as fast as possible. For example, child loggers link only to
- their existing ancestors. In the <code>BasicConfigurator</code>
- example shown earlier, the logger named <code>com.foo.Bar</code> is
- linked directly to the root logger, thereby circumventing the
- nonexistent <code>com</code> or <code>com.foo</code> loggers. This
- significantly improves the speed of the walk, especially in "sparse"
- hierarchies.
- </p>
-
- <p>
- The cost of walking the hierarchy is typically 3
- times slower than when logging is turned off entirely.
- </p>
- </li>
- <li>
- <p>
- <strong>Actually outputting log messages</strong>
- </p>
-
- <p>
- This is the cost of formatting the log output and sending it to
- its target destination. Here again, a serious effort was made to
- make layouts (formatters) perform as quickly as possible. The same
- is true for appenders.
- </p>
- </li>
- </ol>
- </section>
-
- <section name="Conclusions">
- <p>
- Apache Log4cxx is a popular logging package written in C++. One of its
- distinctive features is the notion of inheritance in loggers. Using
- a logger hierarchy it is possible to control which log statements
- are output at arbitrary granularity. This helps reduce the volume of
- logged output and minimize the cost of logging.
- </p>
-
- <p>
- One of the advantages of the log4cxx API is its manageability. Once
- the log statements have been inserted into the code, they can be
- controlled with configuration files. They can be selectively enabled
- or disabled, and sent to different and multiple output targets in
- user-chosen formats. The log4cxx package is designed so that log
- statements can remain in shipped code without incurring a heavy
- performance cost.
- </p>
- </section>
- </body>
-</document>
\ No newline at end of file
