charmap.5: Update to match current glibc

charmap(5) was outdated, bring it to closer to reality by fixing
syntax descriptions to match current glibc code and practices,
adding missing options, removing obsolete comments and references,
and removing now incorrect examples.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man5/charmap.5

@@ -1,5 +1,3 @@
-.\" This file is part of locale(1) which displays the settings of the
-.\" current locale.
 .\" Copyright (C) 1994  Jochen Hein (Hein@Student.TU-Clausthal.de)
 .\"
 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
@@ -18,112 +16,98 @@
 .\" <http://www.gnu.org/licenses/>.
 .\" %%%LICENSE_END
 .\"
-.TH CHARMAP 5 1994-11-28 "" "Linux User Manual"
+.TH CHARMAP 5 2014-06-02 "GNU" "Linux Programmer's Manual"
 .SH NAME
-charmap \- character symbols to define character encodings
+charmap \- characters to define character sets
 .SH DESCRIPTION
-A character set description (charmap) defines a character set of
+A character set description (charmap) defines all available characters
-available characters and their encodings.
+and their encodings in a character set.
-All supported character
+All ISO C compliant character sets should have
-sets should have the
+the ASCII character set as a proper subset.
-.B portable character set
-as a proper subset.
-.\" Not true anymore:
-.\" The portable character set is defined in the file
-.\" .I /usr/lib/nls/charmap/POSIX
-.\" .I /usr/share/i18n/charmap/POSIX
-.\" for reference purposes.
 .SS Syntax
-The charmap file starts with a header, that may consist of the
+The charmap file starts with a header that may consist of the
 following keywords:
 .TP
-.I <codeset>
+.I <code_set_name>
-is followed by the name of the codeset.
+is followed by the name of the character map.
-.TP
-.I <mb_cur_max>
-is followed by the max number of bytes for a multibyte-character.
-Multibyte characters are currently not supported.
-The default value
-is 1.
-.TP
-.I <mb_cur_min>
-is followed by the min number of bytes for a character.
-This
-value must be less than or equal than
-.BR mb_cur_max .
-If not specified, it defaults to
-.BR mb_cur_max .
-.TP
-.I <escape_char>
-is followed by a character that should be used as the
-escape-character for the rest of the file to mark characters that
-should be interpreted in a special way.
-It defaults to
-the backslash (
-.B \\\\
-).
 .TP
 .I <comment_char>
-is followed by a character that will be used as the
+is followed by a character that will be used as the comment character
-comment-character for the rest of the file.
+for the rest of the file.
-It defaults to the
+It defaults to the number sign (#).
-number sign (
+.TP
-.B #
+.I <escape_char>
-).
+is followed by a character that should be used as the escape character
+for the rest of the file to mark characters that should be interpreted
+in a special way.
+It defaults to the backslash (\\).
+.TP
+.I <mb_cur_max>
+is followed by the maximum number of bytes for a character.
+The default value is 1.
+.TP
+.I <mb_cur_min>
+is followed by the minimum number of bytes for a character.
+This value must be less than or equal than
+.IR mb_cur_max .
+If not specified, it defaults to
+.IR mb_cur_max .
 .PP
-The charmap-definition itself starts with the keyword
+The character set definition section starts with the keyword
 .B CHARMAP
-in column 1.
+in the first column.
 
 The following lines may have one of the two following forms to
-define the character-encodings:
+define the character set:
 .TP
-.I <symbolic-name> <encoding> <comments>
+.I <character> <byte-sequence> <comment>
-This form defines exactly one character and its encoding.
+This form defines exactly one character and its byte sequence,
+.I <comment>
+being optional.
 .TP
-.I <symbolic-name>...<symbolic-name> <encoding> <comments>
+.I <character>..<character> <byte-sequence> <comment>
-This form defines a couple of characters.
+This form defines a character range and its byte sequence,
-This is useful only for
+.I <comment>
-multibyte-characters, which are currently not implemented.
+being optional.
 .PP
-The last line in a charmap-definition file must contain
+The character set definition section ends with the string
-.B END CHARMAP.
+.IR "END CHARMAP" .
-.SS Symbolic names
+.PP
-A
+The character set definition section may optionally be followed by a
-.B symbolic name
+section to define widths of characters.
-for a character contains only characters of the
+.PP
-.B portable character set.
+The width section starts with the keyword
-The name itself is enclosed between angle brackets.
+.B WIDTH
-Characters following an
+in the first column.
-.B <escape_char>
+
-are interpreted as itself; for example, the sequence
+The following lines may have one of the two following forms to
-.B "<\\\\\\\\\\\\>>"
+define the widths of the characters:
-represents the symbolic name
-.B "\\\\>"
-enclosed in angle brackets.
-.SS Character encoding
-The
-encoding may be in each of the following three forms:
 .TP
-.I <escape_char>d<number>
+.I <character> <width>
-with a decimal number
+This form defines the width of exactly one character.
 .TP
-.I <escape_char>x<number>
+.I <character>...<character> <width>
-with a hexadecimal number
+This form defines the width for all the characters in the range.
-.TP
+.PP
-.I <escape_char><number>
+The width definition section ends with the string
-with an octal number.
+.IR "END WIDTH" .
-.\" FIXME comments
-.\" FIXME char ... char
 .SH FILES
-.I /usr/share/i18n/charmaps/*
+.TP
-.\" .SH AUTHOR
+.I /usr/share/i18n/charmaps
-.\" Jochen Hein (jochen.hein@delphi.central.de)
+Usual default character map path.
 .SH CONFORMING TO
 POSIX.2.
+.SH EXAMPLE
+The Euro sign is defined as follows in the
+.I UTF\-8
+charmap:
+.PP
+.nf
+<U20AC>     /xe2/x82/xac
+.fi
 .SH SEE ALSO
+.BR iconv (1),
 .BR locale (1),
 .BR localedef (1),
-.BR localeconv (3),
+.BR locale (5),
-.BR setlocale (3),
+.BR charsets (7)
-.BR locale (5)