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 <[email protected]> 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"
