bug#71167: 29.3; vtable: documentation bug

bug#71167: 29.3; vtable: documentation bug

[Joost Kremers]

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


The documentation for 'make-vtable' in vtable.texi has a small bug. Patch
attached.



-- 
Joost Kremers
Life has its moments


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-doc-for-width-slot-of-vtable-column-keyword-para.patch --]
[-- Type: text/x-patch, Size: 1202 bytes --]

From 2af7ecdff1c7b019f0ee4b331b02558e2b39dbd5 Mon Sep 17 00:00:00 2001
From: Joost Kremers <joostkremers@fastmail.com>
Date: Fri, 24 May 2024 09:16:06 +0200
Subject: [PATCH] Fix doc for 'width' slot of vtable ':column' keyword
 parameter

---
 doc/misc/vtable.texi | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/misc/vtable.texi b/doc/misc/vtable.texi
index 822b1097cd9..7252c61b9d2 100644
--- a/doc/misc/vtable.texi
+++ b/doc/misc/vtable.texi
@@ -283,9 +283,9 @@ Making A Table
 @item width
 The width of the column.  This is either a number (the width of that
 many @samp{x} characters in the table's face), or a string on the form
-@samp{Xe@var{x}}, where @var{x} is a number of @samp{x} characters, or a
-string on the form @samp{Xp@var{x}} (denoting a number of pixels), or a
-string on the form @samp{X%} (a percentage of the window's width).
+@samp{@var{x}ex}, where @var{x} is a number of @samp{x} characters, or a
+string on the form @samp{@var{x}px} (denoting a number of pixels), or a
+string on the form @samp{@var{x}%} (a percentage of the window's width).
 
 @item min-width
 This uses the same format as @code{width}, but specifies the minimum
-- 
2.45.1

bug#71167: 29.3; vtable: documentation bug

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Date: Fri, 24 May 2024 09:20:28 +0200
> 
> The documentation for 'make-vtable' in vtable.texi has a small bug. Patch
> attached.

Thanks, but...

>  @item width
>  The width of the column.  This is either a number (the width of that
>  many @samp{x} characters in the table's face), or a string on the form
> -@samp{Xe@var{x}}, where @var{x} is a number of @samp{x} characters, or a
> -string on the form @samp{Xp@var{x}} (denoting a number of pixels), or a
> -string on the form @samp{X%} (a percentage of the window's width).
> +@samp{@var{x}ex}, where @var{x} is a number of @samp{x} characters, or a
> +string on the form @samp{@var{x}px} (denoting a number of pixels), or a
> +string on the form @samp{@var{x}%} (a percentage of the window's width).

...this sentence is a mouthfull: very hard to understand, and the use
of "x" in several different roles doesn't help.  Can we please reword
this to be more clear?

bug#71167: 29.3; vtable: documentation bug

[Joost Kremers]

On Fri, May 24 2024, Eli Zaretskii wrote:
>> From: Joost Kremers <joostkremers@fastmail.fm>
>> Date: Fri, 24 May 2024 09:20:28 +0200
>> 
>> The documentation for 'make-vtable' in vtable.texi has a small bug. Patch
>> attached.
>
> Thanks, but...
>
>>  @item width
>>  The width of the column.  This is either a number (the width of that
>>  many @samp{x} characters in the table's face), or a string on the form
>> -@samp{Xe@var{x}}, where @var{x} is a number of @samp{x} characters, or a
>> -string on the form @samp{Xp@var{x}} (denoting a number of pixels), or a
>> -string on the form @samp{X%} (a percentage of the window's width).
>> +@samp{@var{x}ex}, where @var{x} is a number of @samp{x} characters, or a
>> +string on the form @samp{@var{x}px} (denoting a number of pixels), or a
>> +string on the form @samp{@var{x}%} (a percentage of the window's width).
>
> ...this sentence is a mouthfull: very hard to understand, and the use
> of "x" in several different roles doesn't help.  Can we please reword
> this to be more clear?

Would it help if the x's that refer to a number were replaced with 'n'?

     ‘width’
          The width of the column.  This is either a number (the width
          of that many ‘x’ characters in the table's face), or a string
          on the form ‘Nex’, where N is a number of ‘x’ characters, or a
          string on the form ‘Npx’ (denoting a number of pixels), or a
          string on the form ‘N%’ (a percentage of the window's width).

In source:

```
@item width
The width of the column.  This is either a number (the width of that
many @samp{x} characters in the table's face), or a string on the form
@samp{@var{n}ex}, where @var{n} is a number of @samp{x} characters, or a
string on the form @samp{@var{n}px} (denoting a number of pixels), or a
string on the form @samp{@var{n}%} (a percentage of the window's width).
```


-- 
Joost Kremers
Life has its moments

bug#71167: 29.3; vtable: documentation bug

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Cc: 71167@debbugs.gnu.org
> Date: Fri, 24 May 2024 10:22:02 +0200
> 
> On Fri, May 24 2024, Eli Zaretskii wrote:
> >> From: Joost Kremers <joostkremers@fastmail.fm>
> >> Date: Fri, 24 May 2024 09:20:28 +0200
> >> 
> >> The documentation for 'make-vtable' in vtable.texi has a small bug. Patch
> >> attached.
> >
> > Thanks, but...
> >
> >>  @item width
> >>  The width of the column.  This is either a number (the width of that
> >>  many @samp{x} characters in the table's face), or a string on the form
> >> -@samp{Xe@var{x}}, where @var{x} is a number of @samp{x} characters, or a
> >> -string on the form @samp{Xp@var{x}} (denoting a number of pixels), or a
> >> -string on the form @samp{X%} (a percentage of the window's width).
> >> +@samp{@var{x}ex}, where @var{x} is a number of @samp{x} characters, or a
> >> +string on the form @samp{@var{x}px} (denoting a number of pixels), or a
> >> +string on the form @samp{@var{x}%} (a percentage of the window's width).
> >
> > ...this sentence is a mouthfull: very hard to understand, and the use
> > of "x" in several different roles doesn't help.  Can we please reword
> > this to be more clear?
> 
> Would it help if the x's that refer to a number were replaced with 'n'?
> 
>      ‘width’
>           The width of the column.  This is either a number (the width
>           of that many ‘x’ characters in the table's face), or a string
>           on the form ‘Nex’, where N is a number of ‘x’ characters, or a
>           string on the form ‘Npx’ (denoting a number of pixels), or a
>           string on the form ‘N%’ (a percentage of the window's width).

It's better, but I think it will be even more clear if you make a
@table out of the 3 possible forms of the 'width' slot.

bug#71167: 29.3; vtable: documentation bug

[Joost Kremers]

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

On Fri, May 24 2024, Eli Zaretskii wrote:
> It's better, but I think it will be even more clear if you make a
> @table out of the 3 possible forms of the 'width' slot.

That's a tough one. :D Here's what I came up with:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Update-documentation-for-width-slot-of-vtable-column.patch --]
[-- Type: text/x-patch, Size: 1414 bytes --]

From 6da8c56905db7ada508f80566b1a00bad45a7016 Mon Sep 17 00:00:00 2001
From: Joost Kremers <joostkremers@fastmail.com>
Date: Sat, 25 May 2024 20:38:22 +0200
Subject: [PATCH] Update documentation for 'width' slot of vtable ':columns'
 object.

---
 doc/misc/vtable.texi | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/doc/misc/vtable.texi b/doc/misc/vtable.texi
index 7252c61b9d2..c451a29bdd1 100644
--- a/doc/misc/vtable.texi
+++ b/doc/misc/vtable.texi
@@ -281,11 +281,18 @@ Making A Table
 The name of the column.
 
 @item width
-The width of the column.  This is either a number (the width of that
-many @samp{x} characters in the table's face), or a string on the form
-@samp{@var{x}ex}, where @var{x} is a number of @samp{x} characters, or a
-string on the form @samp{@var{x}px} (denoting a number of pixels), or a
-string on the form @samp{@var{x}%} (a percentage of the window's width).
+The width of the column.  This is can be one of the following:
+
+@table @asis
+@item a number @var{n} or a string of the form @samp{@var{n}ex}
+The width of @var{n} @samp{x} characters in the table's face.
+
+@item a string of the form @samp{@var{n}px}
+A width of @var{n} pixels.
+
+@item a string of the form @samp{@var{n}%}
+@var{n} percent of the window's width.
+@end table
 
 @item min-width
 This uses the same format as @code{width}, but specifies the minimum
-- 
2.45.1


[-- Attachment #3: Type: text/plain, Size: 41 bytes --]



-- 
Joost Kremers
Life has its moments

bug#71167: 29.3; vtable: documentation bug

[Joost Kremers]

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

On Sat, May 25 2024, Joost Kremers wrote:
> On Fri, May 24 2024, Eli Zaretskii wrote:
>> It's better, but I think it will be even more clear if you make a
>> @table out of the 3 possible forms of the 'width' slot.
>
> That's a tough one. :D Here's what I came up with:

Apologies, noticed a typo right after sending... Here's a corrected patch:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Update-documentation-for-width-slot-of-vtable-column.patch --]
[-- Type: text/x-patch, Size: 1411 bytes --]

From 42de82abd54ca290048553d4d073df0086577367 Mon Sep 17 00:00:00 2001
From: Joost Kremers <joostkremers@fastmail.com>
Date: Sat, 25 May 2024 20:38:22 +0200
Subject: [PATCH] Update documentation for 'width' slot of vtable ':columns'
 object.

---
 doc/misc/vtable.texi | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/doc/misc/vtable.texi b/doc/misc/vtable.texi
index 7252c61b9d2..3bd06a7f5a1 100644
--- a/doc/misc/vtable.texi
+++ b/doc/misc/vtable.texi
@@ -281,11 +281,18 @@ Making A Table
 The name of the column.
 
 @item width
-The width of the column.  This is either a number (the width of that
-many @samp{x} characters in the table's face), or a string on the form
-@samp{@var{x}ex}, where @var{x} is a number of @samp{x} characters, or a
-string on the form @samp{@var{x}px} (denoting a number of pixels), or a
-string on the form @samp{@var{x}%} (a percentage of the window's width).
+The width of the column.  This can be one of the following:
+
+@table @asis
+@item a number @var{n} or a string of the form @samp{@var{n}ex}
+The width of @var{n} @samp{x} characters in the table's face.
+
+@item a string of the form @samp{@var{n}px}
+A width of @var{n} pixels.
+
+@item a string of the form @samp{@var{n}%}
+@var{n} percent of the window's width.
+@end table
 
 @item min-width
 This uses the same format as @code{width}, but specifies the minimum
-- 
2.45.1


[-- Attachment #3: Type: text/plain, Size: 41 bytes --]



-- 
Joost Kremers
Life has its moments

bug#71167: 29.3; vtable: documentation bug

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Cc: 71167@debbugs.gnu.org
> Date: Sat, 25 May 2024 20:44:12 +0200
> 
> +The width of the column.  This can be one of the following:
> +
> +@table @asis
> +@item a number @var{n} or a string of the form @samp{@var{n}ex}

This could be improved:

  @item a number @var{n}
  @itemx a string of the form @samp{@var{n}ex}

> +@item a string of the form @samp{@var{n}px}
> +A width of @var{n} pixels.
   ^^^^^^^
"The width", I guess?  Or maybe just "@var{n} pixels"?

Thanks.

bug#71167: 29.3; vtable: documentation bug

[Joost Kremers]

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

On Sat, May 25 2024, Eli Zaretskii wrote:
> This could be improved:
>
>   @item a number @var{n}
>   @itemx a string of the form @samp{@var{n}ex}

Done.

>> +@item a string of the form @samp{@var{n}px}
>> +A width of @var{n} pixels.
>    ^^^^^^^
> "The width", I guess?  Or maybe just "@var{n} pixels"?

"@var{n} pixels" seems best, I think.



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Update-documentation-for-width-slot-of-vtable-column.patch --]
[-- Type: text/x-patch, Size: 1398 bytes --]

From f2df6460e90b9a6eb561026343c193e428189e08 Mon Sep 17 00:00:00 2001
From: Joost Kremers <joostkremers@fastmail.com>
Date: Sat, 25 May 2024 21:55:29 +0200
Subject: [PATCH] Update documentation for 'width' slot of vtable ':column'
 object

---
 doc/misc/vtable.texi | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/doc/misc/vtable.texi b/doc/misc/vtable.texi
index 822b1097cd9..6003435385f 100644
--- a/doc/misc/vtable.texi
+++ b/doc/misc/vtable.texi
@@ -281,11 +281,19 @@ Making A Table
 The name of the column.
 
 @item width
-The width of the column.  This is either a number (the width of that
-many @samp{x} characters in the table's face), or a string on the form
-@samp{Xe@var{x}}, where @var{x} is a number of @samp{x} characters, or a
-string on the form @samp{Xp@var{x}} (denoting a number of pixels), or a
-string on the form @samp{X%} (a percentage of the window's width).
+The width of the column.  This can be one of the following:
+
+@table @asis
+@item a number @var{n}
+@itemx a string of the form @samp{@var{n}ex}
+The width of @var{n} @samp{x} characters in the table's face.
+
+@item a string of the form @samp{@var{n}px}
+@var{n} pixels.
+
+@item a string of the form @samp{@var{n}%}
+@var{n} percent of the window's width.
+@end table
 
 @item min-width
 This uses the same format as @code{width}, but specifies the minimum
-- 
2.45.1


[-- Attachment #3: Type: text/plain, Size: 41 bytes --]



-- 
Joost Kremers
Life has its moments

bug#71167: 29.3; vtable: documentation bug

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Cc: 71167@debbugs.gnu.org
> Date: Sat, 25 May 2024 22:05:26 +0200
> 
> On Sat, May 25 2024, Eli Zaretskii wrote:
> > This could be improved:
> >
> >   @item a number @var{n}
> >   @itemx a string of the form @samp{@var{n}ex}
> 
> Done.
> 
> >> +@item a string of the form @samp{@var{n}px}
> >> +A width of @var{n} pixels.
> >    ^^^^^^^
> > "The width", I guess?  Or maybe just "@var{n} pixels"?
> 
> "@var{n} pixels" seems best, I think.

Thanks, installed on master, and closing the bug.