You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by ts...@apache.org on 2020/08/06 08:36:22 UTC
[logging-log4cxx] 03/05: Changed the FAQ to be a PoC of using
Markdown with Doxygen. Makes more sense to make the content of PR #31
available as FAQ.
This is an automated email from the ASF dual-hosted git repository.
tschoening pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit ea72b50142abfe82fda527ac9dd5ede11e867cab
Author: Thorsten Schöning <ts...@am-soft.de>
AuthorDate: Tue Aug 4 15:43:09 2020 +0200
Changed the FAQ to be a PoC of using Markdown with Doxygen. Makes more sense to make the content of PR #31 available as FAQ.
---
src/site/fml/faq.fml | 70 --------------------------
src/site/markdown/faq.md | 85 ++++++++++++++++++++++++++++++++
src/site/markdown/non-english-logging.md | 44 -----------------
src/site/site.xml | 3 --
4 files changed, 85 insertions(+), 117 deletions(-)
diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml
deleted file mode 100644
index dcc3521..0000000
--- a/src/site/fml/faq.fml
+++ /dev/null
@@ -1,70 +0,0 @@
-<?xml version="1.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.
-
--->
-<faqs title="Frequently Asked Technical Questions">
- <part id="faq">
-
- <faq id="custom_levels"><question>How do I add a custom level to Apache log4cxx?</question>
- <answer>
- <p>This is a common topic for all the Apache logging frameworks and
- typically motivated to try to categorize events by functionality or
- audience. An common request is to add an AUDIT level so that the
- user can configure AUDIT level messages to go to a specific appender.
- However, the logger name was designed explicitly to support
- routing of messages by topic or audience. The common
- pattern of using classnames for logger names obscures the more
- general capability of logger name to represent the topic or audience
- of the logging request. The easiest approach to solve the underlying issue
- is to use a logger names like "AUDIT.com.example.MyPackage.MyClass"
- that allow all AUDIT messages to be routed to a particular appender.
- If you attempted to use a level for that then you would lose
- the ability to distinguish between different significances within
- the audit messages.
- </p></answer></faq>
-
-
- <faq id="msvc_crash"><question>My application on Windows crashes on shutdown?</question>
- <answer>
- <p>Apache log4cxx API calls use C++ Standard Template Library string
- parameters. If the caller is using a different instance or type of the
- C Runtime Library that log4cxx, then it is very likely that some memory
- that was originally allocated by log4cxx would be freed by the caller.
- If log4cxx and the caller are using different C RTL's, the program
- will likely crash at the point. Use "Multithread DLL" with release
- builds of log4cxx and "Multithread DLL Debug" with debug builds.
- </p></answer></faq>
-
- <faq id="unicode"><question>Does Apache log4cxx support Unicode?</question>
- <answer>
- <p>Yes. Apache log4cxx exposes API methods in multiple string flavors
- const char*, std::string, wchar_t*, std::wstring, CFStringRef et al.
- const char* and std::string are interpreted according to the
- current locale settings. Applications should call setlocale(LC_ALL, "")
- on startup or the C RTL will assume US-ASCII.
- Before being processed internally, all these are converted to the
- LogString type which is one of several supported Unicode representations
- selected by the --with-logchar option. When using methods that take LogString arguments,
- the LOG4CXX_STR() macro can be used to convert ASCII literals to
- the current LogString type. FileAppenders support an encoding
- property which should be explicitly specified to "UTF-8" or "UTF-16"
- for XML files.
- </p></answer></faq>
-
-
- </part>
-</faqs>
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
new file mode 100644
index 0000000..e018eea
--- /dev/null
+++ b/src/site/markdown/faq.md
@@ -0,0 +1,85 @@
+<!--
+ 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.
+-->
+
+# Frequently Asked Technical Questions
+## <a name="table_of_contents"></a>Table of contents
+
+<ol>
+ <li><a href="#custom_levels">How do I add a custom level to Apache log4cxx?</a></li>
+ <li><a href="#msvc_crash">My application on Windows crashes on shutdown?</a></li>
+ <li><a href="#unicode">Does Apache log4cxx support Unicode?</a></li>
+ <li><a href="#non_english">Non-English logging</a></li>
+</ol>
+
+## <a name="custom_levels"></a>How do I add a custom level to Apache log4cxx?
+
+This is a common topic for all the Apache logging frameworks and typically motivated to try to
+categorize events by functionality or audience. An common request is to add an AUDIT level so that
+the user can configure AUDIT level messages to go to a specific appender. However, the logger name
+was designed explicitly to support routing of messages by topic or audience. The common pattern of
+using classnames for logger names obscures the more general capability of logger name to represent
+the topic or audience of the logging request. The easiest approach to solve the underlying issue is
+to use a logger names like "AUDIT.com.example.MyPackage.MyClass" that allow all AUDIT messages to be
+routed to a particular appender. If you attempted to use a level for that then you would lose the
+ability to distinguish between different significances within the audit messages.
+
+## <a name="msvc_crash"></a>My application on Windows crashes on shutdown?
+
+Apache log4cxx API calls use C++ Standard Template Library string parameters. If the caller is using
+a different instance or type of the C Runtime Library that log4cxx, then it is very likely that some
+memory that was originally allocated by log4cxx would be freed by the caller. If log4cxx and the
+caller are using different C RTL's, the program will likely crash at the point. Use "Multithread
+DLL" with release builds of log4cxx and "Multithread DLL Debug" with debug builds.
+
+## <a name="unicode"></a>Does Apache log4cxx support Unicode?
+
+Yes. Apache log4cxx exposes API methods in multiple string flavors `const char*`, `std::string`,
+`wchar_t*`, `std::wstring`, `CFStringRef` et al. `const char*` and `std::string` are interpreted
+according to the current locale settings. Applications should call `setlocale(LC_ALL, "")` on
+startup or the C RTL will assume US-ASCII. Before being processed internally, all these are
+converted to the `LogString` type which is one of several supported Unicode representations selected
+by the `--with-logchar` option. When using methods that take `LogString` as arguments, the macor
+`LOG4CXX_STR()` can be used to convert ASCII literals to the current `LogString` type. FileAppenders
+support an encoding property which should be explicitly specified to `UTF-8` or `UTF-16` for XML
+files.
+
+## <a name="non_english"></a>Non-English logging
+
+When logging messages in languages other than English, you may need to
+set your locale correctly for messages to be displayed.
+
+For example, here is some Hebrew text which says "People with disabilities":
+
+ נשים עם מוגבלות
+
+If you are to log this information on a system with a locale of `en_US.UTF-8`,
+the log message will look something like the following:
+
+```
+loggername - ?????????? ???? ??????????????
+```
+
+One way to fix this is to call `setlocale` as follows before the function that logs:
+
+```
+std::setlocale( LC_ALL, "" );
+```
+
+This will then allow the message to be logged appropriately. See issue [LOG4CXX-483][1] for more
+information.
+
+[1]:https://issues.apache.org/jira/browse/LOGCXX-483
diff --git a/src/site/markdown/non-english-logging.md b/src/site/markdown/non-english-logging.md
deleted file mode 100644
index d94166a..0000000
--- a/src/site/markdown/non-english-logging.md
+++ /dev/null
@@ -1,44 +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.
--->
-
-# Non-English logging
-
-When logging messages in languages other than English, you may need to
-set your locale correctly for messages to be displayed.
-
-For example, here is some Hebrew text which says "People with disabilities":
-
-אנשים עם מוגבלות
-
-If you are to log this information on a system with a locale of `en_US.UTF-8`,
-the log message will look something like the following:
-
-```
-loggername - ?????????? ???? ??????????????
-```
-
-One way to fix this is to call `setlocale` as follows before the function that logs:
-
-```
-std::setlocale( LC_ALL, "" );
-```
-
-This will then allow the message to be logged appropriately.
-
-See issue [LOG4CXX-483][1] for more information.
-
-[1]:https://issues.apache.org/jira/browse/LOGCXX-483
diff --git a/src/site/site.xml b/src/site/site.xml
index 2fd8154..c19d505 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -70,9 +70,6 @@
<item name="FAQ"
href="/faq.html"
/>
- <item name="Non-English Logging"
- href="/non-english-logging.html"
- />
</menu>
<menu name="Get"