From f809007b99c684d223677fec1ad0fd9a95340171 Mon Sep 17 00:00:00 2001 From: Marko Myllynen Date: Mon, 20 Oct 2014 08:25:27 +0300 Subject: [PATCH] locale.5: Describe the formats of values locale(5) describes what a locale should define but doesn't spell out how (in what format). The patch attempts to address this, it also has few trivial additional enhancements. * Reference to locale(7) for category descriptions. * Clarify first_workday in NOTES a bit. * Add upstream BZ reference for two missing LC_ADDRESS fields. Signed-off-by: Michael Kerrisk --- man5/locale.5 | 73 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 54 insertions(+), 19 deletions(-) diff --git a/man5/locale.5 b/man5/locale.5 index 5bdb7283b..075687ef2 100644 --- a/man5/locale.5 +++ b/man5/locale.5 @@ -1,3 +1,4 @@ +'\" t -*- coding: UTF-8 -*- .\" Copyright (C) 1994 Jochen Hein (Hein@Student.TU-Clausthal.de) .\" Copyright (C) 2008 Petr Baudis (pasky@suse.cz) .\" Copyright (C) 2014 Michael Kerrisk @@ -54,7 +55,22 @@ can be defined from scratch. If the category should be copied, the only valid keyword in the definition is .B copy -followed by the name of the locale which should be copied. +followed by the name of the locale in double quotes which should be +copied. +.PP +When defining a category from scratch, all field descriptors and strings +should be defined as Unicode code points in angle brackets, unless +otherwise stated below. +For example, "€" is to be presented as "", "%a" as +"", and "Monday" as +"". +Values defined as Unicode code points must be in double quotes, plain +number values are not quoted (but +.BR LC_CTYPE +and +.BR LC_COLLATE +follow special formatting, see system provided locale files for +examples). .SS Locale category sections The following category sections are defined by POSIX: .IP * 3 @@ -84,6 +100,11 @@ the GNU C library supports the following nonstandard categories: .B LC_PAPER .IP * .B LC_TELEPHONE +.PP +See +.BR locale (7) +for more detailed description of each category. + .SS LC_ADDRESS The definition starts with the string .B LC_ADDRESS @@ -106,6 +127,8 @@ The following field descriptors are recognized: .\" .B LC_NAME .\" .I name_fmt .\" keyword. +.\" +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=16983 .TP %a Care of person, or organization. @@ -146,6 +169,8 @@ Country designation, from the keyword. .\" BUG: %l escape sequence from ISO/IEC 14652:2002 is not .\" supported by glibc .\" Local township within town or city. +.\" +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=16983 .TP %z Zip number, postal code. @@ -182,13 +207,13 @@ followed by the two-letter abbreviation of the country (ISO 3166). followed by the three-letter abbreviation of the country (ISO 3166). .TP .I country_num -followed by the numeric country code (ISO 3166). +followed by the numeric country code as plain numbers (ISO 3166). .TP .I country_car followed by the code for the country car number. .TP .I country_isbn -followed by the ISBN code (for books). +followed by the ISBN code as plain numbers (for books). .TP .I lang_name followed by the language name in the language of the current document. @@ -412,12 +437,7 @@ The definition ends with the string .IR "END LC_CTYPE" . .SS LC_COLLATE -.\" FIXME The description of LC_COLLATE lacks a lot of details -The -.B LC_COLLATE -category defines the rules for collating characters. -Due to -limitations of libc not all POSIX-options are implemented. +Due to limitations of glibc not all POSIX-options are implemented. The definition starts with the string .B LC_COLLATE @@ -458,12 +478,12 @@ The definition ends with the string .IR "END LC_COLLATE" . .SS LC_IDENTIFICATION -This category contains meta-information about the locale definition. - The definition starts with the string .B LC_IDENTIFICATION in the first column. +The values in this category are defined as plain strings. + The following keywords are allowed: .TP .I title @@ -586,6 +606,16 @@ The definition starts with the string .B LC_MONETARY in the first column. +Values for +.IR int_curr_symbol , +.IR currency_symbol , +.IR mon_decimal_point , +.IR mon_thousands_sep , +.IR positive_sign , +and +.IR negative_sign +are defined as Unicode code points, the others as plain numbers. + The following keywords are allowed: .TP .I int_curr_symbol @@ -877,8 +907,8 @@ followed by the string that will be used as a group separator when formatting numeric quantities. .TP .I grouping -followed by a sequence of integers separated by semicolons that -describe the formatting of numeric quantities. +followed by a sequence of integers as plain numbers separated by +semicolons that describe the formatting of numeric quantities. .IP Each integer specifies the number of digits in a group. The first integer defines the size of the group immediately @@ -898,6 +928,8 @@ The definition starts with the string .B LC_PAPER in the first column. +Values in this category are defined as plain numbers. + The following keywords are allowed: .TP .I height @@ -1020,7 +1052,7 @@ followed by the appropriate time format when using 12h clock format. This should be left empty for locales not using AM/PM convention. .TP .I week -followed by a list of three values: +followed by a list of three values as plain numbers: The number of days in a week (by default 7), a date of beginning of the week (by default corresponds to Sunday), and the minimal length of the first week in year (by default 4). @@ -1037,7 +1069,7 @@ followed by the number of the first day from the list to be shown in calendar applications. The default value of .B 1 -corresponds to either Sunday or Monday depending +(plain number) corresponds to either Sunday or Monday depending on the value of the second .I week list item. @@ -1048,12 +1080,13 @@ followed by the number of the first working day from the .I day list. The default value is -.BR 2 . +.BR 2 +(plain number). See NOTES. .TP .I cal_direction .\" from localedata/locales/uk_UA -followed by a value that indicates the direction for the +followed by a plain number value that indicates the direction for the display of calendar dates, as follows: .RS .TP @@ -1122,12 +1155,14 @@ and .I day lists appropriately, and set .I first_weekday +and +.I first_workday to .B 1 or .BR 2 , -depending on whether the week actually starts on Sunday or Monday -for the locale. +depending on whether the week and work week actually starts on Sunday or +Monday for the locale. .SH BUGS This manual page isn't complete. .\" .SH AUTHOR