diff options
| author | Maurizio M. Gavioli <mmg@vistamaresoft.com> | 2024-04-14 17:18:08 +0200 |
|---|---|---|
| committer | Maurizio M. Gavioli <mmg@vistamaresoft.com> | 2024-04-14 17:18:08 +0200 |
| commit | a0cff82320840e4be6d40cee8a2432645773a53e (patch) | |
| tree | dbb5b972d03b14f636ef0aa120da8075ee906fc0 /core/text/i18n | |
| parent | 21969fec612b78d34f14b60ad761a3c37860b36b (diff) | |
Fix the format of some `doc.odin` files of the `core` library which did not made into the documentation.
`c/frontend/tokenizer`:
add proper "Example:" header to demo example code,
removed empty lines.
`container/bit_array`:
moved comment before package;
aligned narrative lines to left margin;
converted case lines into bulleted lines ("- ");
converted individual examples to single-tab-indented preformatted text.
`dynlib`:
removed "//+build ignore" line;
added newline at EOF.
`image/netpmb`:
converted indented lines of "Reading", "Wrting" and "Some syntax..." into bulleted lists;
"Formats" indented lines kept as they are as the preformatted text seems relevant to keep the alignments;
doubly indented lines kept as single-indented to keep them different (as the format does not allow for two-level bulleted lists);
removed empy lines.
`os/os2`: WIP, not modified
`sys/info`:
removed "//+build ignore" line;
converted tab-indented initial description into regular left-margin comment;
moved uncommented sample code within the doc comment as an "Example:";
moved simple- and double-tabbed separate comments with sample Windows and macOS outputs within the doc comment as bulleted headlines with preformatted output listings;
removed now empty comments and blank lines after the package line.
`text/i18n`:
removed "//+build ignore" line;
moved the pacakge line at the end;
de-indented the tab-indented introductory narrative;
moved sample code comments into the doc comment as tab-indented code with a proper "Example:" heading;
removed "```" MD attempts at code formatting.
`text/table`:
unindented the comment lines of a descriptive kind;
headlines of major subdivisions are marked as bold;
kept code samples as tab-indented preformatted text (as there are several of them, the standard "Example:" and "Output:" headings cannot be used) removing the "```" MD attempts at code formatting;
removed in-between blank lines.
Diffstat (limited to 'core/text/i18n')
| -rw-r--r-- | core/text/i18n/doc.odin | 185 |
1 files changed, 90 insertions, 95 deletions
diff --git a/core/text/i18n/doc.odin b/core/text/i18n/doc.odin index ef619451e..54bf8b80f 100644 --- a/core/text/i18n/doc.odin +++ b/core/text/i18n/doc.odin @@ -1,111 +1,106 @@ -//+build ignore -package i18n /* - The i18n package is flexible and easy to use. +The `i18n` package is flexible and easy to use. - It has one call to get a translation: `get`, which the user can alias into something like `T`. +It has one call to get a translation: `get`, which the user can alias into something like `T`. - `get`, referred to as `T` here, has a few different signatures. - All of them will return the key if the entry can't be found in the active translation catalog. +`get`, referred to as `T` here, has a few different signatures. +All of them will return the key if the entry can't be found in the active translation catalog. - - `T(key)` returns the translation of `key`. - - `T(key, n)` returns a pluralized translation of `key` according to value `n`. +- `T(key)` returns the translation of `key`. +- `T(key, n)` returns a pluralized translation of `key` according to value `n`. - - `T(section, key)` returns the translation of `key` in `section`. - - `T(section, key, n)` returns a pluralized translation of `key` in `section` according to value `n`. +- `T(section, key)` returns the translation of `key` in `section`. +- `T(section, key, n)` returns a pluralized translation of `key` in `section` according to value `n`. - By default lookup take place in the global `i18n.ACTIVE` catalog for ease of use. - If you want to override which translation to use, for example in a language preview dialog, you can use the following: +By default lookup take place in the global `i18n.ACTIVE` catalog for ease of use. +If you want to override which translation to use, for example in a language preview dialog, you can use the following: - - `T(key, n, catalog)` returns the pluralized version of `key` from explictly supplied catalog. - - `T(section, key, n, catalog)` returns the pluralized version of `key` in `section` from explictly supplied catalog. +- `T(key, n, catalog)` returns the pluralized version of `key` from explictly supplied catalog. +- `T(section, key, n, catalog)` returns the pluralized version of `key` in `section` from explictly supplied catalog. - If a catalog has translation contexts or sections, then ommitting it in the above calls looks up in section "". +If a catalog has translation contexts or sections, then omitting it in the above calls looks up in section "". - The default pluralization rule is n != 1, which is to say that passing n == 1 (or not passing n) returns the singular form. - Passing n != 1 returns plural form 1. +The default pluralization rule is n != 1, which is to say that passing n == 1 (or not passing n) returns the singular form. +Passing n != 1 returns plural form 1. - Should a language not conform to this rule, you can pass a pluralizer procedure to the catalog parser. - This is a procedure that maps an integer to an integer, taking a value and returning which plural slot should be used. +Should a language not conform to this rule, you can pass a pluralizer procedure to the catalog parser. +This is a procedure that maps an integer to an integer, taking a value and returning which plural slot should be used. - You can also assign it to a loaded catalog after parsing, of course. +You can also assign it to a loaded catalog after parsing, of course. - Some code examples follow. -*/ +Example: -/* -```cpp -import "core:fmt" -import "core:text/i18n" - -T :: i18n.get - -mo :: proc() { - using fmt - - err: i18n.Error - - /* - Parse MO file and set it as the active translation so we can omit `get`'s "catalog" parameter. - */ - i18n.ACTIVE, err = i18n.parse_mo(#load("translations/nl_NL.mo")) - defer i18n.destroy() - - if err != .None { return } - - /* - These are in the .MO catalog. - */ - println("-----") - println(T("")) - println("-----") - println(T("There are 69,105 leaves here.")) - println("-----") - println(T("Hellope, World!")) - println("-----") - // We pass 1 into `T` to get the singular format string, then 1 again into printf. - printf(T("There is %d leaf.\n", 1), 1) - // We pass 42 into `T` to get the plural format string, then 42 again into printf. - printf(T("There is %d leaf.\n", 42), 42) - - /* - This isn't in the translation catalog, so the key is passed back untranslated. - */ - println("-----") - println(T("Come visit us on Discord!")) -} - -qt :: proc() { - using fmt - - err: i18n.Error - - /* - Parse QT file and set it as the active translation so we can omit `get`'s "catalog" parameter. - */ - i18n.ACTIVE, err = i18n.parse_qt(#load("translations/nl_NL-qt-ts.ts")) - defer i18n.destroy() - - if err != .None { - return + import "core:fmt" + import "core:text/i18n" + + T :: i18n.get + + mo :: proc() { + using fmt + + err: i18n.Error + + /* + Parse MO file and set it as the active translation so we can omit `get`'s "catalog" parameter. + */ + i18n.ACTIVE, err = i18n.parse_mo(#load("translations/nl_NL.mo")) + defer i18n.destroy() + + if err != .None { return } + + /* + These are in the .MO catalog. + */ + println("-----") + println(T("")) + println("-----") + println(T("There are 69,105 leaves here.")) + println("-----") + println(T("Hellope, World!")) + println("-----") + // We pass 1 into `T` to get the singular format string, then 1 again into printf. + printf(T("There is %d leaf.\n", 1), 1) + // We pass 42 into `T` to get the plural format string, then 42 again into printf. + printf(T("There is %d leaf.\n", 42), 42) + + /* + This isn't in the translation catalog, so the key is passed back untranslated. + */ + println("-----") + println(T("Come visit us on Discord!")) } - /* - These are in the .TS catalog. As you can see they have sections. - */ - println("--- Page section ---") - println("Page:Text for translation =", T("Page", "Text for translation")) - println("-----") - println("Page:Also text to translate =", T("Page", "Also text to translate")) - println("-----") - println("--- installscript section ---") - println("installscript:99 bottles of beer on the wall =", T("installscript", "99 bottles of beer on the wall")) - println("-----") - println("--- apple_count section ---") - println("apple_count:%d apple(s) =") - println("\t 1 =", T("apple_count", "%d apple(s)", 1)) - println("\t 42 =", T("apple_count", "%d apple(s)", 42)) -} -``` -*/
\ No newline at end of file + qt :: proc() { + using fmt + + err: i18n.Error + + /* + Parse QT file and set it as the active translation so we can omit `get`'s "catalog" parameter. + */ + i18n.ACTIVE, err = i18n.parse_qt(#load("translations/nl_NL-qt-ts.ts")) + defer i18n.destroy() + + if err != .None { + return + } + + /* + These are in the .TS catalog. As you can see they have sections. + */ + println("--- Page section ---") + println("Page:Text for translation =", T("Page", "Text for translation")) + println("-----") + println("Page:Also text to translate =", T("Page", "Also text to translate")) + println("-----") + println("--- installscript section ---") + println("installscript:99 bottles of beer on the wall =", T("installscript", "99 bottles of beer on the wall")) + println("-----") + println("--- apple_count section ---") + println("apple_count:%d apple(s) =") + println("\t 1 =", T("apple_count", "%d apple(s)", 1)) + println("\t 42 =", T("apple_count", "%d apple(s)", 42)) + } +*/ +package i18n |