Defun Self Documentation

Defun Self Documentation

[Christopher Dimech]

When using defun, can one include a Self Documenting string or is
Self-Documentation only applicable for interactive functions?

(defun Gdn ()
   "Description"
   Body ...
)

Re: Defun Self Documentation

[tomas]

[-- Attachment #1: Type: text/plain, Size: 487 bytes --]

On Thu, Nov 05, 2020 at 04:16:09PM +0100, Christopher Dimech wrote:
> 
> When using defun, can one include a Self Documenting string or is
> Self-Documentation only applicable for interactive functions?
> 
> (defun Gdn ()
>    "Description"
>    Body ...
> )

No need to be interactive.

Minor nit: convention in Lisp is

  (defun Gdn ()
     "Description"
     Body ... )

i.e. closing parens don't get a line of their own. Readers will
thank you :)

Cheers
 - t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Defun Self Documentation

[Christopher Dimech]

Don't people find it tough to immediately figure out which bracket closes
what?  But if readers will thank me, I would certainly comply.  I come from
the C-Language as is evident.


> Sent: Thursday, November 05, 2020 at 4:45 PM
> From: tomas@tuxteam.de
> To: help-gnu-emacs@gnu.org
> Subject: Re: Defun Self Documentation
>
> On Thu, Nov 05, 2020 at 04:16:09PM +0100, Christopher Dimech wrote:
> >
> > When using defun, can one include a Self Documenting string or is
> > Self-Documentation only applicable for interactive functions?
> >
> > (defun Gdn ()
> >    "Description"
> >    Body ...
> > )
>
> No need to be interactive.
>
> Minor nit: convention in Lisp is
>
>   (defun Gdn ()
>      "Description"
>      Body ... )
>
> i.e. closing parens don't get a line of their own. Readers will
> thank you :)
>
> Cheers
>  - t
>

Re: Defun Self Documentation

[tomas]

[-- Attachment #1: Type: text/plain, Size: 537 bytes --]

On Thu, Nov 05, 2020 at 04:55:54PM +0100, Christopher Dimech wrote:
> Don't people find it tough to immediately figure out which bracket closes
> what?  But if readers will thank me, I would certainly comply.  I come from
> the C-Language as is evident.

Yes to last (I do, too, mostly). For the parens, there's your favourite
editor.

People are not authoritarian around here, and personally, I do hate
authoritarian style, so I won't complain if you use another style.
But conventions help in communication, thus my hint.

Cheers
 - t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Defun Self Documentation

[Christopher Dimech]

I know many are not authoritarian, but as I will be releasing the code,
the whole purpose is for the form to be useful and convenient for users.
I don't see it difficult, otherwise I will ask for people's view.

Regards
Christopher


> Sent: Thursday, November 05, 2020 at 5:00 PM
> From: tomas@tuxteam.de
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: Defun Self Documentation
>
> On Thu, Nov 05, 2020 at 04:55:54PM +0100, Christopher Dimech wrote:
> > Don't people find it tough to immediately figure out which bracket closes
> > what?  But if readers will thank me, I would certainly comply.  I come from
> > the C-Language as is evident.
>
> Yes to last (I do, too, mostly). For the parens, there's your favourite
> editor.
>
> People are not authoritarian around here, and personally, I do hate
> authoritarian style, so I won't complain if you use another style.
> But conventions help in communication, thus my hint.
>
> Cheers
>  - t
>

Re: Defun Self Documentation

[Jean Louis]

* tomas@tuxteam.de <tomas@tuxteam.de> [2020-11-05 19:02]:
> On Thu, Nov 05, 2020 at 04:55:54PM +0100, Christopher Dimech wrote:
> > Don't people find it tough to immediately figure out which bracket closes
> > what?  But if readers will thank me, I would certainly comply.  I come from
> > the C-Language as is evident.

I can understand the problem. Here is short advise:

- (setq electric-pair-mode t)  ;; This will give automatic () instead of only (
  and it will work with [] and "", this helps to make sure what is closed

- highlight matching parenthesis in menu and save options, that
  will give you flashing parenthesis and you will know what you
  are closing.

- additionally you may see in minibuffer also first part of the
  list that you are closing

Re: Defun Self Documentation

[Christopher Dimech]

 Yes, I really like minibuffer details on Closing parentheses.


> Sent: Thursday, November 05, 2020 at 7:08 PM
> From: "Jean Louis" <bugs@gnu.support>
> To: tomas@tuxteam.de
> Cc: "Christopher Dimech" <dimech@gmx.com>, help-gnu-emacs@gnu.org
> Subject: Re: Defun Self Documentation
>
> * tomas@tuxteam.de <tomas@tuxteam.de> [2020-11-05 19:02]:
> > On Thu, Nov 05, 2020 at 04:55:54PM +0100, Christopher Dimech wrote:
> > > Don't people find it tough to immediately figure out which bracket closes
> > > what?  But if readers will thank me, I would certainly comply.  I come from
> > > the C-Language as is evident.
>
> I can understand the problem. Here is short advise:
>
> - (setq electric-pair-mode t)  ;; This will give automatic () instead of only (
>   and it will work with [] and "", this helps to make sure what is closed
>
> - highlight matching parenthesis in menu and save options, that
>   will give you flashing parenthesis and you will know what you
>   are closing.
>
> - additionally you may see in minibuffer also first part of the
>   list that you are closing
>

RE: Defun Self Documentation

[Drew Adams]

> Don't people find it tough to immediately figure out which bracket closes
> what?  But if readers will thank me, I would certainly comply.  I come from
> the C-Language as is evident.

No.

Turn on `show-paren-mode'.

See also option `blink-matching-paren' and the
other `blink-matching-paren-*' options.

Double-click `mouse-1' on a paren, to select it,
its match, and the text between them.

`C-x C-x' bounces the cursor from end to end of
the region.

If code is formatted normally then you can
pretty much count on the ))))) at the end of a
sexp to balance what you'd expect.  Otherwise,
someone (e.g. you) would already have fixed that.

There's zero reason to put an opening or closing
paren on a line by itself, unless you want to
indicate something specially or add a comment in
a particular way.

`C-M-q' indents an entire sexp (e.g. a defun) in
a conventional way.  It, `TAB', and other keys
know Lisp syntax.

Re: RE: Defun Self Documentation

[Christopher Dimech]

Following your argument through, and with show-paren-mode and blink-matching-paren-*,
I agree that it is not a problem having parentheses together.


> Sent: Thursday, November 05, 2020 at 5:15 PM
> From: "Drew Adams" <drew.adams@oracle.com>
> To: "Christopher Dimech" <dimech@gmx.com>, tomas@tuxteam.de
> Cc: help-gnu-emacs@gnu.org
> Subject: RE: Defun Self Documentation
>
> > Don't people find it tough to immediately figure out which bracket closes
> > what?  But if readers will thank me, I would certainly comply.  I come from
> > the C-Language as is evident.
>
> No.
>
> Turn on `show-paren-mode'.
>
> See also option `blink-matching-paren' and the
> other `blink-matching-paren-*' options.
>
> Double-click `mouse-1' on a paren, to select it,
> its match, and the text between them.
>
> `C-x C-x' bounces the cursor from end to end of
> the region.
>
> If code is formatted normally then you can
> pretty much count on the ))))) at the end of a
> sexp to balance what you'd expect.  Otherwise,
> someone (e.g. you) would already have fixed that.
>
> There's zero reason to put an opening or closing
> paren on a line by itself, unless you want to
> indicate something specially or add a comment in
> a particular way.
>
> `C-M-q' indents an entire sexp (e.g. a defun) in
> a conventional way.  It, `TAB', and other keys
> know Lisp syntax.
>
>

Re: Defun Self Documentation

[Stefan Monnier]

> Don't people find it tough to immediately figure out which bracket closes what?

I don't see why that would be important information.  The important
information is to know whether an expression is "inside" or
"next/outside" some other and the indentation already gives you that
information.

Then you have languages like Haskell/Python where you don't even bother
writing the closing paren/brace ;-)


        Stefan

Re: Defun Self Documentation

[Arthur Miller]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Don't people find it tough to immediately figure out which bracket closes what?
>
> I don't see why that would be important information.  The important
> information is to know whether an expression is "inside" or
> "next/outside" some other and the indentation already gives you that
> information.
I was hacking Emacs' configure.ac earlier today. I really wished there
was a better functioning identation and paren-highlighting mode. For
some reason whatever mode is activated in configure.ac, it didn't really
understood the ']' and ')' in some places despite them being correct. 

Re: Defun Self Documentation

[Christopher Dimech]

> Sent: Thursday, November 05, 2020 at 5:51 PM
> From: "Arthur Miller" <arthur.miller@live.com>
> To: "Stefan Monnier" <monnier@iro.umontreal.ca>
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: Defun Self Documentation
>
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
> >> Don't people find it tough to immediately figure out which bracket closes what?
> >
> > I don't see why that would be important information.  The important
> > information is to know whether an expression is "inside" or
> > "next/outside" some other and the indentation already gives you that
> > information.

> I was hacking Emacs' configure.ac earlier today. I really wished there
> was a better functioning identation and paren-highlighting mode. For
> some reason whatever mode is activated in configure.ac, it didn't really
> understood the ']' and ')' in some places despite them being correct.
>

Perhaps there is enough reason for some improvement in indentation and
paren-highlighting mode.

>
>

Re: Defun Self Documentation

[Stefan Monnier]

>> I don't see why that would be important information.  The important
>> information is to know whether an expression is "inside" or
>> "next/outside" some other and the indentation already gives you that
>> information.
> I was hacking Emacs' configure.ac earlier today. I really wished there
> was a better functioning identation and paren-highlighting mode. For
> some reason whatever mode is activated in configure.ac, it didn't really
> understood the ']' and ')' in some places despite them being correct. 

[ Not sure how this relates to the earlier discussion of defun's
  docstrings or placement closing parens, but in any case:  ]

This is 100% under the control of `autoconf-mode`, so that's where
improvements need to be done for that.  IIRC it's not easy to make it
work well reliably because of the "two-level" nature of the language
(IIRC it's a layering on `m4` on top of `sh`), but currently there is no
auto-indentation at all in that mode, so there are plenty of
low-hanging fruits.


        Stefan

Re: Defun Self Documentation

[Michael Heerdegen]

Christopher Dimech <dimech@gmx.com> writes:

> Don't people find it tough to immediately figure out which bracket
> closes what?  But if readers will thank me, I would certainly comply.
> I come from the C-Language as is evident.

My impression: parens are for code editing, for making it easy to write
syntactically correct code.  And as it has been mentioned, Emacs makes
that easy by providing highlighting and paren moving commands etc.

For reading (by humans) indentation is more helpful.  Indentation more
or less directly reflects paren depth.

And to make code even more readable, some people prefer to use
`rainbow-delimiters'.  I guess you would like it.

Michael.

Re: Defun Self Documentation

[Christopher Dimech]

Yes I could like rainbow-delimiters.

Have installed it. Do you know how I can set
rainbow-delimiters-depth-N-face in my init .emacs.


> Sent: Thursday, November 05, 2020 at 6:29 PM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Defun Self Documentation
>
> Christopher Dimech <dimech@gmx.com> writes:
>
> > Don't people find it tough to immediately figure out which bracket
> > closes what?  But if readers will thank me, I would certainly comply.
> > I come from the C-Language as is evident.
>
> My impression: parens are for code editing, for making it easy to write
> syntactically correct code.  And as it has been mentioned, Emacs makes
> that easy by providing highlighting and paren moving commands etc.
>
> For reading (by humans) indentation is more helpful.  Indentation more
> or less directly reflects paren depth.
>
> And to make code even more readable, some people prefer to use
> `rainbow-delimiters'.  I guess you would like it.
>
> Michael.
>
>
>

Re: Defun Self Documentation

[Michael Heerdegen]

Christopher Dimech <dimech@gmx.com> writes:

> Have installed it. Do you know how I can set
> rainbow-delimiters-depth-N-face in my init .emacs.

Your settings could look like this (without the markers of course):

#+begin_src emacs-lisp
(when (require 'rainbow-delimiters nil 'noerror)
  (progn
    (face-spec-set 'rainbow-delimiters-depth-1-face
                   '((((background dark))
                      (:foreground "#6F4014"))
                     (t
                      (:foreground "#574B74331C57"))))
    (face-spec-set 'rainbow-delimiters-depth-2-face
                   '((((background dark))
                      (:foreground "#700094"))
                     (t
                      (:foreground "#A6652D060000"))))
    (face-spec-set 'rainbow-delimiters-depth-3-face
                   '((((background dark))
                      (:foreground "#A665A665FFFF"))
                     (t
                      (:foreground "#00000000A665"))))
    (face-spec-set 'rainbow-delimiters-depth-4-face
                   '((((background dark))
                      (:foreground "#E5FF00"))
                     (t
                      (:foreground "#A665A6650000"))))
    (face-spec-set 'rainbow-delimiters-depth-5-face
                   '((((background dark))
                      (:foreground "#BEBE3AB93AB9"))
                     (t
                      (:foreground "#652465246524"))))
    (face-spec-set 'rainbow-delimiters-depth-6-face
                   '((((background dark))
                      (:foreground "#00B000"))
                     (t
                      (:foreground "#0000A6650000"))))
    (face-spec-set 'rainbow-delimiters-depth-7-face
                   '((((background dark))
                      (:foreground "#FFFFFF"))
                     (t
                      (:foreground "#13935DF7A665"))))
    (face-spec-set 'rainbow-delimiters-depth-8-face
                   '((((background dark))
                      (:foreground "#505050"))
                     (t
                      (:foreground "#7433547506CD"))))
    (face-spec-set 'rainbow-delimiters-depth-9-face
                   '((((background dark))
                      (:foreground "#FFFFA665FFFF"))
                     (t
                      (:foreground "#A6650000A665"))))
    (face-spec-set 'rainbow-delimiters-unmatched-face
                   '((t
                      (:foreground "#88090B" :inverse-video t))))))
#+end_src


Regards,

Michael.

Re: Defun Self Documentation

[Joost Kremers]

On Thu, Nov 05 2020, Christopher Dimech wrote:
> Don't people find it tough to immediately figure out which bracket closes
> what? 

That's what `show-paren-mode` is for. :-) You'll only really need it when
editing existing code, however. For writing code, you should use something that
keeps parentheses balanced (I use `paredit-mode' myself, but there are other
options), and when reading code, you should mostly ignore the parentheses and
focus on the indentation.

This comes to mind:

https://github.com/tarsius/paren-face/blob/master/parentheses.png

;-)

-- 
Joost Kremers
Life has its moments

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

Joost Kremers wrote:

>> Don't people find it tough to immediately figure out which
>> bracket closes what?
>
> That's what `show-paren-mode` is for. :-)

(require 'paren)
(show-paren-mode t)
(setq show-paren-delay 0)

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Eli Zaretskii]

> Date: Thu, 05 Nov 2020 20:38:08 +0100
> From: Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org>
> 
> (require 'paren)          <<<<<<<<<<<<<<< not needed
> (show-paren-mode t)       <<<<<<<<< better use 1 as arg
> (setq show-paren-delay 0) <<<<<<<<< questionable

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

Eli Zaretskii wrote:

> (require 'paren)          <<<<<<<<<<<<<<< not needed

Without it:

~/.emacs:35:7: Warning: assignment to free variable
‘show-paren-delay’

> (setq show-paren-delay 0) <<<<<<<<< questionable

?

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Eli Zaretskii]

> Date: Thu, 05 Nov 2020 22:02:41 +0100
> From: Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org>
> 
> Eli Zaretskii wrote:
> 
> > (require 'paren)          <<<<<<<<<<<<<<< not needed
> 
> Without it:
> 
> ~/.emacs:35:7: Warning: assignment to free variable
> ‘show-paren-delay’

Are you usin lexical-binding in your init files? don't.

> > (setq show-paren-delay 0) <<<<<<<<< questionable
> 
> ?

You are suggesting someone else to use your personal preferences
without explaining your reasons for not liking the default value.
That is questionable practice at best.

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

Eli Zaretskii wrote:

> Are you usin lexical-binding in your init files? don't.

Not in this one. But anyway, *plonk*

>>> (setq show-paren-delay 0) <<<<<<<<< questionable
>> 
>> ?
>
> You are suggesting someone else to use your personal preferences
> without explaining your reasons for not liking the default value.
> That is questionable practice at best.

...

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

>> Are you usin lexical-binding in your init files? don't.
>
> Not in this one. But anyway, *plonk*
>
>>>> (setq show-paren-delay 0) <<<<<<<<< questionable
>>> 
>>> ?
>>
>> You are suggesting someone else to use your personal preferences
>> without explaining your reasons for not liking the default value.
>> That is questionable practice at best.
>
> ...

https://dataswamp.org/~incal/PUNK-FUCKER-LIST

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Eli Zaretskii]

> Date: Fri, 06 Nov 2020 08:18:12 +0100
> From: Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org>
> 
> https://dataswamp.org/~incal/PUNK-FUCKER-LIST

Rude.

Please remove that ASAP, or else I will respond to each of your
messages here with a caveat to readers about your rude conduct.

Re: Defun Self Documentation

[tomas]

[-- Attachment #1: Type: text/plain, Size: 530 bytes --]

On Fri, Nov 06, 2020 at 09:45:59AM +0200, Eli Zaretskii wrote:
> > Date: Fri, 06 Nov 2020 08:18:12 +0100
> > From: Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org>
> > 
> > https://dataswamp.org/~incal/PUNK-FUCKER-LIST
> 
> Rude.

Agreed. Emanuel -- if Eli is in there: please add me to that list.

> Please remove that ASAP, or else I will respond to each of your
> messages here with a caveat to readers about your rude conduct.

Eli: no need to escalate.

Cheers & peace
 - t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

tomas wrote:

> Emanuel -- if Eli is in there: please add me to that list.

Yeah, but this isn't the US/Mexican border, anyone can't just come
and go as they please. Proving over and over that you really belong
is the only way in.

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[tomas]

[-- Attachment #1: Type: text/plain, Size: 116 bytes --]

On Fri, Nov 06, 2020 at 09:38:05AM +0100, Emanuel Berg via Users list for the GNU Emacs text editor wrote:

*plonk*

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

tomas wrote:

> *plonk*

Support plonk, ey, tomas? What heroism ... are you two going to
stand behind a palisade with aquanatic rifles as well? What would
you do if I started to climb that palisade, you think?

Well, I'm not gonna killfile you.

Why ever I would do that.

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Gregory Heytings via Users list for the GNU Emacs text editor]

>> https://dataswamp.org/~incal/PUNK-FUCKER-LIST
>
> Rude.
>
> Please remove that ASAP, or else I will respond to each of your messages 
> here with a caveat to readers about your rude conduct.
>

It's rude indeed, but see his "apology" mail on Sat, 29 Aug 2020 14:52:36 
+0200.  He has a personality disorder, which makes him behave weirdly from 
time to time.  IMO it's better to ignore this when it happens.

Re: Defun Self Documentation

[Eli Zaretskii]

> Date: Fri, 06 Nov 2020 08:44:35 +0000
> From: Gregory Heytings <ghe@sdf.org>
> cc: Emanuel Berg <moasenwood@zoho.eu>, help-gnu-emacs@gnu.org
> 
> >> https://dataswamp.org/~incal/PUNK-FUCKER-LIST
> >
> > Rude.
> >
> > Please remove that ASAP, or else I will respond to each of your messages 
> > here with a caveat to readers about your rude conduct.
> >
> 
> It's rude indeed, but see his "apology" mail on Sat, 29 Aug 2020 14:52:36 
> +0200.  He has a personality disorder, which makes him behave weirdly from 
> time to time.  IMO it's better to ignore this when it happens.

Sorry, I'm not prepared to ignore people who publicly smear the names
of others with profanities.  Those people should be prepared to have
their names publicly smeared as well.

Re: Defun Self Documentation

[Christopher Dimech]

> Sorry, I'm not prepared to ignore people who publicly smear the names
> of others with profanities.  Those people should be prepared to have
> their names publicly smeared as well.

One can do what one wants, but doing what one wants does not mean taking
it to any level of irresponsibility.  Within Gnu we are in the civillised
world, irrespective of which burg people spring from.

Eli is quite correct.

---------------------
Christopher Dimech
General Administrator - Naiad Informatics - GNU Project (Geocomputation)
- Geophysical Simulation
- Geological Subsurface Mapping
- Disaster Preparedness and Mitigation
- Natural Resource Exploration and Production
- Free Software Advocacy


> Sent: Friday, November 06, 2020 at 12:54 PM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: "Gregory Heytings" <ghe@sdf.org>
> Cc: help-gnu-emacs@gnu.org, moasenwood@zoho.eu
> Subject: Re: Defun Self Documentation
>
> > Date: Fri, 06 Nov 2020 08:44:35 +0000
> > From: Gregory Heytings <ghe@sdf.org>
> > cc: Emanuel Berg <moasenwood@zoho.eu>, help-gnu-emacs@gnu.org
> >
> > >> https://dataswamp.org/~incal/PUNK-FUCKER-LIST
> > >
> > > Rude.
> > >
> > > Please remove that ASAP, or else I will respond to each of your messages
> > > here with a caveat to readers about your rude conduct.
> > >
> >
> > It's rude indeed, but see his "apology" mail on Sat, 29 Aug 2020 14:52:36
> > +0200.  He has a personality disorder, which makes him behave weirdly from
> > time to time.  IMO it's better to ignore this when it happens.
>
> Sorry, I'm not prepared to ignore people who publicly smear the names
> of others with profanities.  Those people should be prepared to have
> their names publicly smeared as well.
>
>

Re: Defun Self Documentation

[Gregory Heytings via Users list for the GNU Emacs text editor]

>> It's rude indeed, but see his "apology" mail on Sat, 29 Aug 2020 
>> 14:52:36 +0200.  He has a personality disorder, which makes him behave 
>> weirdly from time to time.  IMO it's better to ignore this when it 
>> happens.
>
> Sorry, I'm not prepared to ignore people who publicly smear the names of 
> others with profanities.  Those people should be prepared to have their 
> names publicly smeared as well.
>

That's correct only if you assume that everyone behaves in a rational way. 
There are people with psychological disabilities, who sometimes do not 
behave rationally.  One particularly impressive disability is for example 
Tourette's syndrome.[1] The best thing you can do is to not take what they 
do and say seriously/literally, IOW, to take what they do and say with 
many grains of salt.  Of course all this is more difficult to perceive 
with people who behave irrationally only at times, and is also more 
difficult to perceive on a mailing list.

[1] https://en.wikipedia.org/wiki/Tourette_syndrome

Re: Defun Self Documentation

[Christopher Dimech]

> Sent: Friday, November 06, 2020 at 6:36 PM
> From: "Gregory Heytings via Users list for the GNU Emacs text editor" <help-gnu-emacs@gnu.org>
> To: "Eli Zaretskii" <eliz@gnu.org>
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: Defun Self Documentation
>
>
> >> It's rude indeed, but see his "apology" mail on Sat, 29 Aug 2020
> >> 14:52:36 +0200.  He has a personality disorder, which makes him behave
> >> weirdly from time to time.  IMO it's better to ignore this when it
> >> happens.
> >
> > Sorry, I'm not prepared to ignore people who publicly smear the names of
> > others with profanities.  Those people should be prepared to have their
> > names publicly smeared as well.
> >
>
> That's correct only if you assume that everyone behaves in a rational way.
> There are people with psychological disabilities, who sometimes do not
> behave rationally.  One particularly impressive disability is for example
> Tourette's syndrome.[1] The best thing you can do is to not take what they
> do and say seriously/literally, IOW, to take what they do and say with
> many grains of salt.  Of course all this is more difficult to perceive
> with people who behave irrationally only at times, and is also more
> difficult to perceive on a mailing list.

That depends on how administrators run the project.  Not all are so understanding.
Have you never worked in a serious job before! Administrators are entitled to
reject anybody who cannot function well in a society.  Still, I would not argue
that Emanuel Berg can offend anybody when writing on his own web pages.

>
> [1] https://en.wikipedia.org/wiki/Tourette_syndrome
>
>

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

Christopher Dimech wrote:

> That depends on how administrators run the project. Not all are
> so understanding. Have you never worked in a serious job before!
> Administrators are entitled to reject anybody who cannot function
> well in a society. Still, I would not argue that Emanuel Berg can
> offend anybody when writing on his own web pages.

Ha ha :) I don't know ... interesting comment :)

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Eli Zaretskii]

> Date: Fri, 06 Nov 2020 17:36:48 +0000
> From: Gregory Heytings <ghe@sdf.org>
> cc: help-gnu-emacs@gnu.org
> 
> > Sorry, I'm not prepared to ignore people who publicly smear the names of 
> > others with profanities.  Those people should be prepared to have their 
> > names publicly smeared as well.
> 
> That's correct only if you assume that everyone behaves in a rational way. 
> There are people with psychological disabilities, who sometimes do not 
> behave rationally.

That's immaterial.  I've asked to remove the obnoxious slander.  It is
an easy thing to do even if one doesn't understand why or doesn't
agree.

I will wait for 3 days for Emanuel to remove that, before I take the
action I promised to take.

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

Eli Zaretskii wrote:

> That's immaterial. I've asked to remove the obnoxious slander.
> It is an easy thing to do even if one doesn't understand why or
> doesn't agree.

(hm ... why am I seeing this? should restart Gnus, perhaps ...)

but: you are reacting on the language?

It is just words, but fine - I made another file, perhaps more to
your liking:

   T H E  C L U E L E S S   O N L I N E  F A C U L T Y

   https://dataswamp.org/~incal/CLUELESS-ONLINE

Everyone happy?

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

Gregory Heytings via Users list for the GNU Emacs text editor wrote:

> That's correct only if you assume that everyone behaves in
> a rational way. There are people with psychological disabilities,
> who sometimes do not behave rationally. One particularly
> impressive disability is for example Tourette's syndrome.[1] The
> best thing you can do is to not take what they do and say
> seriously/literally, IOW, to take what they do and say with many
> grains of salt. Of course all this is more difficult to perceive
> with people who behave irrationally only at times, and is also
> more difficult to perceive on a mailing list.
>
> [1] https://en.wikipedia.org/wiki/Tourette_syndrome

Yeah, I don't know if you are speaking generally here, probably,
but as for me, I don't have any syndrome, I have a damage which
I sustained when I was 32~32 years old. Like I said, there was
a long time I could keep it apart but now the sane and the insane
(if you will) have melted into ONE person so even tho it can
influence in many ways and most definitely is I still don't want to
blame it.

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

Eli Zaretskii wrote:

> Sorry, I'm not prepared to ignore people who publicly smear the
> names of others with profanities. Those people should be prepared
> to have their names publicly smeared as well.

Eli, you being a crybaby trying to defend the Emacs turf against
one person writing mails on a damn ML ... it only proves my point.

In my daily life, I go to the bike shop, everyone is "Oh, Manny",
I go to the tree house, everyone is "Oh, Manny", I go to the
brewery, everyone is *hiccup*, but I go HERE, people are always
trying to tell me, I'm no good, blah blah blah.

Eli is old hands at that. When I came here, ~15 years ago, one of
the first things I wrote was this [1]. Yet there were many flame
wars involving Eli, Juanma, and a bunch of other negativist lamers
I don't remember, who critizised everything I did - just so many
people (not everyone) trying to get me to leave...

Today, we have a bunch of guys asking questions, some of which
implies (I might be wrong, but that's how it looks, TBH) they have
no programming experience whatsoever. They ask questions and it is
like a contest in patience, everyone (almost) is trying their
hardest not to loose their temper and speak their minds which would
be soo embarrassing dear God :$

Again, when I came, I wrote the below Elisp. Now, ~15 years later
Eli still tells me I'm not good enough and can't change the
original values of damn Emacs options without explicitly
stating why. It is so ridiculous.

But Eli, guess what, two things, 1) you couldn't defend your little
turf from me then, and you cannot now, I just DON'T BELIEVE YOU,
I KNOW what I can do with a computer, and I can do whatever the
fuck I want to it, including your little turf program; and 2) if we
pause to take a deep breath, why do you think, when I go to the
bike shop, to the tree house, or to the brewery, there is not
a single little punk fucker to challenge me anywhere? are you the
only punk fucker in the world with a turf to defend? hardly! so how
come you think I never meet any Elis face to face?


[1] https://dataswamp.org/~incal/emacs-init/shell-cli.el

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

Gregory Heytings via Users list for the GNU Emacs text editor wrote:

> It's rude indeed, but see his "apology" mail on Sat, 29 Aug 2020
> 14:52:36 +0200. He has a personality disorder, which makes him
> behave weirdly from time to time. IMO it's better to ignore this
> when it happens.

Yeah ... in practice that's what it is. Some damage to my nervous
system ... probably from head trauma. but now it has gone too far
so I can't tell if I'm my old version or the new, damaged, if you
will ... it is all mixed up ... literally.

Maybe I should change name from "Emanuel Berg" to "Emanuel Berg
2.0" ... or "Emanuel Berg +/-2.0" probably better?

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation (let us do it different)

[Jean Louis]

* Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org> [2020-11-06 10:19]:
> >> Are you usin lexical-binding in your init files? don't.
> >
> > Not in this one. But anyway, *plonk*
> >
> >>>> (setq show-paren-delay 0) <<<<<<<<< questionable
> >>> 
> >>> ?
> >>
> >> You are suggesting someone else to use your personal preferences
> >> without explaining your reasons for not liking the default value.
> >> That is questionable practice at best.
> >
> > ...
> 
> https://dataswamp.org/~incal/PUNK-FUCKER-LIST

While that may be funny, maybe they will not find it funny, but even
if they do this may reject Emacs users to this list or make it
unwelcoming as new users on this list may think they can easily become
target to be put on such list.

Reference:
https://www.gnu.org/philosophy/kind-communication.html

Re: Defun Self Documentation (let us do it different)

[Emanuel Berg via Users list for the GNU Emacs text editor]

Jean Louis wrote:

>> https://dataswamp.org/~incal/PUNK-FUCKER-LIST
>
> While that may be funny, maybe they will not find it funny, but
> even if they do this may reject Emacs users to this list or make
> it unwelcoming as new users on this list may think they can
> easily become target to be put on such list.
>
> Reference:
> https://www.gnu.org/philosophy/kind-communication.html

OK, I agree, I didn't think of the language aspect, I have made
a new list:

  https://dataswamp.org/~incal/CLUELESS-ONLINE

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Stefan Monnier]

>> ~/.emacs:35:7: Warning: assignment to free variable
>> ‘show-paren-delay’
> Are you usin lexical-binding in your init files?

Yes, I am.

> don't.

Why not?

[ And, BTW, lexical-binding has no incidence on the above message which
  is simply due to him byte-compiling his .emacs file (or using
  something like `flymake` to do it for him and report the
  errors&warnings).  ]


        Stefan

Re: Defun Self Documentation

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Fri, 06 Nov 2020 12:02:38 -0500
> 
> >> ~/.emacs:35:7: Warning: assignment to free variable
> >> ‘show-paren-delay’
> > Are you usin lexical-binding in your init files?
> 
> Yes, I am.
> 
> > don't.
> 
> Why not?

I didn't tell _you_ not to do it.

Re: Defun Self Documentation

[Stefan Monnier]

>> >> ~/.emacs:35:7: Warning: assignment to free variable
>> >> ‘show-paren-delay’
>> > Are you usin lexical-binding in your init files?
>> Yes, I am.
>> > don't.
>> Why not?
> I didn't tell _you_ not to do it.

Indeed ;-)
But I wonder why we'd recommend other users not to use lexical-binding
in their `init.el`.


        Stefan

Re: Defun Self Documentation

[Christopher Dimech]

> Indeed ;-)
> But I wonder why we'd recommend other users not to use lexical-binding
> in their `init.el`.
>         Stefan

Because the defun special form didn’t work properly in lexically bound contexts.
But since 24.3, the problem with the symbol counter was resolved, it is no longer
a good advice.  People can use it without any harm.   

---------------------
Christopher Dimech
General Administrator - Naiad Informatics - GNU Project (Geocomputation)
- Geophysical Simulation
- Geological Subsurface Mapping
- Disaster Preparedness and Mitigation
- Natural Resource Exploration and Production
- Free Software Advocacy


> Sent: Friday, November 06, 2020 at 7:50 PM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Defun Self Documentation
>
> >> >> ~/.emacs:35:7: Warning: assignment to free variable
> >> >> ‘show-paren-delay’
> >> > Are you usin lexical-binding in your init files?
> >> Yes, I am.
> >> > don't.
> >> Why not?
> > I didn't tell _you_ not to do it.
> 
> Indeed ;-)
> But I wonder why we'd recommend other users not to use lexical-binding
> in their `init.el`.
> 
> 
>         Stefan
> 
> 
>

Re: Defun Self Documentation

[Stefan Monnier]

>> But I wonder why we'd recommend other users not to use lexical-binding
>> in their `init.el`.
> Because the defun special form didn’t work properly in lexically bound contexts.

I fail to see the connection.  The restriction of `defun` in lexical
context was very minor, only affected rather unusual circumstances
anyway, and could very easily be circumvented.  And I fail to see why it
should have affected init.el files more than others.

> But since 24.3, the problem with the symbol counter was resolved,

I don't know what "problem with the symbol counter" you're referring to.

> People can use it without any harm.

Of course.  Many people do already.


        Stefan

Re: Defun Self Documentation

[Christopher Dimech]

> Sent: Friday, November 06, 2020 at 8:23 PM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Defun Self Documentation
>
> >> But I wonder why we'd recommend other users not to use lexical-binding
> >> in their `init.el`.
> > Because the defun special form didn’t work properly in lexically bound contexts.
> 
> I fail to see the connection.  The restriction of `defun` in lexical
> context was very minor, only affected rather unusual circumstances
> anyway, and could very easily be circumvented.  And I fail to see why it
> should have affected init.el files more than others.
> 
> > But since 24.3, the problem with the symbol counter was resolved,
> 
> I don't know what "problem with the symbol counter" you're referring to.

Let should bind to variables only, but it wasn't.  Nevertheless, the recommendation
is of no value today, and should not be mentioned anymore. 

> 
> > People can use it without any harm.
> 
> Of course.  Many people do already.
> 
> 
>         Stefan
> 
> 
>

RE: Defun Self Documentation

[Drew Adams]

> When using defun, can one include a Self Documenting string or is
> Self-Documentation only applicable for interactive functions?
> 
> (defun Gdn ()
>    "Description"
>    Body ...
> )

Ask Emacs: `C-h f defun'.

,----
| defun is a Lisp macro in ‘byte-run.el’.
| 
| (defun NAME ARGLIST &optional DOCSTRING DECL &rest BODY)
                                ^^^^^^^^^
| 
| Define NAME as a function.
| The definition is (lambda ARGLIST [DOCSTRING] BODY...).
| See also the function ‘interactive’.
| DECL is a declaration, optional, of the form (declare DECLS...) where
| DECLS is a list of elements of the form (PROP . VALUES).  These are
| interpreted according to ‘defun-declarations-alist’.
| The return value is undefined.
`----

That doesn't explicitly tell you that DOCSTRING is the
doc string _for the function_ you're defining, but one
might guess that.

1. `C-h i m elisp', to visit the Elisp manual.
2. `i defun', to go to the doc about `defun'.

There you see this, about the optional doc-string arg:

 DOC, if present, should be a string specifying the function’s
                                                ^^^^^^^^^^^^^^
 documentation string (*note Function Documentation::).
___


Ask Emacs.

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

When writing a docstring to a function make sure all the arguments
appear, all in UPPERCASE, and in the same order they are passed to
the function.

Use this to verify:

(require 'checkdoc)

(setq checkdoc-permit-comma-termination-flag t)

(defun check-package-style ()
  (interactive)
  (let ((msg "Style check..."))
    (message msg)
    (checkdoc-current-buffer t) ; TAKE-NOTES
    (message "%sdone" msg) ))
(defalias 'check-style #'check-package-style)

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Anders Munch]

Eli Zaretskii wrote:
>> > (setq show-paren-delay 0) <<<<<<<<< questionable
>> 
>> ?
>
> You are suggesting someone else to use your personal preferences without
> explaining your reasons for not liking the default value.

The reason for why the current default value is bad: It creates a disconnect
between the user action (moving point) and the observable result (paren
highlight).

The default of 0.125 seconds is on the wrong side of Jakob Nielsen's reactivity
limit:
    https://www.nngroup.com/articles/response-times-3-important-limits/

regards, Anders

Re: Defun Self Documentation

[Eli Zaretskii]

> From: Anders Munch <ajm@flonidan.dk>
> Date: Fri, 6 Nov 2020 09:10:52 +0000
> 
> Eli Zaretskii wrote:
> >> > (setq show-paren-delay 0) <<<<<<<<< questionable
> >> 
> >> ?
> >
> > You are suggesting someone else to use your personal preferences without
> > explaining your reasons for not liking the default value.
> 
> The reason for why the current default value is bad: It creates a disconnect
> between the user action (moving point) and the observable result (paren
> highlight).

Thanks for explaining your reasoning, but let's not forget that
setting that to zero has a downside: if one types fast, it will slow
down redisplay by delaying the response to the typing.

> The default of 0.125 seconds is on the wrong side of Jakob Nielsen's reactivity
> limit:
>     https://www.nngroup.com/articles/response-times-3-important-limits/

Works perfectly for me, for many years, FWIW.  But of course, this is
personal, which is why it is a user option.

Re: Defun Self Documentation

[Anders Munch]

Eli Zaretskii wrote:
> Thanks for explaining your reasoning, but let's not forget that setting that to zero has a downside: if one types fast, it will slow down redisplay by delaying the response to the typing.

There is less work to do because it happens 0.125 seconds later?

I never noticed any slowdown.  Maybe it's mode-specific, some modes are slow at
finding the match?

> But of course, this is personal, which is why it is a user option.

Sure, but we were talking about the default, and the 0.1 seconds is an actual
scientific result.

regards, Anders

Re: Defun Self Documentation

[Eli Zaretskii]

> From: Anders Munch <ajm@flonidan.dk>
> Date: Fri, 6 Nov 2020 15:33:27 +0000
> 
> Eli Zaretskii wrote:
> > Thanks for explaining your reasoning, but let's not forget that setting that to zero has a downside: if one types fast, it will slow down redisplay by delaying the response to the typing.
> 
> There is less work to do because it happens 0.125 seconds later?

No, because with zero value it happens immediately, and the extra work
required to show the overlay will slow down Emacs.

The display of the overlays to show the matching parentheses works
with an idle timer, and that value is the amount of time Emacs should
be idle before the parentheses are highlighted.  If you time fast,
Emacs will never be idle for that much time, so the parentheses will
not be highlighted while typing.  If you set the value to zero, the
parentheses will be highlighted no matter how fast you type, so Emacs
becomes less responsive to your typing.

> > But of course, this is personal, which is why it is a user option.
> 
> Sure, but we were talking about the default, and the 0.1 seconds is an actual
> scientific result.

I'm not sure the 0.1 number is relevant to this feature.  We are not
talking about the reaction time, we are talking about the shortest
time that indicates the user stopped typing.

Re: Defun Self Documentation

[Christopher Dimech]

> I'm not sure the 0.1 number is relevant to this feature.  We are not
> talking about the reaction time, we are talking about the shortest
> time that indicates the user stopped typing.

It all depends if the user would like to get the highliting every time
the cursor gets ta a parenthesis. It is therefore  understandable
not wanting highlithing contiually.

A solution would be a keybinding that cycles, so the hightlite can be
enabled when required.


> Sent: Friday, November 06, 2020 at 4:48 PM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Defun Self Documentation
>
> > From: Anders Munch <ajm@flonidan.dk>
> > Date: Fri, 6 Nov 2020 15:33:27 +0000
> >
> > Eli Zaretskii wrote:
> > > Thanks for explaining your reasoning, but let's not forget that setting that to zero has a downside: if one types fast, it will slow down redisplay by delaying the response to the typing.
> >
> > There is less work to do because it happens 0.125 seconds later?
>
> No, because with zero value it happens immediately, and the extra work
> required to show the overlay will slow down Emacs.
>
> The display of the overlays to show the matching parentheses works
> with an idle timer, and that value is the amount of time Emacs should
> be idle before the parentheses are highlighted.  If you time fast,
> Emacs will never be idle for that much time, so the parentheses will
> not be highlighted while typing.  If you set the value to zero, the
> parentheses will be highlighted no matter how fast you type, so Emacs
> becomes less responsive to your typing.
>
> > > But of course, this is personal, which is why it is a user option.
> >
> > Sure, but we were talking about the default, and the 0.1 seconds is an actual
> > scientific result.
>
> I'm not sure the 0.1 number is relevant to this feature.  We are not
> talking about the reaction time, we are talking about the shortest
> time that indicates the user stopped typing.
>
>

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

Eli, it seems all said and done, you ended up on the downside of
every single point you brought up against me.

I was right to move you to the clueless, away from the punk
fucker, list.

Except not entirely, as you did say

  (show-paren-mode t)

which I changed into the more correct

  (show-paren-mode 1)

hm ... maybe I should add that comment as a footnote?

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

> Except not entirely, as you did say
>
>   (show-paren-mode t)
>
> which I changed into the more correct
>
>   (show-paren-mode 1)

WAIT - or was it the other way around?

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Emanuel Berg via Users list for the GNU Emacs text editor]

>> Except not entirely, as you did say
>>
>>   (show-paren-mode t)
>>
>> which I changed into the more correct
>>
>>   (show-paren-mode 1)
>
> WAIT - or was it the other way around?

I'm sorry Eli, because this unclarity we cannot rule you out from
the The Clueless Online Faculty. You stay on the list:

  https://dataswamp.org/~incal/CLUELESS-ONLINE

and, in the spirit of education, an Elisp version:

  (setq clueless-online-faculty '(eli-zaretskii))

-- 
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal

Re: Defun Self Documentation

[Eric S Fraga]

Please stop.  Thank you.
-- 
Eric S Fraga via Emacs 28.0.50 & org 9.4 on Debian bullseye/sid

Re: Defun Self Documentation

[Michael Heerdegen]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> Please stop.  Thank you.

Side perspective: Now he doesn't ignore his anger although we said he
should, and we also don't ignore it, although he said we should.

Michael.

Re: Defun Self Documentation

[Eli Zaretskii]

> Date: Mon, 09 Nov 2020 05:39:13 +0100
> From: Emanuel Berg via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org>
> 
> >> Except not entirely, as you did say
> >>
> >>   (show-paren-mode t)
> >>
> >> which I changed into the more correct
> >>
> >>   (show-paren-mode 1)
> >
> > WAIT - or was it the other way around?
> 
> I'm sorry Eli, because this unclarity we cannot rule you out from
> the The Clueless Online Faculty. You stay on the list:
> 
>   https://dataswamp.org/~incal/CLUELESS-ONLINE
> 
> and, in the spirit of education, an Elisp version:
> 
>   (setq clueless-online-faculty '(eli-zaretskii))

When you refuse to learn from comments by others on your code, you are
only hurting yourself, in the short and in the long run.  Adding
ad-hominem attacks doesn't change that basic truth.

Hopefully, others have read those comments and will draw their own
conclusions.  It is for them that I wrote those comments in the first
place.