bug#8568: 24.0.50; fringe-indicator-alist doc

bug#8568: 24.0.50; fringe-indicator-alist doc

[Drew Adams]

1. (elisp) Fringe Indicators: "`top-bottom" is missing the closing
single-quote, for some reason: "...used only for the `bottom' and
`top-bottom indicators when the...".
 
2. There is no real explanation of LEFT1 and RIGHT1.  The pseudo
explanation is unintelligible: "The LEFT1 or RIGHT1 bitmaps are used
only for the `bottom' and `top-bottom' indicators when the last (only)
line has no final newline."  That talks about the situation when they
are used, but it doesn't explain what they are or how they are used.
 
3. This var maps logical indicators to bitmaps.  But we need to describe
each logical indicator.  What does it mean?  When is it appropriate to
use it?  For some you can guess, based on the short description: "empty
line indicator" is no doubt appropriate for indicating an empty line.
But what about `overlay-arrow'?  Its description is "Overlay arrow
indicator"  Well, duh, but what does that mean?   When do you use it?
What is it intended for?
 
4. The node ends with "Standard fringe bitmaps for indicators:" and a
list of bitmap symbols.  A bitmap symbol such as `bottom-left-angle' is
meaningless as just a name.  If we can't have images then at least
provide one-line descriptions of what each looks like.  It would also
help to show the default mapping, that is, the default value of
`fringe-indicator-alist'.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-04-25 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/imagesupport/include'
 

bug#8568: 24.0.50; fringe-indicator-alist doc

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Wed, 27 Apr 2011 13:31:14 -0700
> 
> 1. (elisp) Fringe Indicators: "`top-bottom" is missing the closing
> single-quote, for some reason: "...used only for the `bottom' and
> `top-bottom indicators when the...".

Yep, a missing quote.

> 2. There is no real explanation of LEFT1 and RIGHT1.  The pseudo
> explanation is unintelligible: "The LEFT1 or RIGHT1 bitmaps are used
> only for the `bottom' and `top-bottom' indicators when the last (only)
> line has no final newline."  That talks about the situation when they
> are used, but it doesn't explain what they are

This is supposed to be explained in the beginning of the section:

     Emacs can indicate the buffer boundaries--that is, the first and
     last line in the buffer--with angle icons when they appear on the
     screen.  In addition, Emacs can display an up-arrow in the fringe
     to show that there is text above the screen, and a down-arrow to
     show there is text below the screen.

Are the names of each of these all that's missing to fill in the
blanks?

> or how they are used.

This part I actually don't understand.  What do you mean "_how_ they
are used"? by drawing them in the fringes, of course!  What am I
missing?

> 3. This var maps logical indicators to bitmaps.  But we need to describe
> each logical indicator.  What does it mean?  When is it appropriate to
> use it?

Same answer as for #2, and the same text that's supposed to explain
that.

> But what about `overlay-arrow'?  Its description is "Overlay arrow
> indicator"  Well, duh, but what does that mean?   When do you use it?
> What is it intended for?

Type "i overlay-arrow RET" and you will see.  Will a cross-reference
there be enough?

> 4. The node ends with "Standard fringe bitmaps for indicators:" and a
> list of bitmap symbols.  A bitmap symbol such as `bottom-left-angle' is
> meaningless as just a name.  If we can't have images then at least
> provide one-line descriptions of what each looks like.

We _can_ have images, it's just a bit tedious to produce them.  As for
description... it's not easy.  Perhaps you could suggest the proper
descriptions, after looking at each one of the bitmaps.

bug#8568: 24.0.50; fringe-indicator-alist doc

[Drew Adams]

> > 2. There is no real explanation of LEFT1 and RIGHT1.  The pseudo
> > explanation is unintelligible: "The LEFT1 or RIGHT1 bitmaps are used
> > only for the `bottom' and `top-bottom' indicators when the 
> > last (only) line has no final newline."  That talks about the
> > situation when they are used, but it doesn't explain what they are
> 
> This is supposed to be explained in the beginning of the section:
> 
>      Emacs can indicate the buffer boundaries--that is, the first and
>      last line in the buffer--with angle icons when they appear on the
>      screen.  In addition, Emacs can display an up-arrow in the fringe
>      to show that there is text above the screen, and a down-arrow to
>      show there is text below the screen.

That is _not_ at the beginning of the section.  That is part of the description
of a different variable, user option `indicate-buffer-boundaries'.  That seems
to pertain only to fringe that indicates buffer boundaries, not to fringe in
general.
 
> Are the names of each of these all that's missing to fill in the
> blanks?

I guess so.  We mention names (for `fringe-indicator-alist' INDICATOR values)
and we give some description (for `indicate-buffer-boundaries'), but we don't
link the description to the indicator names.

My reading of this node and the uses I see of `fringe-indicator-alist' in the
source code suggest that this variable is general, for use with fringe in
general and not just for use with fringe that indicates buffer boundaries.

So I certainly would not expect the description of buffer-boundary indication to
apply to the possible INDICATOR values for `fringe-indicator-alist'.  Am I wrong
about that?

[BTW, I just noticed that "is list of symbols" should be "is a list of
symbols".]

> > or how they are used.
> 
> This part I actually don't understand.  What do you mean "_how_ they
> are used"? by drawing them in the fringes, of course!  What am I
> missing?

I meant when it is appropriate to use them.  I am thinking of the general, not
just the default case - that is, use of `fringe-indicator-alist' in general,
whatever its current value might be.

But linking specific indicators to their use in `indicate-buffer-boundaries
behaviors is a help, I suppose.  That at least explains what those indicators
are meant for in the default case.

BTW, is it the case that the _only_ possible values of INDICATOR for
`fringe-indicator-list' are those symbols listed?  I don't have the C source,
but if that is the case then in Lisp the :type for the defcustom would restrict
the values to truncation, continuation, ..., unknown.

If these are the only possible values, then the doc should say so.  Especially
since there is no limit to the values for BITMAPS (users can add their own
fringe BITMAPS, but presumably not logical INDICATORS).

> > 3. This var maps logical indicators to bitmaps.  But we 
> > need to describe each logical indicator.  What does it mean?
> >  When is it appropriate to use it?
> 
> Same answer as for #2, and the same text that's supposed to explain
> that.

See above.  Each logical INDICATOR needs to be described, in terms of its
generally intended use/meaning.

> > But what about `overlay-arrow'?  Its description is "Overlay arrow
> > indicator"  Well, duh, but what does that mean?   When do 
> > you use it? What is it intended for?
> 
> Type "i overlay-arrow RET" and you will see.  Will a cross-reference
> there be enough?

It's certainly necessary. And probably sufficient, though we should still give a
few-words description of it in this node, just as for each of the other fringe
indicators (each needs a one-liner).

A fringe indicator value of `overlay-arrow' is not necessarily related, a
priori, to the variables `overlay-arrow-string' etc.  And a user would not
necessarily think to look for the undefined term in the index.

> > 4. The node ends with "Standard fringe bitmaps for 
> > indicators:" and a list of bitmap symbols.  A bitmap symbol such as 
> > `bottom-left-angle' is meaningless as just a name.  If we can't
> > have images then at least provide one-line descriptions of what
> > each looks like.
> 
> We _can_ have images, it's just a bit tedious to produce them.

Let's have an image plus a one-line (phrase) description for each.  The
description is important for displays that might not support images (yes, one
can imagine development on such a display for use by users with displays that
can show the bitmaps).

> As for description... it's not easy.  Perhaps you could
> suggest the proper descriptions, after looking at each one
> of the bitmaps.

How can I see each of the bitmaps?  If I could see them then yes, I could try to
give you a one-liner describing each.

FWIW, professional doc nearly always _requires_ each image to be accompanied by
a description, for accessibility reasons.  The wording describes what is shown
in the image (not its significance etc.).  E.g., "Two circles left and right,
the left one with label `Foo' and the right one with label `Bar'.  An arrow from
the `Foo' circle to the `Bar' circle, labeled `Toto'.".

bug#8568: 24.0.50; fringe-indicator-alist doc

[Chong Yidong]

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

> 1. (elisp) Fringe Indicators: "`top-bottom" is missing the closing
> single-quote
>  
> 2. There is no real explanation of LEFT1 and RIGHT1.
>  
> 3. This var maps logical indicators to bitmaps.  But we need to describe
> each logical indicator.

Fixed in trunk.  Thanks.