Info documentation does not match Help documentation

Info documentation does not match Help documentation

[Raffaele Ricciardi]

Hello there,

I've noticed that the documentation for a symbol in Info mode doesn't 
match the
documentation for the same symbol in Help mode.  I expected both 
documentations
to be the documentation string of the symbol.  Am I missing something?

Compare for instance:

C-h S define-minor-mode RET

With:

C-h f define-minor-mode RET

Or try the same for `thing-at-point'.

Re: Info documentation does not match Help documentation

[Eli Zaretskii]

> From: Raffaele Ricciardi <rfflrccrd@gmail.com>
> Date: Thu, 16 Aug 2012 18:52:42 +0100
> 
> I've noticed that the documentation for a symbol in Info mode
> doesn't match the documentation for the same symbol in Help mode.  I
> expected both documentations to be the documentation string of the
> symbol.  Am I missing something?

The text you see doesn't have to be identical, as it comes from two
different places and serves different purposes.  "C-h S" brings the
relevant section from the manual, which describes the topic in more
detail.  By contrast, the doc string comes from the code itself, and
is a concise description of the symbol, and it alone.

The information should be similar and consistent, though.  If you spot
any inconsistencies, please report them as bugs using "M-x
report-emacs-bug".

Re: Info documentation does not match Help documentation

[Raffaele Ricciardi]

On 08/16/2012 08:55 PM, Eli Zaretskii wrote:
 >> From: Raffaele Ricciardi <rfflrccrd@gmail.com>
 >> Date: Thu, 16 Aug 2012 18:52:42 +0100
 >>
 >> I've noticed that the documentation for a symbol in Info mode
 >> doesn't match the documentation for the same symbol in Help mode.  I
 >> expected both documentations to be the documentation string of the
 >> symbol.  Am I missing something?
 >
 > The text you see doesn't have to be identical, as it comes from two
 > different places and serves different purposes.  "C-h S" brings the
 > relevant section from the manual, which describes the topic in more
 > detail.  By contrast, the doc string comes from the code itself, and
 > is a concise description of the symbol, and it alone.
 >
 > The information should be similar and consistent, though.  If you spot
 > any inconsistencies, please report them as bugs using "M-x
 > report-emacs-bug".
 >

Thank you for the explanation.  In my opinion, this leads to more work than
necessary for the maintainers.  It leads to more work for users, too, 
for they
may have to read two versions of mostly the same documentation, or they may
resolve - as I've done - to always look into the Info documentation when
available, in case they might be missing something.  Duplication is 
evil, isn't
it? ;-)

Re: Info documentation does not match Help documentation

[drain]

If you've altered the source code, or customized your inits extensively,
you'll want help and info to spit out contrasting data.

The highest-frequency place of conflict will likely be the key bindings. If
I lookup forward-char with help, I will be given my custom definition; but
if I look it up with info, I will be given the default. This discrepancy is
useful: it reminds me what I have altered the program from and to.





--
View this message in context: http://emacs.1067599.n5.nabble.com/Info-documentation-does-not-match-Help-documentation-tp261635p261644.html
Sent from the Emacs - Help mailing list archive at Nabble.com.

Re: Info documentation does not match Help documentation

[Raffaele Ricciardi]

On 08/16/2012 10:40 PM, drain wrote:
 > If you've altered the source code, or customized your inits extensively,
 > you'll want help and info to spit out contrasting data.
 >
 > The highest-frequency place of conflict will likely be the key 
bindings. If
 > I lookup forward-char with help, I will be given my custom 
definition; but
 > if I look it up with info, I will be given the default. This 
discrepancy is
 > useful: it reminds me what I have altered the program from and to.

Actually, I wasn't thinking about Info and Help drawing from the same 
source.
This cannot be done, as Help draws from the compiled code, whilst Info draws
from the manuals, and as your example shows, they must be kept separate 
anyway,
and the Info manual pristine.

I was thinking about both documentations being maintained in a single place.
Then, some sort of preprocessing would replicate it from one source to the
other.

Maybe things started the way they are now to save memory at runtime, and 
memory
may still be a scarce resource on some platforms supported by Emacs.

RE: Info documentation does not match Help documentation

[Drew Adams]

> > I've noticed that the documentation for a symbol in Info mode
> > doesn't match the documentation for the same symbol in Help mode.  I
> > expected both documentations to be the documentation string of the
> > symbol.  Am I missing something?
> 
> The text you see doesn't have to be identical, as it comes from two
> different places and serves different purposes.  "C-h S" brings the
> relevant section from the manual, which describes the topic in more
> detail.  By contrast, the doc string comes from the code itself, and
> is a concise description of the symbol, and it alone.
> 
> The information should be similar and consistent, though.  If you spot
> any inconsistencies, please report them as bugs using "M-x
> report-emacs-bug".

+1 for what Eli said.  I would add that the description in the manual can also
be different because it is in a particular context.  It is typically surrounded
by text that provides more background and puts it in relation with other things.

A manual, even a purely reference manual (and the Elisp manual is part
reference, part user guide), is not just a list of APIs with no explanation.  At
the very least, it groups related APIs together.  That provides helpful context
that is not available in a doc string.

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.