bug#1947: 23.0.60; Please document use of `dired' with an explicit file list

bug#1947: 23.0.60; Please document use of `dired' with an explicit file list

[Drew Adams]

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'
 

bug#1947: 23.0.60; Please document use of `dired' with an explicit file list

[Kevin Rodgers]

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

bug#1947: 23.0.60; Please document use of `dired' with an explicit file list

[Lars Magne Ingebrigtsen]

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/

bug#1947: 23.0.60; Please document use of `dired' with an explicit file list

[Drew Adams]

> > 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.

bug#1947: 23.0.60; Please document use of `dired' with an explicit file list

[Eli Zaretskii]

> 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.

bug#1947: 23.0.60; Please document use of `dired' with an explicit file list

[Drew Adams]

> > 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.

bug#1947: 23.0.60; Please document use of `dired' with an explicit file list

[Eli Zaretskii]

> 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...

bug#1947: 23.0.60; Please document use of `dired' with an explicit file list

[Drew Adams]

> > 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.