charmap.5: clarify keyword syntax

charmap.5: clarify keyword syntax

[Marko Myllynen]

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(-)

diff --git a/man5/charmap.5 b/man5/charmap.5
index 31e3cb4..f43d5a5 100644
--- a/man5/charmap.5
+++ b/man5/charmap.5
@@ -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,

-- 
Marko Myllynen
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: charmap.5: clarify keyword syntax

[Michael Kerrisk (man-pages)]

On 06/13/2016 09:20 AM, Marko Myllynen wrote:
> Hi Michael,
> 
> The patch below updates charmap.5 to match the syntax all the glibc
> charmap files are using currently.

Thanks, Marko. Applied.

Cheers,

Michael



> ---
>  man5/charmap.5 | 20 ++++++++++----------
>  1 file changed, 10 insertions(+), 10 deletions(-)
> 
> diff --git a/man5/charmap.5 b/man5/charmap.5
> index 31e3cb4..f43d5a5 100644
> --- a/man5/charmap.5
> +++ b/man5/charmap.5
> @@ -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,
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: charmap.5: clarify keyword syntax

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 511 bytes --]

On 13 Jun 2016 10:20, Marko Myllynen wrote:
> 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.
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: charmap.5: clarify keyword syntax

[Marko Myllynen]

Hi,

On 2016-06-14 19:56, Mike Frysinger wrote:
> On 13 Jun 2016 10:20, Marko Myllynen wrote:
>> 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
> is followed by the name of the character map.

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

Thanks,

-- 
Marko Myllynen
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: charmap.5: clarify keyword syntax

[Michael Kerrisk (man-pages)]

On 06/15/2016 09:58 AM, Marko Myllynen wrote:
> Hi,
> 
> On 2016-06-14 19:56, Mike Frysinger wrote:
>> On 13 Jun 2016 10:20, Marko Myllynen wrote:
>>> 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
>> is followed by the name of the character map.
> 
> (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 >

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: charmap.5: clarify keyword syntax

[Marko Myllynen]

Hi,

On 2016-06-20 23:34, Michael Kerrisk (man-pages) wrote:
> On 06/15/2016 09:58 AM, Marko Myllynen wrote:
>> On 2016-06-14 19:56, Mike Frysinger wrote:
>>> On 13 Jun 2016 10:20, Marko Myllynen wrote:
>>>> 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
>>> is followed by the name of the character map.
>>
>> (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 >

Thanks, the patch below seems to do the trick:

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

diff --git a/man5/charmap.5 b/man5/charmap.5
index f43d5a5..9bc2440 100644
--- a/man5/charmap.5
+++ b/man5/charmap.5
@@ -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,

-- 
Marko Myllynen
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: charmap.5: clarify keyword syntax

[Michael Kerrisk (man-pages)]

Ho Marko,

On 06/21/2016 09:07 AM, Marko Myllynen wrote:
> Hi,
>
> On 2016-06-20 23:34, Michael Kerrisk (man-pages) wrote:
>> On 06/15/2016 09:58 AM, Marko Myllynen wrote:
>>> On 2016-06-14 19:56, Mike Frysinger wrote:
>>>> On 13 Jun 2016 10:20, Marko Myllynen wrote:
>>>>> 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
>>>> is followed by the name of the character map.
>>>
>>> (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 >
>
> Thanks, the patch below seems to do the trick:

Thanks! Applied.

Cheers,

Michael


>
> ---
>  man5/charmap.5 | 22 +++++++++++-----------
>  1 file changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/man5/charmap.5 b/man5/charmap.5
> index f43d5a5..9bc2440 100644
> --- a/man5/charmap.5
> +++ b/man5/charmap.5
> @@ -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,
>


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html