unofficial mirror of help-gnu-emacs@gnu.org
 help / color / mirror / Atom feed
* Emacs documentation sources
@ 2007-09-26  8:04 Dave Pawson
  2007-09-26  9:23 ` Eli Zaretskii
                   ` (3 more replies)
  0 siblings, 4 replies; 18+ messages in thread
From: Dave Pawson @ 2007-09-26  8:04 UTC (permalink / raw)
  To: emac list

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

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

* Re: Emacs documentation sources
  2007-09-26  8:04 Emacs documentation sources Dave Pawson
@ 2007-09-26  9:23 ` Eli Zaretskii
  2007-09-26 17:43 ` Sean Sieger
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 18+ messages in thread
From: Eli Zaretskii @ 2007-09-26  9:23 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
  2007-09-26  8:04 Emacs documentation sources Dave Pawson
  2007-09-26  9:23 ` Eli Zaretskii
@ 2007-09-26 17:43 ` Sean Sieger
       [not found] ` <mailman.1329.1190828635.18990.help-gnu-emacs@gnu.org>
       [not found] ` <mailman.1306.1190798609.18990.help-gnu-emacs@gnu.org>
  3 siblings, 0 replies; 18+ messages in thread
From: Sean Sieger @ 2007-09-26 17:43 UTC (permalink / raw)
  To: help-gnu-emacs

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?

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

* Re: Emacs documentation sources
       [not found] ` <mailman.1329.1190828635.18990.help-gnu-emacs@gnu.org>
@ 2007-09-26 18:07   ` Richard G Riley
  2007-09-26 18:55     ` Drew Adams
  2007-09-27  8:44     ` Thien-Thi Nguyen
  0 siblings, 2 replies; 18+ messages in thread
From: Richard G Riley @ 2007-09-26 18:07 UTC (permalink / raw)
  To: help-gnu-emacs

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?

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

* RE: Emacs documentation sources
  2007-09-26 18:07   ` Richard G Riley
@ 2007-09-26 18:55     ` Drew Adams
  2007-09-27  8:44     ` Thien-Thi Nguyen
  1 sibling, 0 replies; 18+ messages in thread
From: Drew Adams @ 2007-09-26 18:55 UTC (permalink / raw)
  To: Richard G Riley, help-gnu-emacs

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

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

* Re: Emacs documentation sources
       [not found] ` <mailman.1306.1190798609.18990.help-gnu-emacs@gnu.org>
@ 2007-09-26 19:53   ` David Kastrup
  2007-09-26 21:18     ` Eli Zaretskii
       [not found]     ` <mailman.1354.1190841494.18990.help-gnu-emacs@gnu.org>
  0 siblings, 2 replies; 18+ messages in thread
From: David Kastrup @ 2007-09-26 19:53 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
  2007-09-26 19:53   ` David Kastrup
@ 2007-09-26 21:18     ` Eli Zaretskii
       [not found]     ` <mailman.1354.1190841494.18990.help-gnu-emacs@gnu.org>
  1 sibling, 0 replies; 18+ messages in thread
From: Eli Zaretskii @ 2007-09-26 21:18 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
       [not found]     ` <mailman.1354.1190841494.18990.help-gnu-emacs@gnu.org>
@ 2007-09-27  6:17       ` David Kastrup
  2007-09-27  7:59         ` Eli Zaretskii
                           ` (2 more replies)
  0 siblings, 3 replies; 18+ messages in thread
From: David Kastrup @ 2007-09-27  6:17 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
  2007-09-27  6:17       ` David Kastrup
@ 2007-09-27  7:59         ` Eli Zaretskii
       [not found]         ` <mailma\x04n.1375.1190879967.18990.help-gnu-emacs@gnu.org>
       [not found]         ` <mailman.1375.1190879967.18990.help-gnu-emacs@gnu.org>
  2 siblings, 0 replies; 18+ messages in thread
From: Eli Zaretskii @ 2007-09-27  7:59 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
  2007-09-26 18:07   ` Richard G Riley
  2007-09-26 18:55     ` Drew Adams
@ 2007-09-27  8:44     ` Thien-Thi Nguyen
  1 sibling, 0 replies; 18+ messages in thread
From: Thien-Thi Nguyen @ 2007-09-27  8:44 UTC (permalink / raw)
  To: help-gnu-emacs

() 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

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

* Re: Emacs documentation sources
       [not found]         ` <mailma\x04n.1375.1190879967.18990.help-gnu-emacs@gnu.org>
@ 2007-09-27 20:17           ` David Kastrup
  2007-09-28  8:13             ` Eli Zaretskii
       [not found]             ` <mailman.1419.1190967231.18990.help-gnu-emacs@gnu.org>
  0 siblings, 2 replies; 18+ messages in thread
From: David Kastrup @ 2007-09-27 20:17 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
  2007-09-27 20:17           ` David Kastrup
@ 2007-09-28  8:13             ` Eli Zaretskii
       [not found]             ` <mailman.1419.1190967231.18990.help-gnu-emacs@gnu.org>
  1 sibling, 0 replies; 18+ messages in thread
From: Eli Zaretskii @ 2007-09-28  8:13 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
       [not found]         ` <mailman.1375.1190879967.18990.help-gnu-emacs@gnu.org>
@ 2007-09-28 15:31           ` Stefan Monnier
  0 siblings, 0 replies; 18+ messages in thread
From: Stefan Monnier @ 2007-09-28 15:31 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
       [not found]             ` <mailman.1419.1190967231.18990.help-gnu-emacs@gnu.org>
@ 2007-09-28 15:36               ` Stefan Monnier
  2007-09-28 23:13               ` David Kastrup
  1 sibling, 0 replies; 18+ messages in thread
From: Stefan Monnier @ 2007-09-28 15:36 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
       [not found]             ` <mailman.1419.1190967231.18990.help-gnu-emacs@gnu.org>
  2007-09-28 15:36               ` Stefan Monnier
@ 2007-09-28 23:13               ` David Kastrup
  2007-09-29 16:19                 ` Eli Zaretskii
       [not found]                 ` <mailman.1475.1191082767.18990.help-gnu-emacs@gnu.org>
  1 sibling, 2 replies; 18+ messages in thread
From: David Kastrup @ 2007-09-28 23:13 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
  2007-09-28 23:13               ` David Kastrup
@ 2007-09-29 16:19                 ` Eli Zaretskii
       [not found]                 ` <mailman.1475.1191082767.18990.help-gnu-emacs@gnu.org>
  1 sibling, 0 replies; 18+ messages in thread
From: Eli Zaretskii @ 2007-09-29 16:19 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
       [not found]                 ` <mailman.1475.1191082767.18990.help-gnu-emacs@gnu.org>
@ 2007-09-29 17:00                   ` David Kastrup
  2007-09-29 19:09                     ` Juanma Barranquero
  0 siblings, 1 reply; 18+ messages in thread
From: David Kastrup @ 2007-09-29 17:00 UTC (permalink / raw)
  To: help-gnu-emacs

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

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

* Re: Emacs documentation sources
  2007-09-29 17:00                   ` David Kastrup
@ 2007-09-29 19:09                     ` Juanma Barranquero
  0 siblings, 0 replies; 18+ messages in thread
From: Juanma Barranquero @ 2007-09-29 19:09 UTC (permalink / raw)
  To: David Kastrup; +Cc: help-gnu-emacs

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

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

end of thread, other threads:[~2007-09-29 19:09 UTC | newest]

Thread overview: 18+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2007-09-26  8:04 Emacs documentation sources Dave Pawson
2007-09-26  9:23 ` Eli Zaretskii
2007-09-26 17:43 ` Sean Sieger
     [not found] ` <mailman.1329.1190828635.18990.help-gnu-emacs@gnu.org>
2007-09-26 18:07   ` Richard G Riley
2007-09-26 18:55     ` Drew Adams
2007-09-27  8:44     ` Thien-Thi Nguyen
     [not found] ` <mailman.1306.1190798609.18990.help-gnu-emacs@gnu.org>
2007-09-26 19:53   ` David Kastrup
2007-09-26 21:18     ` Eli Zaretskii
     [not found]     ` <mailman.1354.1190841494.18990.help-gnu-emacs@gnu.org>
2007-09-27  6:17       ` David Kastrup
2007-09-27  7:59         ` Eli Zaretskii
     [not found]         ` <mailma\x04n.1375.1190879967.18990.help-gnu-emacs@gnu.org>
2007-09-27 20:17           ` David Kastrup
2007-09-28  8:13             ` Eli Zaretskii
     [not found]             ` <mailman.1419.1190967231.18990.help-gnu-emacs@gnu.org>
2007-09-28 15:36               ` Stefan Monnier
2007-09-28 23:13               ` David Kastrup
2007-09-29 16:19                 ` Eli Zaretskii
     [not found]                 ` <mailman.1475.1191082767.18990.help-gnu-emacs@gnu.org>
2007-09-29 17:00                   ` David Kastrup
2007-09-29 19:09                     ` Juanma Barranquero
     [not found]         ` <mailman.1375.1190879967.18990.help-gnu-emacs@gnu.org>
2007-09-28 15:31           ` Stefan Monnier

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).