From a766986f6d443ba1d50e3af25f3306fa56e4518e Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Fri, 29 Feb 2008 09:19:51 +0000 Subject: [PATCH] More doxygen topic overview cleanup. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52191 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/mainpages/topics.h | 188 +++++++++--------- docs/doxygen/mainpages/utilities.h | 2 +- docs/doxygen/overviews/internationalization.h | 140 ++++++------- 3 files changed, 167 insertions(+), 163 deletions(-) diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h index cc38c80125..a3eec23de8 100644 --- a/docs/doxygen/mainpages/topics.h +++ b/docs/doxygen/mainpages/topics.h @@ -6,101 +6,101 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// - /*! - @page page_topics Topic overviews - - This chapter contains a selection of topic overviews. - The following are a basic categorization of them: - - @li @ref page_topics_starting - @li @ref page_topics_programming - @li @ref page_topics_nongui - @li @ref page_topics_drawing - @li @ref page_topics_gui - @li @ref page_topics_indivctrl - - -
- - - @section page_topics_starting Starting with wxWidgets - - @li @subpage overview_referencenotes - @li @subpage overview_roughguide - @li @subpage overview_helloworld - @li @subpage overview_python - - @section page_topics_programming Programming with wxWidgets - - @li @subpage overview_backwardcompat - @li @subpage overview_runtimeclass - @li @subpage overview_refcount - @li @subpage overview_app - @li @subpage overview_unicode - @li @subpage overview_mbconvclasses - @li @subpage overview_internationalization - @li @subpage overview_nonenglish - @li @subpage overview_debugging - @li @subpage overview_log - @li @subpage overview_eventhandling - @li @subpage overview_exceptions - @li @subpage overview_windowstyles - @li @subpage overview_windowdeletion - @li @subpage overview_windowids - @li @subpage overview_envvars - - @section page_topics_nongui Overviews of non-GUI classes - - @li @subpage overview_string - @li @subpage overview_bufferclasses - @li @subpage overview_datetime - @li @subpage overview_container - @li @subpage overview_file - @li @subpage overview_stream - @li @subpage overview_thread - @li @subpage overview_config - @li @subpage overview_fs - @li @subpage overview_resyntax - @li @subpage overview_arc - @li @subpage overview_ipc - - @section page_topics_drawing Drawing related classes - - @li @subpage overview_dc - @li @subpage overview_bitmap - @li @subpage overview_font - @li @subpage overview_fontencoding - @li @subpage overview_printing - @li @subpage overview_unixprinting - - @section page_topics_gui Overviews of GUI classes - - @li @subpage overview_sizer - @li @subpage overview_xrc - @li @subpage overview_windowsizing - @li @subpage overview_scrolling - @li @subpage overview_dialog - @li @subpage overview_validator - @li @subpage overview_dataobject - @li @subpage overview_dnd - @li @subpage overview_constraints - - @section page_topics_indivctrl Overviews of individual controls - - @li @subpage overview_html - @li @subpage overview_richtextctrl - @li @subpage overview_aui - @li @subpage overview_cmndlg - @li @subpage overview_toolbar - @li @subpage overview_grid - @li @subpage overview_treectrl - @li @subpage overview_listctrl - @li @subpage overview_splitterwindow - @li @subpage overview_imagelist - @li @subpage overview_bookctrl - @li @subpage overview_tips - @li @subpage overview_docview +@page page_topics Topic Overviews + +This chapter contains a selection of topic overviews. +The following is a basic categorization of them: + +@li @ref page_topics_starting +@li @ref page_topics_programming +@li @ref page_topics_nongui +@li @ref page_topics_drawing +@li @ref page_topics_gui +@li @ref page_topics_indivctrl + + +
+ + +@section page_topics_starting Starting with wxWidgets + +@li @subpage overview_referencenotes +@li @subpage overview_roughguide +@li @subpage overview_helloworld +@li @subpage overview_python + +@section page_topics_programming Programming with wxWidgets + +@li @subpage overview_backwardcompat +@li @subpage overview_runtimeclass +@li @subpage overview_refcount +@li @subpage overview_app +@li @subpage overview_unicode +@li @subpage overview_mbconvclasses +@li @subpage overview_i18n +@li @subpage overview_nonenglish +@li @subpage overview_debugging +@li @subpage overview_log +@li @subpage overview_eventhandling +@li @subpage overview_exceptions +@li @subpage overview_windowstyles +@li @subpage overview_windowdeletion +@li @subpage overview_windowids +@li @subpage overview_envvars + +@section page_topics_nongui Non-GUI Classes + +@li @subpage overview_string +@li @subpage overview_bufferclasses +@li @subpage overview_datetime +@li @subpage overview_container +@li @subpage overview_file +@li @subpage overview_stream +@li @subpage overview_thread +@li @subpage overview_config +@li @subpage overview_fs +@li @subpage overview_resyntax +@li @subpage overview_arc +@li @subpage overview_ipc + +@section page_topics_drawing Drawing Related Classes + +@li @subpage overview_dc +@li @subpage overview_bitmap +@li @subpage overview_font +@li @subpage overview_fontencoding +@li @subpage overview_printing +@li @subpage overview_unixprinting + +@section page_topics_gui GUI Classes + +@li @subpage overview_sizer +@li @subpage overview_xrc +@li @subpage overview_windowsizing +@li @subpage overview_scrolling +@li @subpage overview_dialog +@li @subpage overview_validator +@li @subpage overview_dataobject +@li @subpage overview_dnd +@li @subpage overview_constraints + +@section page_topics_indivctrl Individual Controls + +@li @subpage overview_html +@li @subpage overview_richtextctrl +@li @subpage overview_aui +@li @subpage overview_cmndlg +@li @subpage overview_toolbar +@li @subpage overview_grid +@li @subpage overview_treectrl +@li @subpage overview_listctrl +@li @subpage overview_splitterwindow +@li @subpage overview_imagelist +@li @subpage overview_bookctrl +@li @subpage overview_tips +@li @subpage overview_docview */ + diff --git a/docs/doxygen/mainpages/utilities.h b/docs/doxygen/mainpages/utilities.h index 74369912f5..c557e66b77 100644 --- a/docs/doxygen/mainpages/utilities.h +++ b/docs/doxygen/mainpages/utilities.h @@ -347,7 +347,7 @@ changing the other aspects of the programs behaviour. More information about this sample can be found in the @c readme.txt file in - its directory. Please see also i18n overview. + its directory. Please also see the @ref overview_i18n. @subsection page_utils_samples_layout Layout sample diff --git a/docs/doxygen/overviews/internationalization.h b/docs/doxygen/overviews/internationalization.h index 8507087054..95f9d1677d 100644 --- a/docs/doxygen/overviews/internationalization.h +++ b/docs/doxygen/overviews/internationalization.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: internationalization +// Name: internationalization.h // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,72 +8,76 @@ /*! - @page internationalization_overview Internationalization - - Although internationalization of an application (i18n for short) involves far - more than just translating its text messages to another message - date, time and - currency formats need changing too, some languages are written left to right - and others right to left, character encoding may differ and many other things - may need changing too - it is a necessary first step. wxWidgets provides - facilities for message translation with its - #wxLocale class and is itself fully translated into several - languages. Please consult wxWidgets home page for the most up-to-date - translations - and if you translate it into one of the languages not done - yet, your translations would be gratefully accepted for inclusion into future - versions of the library! - The wxWidgets approach to i18n closely follows the GNU gettext package. wxWidgets uses the - message catalogs which are binary compatible with gettext catalogs and this - allows to use all of the programs in this package to work with them. But note - that no additional libraries are needed during run-time, however, so you - have only the message catalogs to distribute and nothing else. - During program development you will need the gettext package for - working with message catalogs. @b Warning: gettext versions 0.10 are known - to be buggy, so you should find a later version of it! - There are two kinds of message catalogs: source catalogs which are text files - with extension .po and binary catalogs which are created from the source ones - with @e msgfmt program (part of gettext package) and have the extension .mo. - Only the binary files are needed during program execution. - The program i18n involves several steps: - - - Translating the strings in the program text using - #wxGetTranslation or equivalently the - #_() macro. - Extracting the strings to be translated from the program: this uses the - work done in the previous step because @c xgettext program used for string - extraction recognises the standard _() as well as (using its @c -k option) - our wxGetTranslation and extracts all strings inside the calls to these - functions. Alternatively, you may use @c -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. - Translating the strings extracted in the previous step to other - language(s). It involves editing the .po file. - Compiling the .po file into .mo file to be used by the program. - Installing the .mo files with your application in the appropriate - location for the target system which is the one returned by - wxStandardPaths::GetLocalizedResourcesDir(wxStandardPaths::ResourceCat_Messages). - If the message catalogs are not installed in this default location you may - explicitly use #AddCatalogLookupPathPrefix() to - still allow wxWidgets to find them but it is strongly recommended to use the - default directory. - Setting the appropriate locale in your program to use the strings for the - given language: see #wxLocale. - - - See also the http://www.gnu.org/software/gettext/manual/gettext.html. - See also @ref nonenglish_overview. - It focuses on handling charsets related problems. - Finally, take a look at the @ref sampleinternat_overview which shows - you how all this looks in practice. - @b Translating menu accelerators - If you translate the accelerator modifier names (Ctrl, Alt and Shift) in your menu labels, you may find - the accelerators no longer work. In your message catalogs, you need to provide individual translations - of these modifiers from their lower case names (ctrl, alt, shift) so that the wxWidgets accelerator - code can recognise them even when translated. wxWidgets does not provide translations for all of these - currently. wxWidgets does not yet handle translated special key names such as Backspace, - End, Insert, etc. - - */ +@page overview_i18n Internationalization +Although internationalization of an application (i18n for short) involves far +more than just translating its text messages to another message - date, time +and currency formats need changing too, some languages are written left to +right and others right to left, character encoding may differ and many other +things may need changing too - it is a necessary first step. wxWidgets provides +facilities for message translation with it's wxLocale class and is itself fully +translated into several languages. Please consult wxWidgets home page for the +most up-to-date translations - and if you translate it into one of the +languages not done yet, your translations would be gratefully accepted for +inclusion into future versions of the library! + +The wxWidgets approach to i18n closely follows the GNU gettext package. +wxWidgets uses the message catalogs which are binary compatible with gettext +catalogs and this allows to use all of the programs in this package to work +with them. But note that no additional libraries are needed during run-time, +however, so you have only the message catalogs to distribute and nothing else. + +During program development you will need the gettext package for working with +message catalogs. @b Warning: gettext versions @< 0.10 are known to be buggy, +so you should find a later version of it! + +There are two kinds of message catalogs: source catalogs which are text files +with extension .po and binary catalogs which are created from the source ones +with @e msgfmt program (part of gettext package) and have the extension .mo. +Only the binary files are needed during program execution. + +Translating your application involves several steps: + +@li Translating the strings in the program text using wxGetTranslation or + equivalently the @c _() macro. +@li Extracting the strings to be translated from the program: this uses the + work done in the previous step because @c xgettext program used for string + extraction recognises the standard @c _() as well as (using its @c -k + option) our wxGetTranslation and extracts all strings inside the calls to + these functions. Alternatively, you may use @c -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. +@li Translating the strings extracted in the previous step to other + language(s). It involves editing the .po file. +@li Compiling the .po file into .mo file to be used by the program. +@li Installing the .mo files with your application in the appropriate location + for the target system which is the one returned by + wxStandardPaths::GetLocalizedResourcesDir( + wxStandardPaths::ResourceCat_Messages ). If the message catalogs are not + installed in this default location you may explicitly use + wxLocale::AddCatalogLookupPathPrefix() to still allow wxWidgets to find + them but it is strongly recommended to use the default directory. +@li Setting the appropriate locale in your program to use the strings for the + given language: see wxLocale. + + +@section overview_i18n_menuaccel Translating Menu Accelerators + +If you translate the accelerator modifier names (Ctrl, Alt and Shift) in your +menu labels, you may find the accelerators no longer work. In your message +catalogs, you need to provide individual translations of these modifiers from +their lower case names (ctrl, alt, shift) so that the wxWidgets accelerator +code can recognise them even when translated. wxWidgets does not provide +translations for all of these currently. wxWidgets does not yet handle +translated special key names such as Backspace, End, Insert, etc. + + +@seealso + +@li The gettext Manual: http://www.gnu.org/software/gettext/manual/gettext.html +@li @ref overview_nonenglish - It focuses on handling charsets related problems. +@li @ref page_utils_samples_internat - Shows you how all this looks in practice. + +*/ -- 2.47.2