* Add the locale kit to the main page

* Complete and correct some parts of locale and catalog classes reference
 * Ensure the methods are prefixed with the class name so doxygen knows where they belong.


git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@37898 a95241bf-73f2-0310-859d-f6bbb57e9c96

docs/user/book.dox

@@ -5,6 +5,7 @@
 
   - \ref app | \link app_intro \em Introduction \endlink
   - \ref drivers
+  - \ref locale | \link locale_intro \em Introduction \endlink
   - \ref midi1
   - \ref midi2 | \link midi2_intro \em Introduction \endlink
   - \ref support | \link support_intro \em Introduction \endlink
@@ -27,6 +28,8 @@
   \brief Collection of utility classes that are used throughout the API.
   \defgroup libbe (libbe.so)
   \defgroup libroot (libroot.so)
+  \defgroup locale (liblocale.so)
+  \brief Collection of classes for localizing applications.
 */
 
 ///// Subgroups /////

docs/user/locale/Catalog.dox

@@ -1,7 +1,7 @@
 /*!
 \class BCatalog
 \ingroup locale
-\brief class handling string localization
+\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
@@ -28,11 +28,29 @@ 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.
 
+\section Chaining of catalogs
+The catalogs you get from the locale kit are designed to use a fallback system
+so that the user get strings in the language he's the more fluent with,
+depending onwhat isavailable.
+
+For example, if the user set hislanguage preferences as french(France), spanish,
+english, when an application loads a catalog, the following rules are used :
+	\item Try to load a french(France) catalog. If it is found, this catalog
+will automatically include strings from the generic french catalog.
+	\item Try to load a generic french catalog.
+	\item Try to load a generic spanish catalog.
+	\item Try to load a generic english catalog.
+	\item If all of them failed, use the strings that ar ein the source code.
+
+Note that french(France) will failback to french, but then directly to the
+language in the source code. This avoids mixing 3 or more languages in the same
+application if the catalogs are incomplete and avoids confusion.
+
 */
 
 /*!
-\fn BCatalog(const char* signature, const char* language = NULL, uint32 fingerprint = 0)
-\brief Construct a catalog for the given application
+\fn BCatalog::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
@@ -51,9 +69,9 @@ 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* BCatalog::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
+\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
@@ -73,3 +91,81 @@ control.
 
 */
 
+/*!
+\fn const char* BCatalog::GetStringNoAutoCollate(const char* string, const char* context = NULL, const char* comment = NULL)
+\fn const char* GetStringNoAutoCollate(uint32 id)
+\brief Get a string from the catalog, without registering it for collectcatkeys.
+
+This function does exactly the same thing as GetString, except it will not be
+parsed by the collectcatkeys tool. This allows you, for example, to translate a
+string constant that you declared at another place, without getting a warning
+message from collectcatkeys.
+
+*/
+
+
+/*!
+\fn status_t BCatalog::GetData(const char* name, BMessage* msg)
+\fn status_t BCatalog::GetData(uint32 id, BMessage* msg)
+\brief Get custom data from the catalog.
+
+This function allows you to localize something else than raw text. This may
+include pictures, sounds, videos, or anything else. Note there is no support for
+generatinga catalog with such data inside, and the current format may not
+support it. If you need to localize data that is not text, it is advised to
+handle it by yourself.
+
+*/
+
+/*!
+\fn status_t BCatalog::GetSignature(BString* sig)
+\brief Get the catalog mime-signature.
+
+This function fills the sig string with the mime-signature associated to the
+catalog.
+
+*/
+
+/*!
+\fn status_t BCatalog::GetLanguage(BString* lang)
+\brief Get the catalog language.
+
+This function fills the lang string with the language name for the catalog.
+*/
+
+/*!
+\fn status_t BCatalog::GetFingerprint(uint32* fp)
+\brief Get the catalog fingerprint.
+
+This function setsfp to the fingerprint of the catalog. This allows you to check
+which version of the sourcecode this catalog was generated from.
+*/
+
+/*!
+\fn status_t BCatalog::SetCatalog(const char* signature, uint32 fingerprint)
+\brief Reload the string data.
+
+This function reloads the data for the given signature and fingerprint.
+*/
+
+/*!
+\fn status_t BCatalog::InitCheck()
+\brief Check if the catalog is in an useable state.
+
+This function returns B_OK if the catalog is initialized properly.
+*/
+
+/*!
+\fn int32 BCatalog::CountItems()
+\brief Returns the number of items in the catalog.
+
+This function returns the number of strings in the catalog.
+*/
+
+/*!
+\fn BCatalogaddOn* BCatalog::CatalogAddOn()
+\brief Returns the internal storage for this catalog.
+
+This function returns the internal storage class used by this catalog.
+You should not have to use it.
+*/

docs/user/locale/Locale.dox

@@ -12,7 +12,7 @@ accented chars and other special cases that vary over the different locales.
 */
 
 /*!
-\fn const BCollator* Collator() const
+\fn const BLocale::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
@@ -21,7 +21,7 @@ set of strings.
 */
 
 /*!
-\fn const BCountry* Country() const
+\fn const BLocale::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
@@ -31,14 +31,14 @@ data that is not language-dependant (such as the country flag).
 */
 
 /*!
-\fn const BLanguage* Language() const
+\fn const BLocale::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
+\fn int BLocale::StringCompare(const char* s1, const char* s2) const
+\fn int BLocale::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.
@@ -46,7 +46,7 @@ These methods are short-hands to Collator()->StringCompare.
 */
 
 /*!
-\fn void GetSortKey(const char* string, BString* key) const
+\fn void BLocale::GetSortKey(const char* string, BString* key) const
 \brief Computes the sort key of a string
 
 This method is a short-hand to Collator()->GetSortKey.

docs/user/locale/localeintro.dox

@@ -6,4 +6,13 @@ 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.
 
+The main way to access locale data is through the be_locale_roster. This is a
+global instance of the BLocaleRoster class, storing the data for localizing an
+application according to the user's preferred settings. The locale roster also
+acts as a factory to instanciate most of the other classes. However, there are
+some cases where you will need to instanciate another class by yourself, to
+use it with custom settings. For example, you may need to format a date with
+a fixed format in english for including in an e-mail header, as it is the only
+format accepted there.
+
 */