* bug#1947: 23.0.60; Please document use of `dired' with an explicit file list @ 2009-01-18 18:44 Drew Adams 2009-01-20 3:20 ` Kevin Rodgers 0 siblings, 1 reply; 8+ messages in thread From: Drew Adams @ 2009-01-18 18:44 UTC (permalink / raw) To: emacs-pretest-bug As far as I can tell, the use of `dired' with an explicit list of file and directory names is undocumented (beyond the source code). It is mentioned in neither the Emacs manual nor the Elisp manual. This is a useful feature - at least as useful as many of the other Dired features that are documented. Questions about being able to open Dired with an explicit list of files from different directories are asked from time to time on help-gnu-emacs. The logical place to document this is in the Emacs manual, node `Dired Enter'. That's so, even though to use this feature you must have a list of file names. A simple example using `defvar' or `setq' to define such a list would be sufficient - there are similar simple uses of Emacs Lisp in the Emacs manual. In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600) of 2009-01-04 on LENNART-69DE564 Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include -fno-crossjumping' ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#1947: 23.0.60; Please document use of `dired' with an explicit file list 2009-01-18 18:44 bug#1947: 23.0.60; Please document use of `dired' with an explicit file list Drew Adams @ 2009-01-20 3:20 ` Kevin Rodgers 2011-07-10 14:58 ` Lars Magne Ingebrigtsen 0 siblings, 1 reply; 8+ messages in thread From: Kevin Rodgers @ 2009-01-20 3:20 UTC (permalink / raw) To: bug-gnu-emacs; +Cc: emacs-pretest-bug Drew Adams wrote: > As far as I can tell, the use of `dired' with an explicit list of file > and directory names is undocumented (beyond the source code). It is > mentioned in neither the Emacs manual nor the Elisp manual. > > This is a useful feature - at least as useful as many of the other > Dired features that are documented. Questions about being able to > open Dired with an explicit list of files from different directories > are asked from time to time on help-gnu-emacs. > > The logical place to document this is in the Emacs manual, node `Dired > Enter'. That's so, even though to use this feature you must have a > list of file names. A simple example using `defvar' or `setq' to > define such a list would be sufficient - there are similar simple uses > of Emacs Lisp in the Emacs manual. It is explained in dired's doc string. Since the only way to use this feature is via Lisp (not M-x), I think the Emacs Lisp manual would be a better place to document it. -- Kevin Rodgers Denver, Colorado, USA ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#1947: 23.0.60; Please document use of `dired' with an explicit file list 2009-01-20 3:20 ` Kevin Rodgers @ 2011-07-10 14:58 ` Lars Magne Ingebrigtsen 2011-07-10 17:36 ` Drew Adams 0 siblings, 1 reply; 8+ messages in thread From: Lars Magne Ingebrigtsen @ 2011-07-10 14:58 UTC (permalink / raw) To: Kevin Rodgers; +Cc: 1947 Kevin Rodgers <kevin.d.rodgers@gmail.com> writes: > It is explained in dired's doc string. Since the only way to use this > feature is via Lisp (not M-x), I think the Emacs Lisp manual would be a > better place to document it. However, the Emacs Lisp manual doesn't document dired at all, so I think the current solution is best -- leave the documentation in the doc string of the `dired' command. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#1947: 23.0.60; Please document use of `dired' with an explicit file list 2011-07-10 14:58 ` Lars Magne Ingebrigtsen @ 2011-07-10 17:36 ` Drew Adams 2011-07-10 17:47 ` Eli Zaretskii 0 siblings, 1 reply; 8+ messages in thread From: Drew Adams @ 2011-07-10 17:36 UTC (permalink / raw) To: 'Lars Magne Ingebrigtsen', 'Kevin Rodgers'; +Cc: 1947 > > It is explained in dired's doc string. Since the only way > > to use this feature is via Lisp (not M-x), I think the Emacs Lisp > > manual would be a better place to document it. > > However, the Emacs Lisp manual doesn't document dired at all, > so I think the current solution is best -- leave the > documentation in the doc string of the `dired' command. No, that does not address the bug report at all. The goal should be to improve Emacs for users, not simply to close bugs willy nilly without addressing them. This should be documented in the _Emacs_ manual. Not everything that requires a little Emacs Lisp is relegated to the Elisp manual. This is something that ordinary users should be made aware of. Simply mentioning it in the doc string of `dired' is not sufficient. Time has proven this to be the case. Although this is a very useful and very easy to use feature, few users are aware of it. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#1947: 23.0.60; Please document use of `dired' with an explicit file list 2011-07-10 17:36 ` Drew Adams @ 2011-07-10 17:47 ` Eli Zaretskii 2011-07-10 18:30 ` Drew Adams 0 siblings, 1 reply; 8+ messages in thread From: Eli Zaretskii @ 2011-07-10 17:47 UTC (permalink / raw) To: Drew Adams; +Cc: larsi, kevin.d.rodgers, 1947 > From: "Drew Adams" <drew.adams@oracle.com> > Date: Sun, 10 Jul 2011 10:36:33 -0700 > Cc: 1947@debbugs.gnu.org > > This is something that ordinary users should be made aware of. Simply > mentioning it in the doc string of `dired' is not sufficient. I disagree. Users are supposed to read _both_ doc strings and the manual. Therefore, something mentioned in the doc string does not necessarily has to be described in the manual as well, especially if it's an obscure feature used in special situations. The manual is for describing things better, in more easily readable form, without restrictions of doc string format. But it doesn't have to tell everything. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#1947: 23.0.60; Please document use of `dired' with an explicit file list 2011-07-10 17:47 ` Eli Zaretskii @ 2011-07-10 18:30 ` Drew Adams 2011-07-10 18:44 ` Eli Zaretskii 0 siblings, 1 reply; 8+ messages in thread From: Drew Adams @ 2011-07-10 18:30 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: larsi, kevin.d.rodgers, 1947 > > This is something that ordinary users should be made aware > > of. Simply mentioning it in the doc string of `dired' is > > not sufficient. > > I disagree. Users are supposed to read _both_ doc strings and the > manual. Therefore, something mentioned in the doc string does not > necessarily has to be described in the manual as well, Irrelevant: * No one said anything about what users are "supposed to do". * No one argued that either doc strings or the manual is a substitute for the other. * No one said that everything that is mentioned in any doc string "necessarily" needs to be described also in the manual. Your arguments are facile, but you are arguing against a straw man. It's about _this_ particular feature, whose description, in passing, in the `dired' doc string has proven to be insufficient to make users aware of this very useful feature. > especially if it's an obscure feature used in special situations. Not relevant here. This is a very useful, although relatively unknown, feature. This feature is not obscure by its nature; it is simply not known well enough. This bug report is about obviating some of that ignorance. > The manual is for describing things better, in more easily readable > form, without restrictions of doc string format. But it doesn't have > to tell everything. Irrelevant; straw man. No one said the manual has "to tell everything". Speak not in useless generalities, please. Speak to _this_ bug report; speak about the documentation of _this_ Dired feature. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#1947: 23.0.60; Please document use of `dired' with an explicit file list 2011-07-10 18:30 ` Drew Adams @ 2011-07-10 18:44 ` Eli Zaretskii 2011-07-10 20:07 ` Drew Adams 0 siblings, 1 reply; 8+ messages in thread From: Eli Zaretskii @ 2011-07-10 18:44 UTC (permalink / raw) To: Drew Adams; +Cc: larsi, kevin.d.rodgers, 1947 > From: "Drew Adams" <drew.adams@oracle.com> > Cc: <larsi@gnus.org>, <kevin.d.rodgers@gmail.com>, <1947@debbugs.gnu.org> > Date: Sun, 10 Jul 2011 11:30:59 -0700 > > Your arguments are facile, but you are arguing against a straw man. > [...] > Speak not in useless generalities, please. Abusive as usual... ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#1947: 23.0.60; Please document use of `dired' with an explicit file list 2011-07-10 18:44 ` Eli Zaretskii @ 2011-07-10 20:07 ` Drew Adams 0 siblings, 0 replies; 8+ messages in thread From: Drew Adams @ 2011-07-10 20:07 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: larsi, kevin.d.rodgers, 1947 > > you are arguing against a straw man.... > > Speak not in useless generalities, please. > > Abusive as usual... You are making an ad hominem attack. Arguments about the bug report, please. I'm sorry if you take offense, but pointing out that your argument was an unhelpful generality unrelated to the bug report or to any of the arguments advanced to support it is _not_ abuse. Perhaps you really thought that I argued that everything in every doc string must also be in the manual. But I doubt it. You've said similar things before (over and over, in fact), and each time I've pointed out that I haven't made such a claim. I think you know full well by now that this is a straw man argument you're erecting. But whether you recognized it before or not, please recognize now that I did not argue any such thing, and that your countering such a nonexistent claim is irrelevant, distracting, and unhelpful. Yes, not everything in every doc string belongs also in the manual. So what? What about _this_ particular feature? You might not like having it pointed out that your argument does not address the issue, but pointing that out is neither ad hominem nor irrelevant. It's trying to get back on track, to this particular issue. I'm sorry if you feel hurt or angry. Please relax. Try not to be so personally close to your arguments. It's not about you, or me; there is nothing personal here. We all make irrelevant arguments sometimes. Let's keep the discussion on track: it's about the bug report. Give some arguments why this particular feature should not be documented in the manual, please. We should all be trying to help the users here; that's all. We have 20 (!) nodes in the Emacs manual about Dired. I feel that this relatively unknown feature is an important (useful) Dired feature, worth pointing out somewhere among those 20 sections. If someone wants to learn about particular Dired features (there are many), s?he will not necessarily consult only the `dired' doc string. S?he will sometimes consult the manual first, or instead. You say that users "are supposed to" consult both. Fine, but a user will not necessarily look to the doc string for info about particular Dired features - and if s?he does s?he will be quite disappointed in general. Not to mention that users do not always do what you might think they are "supposed to" do. It's about helping users get information that we think could be useful to them. I think this particular info is very useful - and not at all obvious. You are free to disagree, and that's where I would like to see arguments. Let us know why this info is not something we should be communicating better. ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2011-07-10 20:07 UTC | newest] Thread overview: 8+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2009-01-18 18:44 bug#1947: 23.0.60; Please document use of `dired' with an explicit file list Drew Adams 2009-01-20 3:20 ` Kevin Rodgers 2011-07-10 14:58 ` Lars Magne Ingebrigtsen 2011-07-10 17:36 ` Drew Adams 2011-07-10 17:47 ` Eli Zaretskii 2011-07-10 18:30 ` Drew Adams 2011-07-10 18:44 ` Eli Zaretskii 2011-07-10 20:07 ` Drew Adams
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).