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

From: "Drew Adams" <[email-masked]>
Date: Sun, 10 Jul 2011 11:30:59 -0700

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