Re: Info documentation does not match Help documentation

[Eli Zaretskii]

> From: Raffaele Ricciardi <rfflrccrd@gmail.com>
> Date: Thu, 16 Aug 2012 22:24:17 +0100
> 
> Thank you for the explanation.  In my opinion, this leads to more work than
> necessary for the maintainers.

That is true, but there are good reasons for this additional work.

> It leads to more work for users, too, for they may have to read two
> versions of mostly the same documentation

That's not how you are supposed to use these two documentation
sources.  The manual should be read whenever you want to use, or
consider using, an API or command, or a family of those, the first
time, and want to get the initial overview and the overall context of
the features you are about to use.  Reading the manual will give you
more in-depth description, understanding, and links to other related
features than the doc string ever can.

By contrast, the doc strings describe specifically the one symbol
they are tied to.  They cannot be too long (because they are part of
the executable's memory footprint), and a series of doc strings can
never tell a consistent story like the manual does.

So read the manual the first time, then use doc strings, and return to
the manual only if the doc string does not provide some minor detail
or broader picture.

> Duplication is evil, isn't it? ;-)

Yes, but this one isn't a duplication.