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