charmap.5: clarify keyword syntax

Hi Michael,

The patch below updates charmap.5 to match the syntax all the glibc charmap files are using currently.

---
 man5/charmap.5 | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

man5/charmap.5 +10 -10

index 31e3cb4..f43d5a5 100644
@@ -49,9 +49,9 @@ The default value is 1.
 .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 .
+.IR <mb_cur_max> .
 If not specified, it defaults to
-.IR mb_cur_max .
+.IR <mb_cur_max> .
 .PP
 The character set definition section starts with the keyword
 .I CHARMAP

@@ -60,14 +60,14 @@ in the first column.
 The following lines may have one of the two following forms to
 define the character set:
 .TP
-.I <character> <byte-sequence> <comment>
+.I <character> byte-sequence comment
 This form defines exactly one character and its byte sequence,
-.I <comment>
+.I comment
 being optional.
 .TP
-.I <character>..<character> <byte-sequence> <comment>
+.I <character>..<character> byte-sequence comment
 This form defines a character range and its byte sequence,
-.I <comment>
+.I comment
 being optional.
 .PP
 The character set definition section ends with the string

@@ -77,7 +77,7 @@ The character set definition section may optionally be followed by a
 section to define widths of characters.
 .PP
 The
-.B WIDTH_DEFAULT
+.I WIDTH_DEFAULT
 keyword can be used to define the default width for all characters
 not explicitly listed.
 The default character width is 1.

@@ -89,10 +89,10 @@ in the first column.
 The following lines may have one of the two following forms to
 define the widths of the characters:
 .TP
-.I <character> <width>
+.I <character> width
 This form defines the width of exactly one character.
 .TP
-.I <character>...<character> <width>
+.I <character>...<character> width
 This form defines the width for all the characters in the range.
 .PP
 The width definition section ends with the string

@@ -109,7 +109,7 @@ The Euro sign is defined as follows in the
 charmap:
 .PP
 .nf
-<U20AC>     /xe2/x82/xac
+<U20AC>     /xe2/x82/xac EURO SIGN
 .fi
 .SH SEE ALSO
 .BR iconv (1),

Thanks,

The patch below updates charmap.5 to match the syntax all the glibc charmap files are using currently.

Quoted 2 lines · Marko Myllynen

The patch below updates charmap.5 to match the syntax all the glibc charmap files are using currently.

hmm, i guess this is confusing. when i read the man page, i see it as the normal syntax of "<required value>" rather than the <> being literal characers that you need to type out. although in that regard, i would expect it to look something like:
<character> <byte-sequence> [comment]

although in the locale(5) page, we rarely use the <foo> syntax.

is followed by the name of the character map.

Hi,

Quoted 11 lines · Mike Frysinger

Quoted 2 lines · Marko Myllynen

The patch below updates charmap.5 to match the syntax all the glibc charmap files are using currently.

hmm, i guess this is confusing. when i read the man page, i see it as the normal syntax of "<required value>" rather than the <> being literal characers that you need to type out. although in that regard, i would expect it to look something like:
<character> <byte-sequence> [comment]

although in the locale(5) page, we rarely use the <foo> syntax.

Yes, in the locale(5) page <foo> is now used only in cases like:

The characters <space> and <tab> are automatically included.

In the glibc charmap files the <> notation is used with keywords, the man pages states that comment is optional but would it make thing clearer if we would use something like:

.TP
<
.I code_set_name

Quoted 1 line

is followed by the name of the character map.

(Ok, that renders badly but you get the idea.)

Quoted 26 lines · Marko Myllynen

Quoted 11 lines · Mike Frysinger

Quoted 2 lines · Marko Myllynen

The patch below updates charmap.5 to match the syntax all the glibc charmap files are using currently.

hmm, i guess this is confusing. when i read the man page, i see it as the normal syntax of "<required value>" rather than the <> being literal characers that you need to type out. although in that regard, i would expect it to look something like:
<character> <byte-sequence> [comment]

although in the locale(5) page, we rarely use the <foo> syntax.

Yes, in the locale(5) page <foo> is now used only in cases like:

The characters <space> and <tab> are automatically included.

In the glibc charmap files the <> notation is used with keywords, the man pages states that comment is optional but would it make thing clearer if we would use something like:

.TP
<
.I code_set_name

Quoted 1 line

is followed by the name of the character map.

Quoted 1 line

(Ok, that renders badly but you get the idea.)

I'd take patches to fix this.

I think you want:

.TP
.RI < code_set_name >

Hi,

Quoted 29 lines · Michael Kerrisk (man-pages)

Quoted 27 lines · Marko Myllynen

Quoted 11 lines · Mike Frysinger

Quoted 2 lines · Marko Myllynen

The patch below updates charmap.5 to match the syntax all the glibc charmap files are using currently.

hmm, i guess this is confusing. when i read the man page, i see it as the normal syntax of "<required value>" rather than the <> being literal characers that you need to type out. although in that regard, i would expect it to look something like:
<character> <byte-sequence> [comment]

although in the locale(5) page, we rarely use the <foo> syntax.

Yes, in the locale(5) page <foo> is now used only in cases like:

The characters <space> and <tab> are automatically included.

In the glibc charmap files the <> notation is used with keywords, the man pages states that comment is optional but would it make thing clearer if we would use something like:

.TP
<
.I code_set_name

Quoted 1 line

is followed by the name of the character map.

(Ok, that renders badly but you get the idea.)

Quoted 6 lines

I'd take patches to fix this.

I think you want:

.TP
.RI < code_set_name >

Thanks, the patch below seems to do the trick:

---
 man5/charmap.5 | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

man5/charmap.5 +11 -11

index f43d5a5..9bc2440 100644
@@ -28,30 +28,30 @@ can use charmaps to create locale variants for different character sets.
 The charmap file starts with a header that may consist of the
 following keywords:
 .TP
-.I <code_set_name>
+.RI < code_set_name >
 is followed by the name of the character map.
 .TP
-.I <comment_char>
+.RI < comment_char >
 is followed by a character that will be used as the comment character
 for the rest of the file.
 It defaults to the number sign (#).
 .TP
-.I <escape_char>
+.RI < 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>
+.RI < mb_cur_max >
 is followed by the maximum number of bytes for a character.
 The default value is 1.
 .TP
-.I <mb_cur_min>
+.RI < 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> .
+.RI < mb_cur_max >.
 If not specified, it defaults to
-.IR <mb_cur_max> .
+.RI < mb_cur_max >.
 .PP
 The character set definition section starts with the keyword
 .I CHARMAP

@@ -60,12 +60,12 @@ in the first column.
 The following lines may have one of the two following forms to
 define the character set:
 .TP
-.I <character> byte-sequence comment
+.RI < character >\  byte-sequence\ comment
 This form defines exactly one character and its byte sequence,
 .I comment
 being optional.
 .TP
-.I <character>..<character> byte-sequence comment
+.RI < character >..< character >\  byte-sequence\ comment
 This form defines a character range and its byte sequence,
 .I comment
 being optional.

@@ -89,10 +89,10 @@ in the first column.
 The following lines may have one of the two following forms to
 define the widths of the characters:
 .TP
-.I <character> width
+.RI < character >\  width
 This form defines the width of exactly one character.
 .TP
-.I <character>...<character> width
+.RI < character >...< character >\  width
 This form defines the width for all the characters in the range.
 .PP
 The width definition section ends with the string

Cheers,