From 0bbe4e299cbd52fa9bef7819ec533cc6be9348f6 Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Sat, 25 Jan 2003 22:49:41 +0000
Subject: [PATCH] documented wxT(), _T(), _()

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@18929 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 docs/latex/wx/function.tex | 121 +++++++++++++++++++++++++++++++++----
 docs/latex/wx/ti18n.tex    |  16 ++---
 docs/latex/wx/tunicode.tex |  20 +++---
 3 files changed, 127 insertions(+), 30 deletions(-)

diff --git a/docs/latex/wx/function.tex b/docs/latex/wx/function.tex
index 9d855cb5aa..2e04f4c8d6 100644
--- a/docs/latex/wx/function.tex
+++ b/docs/latex/wx/function.tex
@@ -216,6 +216,7 @@ the corresponding topic.
 \helpref{wxStrlen}{wxstrlen}\\
 \helpref{wxSysErrorCode}{wxsyserrorcode}\\
 \helpref{wxSysErrorMsg}{wxsyserrormsg}\\
+\helpref{wxT}{wxt}\\
 \helpref{wxToLower}{wxtolower}\\
 \helpref{wxToUpper}{wxtoupper}\\
 \helpref{wxTraceLevel}{wxtracelevel}\\
@@ -230,7 +231,9 @@ the corresponding topic.
 \helpref{wxVsnprintf}{wxvsnprintf}\\
 \helpref{wxWakeUpIdle}{wxwakeupidle}\\
 \helpref{wxWriteResource}{wxwriteresource}\\
-\helpref{wxYield}{wxyield}
+\helpref{wxYield}{wxyield}\\
+\helpref{\_}{underscore}\\
+\helpref{\_T}{underscoret}
 
 \section{Version macros}\label{versionfunctions}
 
@@ -1189,6 +1192,19 @@ deleted with the {\it delete} operator.
 
 This function is deprecated, use \helpref{wxString}{wxstring} class instead.
 
+\membersection{::wxGetTranslation}\label{wxgettranslation}
+
+\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
+
+This function returns the translation of string {\it str} in the current
+\helpref{locale}{wxlocale}. If the string is not found in any of the loaded
+message catalogs (see \helpref{internationalization overview}{internationalization}), the
+original string is returned. In debug build, an error message is logged -- this
+should help to find the strings which were not yet translated. As this function
+is used very often, an alternative (and also common in Unix world) syntax is
+provided: the \helpref{\_()}{underscore} macro is defined to do the same thing
+as wxGetTranslation.
+
 \membersection{::wxIsEmpty}\label{wxisempty}
 
 \func{bool}{wxIsEmpty}{\param{const char *}{ p}}
@@ -1237,18 +1253,6 @@ This is a safe version of standard function {\it strlen()}: it does exactly the
 same thing (i.e. returns the length of the string) except that it returns 0 if
 {\it p} is the {\tt NULL} pointer.
 
-\membersection{::wxGetTranslation}\label{wxgettranslation}
-
-\func{const char *}{wxGetTranslation}{\param{const char * }{str}}
-
-This function returns the translation of string {\it str} in the current
-\helpref{locale}{wxlocale}. If the string is not found in any of the loaded
-message catalogs (see \helpref{internationalization overview}{internationalization}), the
-original string is returned. In debug build, an error message is logged - this
-should help to find the strings which were not yet translated. As this function
-is used very often, an alternative syntax is provided: the \_() macro is
-defined as wxGetTranslation().
-
 \membersection{::wxSnprintf}\label{wxsnprintf}
 
 \func{int}{wxSnprintf}{\param{wxChar *}{buf}, \param{size\_t }{len}, \param{const wxChar *}{format}, \param{}{...}}
@@ -1265,6 +1269,69 @@ enough space.
 
 \helpref{wxVsnprintf}{wxvsnprintf}, \helpref{wxString::Printf}{wxstringprintf}
 
+\membersection{wxT}\label{wxt}
+
+\func{wxChar}{wxT}{\param{char }{ch}}
+
+\func{const wxChar *}{wxT}{\param{const char *}{s}}
+
+wxT() is a macro which can be used with character and string literals (in other
+words, {\tt 'x'} or {\tt "foo"}) to automatically convert them to Unicode in
+Unicode build configuration. Please see the 
+\helpref{Unicode overview}{unicode} for more information.
+
+This macro is simply returns the value passed to it without changes in ASCII
+build. In fact, its definition is:
+\begin{verbatim}
+#ifdef UNICODE
+#define wxT(x) L ## x
+#else // !Unicode
+#define wxT(x) x
+#endif
+\end{verbatim}
+
+\membersection{wxTRANSLATE}\label{wxtranslate}
+
+\func{const wxChar *}{wxTRANSLATE}{\param{const char *}{s}}
+
+This macro doesn't do anything in the program code -- it simply expands to the
+value of its argument (expand in Unicode build where it is equivalent to 
+\helpref{wxT}{wxt} which makes it unnecessary to use both wxTRANSLATE and wxT
+with the same string which would be really unreadable).
+
+However it does have a purpose and it is to mark the literal strings for the
+extraction into the message catalog created by {\tt xgettext} program. Usually
+this is achieved using \helpref{\_()}{underscore} but that macro not only marks
+the string for extraction but also expands into 
+\helpref{wxGetTranslation}{wxgettranslation} function call which means that it
+cannot be used in some situations, notably for the static arrays
+initialization.
+
+Here is an example which should make it more clear: suppose that you have a
+static array of strings containing the weekday names and which have to be
+translated (note that it is a bad example, really, as
+\helpref{wxDateTime}{wxdatetime} already can be used to get the localized week
+day names already). If you write
+\begin{verbatim}
+static const wxChar * const weekdays[] = { _("Mon"), ..., _("Sun") };
+...
+// use weekdays[n] as usual
+\end{verbatim}
+the code wouldn't compile because the function calls are forbidden in the array
+initializer. So instead you should do
+\begin{verbatim}
+static const wxChar * const weekdays[] = { wxTRANSLATE("Mon"), ..., wxTRANSLATE("Sun") };
+...
+// use wxGetTranslation(weekdays[n])
+\end{verbatim}
+here.
+
+Note that although the code {\bf would} compile if you simply omit
+wxTRANSLATE() in the above, it wouldn't work as expected because there would be
+no translations for the weekday names in the program message catalog and
+wxGetTranslation wouldn't find them.
+
+
 \membersection{::wxToLower}\label{wxtolower}
 
 \func{char}{wxToLower}{\param{char }{ch}}
@@ -1296,6 +1363,34 @@ argument instead of arbitrary number of parameters.
 
 \helpref{wxSnprintf}{wxsnprintf}, \helpref{wxString::PrintfV}{wxstringprintfv}
 
+
+\membersection{\_}\label{underscore}
+
+\func{const wxChar *}{\_}{\param{const char *}{s}}
+
+This macro expands into a call to \helpref{wxGetTranslation}{wxgettranslation} 
+function, so it marks the message for the extraction by {\tt xgettext} just as
+\helpref{wxTRANSLATE}{wxtranslate} does, but also returns the translation of
+the string for the current locale during execution.
+
+Don't confuse this macro with \helpref{\_T()}{underscoret}!
+
+
+\membersection{\_T}\label{underscoret}
+
+\func{wxChar}{\_T}{\param{char }{ch}}
+
+\func{const wxChar *}{\_T}{\param{const wxChar }{ch}}
+
+This macro is exactly the same as \helpref{wxT}{wxt} and is defined in
+wxWindows simply because it may be more intuitive for Windows programmers as
+the standard Win32 headers also define it (as well as yet another name for the
+same macro which is {\tt \_TEXT()}).
+
+Don't confuse this macro with \helpref{\_()}{underscore}!
+
+\membersection{\_}\label{underscore}
+
 \section{Dialog functions}\label{dialogfunctions}
 
 Below are a number of convenience functions for getting input from the
diff --git a/docs/latex/wx/ti18n.tex b/docs/latex/wx/ti18n.tex
index 7cfb9532c7..8aaca5348e 100644
--- a/docs/latex/wx/ti18n.tex
+++ b/docs/latex/wx/ti18n.tex
@@ -31,14 +31,16 @@ The program i18n involves several steps:
 
 \begin{enumerate}\itemsep=0pt
 \item Translating the strings in the program text using 
-\helpref{wxGetTranslation}{wxgettranslation} or equivalently the \_() macro.
+\helpref{wxGetTranslation}{wxgettranslation} or equivalently the 
+\helpref{\_()}{underscore} macro.
 \item Extracting the strings to be translated from the program: this uses the
-work done in the previous step because {\it xgettext} program used for string
-extraction may be told (using its -k option) to recognise \_() and
-wxGetTranslation and extract all strings inside the calls to these functions.
-Alternatively, you may use -a option to extract all the strings, but it will
-usually result in many strings being found which don't have to be translated at
-all. This will create a text message catalog - a .po file.
+work done in the previous step because {\tt xgettext} program used for string
+extraction recognises the standard \_() as well as (using its {\tt -k} option)
+our wxGetTranslation and extracts all strings inside the calls to these
+functions. Alternatively, you may use {\tt -a} option to extract all the
+strings, but it will usually result in many strings being found which don't
+have to be translated at all. This will create a text message catalog -- a .po
+file.
 \item Translating the strings extracted in the previous step to other
 language(s). It involves editing the .po file.
 \item Compiling the .po file into .mo file to be used by the program.
diff --git a/docs/latex/wx/tunicode.tex b/docs/latex/wx/tunicode.tex
index 562fcf5834..aa491e3242 100644
--- a/docs/latex/wx/tunicode.tex
+++ b/docs/latex/wx/tunicode.tex
@@ -130,25 +130,25 @@ a separate type for strings though, because the standard
 \helpref{wxString}{wxstring} supports Unicode, i.e. it stores either ANSI or
 Unicode strings depending on the compile mode.
 
-Finally, there is a special {\tt wxT()} macro which should enclose all literal
-strings in the program. As it is easy to see comparing the last fragment with
-the one above, this macro expands to nothing in the (usual) ANSI mode and
-prefixes {\tt 'L'} to its argument in the Unicode mode.
+Finally, there is a special \helpref{wxT()}{wxt} macro which should enclose all
+literal strings in the program. As it is easy to see comparing the last
+fragment with the one above, this macro expands to nothing in the (usual) ANSI
+mode and prefixes {\tt 'L'} to its argument in the Unicode mode.
 
 The important conclusion is that if you use {\tt wxChar} instead of 
 {\tt char}, avoid using C style strings and use {\tt wxString} instead and
-don't forget to enclose all string literals inside {\tt wxT()} macro, your
+don't forget to enclose all string literals inside \helpref{wxT()}{wxt} macro, your
 program automatically becomes (almost) Unicode compliant!
 
 Just let us state once again the rules:
 
 \begin{itemize}
 \item Always use {\tt wxChar} instead of {\tt char}
-\item Always enclose literal string constants in {\tt wxT()} macro unless
-they're already converted to the right representation (another standard
-wxWindows macro {\tt \_()} does it, so there is no need for {\tt wxT()} in this
-case) or you intend to pass the constant directly to an external function
-which doesn't accept wide-character strings.
+\item Always enclose literal string constants in \helpref{wxT()}{wxt} macro
+unless they're already converted to the right representation (another standard
+wxWindows macro \helpref{\_()}{underscore} does it, for example, so there is no
+need for {\tt wxT()} in this case) or you intend to pass the constant directly
+to an external function which doesn't accept wide-character strings.
 \item Use {\tt wxString} instead of C style strings.
 \end{itemize}