Subject: Re: bug#71167: 29.3; vtable: documentation bug

From: Eli Zaretskii <[email-masked]>
Date: Fri, 24 May 2024 14:00:37 +0300

> From: Joost Kremers <[email-masked]>
> Cc: [email-masked]
> Date: Fri, 24 May 2024 10:22:02 +0200
> 
> On Fri, May 24 2024, Eli Zaretskii wrote:
> >> From: Joost Kremers <[email-masked]>
> >> 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.