* bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. [not found] ` <<838smzvk86.fsf@gnu.org> @ 2019-12-26 17:49 ` Drew Adams 0 siblings, 0 replies; 9+ messages in thread From: Drew Adams @ 2019-12-26 17:49 UTC (permalink / raw) To: Eli Zaretskii, Drew Adams; +Cc: 38736 > > > Like I said: eval's doc string documents this > > > feature, > > > > I see nothing in the doc string of `eval' that > > tells you `%S' in the `message' format string is > > controlled by `print-length'. Or even anything > > close to it. > > Sorry, I meant eval-expression, what is run by M-:. FWIW, I made it clear that I did not use `eval-expression' (`M-:): >>> How did you get the ellipsis in *Messages*? >> >> By a call (message "Result: %S" result), >> where the value of `result' is a long list. And when you then said that (message "Result: %S" result) is "not a call, that's evaluation", I replied that it was used "in code, in a function body." The general point is that a user who wants to know about the behavior of `message', in particular for a format string with %S (but not limited to that), now needs to dig deep into a chain of doc strings or manual links. `message', like `format', is very commonly used. And (I think) %S may be the most commonly used %-sequence with `message'. We now clutter the doc of `message' with info about ` and ', and to link to the doc for `format-message'. That further complicates trying to understand `message' behavior. The `message' doc even has this gratuitous text now: To display STRING without special treatment, use (message "%s" STRING). There's no STRING in the function signature. There's nothing special about a STRING arg, and %s doesn't just print a STRING as a string - it prints anything as a string. Parameter ARGS isn't even described by name. It's OK that we say that "the rest are data to be formatted...". But, especially because of that sentence about STRING data, it's not made sufficiently clear that the "data", are Lisp objects of any kind. If you really want to have a statement about using %s to produce string output then just say that. Don't show a call to `message' where the second arg is STRING - that's misleading. Here's my suggestion, at this point. But perhaps we can do better - I don't have all the answers. 1. Say that the ARGS are Lisp objects of any kind. 2. Say that ARGS are handled by `format-message', (alas) and the result is shown as a message. 3. Users can follow the `format-message' link to get all the formatting info they need. 4. Don't mention `, ', or %. That doesn't help without more info; it's just noise. 5. If you _do_ show an example using % then use %S, and point out that it uses `prin1'. (Maybe even say that `prin1' is controlled by variables such as `print-level'.) #3 is a step back from my initial suggestion for trying to shorten the journey to info about the `prin1' variables. #5 might mitigate #3. I don't have a perfect solution, at this point. It's _really_ too bad that we had to introduce `format-message'. Going from `message' doc to `format-message' doc works against usability and understanding. As opposed to `format', the `format-message' doc talks only about the new "quoting" hoops. It forces you to move to the `format' doc to get the %-sequences info you really need, to make use of `message' in the most common ways. The "quoting" stuff should be the last, not the first, thing you read when trying to understand `message' and the like. (And `format-message' is specifically for messaging.) It would be better - if we're forced to send people to `format-message' first - if its doc string contained all of the info that's in the `format' doc, and it added the "quoting" stuff only at the end. Better, IOW, for users coming from `message' and the like to get the main format-control info (%-sequences) first. As it stands now, the cart ("quoting") is put before the horse (%-sequences), when trying to understand `message' and the like. I know that we don't want to just duplicate all the `format' doc. That's not great. But `message' is a high-level access point for using format control strings, and to get to the important info about those, you now have to get past the unhelpful, noisy doc of `format-message'. If a user stops at that doc, and doesn't plow forward to the `format' doc, then the most important messages about `message' will not get through. [This would have been avoided as a problem if `message' had not been co-opted to use `format-message', i.e., if we had instead just added a separate function, e.g., `message-with-quote-munging', which used `format-message'. Alas, that ship has sailed.] ^ permalink raw reply [flat|nested] 9+ messages in thread
[parent not found: <<<006e6244-dd0a-46a8-8c61-36744b3216de@default>]
[parent not found: <<<83pngcv5ha.fsf@gnu.org>]
[parent not found: <<32378b4e-d158-48d5-a48c-7afde59f5d32@default>]
[parent not found: <<83d0ccuxoe.fsf@gnu.org>]
* bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. [not found] ` <<83d0ccuxoe.fsf@gnu.org> @ 2019-12-25 20:54 ` Drew Adams 2019-12-26 3:28 ` Eli Zaretskii 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2019-12-25 20:54 UTC (permalink / raw) To: Eli Zaretskii, Drew Adams; +Cc: 38736-done > > > How did you get the ellipsis in *Messages*? > > > > By a call (message "Result: %S" result), where > > the value of `result' is a long list. > > That's not a "call", that's evaluation. Huh? It's in code, in a function body. But of course, code (source/byte-compiled) is evaluated (interpreted, executed, whatever term you prefer). Executing that code means evaluating that sexp, yes. And? It's not clear what hairs you are trying to split, here. > And using %S is a prerequisite, AFAIK; you won't > get the ellipsis with other formats. Correct, which is why I said (message "%S"), and not just calling `message'. > Like I said: eval's doc string documents this > feature, I see nothing in the doc string of `eval' that tells you `%S' in the `message' format string is controlled by `print-length'. Or even anything close to it. eval is a built-in function in 'C source code'. (eval FORM &optional LEXICAL) Evaluate FORM and return its value. If LEXICAL is t, evaluate using lexical scoping. LEXICAL can also be an actual lexical environment, in the form of an alist mapping symbols to their value. Pointing to `eval' here seems like a very red herring. > you just looked for the documentation in the > wrong place `C-h f eval' is the right place? How so? How does it help? > (and still found it, albeit through a long path). Exactly what I reported. A long road to get to info about a commonly used construct. (Or do you still maintain that %S is rarely used with `message'?) And note that if you try to find it in the Elisp manual, starting with `message' (node `Displaying Messages') and linking to node `Formatting Strings', then what you find for %S is this: '%S' Replace the specification with the printed representation of the object, made with quoting (that is, using 'prin1'-*note Output Functions::). Thus, strings are enclosed in '"' characters, and '\' characters appear where necessary before special characters. Then you need to follow the `Output Functions' link to read about `prin1'. Again, several links to follow. Even in `Formatting Strings' it would make sense to not give the impression that `prin1' is only about "quoting". "quoting (that is, using `prin1'" `prin1's use of variables `print-length' etc. have nothing to do with "quoting". > So I see nothing to be done here, and I'm > closing this bug report. Too bad, once again. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. 2019-12-25 20:54 ` Drew Adams @ 2019-12-26 3:28 ` Eli Zaretskii 0 siblings, 0 replies; 9+ messages in thread From: Eli Zaretskii @ 2019-12-26 3:28 UTC (permalink / raw) To: Drew Adams; +Cc: 38736 > Date: Wed, 25 Dec 2019 12:54:54 -0800 (PST) > From: Drew Adams <drew.adams@oracle.com> > Cc: 38736-done@debbugs.gnu.org > > > Like I said: eval's doc string documents this > > feature, > > I see nothing in the doc string of `eval' that > tells you `%S' in the `message' format string is > controlled by `print-length'. Or even anything > close to it. Sorry, I meant eval-expression, what is run by M-:. ^ permalink raw reply [flat|nested] 9+ messages in thread
[parent not found: <<006e6244-dd0a-46a8-8c61-36744b3216de@default>]
[parent not found: <<83pngcv5ha.fsf@gnu.org>]
* bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. [not found] ` <<83pngcv5ha.fsf@gnu.org> @ 2019-12-25 16:44 ` Drew Adams 2019-12-25 17:23 ` Eli Zaretskii 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2019-12-25 16:44 UTC (permalink / raw) To: Eli Zaretskii, Drew Adams; +Cc: 38736 > > Consider trying to figure out, when looking at a message in > > `*Messages*', why a long list value shows ellipsis ("..."), > > instead of showing all the elements. > > How did you get the ellipsis in *Messages*? By a call (message "Result: %S" result), where the value of `result' is a long list. > I'm guessing you invoked 'eval', because this is a > feature of 'eval'. So looking for the information > in the doc string of 'message' is a somewhat strange > place. `message', like other functions, evaluates its args. And `format' for %S ends up using `prin1'. Help-wise, to get from `message' and `...' to `print-length' is a long haul. > > Following the `format-message' link, you still get no clue about > > this, but you then follow a link for `format'. There you still > > get no clue about it, but you see that %S uses `prin1'. > > > > Following the `prin1' link you finally find out that you can control > > `message's use of ellipsis using `print-length' and `print-level'. > > > > Users shouldn't have to go through all of that (and that even assumes > > that they are able to guess that following just that thread might get > > them somewhere useful). > > > > What's true for `message' is also true for `error', etc. At least > > the doc of `format' - and probably its often-used callers, such as > > `message' - should specifically mention these "print"-controlling > > (really just formatting) variables. > > I don't think it's reasonable to ask to have this low-level stuff > bubble up to such high levels, which are quite far from the features > which are affected by these variables. It's not lower-level than are the details currently included about %, `, and '. If it's enough for the `message' doc to just refer to `format-message' for `print-length' (eventually, after following links), then it should be enough for that doc to just refer to `format-message' for the info about %, `, and ', no? And as mentioned, % is not even mentioned in the doc for `format-message'. Why is it more important to mention % in the "higher-level" function `message' than in `format-message'? > %S is not a frequently used format, Why do you think so? It's perhaps the most common formatting string when using `message' for debugging etc., which I think is a common use case. %S is the most general formatting string, accepting any Lisp object. > I'd expect users who use %S to know already > about the ellipsis and how to control it. IOW, you expect users of `message' - which is pretty much everyone who uses Elisp - to know that. Well, I use `message' and `%S' a lot, yet I had to track it down, exactly as reported: `message' > `format-message' > `format' > %S > `prin1' > `print-length' Using %S with `message' likely doesn't give you `...' often. When it does, you can want to ask Emacs how to control that. Currently you have to dig deeply to find out. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. 2019-12-25 16:44 ` Drew Adams @ 2019-12-25 17:23 ` Eli Zaretskii 2019-12-26 3:24 ` Michael Heerdegen 0 siblings, 1 reply; 9+ messages in thread From: Eli Zaretskii @ 2019-12-25 17:23 UTC (permalink / raw) To: Drew Adams; +Cc: 38736-done > Date: Wed, 25 Dec 2019 08:44:53 -0800 (PST) > From: Drew Adams <drew.adams@oracle.com> > Cc: 38736@debbugs.gnu.org > > > > Consider trying to figure out, when looking at a message in > > > `*Messages*', why a long list value shows ellipsis ("..."), > > > instead of showing all the elements. > > > > How did you get the ellipsis in *Messages*? > > By a call (message "Result: %S" result), where the > value of `result' is a long list. That's not a "call", that's evaluation. And using %S is a prerequisite, AFAIK; you won't get the ellipsis with other formats. Like I said: eval's doc string documents this feature, you just looked for the documentation in the wrong place (and still found it, albeit through a long path). So I see nothing to be done here, and I'm closing this bug report. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. 2019-12-25 17:23 ` Eli Zaretskii @ 2019-12-26 3:24 ` Michael Heerdegen 2019-12-26 16:23 ` Eli Zaretskii 0 siblings, 1 reply; 9+ messages in thread From: Michael Heerdegen @ 2019-12-26 3:24 UTC (permalink / raw) To: 38736 Eli Zaretskii <eliz@gnu.org> writes: > Like I said: eval's doc string documents this feature I don't understand that comment either, did you mean `prin1'? > you just looked for the documentation in the wrong place (and still > found it, albeit through a long path). So I see nothing to be done > here, and I'm closing this bug report. I can agree that what we have is acceptable. But in this sentence in the docstring of `message': "The first argument is a format control string [...]" "format" could get quoted so that it gets transformed into a link to the `format' help page - right? Michael. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. 2019-12-26 3:24 ` Michael Heerdegen @ 2019-12-26 16:23 ` Eli Zaretskii 0 siblings, 0 replies; 9+ messages in thread From: Eli Zaretskii @ 2019-12-26 16:23 UTC (permalink / raw) To: Michael Heerdegen; +Cc: 38736 > From: Michael Heerdegen <michael_heerdegen@web.de> > Cc: eliz@gnu.org, drew.adams@oracle.com > Date: Thu, 26 Dec 2019 04:24:07 +0100 > > But in this sentence in the docstring of `message': > > "The first argument is a format control string [...]" > > "format" could get quoted so that it gets transformed into a link to the > `format' help page - right? No, because that "format" is not a reference to 'format' the function. There's a link to 'format-message' a little bit below that, so I think we are fine on that front. ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. @ 2019-12-24 21:02 Drew Adams 2019-12-25 14:34 ` Eli Zaretskii 0 siblings, 1 reply; 9+ messages in thread From: Drew Adams @ 2019-12-24 21:02 UTC (permalink / raw) To: 38736 The doc string of `format' doesn't tell you anything about control by `print-level', `print-length', etc. Please consider adding such info. Consider trying to figure out, when looking at a message in `*Messages*', why a long list value shows ellipsis ("..."), instead of showing all the elements. You try `C-h f message', which says nothing about this. The most it does is provide a bunch of details about the formatting intermediary `format-message', imposed since Emacs 25. Are details about %, `, and ' so important for `message' that they merit a paragraph, but `print-level' and `print-length' are not so important? (What's more: the doc string for `message' goes into more detail than the one for `format-message', which doesn't even mention %, even though the former tells you to refer to the latter "for details".) Following the `format-message' link, you still get no clue about this, but you then follow a link for `format'. There you still get no clue about it, but you see that %S uses `prin1'. Following the `prin1' link you finally find out that you can control `message's use of ellipsis using `print-length' and `print-level'. Users shouldn't have to go through all of that (and that even assumes that they are able to guess that following just that thread might get them somewhere useful). What's true for `message' is also true for `error', etc. At least the doc of `format' - and probably its often-used callers, such as `message' - should specifically mention these "print"-controlling (really just formatting) variables. In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32) of 2019-08-29 Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd Windowing system distributor `Microsoft Corp.', version 10.0.17763 Configured using: `configure --without-dbus --host=x86_64-w64-mingw32 --without-compress-install 'CFLAGS=-O2 -static -g3'' ^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc. 2019-12-24 21:02 Drew Adams @ 2019-12-25 14:34 ` Eli Zaretskii 0 siblings, 0 replies; 9+ messages in thread From: Eli Zaretskii @ 2019-12-25 14:34 UTC (permalink / raw) To: Drew Adams; +Cc: 38736 > Date: Tue, 24 Dec 2019 13:02:55 -0800 (PST) > From: Drew Adams <drew.adams@oracle.com> > > The doc string of `format' doesn't tell you anything about control by > `print-level', `print-length', etc. Please consider adding such info. > > Consider trying to figure out, when looking at a message in > `*Messages*', why a long list value shows ellipsis ("..."), instead of > showing all the elements. You try `C-h f message', which says nothing > about this. The most it does is provide a bunch of details about the > formatting intermediary `format-message', imposed since Emacs 25. How did you get the ellipsis in *Messages*? I'm guessing you invoked 'eval', because this is a feature of 'eval'. So looking for the information in the doc string of 'message' is a somewhat strange place. The doc string of 'eval' does mention the variables which control when the ellipsis is produced. > Following the `format-message' link, you still get no clue about this, > but you then follow a link for `format'. There you still get no clue > about it, but you see that %S uses `prin1'. > > Following the `prin1' link you finally find out that you can control > `message's use of ellipsis using `print-length' and `print-level'. > > Users shouldn't have to go through all of that (and that even assumes > that they are able to guess that following just that thread might get > them somewhere useful). > > What's true for `message' is also true for `error', etc. At least the > doc of `format' - and probably its often-used callers, such as `message' > - should specifically mention these "print"-controlling (really just > formatting) variables. I don't think it's reasonable to ask to have this low-level stuff bubble up to such high levels, which are quite far from the features which are affected by these variables. %S is not a frequently used format, so describing what prin1 does in the doc strings of 'message' etc. just for its sake doesn't seem like a good idea to me. OTOH, I'd expect users who use %S to know already about the ellipsis and how to control it. ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2019-12-26 17:49 UTC | newest] Thread overview: 9+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <<<<006e6244-dd0a-46a8-8c61-36744b3216de@default> [not found] ` <<<<83pngcv5ha.fsf@gnu.org> [not found] ` <<<32378b4e-d158-48d5-a48c-7afde59f5d32@default> [not found] ` <<<83d0ccuxoe.fsf@gnu.org> [not found] ` <<4a9b955a-ac97-41d9-a373-fc37b37581a4@default> [not found] ` <<838smzvk86.fsf@gnu.org> 2019-12-26 17:49 ` bug#38736: 26.3; ellipsis in `*Messages*', doc of `format' etc Drew Adams [not found] <<<006e6244-dd0a-46a8-8c61-36744b3216de@default> [not found] ` <<<83pngcv5ha.fsf@gnu.org> [not found] ` <<32378b4e-d158-48d5-a48c-7afde59f5d32@default> [not found] ` <<83d0ccuxoe.fsf@gnu.org> 2019-12-25 20:54 ` Drew Adams 2019-12-26 3:28 ` Eli Zaretskii [not found] <<006e6244-dd0a-46a8-8c61-36744b3216de@default> [not found] ` <<83pngcv5ha.fsf@gnu.org> 2019-12-25 16:44 ` Drew Adams 2019-12-25 17:23 ` Eli Zaretskii 2019-12-26 3:24 ` Michael Heerdegen 2019-12-26 16:23 ` Eli Zaretskii 2019-12-24 21:02 Drew Adams 2019-12-25 14:34 ` Eli Zaretskii
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.