* Fix some outdated information in documentation files

* Add a very small part of documentation about the Locale Kit. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@37873 a95241bf-73f2-0310-859d-f6bbb57e9c96
2010-08-03 16:02:55 +00:00
parent 2b1c0755dd
commit e9fd63ec7c
6 changed files with 143 additions and 4 deletions
@@ -465,6 +465,7 @@ WARN_LOGFILE           =
 INPUT                  = . \
 						 app \
                         drivers \
+						 locale \
                         midi \
                         midi2 \
                         support \
@@ -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.

@@ -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
@@ -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.
+
+*/
+
@@ -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.
+
+*/
@@ -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.
+
+*/