Emacs documentation sources

Emacs documentation sources

[Dave Pawson]

http://www.emacswiki.org/cgi-bin/emacs-en/CategoryDocumentation

Collated from the comments on Steves' thread about 'revert'.

regards

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Re: Emacs documentation sources

[Eli Zaretskii]

> Date: Wed, 26 Sep 2007 09:04:57 +0100
> From: "Dave Pawson" <dave.pawson@gmail.com>
> 
> http://www.emacswiki.org/cgi-bin/emacs-en/CategoryDocumentation

IMO, it should describe much more Info-mode commands.  Without using
the manual, the Emacs help system is quite crippled, especially for
newbies.  Doc strings not always target newbies, because they cannot
be too wordy (due to considerations of memory footprint of the running
Emacs).

Re: Emacs documentation sources

[Sean Sieger]

From http://www.emacswiki.org/cgi-bin/emacs-en/CategoryDocumentation

`Emacs comes with ReferenceCards. Emacs is known as “the
SelfDocumenting” editor, though, so while the refcard can be useful, one
should learn to rely on InfoMode for most of the more complicated
features of this editor.'

Isn't the self-documenting attribute demostrated by the documentation
written into the elisp code and displayed with `C-h m', rather than
something to do with info?

Re: Emacs documentation sources

[Richard G Riley]

Sean Sieger <sean.sieger@gmail.com> writes:

> From http://www.emacswiki.org/cgi-bin/emacs-en/CategoryDocumentation
>
> `Emacs comes with ReferenceCards. Emacs is known as “the
> SelfDocumenting” editor, though, so while the refcard can be useful, one
> should learn to rely on InfoMode for most of the more complicated
> features of this editor.'
>
> Isn't the self-documenting attribute demostrated by the documentation
> written into the elisp code and displayed with `C-h m', rather than
> something to do with info?

I've often thought it a pity that there is no, apparent, link from the
function docs back to the relevant sections of potentially helpful Info
files. Or?

RE: Emacs documentation sources

[Drew Adams]

> I've often thought it a pity that there is no, apparent, link from the
> function docs back to the relevant sections of potentially helpful Info
> files. Or?

AFAIK, there are not usually links in the *Help* buffer for a function or variable to the relevant portions of the manual. Instead, the links there take you to the source-code definitions.

There is, however, `C-h F', at least; it takes you to the manual section for an Emacs command (but not for a non-interactive function).

I also proposed that the link on a function etc. name in an *Apropos* buffer take you to the relevant manual page - the link on its `Function' etc. field would still take you to the doc string (*Help*). This was accepted, though that doesn't necessarily mean it will be implemented. 

Re: Emacs documentation sources

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Wed, 26 Sep 2007 09:04:57 +0100
>> From: "Dave Pawson" <dave.pawson@gmail.com>
>> 
>> http://www.emacswiki.org/cgi-bin/emacs-en/CategoryDocumentation
>
> IMO, it should describe much more Info-mode commands.  Without using
> the manual, the Emacs help system is quite crippled, especially for
> newbies.  Doc strings not always target newbies, because they cannot
> be too wordy (due to considerations of memory footprint of the running
> Emacs).

Uh what?  Doc strings are not placed in the memory of Emacs except for
those of uncompiled Lisp code.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs documentation sources

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Wed, 26 Sep 2007 21:53:00 +0200
> 
> Uh what?  Doc strings are not placed in the memory of Emacs except for
> those of uncompiled Lisp code.

You mean, when I'm looking at a buffer that displays the doc string of
something, that doc string is not in memory?

Re: Emacs documentation sources

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Kastrup <dak@gnu.org>
>> Date: Wed, 26 Sep 2007 21:53:00 +0200
>> 
>> Uh what?  Doc strings are not placed in the memory of Emacs except for
>> those of uncompiled Lisp code.
>
> You mean, when I'm looking at a buffer that displays the doc string of
> something, that doc string is not in memory?

Only as long as the help buffer persists with this content.  Do you
really claim the ephemeral size of the help buffer to be an important
consideration concerning the size of DOC strings?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs documentation sources

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Thu, 27 Sep 2007 08:17:13 +0200
> 
> Do you really claim the ephemeral size of the help buffer to be an
> important consideration concerning the size of DOC strings?

Do you really claim that the size of DOC strings is of no concern at
all?

Re: Emacs documentation sources

[Thien-Thi Nguyen]

() Richard G Riley <rileyrgdev@googlemail.com>
() Wed, 26 Sep 2007 20:07:14 +0200

   there is no, apparent, link [...] Or?

(defun foo ()
  "Return 42.  See info node `(emacs)'."
  42)

(describe-function 'foo)

it is apparent if you make it apparent.

thi

Re: Emacs documentation sources

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Kastrup <dak@gnu.org>
>> Date: Thu, 27 Sep 2007 08:17:13 +0200
>> 
>> Do you really claim the ephemeral size of the help buffer to be an
>> important consideration concerning the size of DOC strings?
>
> Do you really claim that the size of DOC strings is of no concern at
> all?

Since they reside in the .elc files and/or the DOC file and are only
ever loaded into memory temporarily when they are actually consulted,
they take up only disk space, not main memory.  Just like the manual.

So yes, I disagree with the following claim of you that you made in
the thread and seemingly already forgot:

    Doc strings not always target newbies, because they cannot be too
    wordy (due to considerations of memory footprint of the running
    Emacs).

The memory footprint of the running Emacs is not affected by DOC
strings since DOC strings from byte-compiled or preloaded files are
not kept in memory.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs documentation sources

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Thu, 27 Sep 2007 22:17:40 +0200
> 
> > Do you really claim that the size of DOC strings is of no concern at
> > all?
> 
> Since they reside in the .elc files and/or the DOC file and are only
> ever loaded into memory temporarily when they are actually consulted,
> they take up only disk space, not main memory.  Just like the manual.

Perhaps you should re-read th relevant sources before you make such
assertions.  What I see there is that each displayed doc string is
kept in memory twice, and it remains in memory until the next GC.

So, temporary or not, the doc strings do in fact occupy memory for
more than a split second.

Re: Emacs documentation sources

[Stefan Monnier]

>> Do you really claim the ephemeral size of the help buffer to be an
>> important consideration concerning the size of DOC strings?

> Do you really claim that the size of DOC strings is of no concern at
> all?

Yes.


        Stefan

Re: Emacs documentation sources

[Stefan Monnier]

>> > Do you really claim that the size of DOC strings is of no concern at
>> > all?
>> 
>> Since they reside in the .elc files and/or the DOC file and are only
>> ever loaded into memory temporarily when they are actually consulted,
>> they take up only disk space, not main memory.  Just like the manual.

> Perhaps you should re-read th relevant sources before you make such
> assertions.  What I see there is that each displayed doc string is
> kept in memory twice, and it remains in memory until the next GC.

> So, temporary or not, the doc strings do in fact occupy memory for
> more than a split second.

Absolutely negligible.  If you add 10KB to a docstring (i.e. a *lot* more
text), that will add in the order of 10-20KB to the Emacs process on the
conditions that the user has looked at that docstring.  I.e. it will bump
the process's size from maybe 10MB to 10.02MB.  If you add 10KB to each and
every docstring ever written, then the process size will grow by about 10KB
times the number of docstring viewed in *Help*.
Absolutely negligible.


        Stefan

Re: Emacs documentation sources

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Kastrup <dak@gnu.org>
>> Date: Thu, 27 Sep 2007 22:17:40 +0200
>> 
>> > Do you really claim that the size of DOC strings is of no concern at
>> > all?
>> 
>> Since they reside in the .elc files and/or the DOC file and are only
>> ever loaded into memory temporarily when they are actually consulted,
>> they take up only disk space, not main memory.  Just like the manual.
>
> Perhaps you should re-read th relevant sources before you make such
> assertions.  What I see there is that each displayed doc string is
> kept in memory twice, and it remains in memory until the next GC.
>
> So, temporary or not, the doc strings do in fact occupy memory for
> more than a split second.

"occupy" is the wrong word for something that goes away on garbage
collection.  _Everything_ in Emacs touches memory until it gets
collected.  But DOC strings are not even loaded _until_ you look at
them explicitly.

So your claim that DOC strings have to be kept terse for memory
conversation reasons is plain and unadulterated nonsense.  And this
utterly silly smokescreen followup thread (where you, quite prudently,
snip out the original _relevant_ wrong claim of yours time and again
in order to argue some less embarrassing points) does not change that.

We might as well call it quits.

Again, here is your quote which started this:

    Doc strings not always target newbies, because they cannot be too
    wordy (due to considerations of memory footprint of the running
    Emacs).

Please don't omit this quote if you feel you want to continue to
pretend defending it.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs documentation sources

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: Sat, 29 Sep 2007 01:13:21 +0200
> 
> But DOC strings are not even loaded _until_ you look at
> them explicitly.

You seem to forget about the `apropos-*' commands (which were the
reason for this thread in the first place).

> So your claim that DOC strings have to be kept terse for memory
> conversation reasons is plain and unadulterated nonsense.  And this
> utterly silly smokescreen followup thread (where you, quite prudently,
> snip out the original _relevant_ wrong claim of yours time and again
> in order to argue some less embarrassing points) does not change that.

I admire your argument culture and style, David.

> Again, here is your quote which started this:
> 
>     Doc strings not always target newbies, because they cannot be too
>     wordy (due to considerations of memory footprint of the running
>     Emacs).
> 
> Please don't omit this quote if you feel you want to continue to
> pretend defending it.

Done.

Re: Emacs documentation sources

[David Kastrup]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: David Kastrup <dak@gnu.org>
>> Date: Sat, 29 Sep 2007 01:13:21 +0200
>> 
>> But DOC strings are not even loaded _until_ you look at
>> them explicitly.
>
> You seem to forget about the `apropos-*' commands (which were the
> reason for this thread in the first place).

The only apropos command that gets possibly involved here is C-u C-h
d, namely apropos-documentation with DO-ALL set.  And then the _size_
of the docs strings is mostly irrelevant, the performance is impacted
by the _number_ of them.

>> So your claim that DOC strings have to be kept terse for memory
>> conversation reasons is plain and unadulterated nonsense.  And this
>> utterly silly smokescreen followup thread (where you, quite
>> prudently, snip out the original _relevant_ wrong claim of yours
>> time and again in order to argue some less embarrassing points)
>> does not change that.
>
> I admire your argument culture and style, David.

Sorry for calling your game.

>> Again, here is your quote which started this:
>> 
>>     Doc strings not always target newbies, because they cannot be too
>>     wordy (due to considerations of memory footprint of the running
>>     Emacs).
>> 
>> Please don't omit this quote if you feel you want to continue to
>> pretend defending it.
>
> Done.

Fine.  Now is there anybody except Eli that would thing it likely that
DOC strings are necessary because of the memory footprint of the
running Emacs?

While the memory footprint of the running Emacs is presumably not
affected by a non-terse manual?

At the current point of time, this argument is just specious.  In the
long long history of Emacs, there has been a time indeed when DOC
strings were stored in memory (rather than passed through temporarily
on demand).  To stop this from being a possible concern, they have
been externalized to disk files.  Likely somewhere in the Emacs 18.*
series.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Emacs documentation sources

[Juanma Barranquero]

On 9/29/07, David Kastrup <dak@gnu.org> wrote:

> Sorry for calling your game.

At which point you stopped reading the thread and started reading
Eli's mind? I ask because the comment Eli was replying to is about
Eli's motivations, not his arguments.

FWIW (not much, I suppose), I think that's unfair and uncalled for.

             Juanma