[haiku-commits] r37873 - in haiku/trunk/docs/user: . locale

  • From: pulkomandy@xxxxxxxxxxxxxxxxx
  • To: haiku-commits@xxxxxxxxxxxxx
  • Date: Tue, 3 Aug 2010 18:02:55 +0200 (CEST)

Author: pulkomandy
Date: 2010-08-03 18:02:55 +0200 (Tue, 03 Aug 2010)
New Revision: 37873
Changeset: http://dev.haiku-os.org/changeset/37873

Added:
   haiku/trunk/docs/user/locale/
   haiku/trunk/docs/user/locale/Catalog.dox
   haiku/trunk/docs/user/locale/Locale.dox
   haiku/trunk/docs/user/locale/localeintro.dox
Modified:
   haiku/trunk/docs/user/Doxyfile
   haiku/trunk/docs/user/HOWTO
   haiku/trunk/docs/user/apidoc.dox
Log:
 * Fix some outdated information in documentation files
 * Add a very small part of documentation about the Locale Kit.


Modified: haiku/trunk/docs/user/Doxyfile
===================================================================
--- haiku/trunk/docs/user/Doxyfile      2010-08-03 15:51:54 UTC (rev 37872)
+++ haiku/trunk/docs/user/Doxyfile      2010-08-03 16:02:55 UTC (rev 37873)
@@ -465,6 +465,7 @@
 INPUT                  = . \
                                                 app \
                          drivers \
+                                                locale \
                          midi \
                          midi2 \
                          support \

Modified: haiku/trunk/docs/user/HOWTO
===================================================================
--- haiku/trunk/docs/user/HOWTO 2010-08-03 15:51:54 UTC (rev 37872)
+++ haiku/trunk/docs/user/HOWTO 2010-08-03 16:02:55 UTC (rev 37873)
@@ -1,11 +1,11 @@
 
-THE OPENBEOS BOOK HOWTO
+THE HAIKU BOOK HOWTO
 
-The end user documentation for OpenBeOS is automatically generated from the 
+The end user documentation for Haiku is automatically generated from the 
 source code using the Doxygen tool. We are talking BeBook-style documentation 
 here, not development related docs (those belong in /current/docs/develop).
 
-This HOWTO only explains how to include your kit into the "OpenBeOS Book", it
+This HOWTO only explains how to include your kit into the "Haiku Book", it
 is not a Doxygen tutorial. For information about using Doxygen, see the Doxygen
 manual, www.doxygen.org, and OpenBeOS newletters 31 and 29.
 

Modified: haiku/trunk/docs/user/apidoc.dox
===================================================================
--- haiku/trunk/docs/user/apidoc.dox    2010-08-03 15:51:54 UTC (rev 37872)
+++ haiku/trunk/docs/user/apidoc.dox    2010-08-03 16:02:55 UTC (rev 37873)
@@ -68,7 +68,7 @@
                        of the methods, variables, functions, etc. will have to 
be the same.
                -# The root directory of the public API headers is at \c
                        /trunk/headers/os. In a similar vein, the root of the 
documentation
-                       files is at \c /trunk/src/documentation/haiku_book. The 
subdirectory
+                       files is at \c /trunk/docs/user. The subdirectory
                        structure, or the division of kits, will also be 
replicated.
                -# The name of the files is the same as the base of the header 
files,
                        with the \c dox extension. So \c Something.h becomes \c

Added: haiku/trunk/docs/user/locale/Catalog.dox
===================================================================
--- haiku/trunk/docs/user/locale/Catalog.dox                            (rev 0)
+++ haiku/trunk/docs/user/locale/Catalog.dox    2010-08-03 16:02:55 UTC (rev 
37873)
@@ -0,0 +1,75 @@
+/*!
+\class BCatalog
+\ingroup locale
+\brief class handling string localization
+
+BCatalog is the class that allows you to perform string localization. This 
means
+you give it a string in english, and it automatically returns the translation 
of
+this string in the user's specified language, if available.
+
+Most of the time, you don't have to deal with BCatalog directly. You use the
+translation macros instead. However, there are some cases where you will have 
to
+use catalogs directly. These include :
+       \item Tools for managing catalogs : if you want to add, remove or edit
+entries in a catalog, you need to do it using the BCatalog class.
+       \item Accessing catalogs other than your own : the macros only grant you
+access to the catalog linked with your application. To access other catalogs
+(for example if you create a script interpreter and want to localize the
+scripts), you will have to open a catalog associated with your script.
+
+\section Using the macros
+You don't have to do much in your program to handle catalogs. You must first
+set the B_TRANSLATE_CONTEXT define to a string that identifies which part of 
the
+application the strings you will translate are in. This allows the translators
+to keep track of the strings in the catalog more easily, and find where they 
are
+visible in the application. then, all you have to do, is enclose any string you
+want to make translatable in the B_TRANSLATE() macro. This macro has two uses,
+it will allow your text to be replaced at run-time by the proper localized one,
+but it will also allow to build the base catalog, the one that you will send to
+the translator team, from your sourcecode.
+
+*/
+
+/*!
+\fn BCatalog(const char* signature, const char* language = NULL, uint32 
fingerprint = 0)
+\brief Construct a catalog for the given application
+
+This constructor builds a catalog for the application with the given mime
+signature. In Haiku, the mime signature is used as a way to uniquely identify a
+catalog and match it with the corresponding application.
+
+If you don't specify a language, the system default list will be used.
+The language is passed here as a 2 letter ISO code.
+
+The fingerprint is a way to check that the catalog that will be loaded matches
+the current version of the application. A catalog made for a different version
+of the application can be loaded if you set the fingerprint to 0. This is
+usually not a problem, it only means that some strings may not be translated
+properly. But if you want to provide different versions of your application, it
+may be useful to separate their catalogs.
+
+*/
+
+/*!
+\fn const char* GetString(const char* string, const char* context = NULL, 
const char* comment = NULL)
+\fn const char* GetString(uint32 id)
+\brief Get a string from the catalog
+
+This method access the data of the catalog and reeturns you the translated
+version of the string. You must pass it the context where the string is, as
+the same string may appear somewhere else and need a differnet translation.
+The comment is optional. It is meant as an help to translators, when the string
+alone is not helpful enough or there are special things to note. The comment is
+also used as a way to uniquely identify a string, so if two identical strings
+share the same context, it is still possible to provide different translations.
+
+The id based version of this method is slightly faster, as it doesn't have to
+compute the hash from the 3 parameters. However, it will fail if there is an
+hash collision, so you should still fallback to the first one in case of
+problems. Also note that the hash value may be different from one catalog to
+another, depending on the file format they are stored in, so you shouldn't rely
+on this method unless you are sure you can keep all the catalog files under
+control.
+
+*/
+

Added: haiku/trunk/docs/user/locale/Locale.dox
===================================================================
--- haiku/trunk/docs/user/locale/Locale.dox                             (rev 0)
+++ haiku/trunk/docs/user/locale/Locale.dox     2010-08-03 16:02:55 UTC (rev 
37873)
@@ -0,0 +1,54 @@
+/*!
+\class BLocale
+\ingroup locale
+\brief Class for representing a locale and its settings
+
+A locale is defined by the combination of a country and a language. Using these
+two informations, it is possible to determine the format to use for date, time,
+and number formatting. The BLocale class also provide collators, which allows
+you to sort a list of strings properly depending on a set of rules about
+accented chars and other special cases that vary over the different locales.
+
+*/
+
+/*!
+\fn const BCollator* Collator() const
+\brief Returns the collator associated to this locale
+
+Returns the collator in use for this locale, allowing you to use it to sort a
+set of strings.
+
+*/
+
+/*!
+\fn const BCountry* Country() const
+\brief Returns the country associated to this locale
+
+A locale is defined by the combination of a country and a language. This
+method gets the country part of this information, so you can access the
+data that is not language-dependant (such as the country flag).
+
+*/
+
+/*!
+\fn const BLanguage* Language() const
+\brief Returns the language associated to this locale
+
+*/
+
+/*!
+\fn int StringCompare(const char* s1, const char* s2) const
+\fn int StringCompare(const BString* s1, const BString* s2) const
+\brief Compares two strings using the locale's collator
+
+These methods are short-hands to Collator()->StringCompare.
+
+*/
+
+/*!
+\fn void GetSortKey(const char* string, BString* key) const
+\brief Computes the sort key of a string
+
+This method is a short-hand to Collator()->GetSortKey.
+
+*/

Added: haiku/trunk/docs/user/locale/localeintro.dox
===================================================================
--- haiku/trunk/docs/user/locale/localeintro.dox                                
(rev 0)
+++ haiku/trunk/docs/user/locale/localeintro.dox        2010-08-03 16:02:55 UTC 
(rev 37873)
@@ -0,0 +1,9 @@
+/*!
+\page locale_intro Introduction to the Locale Kiit
+
+The Locale Kit provides a set of tools for internationalizing, localizing and
+translating your software. This includes not only replacing string with their
+translations at runtime, but also more complex tasks such as formating numbers,
+dates, and times in a way that match the locale preferences of the user.
+
+*/


Other related posts:

  • » [haiku-commits] r37873 - in haiku/trunk/docs/user: . locale - pulkomandy