bug#6113: 23.1.97; doc of :box face attibute

bug#6113: 23.1.97; doc of :box face attibute

[Drew Adams]

emacs -Q
 
Visit node Face Attributes in the Elisp manual.
 
The description of attribute :box does not say what the possible values
of :line-width are or what they mean.
 
Take a look at face `mode-line-inactive', for instance.  It has a
`line-width' of -1.  There is no way to understand this unless it is
documented properly.  Even for positive values, we say nothing about
what the width units are (e.g. pixels).
 

In GNU Emacs 23.1.97.1 (i386-mingw-nt5.1.2600)
 of 2010-05-04 on G41R2F1
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/xpm/include'
 

bug#6113: 23.1.97; doc of :box face attibute

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> The description of attribute :box does not say what the possible values
> of :line-width are or what they mean.
>
> Take a look at face `mode-line-inactive', for instance.  It has a
> `line-width' of -1.  There is no way to understand this unless it is
> documented properly.  Even for positive values, we say nothing about
> what the width units are (e.g. pixels).

I don't think the units need clarification, really -- I think all the
width/height things when talking about faces would naturally be assumed
to be pixels.

But I have no idea what a negative `line-width' would mean, and that
needs documentation.  I've skimmed the C code that deals with
`line-width', but it's still rather obscure to me.

Could someone who knows what a negative `line-width' in :box means
document this in the manual?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#6113: 23.1.97; doc of :box face attibute

[Juanma Barranquero]

On Sun, Jul 3, 2011 at 02:06, Lars Magne Ingebrigtsen <larsi@gnus.org> wrote:

> Could someone who knows what a negative `line-width' in :box means

From xfaces.c:realize_x_face():

          if (EQ (keyword, QCline_width))
            {
              if (INTEGERP (value) && XINT (value) != 0)
                face->box_line_width = XINT (value);
            }
          else
            /* etc. */

and from dispextern.h:

  /* Non-zero means characters in this face have a box that thickness
     around them.  If it is negative, the absolute value indicates the
     thickness, and the horizontal lines of box (top and bottom) are
     drawn inside of characters glyph area.  The vertical lines of box
     (left and right) are drawn as the same way as the case that this
     value is positive.  */
  int box_line_width;

    Juanma

bug#6113: 23.1.97; doc of :box face attibute

[Chong Yidong]

Lars Magne Ingebrigtsen <larsi@gnus.org> writes:

> But I have no idea what a negative `line-width' would mean, and that
> needs documentation.  I've skimmed the C code that deals with
> `line-width', but it's still rather obscure to me.

Yeah, I documented it.

bug#6113: 23.1.97; doc of :box face attibute

[Drew Adams]

> > The description of attribute :box does not say what the 
> > possible values
> > of :line-width are or what they mean.
> >
> > Take a look at face `mode-line-inactive', for instance.  It has a
> > `line-width' of -1.  There is no way to understand this unless it is
> > documented properly.  Even for positive values, we say nothing about
> > what the width units are (e.g. pixels).
> 
> I don't think the units need clarification, really -- I think all the
> width/height things when talking about faces would naturally 
> be assumed to be pixels.

The question is not what you would assume the units to be.  Please just state
what the units are.  A user will not necessarily assume anything about the
units.  They could be points or anything else.  It doesn't take much to tell
users what they are.  You need only add two words: "in pixels".

Search for "pixel" in the manual and you will see that this is standard
procedure.  It is normal for doc to tell users what the units of measurements or
quantities are.