GNU bug report logs - #71167
29.3; vtable: documentation bug

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 71167 in the body.
You can then email your comments to 71167 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Joost Kremers <joostkremers <at> fastmail.fm>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.3; vtable: documentation bug
Date: Fri, 24 May 2024 09:20:28 +0200

[Message part 1 (text/plain, inline)]

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



-- 
Joost Kremers
Life has its moments

[0001-Fix-doc-for-width-slot-of-vtable-column-keyword-para.patch (text/x-patch, inline)]

From 2af7ecdff1c7b019f0ee4b331b02558e2b39dbd5 Mon Sep 17 00:00:00 2001
From: Joost Kremers <joostkremers <at> 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 <at> var{x}}, where @var{x} is a number of @samp{x} characters, or a
-string on the form @samp{Xp <at> 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

Message #8 received at 71167 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Joost Kremers <joostkremers <at> fastmail.fm>
Cc: 71167 <at> debbugs.gnu.org
Subject: Re: bug#71167: 29.3; vtable: documentation bug
Date: Fri, 24 May 2024 10:49:06 +0300

> From: Joost Kremers <joostkremers <at> 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 <at> var{x}}, where @var{x} is a number of @samp{x} characters, or a
> -string on the form @samp{Xp <at> 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?

Message #11 received at 71167 <at> debbugs.gnu.org (full text, mbox):

From: Joost Kremers <joostkremers <at> fastmail.fm>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 71167 <at> debbugs.gnu.org
Subject: Re: bug#71167: 29.3; vtable: documentation bug
Date: Fri, 24 May 2024 10:22:02 +0200

On Fri, May 24 2024, Eli Zaretskii wrote:
>> From: Joost Kremers <joostkremers <at> 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 <at> var{x}}, where @var{x} is a number of @samp{x} characters, or a
>> -string on the form @samp{Xp <at> 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

Message #14 received at 71167 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Joost Kremers <joostkremers <at> fastmail.fm>
Cc: 71167 <at> debbugs.gnu.org
Subject: Re: bug#71167: 29.3; vtable: documentation bug
Date: Fri, 24 May 2024 14:00:37 +0300

> From: Joost Kremers <joostkremers <at> fastmail.fm>
> Cc: 71167 <at> debbugs.gnu.org
> Date: Fri, 24 May 2024 10:22:02 +0200
> 
> On Fri, May 24 2024, Eli Zaretskii wrote:
> >> From: Joost Kremers <joostkremers <at> 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 <at> var{x}}, where @var{x} is a number of @samp{x} characters, or a
> >> -string on the form @samp{Xp <at> 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.

Message #17 received at 71167 <at> debbugs.gnu.org (full text, mbox):

From: Joost Kremers <joostkremers <at> fastmail.fm>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 71167 <at> debbugs.gnu.org
Subject: Re: bug#71167: 29.3; vtable: documentation bug
Date: Sat, 25 May 2024 20:41:28 +0200

[Message part 1 (text/plain, inline)]

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:

[0001-Update-documentation-for-width-slot-of-vtable-column.patch (text/x-patch, inline)]

From 6da8c56905db7ada508f80566b1a00bad45a7016 Mon Sep 17 00:00:00 2001
From: Joost Kremers <joostkremers <at> 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

[Message part 3 (text/plain, inline)]

-- 
Joost Kremers
Life has its moments

Message #20 received at 71167 <at> debbugs.gnu.org (full text, mbox):

From: Joost Kremers <joostkremers <at> fastmail.fm>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 71167 <at> debbugs.gnu.org
Subject: Re: bug#71167: 29.3; vtable: documentation bug
Date: Sat, 25 May 2024 20:44:12 +0200

[Message part 1 (text/plain, inline)]

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:

[0001-Update-documentation-for-width-slot-of-vtable-column.patch (text/x-patch, inline)]

From 42de82abd54ca290048553d4d073df0086577367 Mon Sep 17 00:00:00 2001
From: Joost Kremers <joostkremers <at> 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

[Message part 3 (text/plain, inline)]

-- 
Joost Kremers
Life has its moments

Message #23 received at 71167 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Joost Kremers <joostkremers <at> fastmail.fm>
Cc: 71167 <at> debbugs.gnu.org
Subject: Re: bug#71167: 29.3; vtable: documentation bug
Date: Sat, 25 May 2024 21:56:31 +0300

> From: Joost Kremers <joostkremers <at> fastmail.fm>
> Cc: 71167 <at> 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.

Message #26 received at 71167 <at> debbugs.gnu.org (full text, mbox):

From: Joost Kremers <joostkremers <at> fastmail.fm>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 71167 <at> debbugs.gnu.org
Subject: Re: bug#71167: 29.3; vtable: documentation bug
Date: Sat, 25 May 2024 22:05:26 +0200

[Message part 1 (text/plain, inline)]

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.

[0001-Update-documentation-for-width-slot-of-vtable-column.patch (text/x-patch, inline)]

From f2df6460e90b9a6eb561026343c193e428189e08 Mon Sep 17 00:00:00 2001
From: Joost Kremers <joostkremers <at> 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 <at> var{x}}, where @var{x} is a number of @samp{x} characters, or a
-string on the form @samp{Xp <at> 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

[Message part 3 (text/plain, inline)]

-- 
Joost Kremers
Life has its moments

Message #31 received at 71167-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Joost Kremers <joostkremers <at> fastmail.fm>
Cc: 71167-done <at> debbugs.gnu.org
Subject: Re: bug#71167: 29.3; vtable: documentation bug
Date: Sun, 26 May 2024 12:20:24 +0300

> From: Joost Kremers <joostkremers <at> fastmail.fm>
> Cc: 71167 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.