* bug#8568: 24.0.50; fringe-indicator-alist doc @ 2011-04-27 20:31 Drew Adams 2011-04-27 20:53 ` Eli Zaretskii 2012-01-28 13:49 ` Chong Yidong 0 siblings, 2 replies; 4+ messages in thread From: Drew Adams @ 2011-04-27 20:31 UTC (permalink / raw) To: 8568 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' ^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#8568: 24.0.50; fringe-indicator-alist doc 2011-04-27 20:31 bug#8568: 24.0.50; fringe-indicator-alist doc Drew Adams @ 2011-04-27 20:53 ` Eli Zaretskii 2011-04-27 21:48 ` Drew Adams 2012-01-28 13:49 ` Chong Yidong 1 sibling, 1 reply; 4+ messages in thread From: Eli Zaretskii @ 2011-04-27 20:53 UTC (permalink / raw) To: Drew Adams; +Cc: 8568 > 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. ^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#8568: 24.0.50; fringe-indicator-alist doc 2011-04-27 20:53 ` Eli Zaretskii @ 2011-04-27 21:48 ` Drew Adams 0 siblings, 0 replies; 4+ messages in thread From: Drew Adams @ 2011-04-27 21:48 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 8568 > > 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'.". ^ permalink raw reply [flat|nested] 4+ messages in thread
* bug#8568: 24.0.50; fringe-indicator-alist doc 2011-04-27 20:31 bug#8568: 24.0.50; fringe-indicator-alist doc Drew Adams 2011-04-27 20:53 ` Eli Zaretskii @ 2012-01-28 13:49 ` Chong Yidong 1 sibling, 0 replies; 4+ messages in thread From: Chong Yidong @ 2012-01-28 13:49 UTC (permalink / raw) To: Drew Adams; +Cc: 8568 "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. ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2012-01-28 13:49 UTC | newest] Thread overview: 4+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2011-04-27 20:31 bug#8568: 24.0.50; fringe-indicator-alist doc Drew Adams 2011-04-27 20:53 ` Eli Zaretskii 2011-04-27 21:48 ` Drew Adams 2012-01-28 13:49 ` Chong Yidong
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.