Doc strings starting with a line break

Doc strings starting with a line break

[Tino Calancha]

Hi,

i am wondering what could be the reason for some doc strings
starting with a break line.
For instance, see `isearch-forward' or `looking-at-p'.

Tino

Re: Doc strings starting with a line break

[Richard Copley]

On 18 September 2016 at 11:51, Tino Calancha <tino.calancha@gmail.com> wrote:
> i am wondering what could be the reason for some doc strings
> starting with a break line.
> For instance, see `isearch-forward' or `looking-at-p'.

The newline is escaped so it's not part of the docstring. For
`looking-at-p' it allows the following line of code to fit into 80
characters. For `isearch-forward' it seems unnecessary but it
has been that way for 24 years. They do things differently
there :)

Re: Doc strings starting with a line break

[Tino Calancha]

On Sun, 18 Sep 2016, Richard Copley wrote:

> On 18 September 2016 at 11:51, Tino Calancha <tino.calancha@gmail.com> wrote:
>> i am wondering what could be the reason for some doc strings
>> starting with a break line.
>> For instance, see `isearch-forward' or `looking-at-p'.
>
> The newline is escaped so it's not part of the docstring. For
> `looking-at-p' it allows the following line of code to fit into 80
> characters.
I guess would fit without that trick: i count 77 characters.
> For `isearch-forward' it seems unnecessary but it
> has been that way for 24 years. They do things differently
> there :)
I see.  Indeed, it's being a long time.
I will accept these strings as a cargo cult.

Re: Doc strings starting with a line break

[Andreas Schwab]

On Sep 18 2016, Tino Calancha <tino.calancha@gmail.com> wrote:

> i am wondering what could be the reason for some doc strings
> starting with a break line.
> For instance, see `isearch-forward' or `looking-at-p'.

I don't see anything unusual.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Doc strings starting with a line break

[Tino Calancha]

On Sun, 18 Sep 2016, Andreas Schwab wrote:

> On Sep 18 2016, Tino Calancha <tino.calancha@gmail.com> wrote:
>
>> i am wondering what could be the reason for some doc strings
>> starting with a break line.
>> For instance, see `isearch-forward' or `looking-at-p'.
>
> I don't see anything unusual.
You need to read the source code:  In *Help* buffer there is no
difference at all.

Re: Doc strings starting with a line break

[Stefan Monnier]

>> i am wondering what could be the reason for some doc strings
>> starting with a break line.
>> For instance, see `isearch-forward' or `looking-at-p'.

> The newline is escaped so it's not part of the docstring. For
> `looking-at-p' it allows the following line of code to fit into 80
> characters. For `isearch-forward' it seems unnecessary but it
> has been that way for 24 years. They do things differently
> there :)

There's a special hack in the Lisp reader which reads such strings as
the constant 0 (under some circumstances) so that we don't allocate
memory for those strings which will soon after be replaced by
a reference to some part of the DOC file (via Snarf-documentation).

This memory could/would be recovered by GC, so it wouldn't be completely
wasted, but it usually wouldn't be returned to the OS (IOW it would stay
in the free-list of Elisp's memory manager), so it would result in
a slightly larger bin/emacs executable and initial memory footprint
(unless we replace this current hack by some other mechanism, obviously).


        Stefan

Re: Doc strings starting with a line break

[Andreas Schwab]

On Sep 18 2016, Stefan Monnier <monnier@iro.umontreal.ca> wrote:

> There's a special hack in the Lisp reader which reads such strings as
> the constant 0 (under some circumstances) so that we don't allocate
> memory for those strings which will soon after be replaced by
> a reference to some part of the DOC file (via Snarf-documentation).

That feature is only used in elc files, though (and some el files that
are explicitly loaded noncompiled like loaddefs.el).

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Doc strings starting with a line break

[Stefan Monnier]

>> There's a special hack in the Lisp reader which reads such strings as
>> the constant 0 (under some circumstances) so that we don't allocate
>> memory for those strings which will soon after be replaced by
>> a reference to some part of the DOC file (via Snarf-documentation).
> That feature is only used in elc files, though (and some el files that
> are explicitly loaded noncompiled like loaddefs.el).

I'm fuzzy on the details, indeed.  But IIRC the .elc files never
contains strings that start with "\<lf> so this special hack doesn't
apply to them (we have another (related) hack for the (#$ . <N>) cons
cells of those preloaded .elc files).

IOW, it might be that nowadays this hack only applies to
loaddefs.el, really.  Funnily enough the patch below make Emacs crash,
rather than just changing its size.


        Stefan


diff --git a/src/lread.c b/src/lread.c
index ef58b20..21a8f01 100644
--- a/src/lread.c
+++ b/src/lread.c
@@ -3096,8 +3096,8 @@ read1 (Lisp_Object readcharfun, int *pch, bool first_in_list)
 	/* If purifying, and string starts with \ newline,
 	   return zero instead.  This is for doc strings
 	   that we are really going to find in etc/DOC.nn.nn.  */
-	if (!NILP (Vpurify_flag) && NILP (Vdoc_file_name) && cancel)
-	  return make_number (0);
+	/* if (!NILP (Vpurify_flag) && NILP (Vdoc_file_name) && cancel)
+	 *   return make_number (0); */
 
 	if (! force_multibyte && force_singlebyte)
 	  {