all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Info documentation does not match Help documentation
@ 2012-08-16 17:52 Raffaele Ricciardi
  2012-08-16 19:55 ` Eli Zaretskii
       [not found] ` <mailman.7120.1345146916.855.help-gnu-emacs@gnu.org>
  0 siblings, 2 replies; 7+ messages in thread
From: Raffaele Ricciardi @ 2012-08-16 17:52 UTC (permalink / raw)
  To: help-gnu-emacs

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


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Info documentation does not match Help documentation
  2012-08-16 17:52 Info documentation does not match Help documentation Raffaele Ricciardi
@ 2012-08-16 19:55 ` Eli Zaretskii
  2012-08-17  0:51   ` Drew Adams
       [not found] ` <mailman.7120.1345146916.855.help-gnu-emacs@gnu.org>
  1 sibling, 1 reply; 7+ messages in thread
From: Eli Zaretskii @ 2012-08-16 19:55 UTC (permalink / raw)
  To: help-gnu-emacs

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



^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Info documentation does not match Help documentation
       [not found] ` <mailman.7120.1345146916.855.help-gnu-emacs@gnu.org>
@ 2012-08-16 21:24   ` Raffaele Ricciardi
  2012-08-16 21:40     ` drain
                       ` (2 more replies)
  0 siblings, 3 replies; 7+ messages in thread
From: Raffaele Ricciardi @ 2012-08-16 21:24 UTC (permalink / raw)
  To: help-gnu-emacs

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? ;-)


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Info documentation does not match Help documentation
  2012-08-16 21:24   ` Raffaele Ricciardi
@ 2012-08-16 21:40     ` drain
       [not found]     ` <mailman.7125.1345153237.855.help-gnu-emacs@gnu.org>
  2012-08-17  6:39     ` Eli Zaretskii
  2 siblings, 0 replies; 7+ messages in thread
From: drain @ 2012-08-16 21:40 UTC (permalink / raw)
  To: Help-gnu-emacs

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.



^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Info documentation does not match Help documentation
       [not found]     ` <mailman.7125.1345153237.855.help-gnu-emacs@gnu.org>
@ 2012-08-16 22:28       ` Raffaele Ricciardi
  0 siblings, 0 replies; 7+ messages in thread
From: Raffaele Ricciardi @ 2012-08-16 22:28 UTC (permalink / raw)
  To: help-gnu-emacs

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.


^ permalink raw reply	[flat|nested] 7+ messages in thread

* RE: Info documentation does not match Help documentation
  2012-08-16 19:55 ` Eli Zaretskii
@ 2012-08-17  0:51   ` Drew Adams
  0 siblings, 0 replies; 7+ messages in thread
From: Drew Adams @ 2012-08-17  0:51 UTC (permalink / raw)
  To: 'Eli Zaretskii', help-gnu-emacs


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




^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Info documentation does not match Help documentation
  2012-08-16 21:24   ` Raffaele Ricciardi
  2012-08-16 21:40     ` drain
       [not found]     ` <mailman.7125.1345153237.855.help-gnu-emacs@gnu.org>
@ 2012-08-17  6:39     ` Eli Zaretskii
  2 siblings, 0 replies; 7+ messages in thread
From: Eli Zaretskii @ 2012-08-17  6:39 UTC (permalink / raw)
  To: help-gnu-emacs

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



^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2012-08-17  6:39 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-08-16 17:52 Info documentation does not match Help documentation Raffaele Ricciardi
2012-08-16 19:55 ` Eli Zaretskii
2012-08-17  0:51   ` Drew Adams
     [not found] ` <mailman.7120.1345146916.855.help-gnu-emacs@gnu.org>
2012-08-16 21:24   ` Raffaele Ricciardi
2012-08-16 21:40     ` drain
     [not found]     ` <mailman.7125.1345153237.855.help-gnu-emacs@gnu.org>
2012-08-16 22:28       ` Raffaele Ricciardi
2012-08-17  6:39     ` Eli Zaretskii

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.