A peek to the other side

A peek to the other side

[emacsq via Users list for the GNU Emacs text editor]

I tried making a Visual Studio Code extension to see how it could be make more emacs-like if I had to use it for something.

If you didn't you don't know how lucky you are with the integrated Elisp manual. It doesn't have an integrated manual, you have to browse a huge HTML file to find some API call :

https://code.visualstudio.com/api/references/vscode-api

And as usual with APIs (unlike Emacs' open system) you can only access what the developers expose via the API which is very limiting compared to Emacs.
You can't change everything, so you don't shoot yourself in the foot. I prefer Emacs' approach where I can even break the system, which is a great learning experience.

RE: [External] : A peek to the other side

[Drew Adams]

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

> If you didn't you don't know how lucky you are with the integrated
> Elisp manual. It doesn't have an integrated manual, you have to browse
> a huge HTML file to find some API call...

The built-in help and thorough-going introspection of
Emacs and Elisp are in fact outgrowths from Lisp and
the Lisp community.  Lisp has had this strength from
the outset.

And RMS has always had a strong will to keep Emacs
open and self-aware/self-documenting.  "Doc", in
multiple senses, has always been important to Emacs.
And Eli has continued this practice and direction.
We've all been lucky for such attention to doc/help.

> And as usual with APIs (unlike Emacs' open system) you can only access
> what the developers expose via the API which is very limiting compared
> to Emacs.

Yep, free, open code, down to the bit-level.  It's
free turtles all the way down.

IMO, even the notion of "internal" variable, function,
or other Lisp construct is a misnomer in Emacs.  (I'm
in a minority on this.)

That "internal" label can/should never mean more than
a _relative_ and rough indication of some imagined
probability that the thing might change.  Everything
might change, and nothing is really "internal".

Unfortunately, there's been more of a tendency in
recent years to "name-claim" more things to be
"internal", as if that somehow protected something or
someone (Emacs development/developers? Elisp users?).

As always (esp. with Lisp), some things whose creator
never thought of as possibly useful or needed outside
the initial context do find useful uses by _users_.

By using something thought/intended to be "internal",
users can discover real uses and put to the lie the
notion that the thing should be considered internal
or in some way restricted.

The tendency to think in strong black-&-white,
internal/external, baked/fluid, closed/open terms
comes also (I think) from the fact that developers
come to Emacs and Elisp from working with other, more
static/structured languages and environments - worlds
where there really can be a strong use and need for
an inside/outside separation and protecting coders
from themselves and code from itself (beyond purposes
of abstraction).

> You can't change everything, so you don't shoot yourself in the foot. I
> prefer Emacs' approach where I can even break the system, which is a
> great learning experience.

Indeed.  Not only learning for an individual, but
discovering and inventing for everyone.

[-- Attachment #2: winmail.dat --]
[-- Type: application/ms-tnef, Size: 14754 bytes --]

Re: [External] : A peek to the other side

[Stefan Monnier via Users list for the GNU Emacs text editor]

>> If you didn't you don't know how lucky you are with the integrated
>> Elisp manual. It doesn't have an integrated manual, you have to browse
>> a huge HTML file to find some API call...
> The built-in help and thorough-going introspection of
> Emacs and Elisp are in fact outgrowths from Lisp and
> the Lisp community.  Lisp has had this strength from
> the outset.

I don't know about the various forms of introspection, but at AFAIK
(none of this is 100% sure, sadly) in the specific case of docstrings,
this comes from TECO and I believe it was added to TECO by Richard while
working on the TECO version of Emacs.

> And RMS has always had a strong will to keep Emacs open and
> self-aware/self-documenting.  "Doc", in multiple senses, has always
> been important to Emacs.

While the GPL doesn't say anything about it, it's clear that's an
important part of empowering users, so it's closely linked to the ideals
of Free Software.

[ In a sense, the source code of a program is a kind of documentation of
  the corresponding assembly generated by the compiler.  ]

> Unfortunately, there's been more of a tendency in
> recent years to "name-claim" more things to be
> "internal", as if that somehow protected something or
> someone (Emacs development/developers? Elisp users?).

Note the strong difference between the "--" naming convention to
announce a function/var is internal, with the use of strong language
abstraction to make internal inaccessible.

Emacs is not in the business of preventing users from shooting
themselves in the foot, but we do try to make it easier for the users
not to shoot themselves in the foot, which is why we like to document
with "--" when a function is intended to be internal.


        Stefan

RE: [External] : A peek to the other side

[Drew Adams]

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

> > The built-in help and thorough-going introspection of
> > Emacs and Elisp are in fact outgrowths from Lisp and
> > the Lisp community.  Lisp has had this strength from
> > the outset.
> 
> I don't know about the various forms of introspection, but at AFAIK
> (none of this is 100% sure, sadly) in the specific case of docstrings,
> this comes from TECO and I believe it was added to TECO by Richard
> while working on the TECO version of Emacs.

Yes, but RMS was embedded in a culture of Lisp.  The
editor used at MIT then was TECO.  And unlike Interlisp
the MacLisp environment used editing etc. tools that
were outside Lisp itself.  The "open" approach to
editing, and to help in code editing, came from the use
(practice) of Lisp: interactive, live modification of code.

> > And RMS has always had a strong will to keep Emacs open and
> > self-aware/self-documenting.  "Doc", in multiple senses, 
> > has always been important to Emacs.
> 
> While the GPL doesn't say anything about it, it's clear that's an
> important part of empowering users, so it's closely linked to the
> ideals of Free Software.

Yes.

> [ In a sense, the source code of a program is a kind of documentation
>   of the corresponding assembly generated by the compiler. ]

Yes.  Even so, there's been no tendency in Emacs to
skimp on providing good doc and code comments.  IOW,
the availability of the source code isn't taken as an
excuse to not improve transparency by supplementing
code with doc.

> > Unfortunately, there's been more of a tendency in
> > recent years to "name-claim" more things to be
> > "internal", as if that somehow protected something or
> > someone (Emacs development/developers? Elisp users?).
> 
> Note the strong difference between the "--" naming convention to
> announce a function/var is internal, with the use of strong language
> abstraction to make internal inaccessible.

Yes, of course.  That's at least in the right direction.

And of course there's the even stronger difference
between providing source code and withholding it.  It's
about transparency and intentionally fostering it.

> Emacs is not in the business of preventing users from shooting
> themselves in the foot, but we do try to make it easier for the users
> not to shoot themselves in the foot, which is why we like to document
> with "--" when a function is intended to be internal.

Black-&-white.  Users are developers of Emacs, and its
developers are users.

Intention to be internal, as a _Note to (communal) self_
that XYZ might be fragile, or might need to change soon,
or has this limitation, or whatever, is better written
out specifically in comments or doc - saying why, in
what ways, under what conditions, etc.  Specifics,
reasons - think it out and express it explicitly.
Don't just label: `--'.

Just labeling something "internal" can do as much harm
as good (or more).  It's too easy to do and forget.
It takes no responsibility for communicating what's
going on - what's _behind_ the intention/judgment.
It's a crutchy, misleading label, at best (and worst)
providing (whom?) a false sense of security.

It essentially belies a perceived or intended/wished
separation between users ("lusers") and developers.
And that's a separation that free software ultimately
explodes, intentionally, explicitly, forthrightly.

At the very least, every use of `--' should have an
easily findable comment or doc, explaining what it's
about - why the labeler labeled it so.  A guess is
that if that guideline were adopted there'd be a lot
less gratuitous use (misuse) of `--'.  And updating
out-of-date `--' would be less problematic.  Today,
it's an irresponsible, easy "label `--' willy nilly,
and forget about it."
___

Just one opinion...

[-- Attachment #2: winmail.dat --]
[-- Type: application/ms-tnef, Size: 15802 bytes --]

Re: [External] : A peek to the other side

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> Date: Tue, 22 Feb 2022 18:25:44 +0000
> Cc: "'Help-Gnu-Emacs \(help-gnu-emacs@gnu.org\)'" <help-gnu-emacs@gnu.org>
> 
> At the very least, every use of `--' should have an
> easily findable comment or doc, explaining what it's
> about - why the labeler labeled it so.  A guess is
> that if that guideline were adopted there'd be a lot
> less gratuitous use (misuse) of `--'.  And updating
> out-of-date `--' would be less problematic.  Today,
> it's an irresponsible, easy "label `--' willy nilly,
> and forget about it."

You make it sound like we are too lazy to do this stuff, so we use a
cop-out.

Nothing is farther from the truth.  The free time we have to work on
Emacs is used to its last second.  There's only so much one can do in
a given time, and it is therefore wise to prioritize the jobs and do
the more important ones first.  Abundantly documenting APIs we
consider to be internal, not-for-use, subject-to-change-without-notice
is way down the priority list, that's all.  So we keep the
documentation of those to the absolute minimum: by using the "--"
indication, and we expect Emacs programmers to trust us on that.
Anything else would simply be a case of bad judgment and misuse of the
time we have to contribute.

Re: [External] : A peek to the other side

[Stefan Monnier via Users list for the GNU Emacs text editor]

> is way down the priority list, that's all.  So we keep the
> documentation of those to the absolute minimum: by using the "--"
> indication, and we expect Emacs programmers to trust us on that.

Actually, the explanation for "--" is often available in its full glory
by email anyway ;-)

> Anything else would simply be a case of bad judgment and misuse of the
> time we have to contribute.

And also of the time of people who read the code.


        Stefan

Re: [External] : A peek to the other side

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

Drew Adams wrote:

> Intention to be internal, as a _Note to (communal) self_
> that XYZ might be fragile, or might need to change soon, or
> has this limitation, or whatever, is better written out
> specifically in comments or doc - saying why, in what ways,
> under what conditions, etc. Specifics, reasons - think it
> out and express it explicitly. Don't just label: `--'.

Indeed, if it doesn't do anything it has no meaning ...

If it has meaning in the sense we hope it will be used
correctly by the guy writing the code and this meaning will
hopefully reach the guy reading the code and this meaning will
hopefully be correctly conveyed to him and hopefully acted
upon as intended then ... how often do we hope all that
will happen?

When it comes to humans, even a simple task like closing
a door or putting back a tool in its right place ... this
fails _at least_ one or two times out of five.

That kind of half-random stuff should never be built into
computers and programming languages ...

-- 
underground experts united
https://dataswamp.org/~incal

Re: [External] : A peek to the other side

[Arthur Miller]

Drew Adams <drew.adams@oracle.com> writes:

>> If you didn't you don't know how lucky you are with the integrated
>> Elisp manual. It doesn't have an integrated manual, you have to browse
>> a huge HTML file to find some API call...
>
> The built-in help and thorough-going introspection of
> Emacs and Elisp are in fact outgrowths from Lisp and
> the Lisp community.  Lisp has had this strength from
> the outset.
>
> And RMS has always had a strong will to keep Emacs
> open and self-aware/self-documenting.  "Doc", in
> multiple senses, has always been important to Emacs.
> And Eli has continued this practice and direction.
> We've all been lucky for such attention to doc/help.

+1 Yes, thanks guys!

>> And as usual with APIs (unlike Emacs' open system) you can only access
>> what the developers expose via the API which is very limiting compared
>> to Emacs.
>
> Yep, free, open code, down to the bit-level.  It's
> free turtles all the way down.
>
> IMO, even the notion of "internal" variable, function,
> or other Lisp construct is a misnomer in Emacs.  (I'm
> in a minority on this.)
>
> That "internal" label can/should never mean more than
> a _relative_ and rough indication of some imagined
> probability that the thing might change.  Everything
> might change, and nothing is really "internal".
>
> Unfortunately, there's been more of a tendency in
> recent years to "name-claim" more things to be
> "internal", as if that somehow protected something or
> someone (Emacs development/developers? Elisp users?).
>
> As always (esp. with Lisp), some things whose creator
> never thought of as possibly useful or needed outside
> the initial context do find useful uses by _users_.
>
> By using something thought/intended to be "internal",
> users can discover real uses and put to the lie the
> notion that the thing should be considered internal
> or in some way restricted.
>
> The tendency to think in strong black-&-white,
> internal/external, baked/fluid, closed/open terms
> comes also (I think) from the fact that developers
> come to Emacs and Elisp from working with other, more
> static/structured languages and environments - worlds
> where there really can be a strong use and need for
> an inside/outside separation and protecting coders
> from themselves and code from itself (beyond purposes
> of abstraction).

I don't think it is so white or black. It is more like, here is an API, we
promise it will stay stable, we won't change it, we make commitment to keep
those same in the future to keep your applicaiton stable too and minimize your
effort as an application writer. But for "private", of which "internal" is Elisp
version, there are no such compatibility guarantee. It can be that some code
bases are not so dedicated to keeping public APIs very stable, while others are
more rigorous in that regard. But yes, everything changes, nothing is written in
stone. 

>> You can't change everything, so you don't shoot yourself in the foot. I
>> prefer Emacs' approach where I can even break the system, which is a
>> great learning experience.

Yepp, indeed, I love doing this myself :-). 

> Indeed.  Not only learning for an individual, but
> discovering and inventing for everyone.

Yes, and that is great thing not just with Emacs or GNU/FSF software, but with
all open source software. It empowers everyone interested to become part of
development, not just those with money to invest in shiny new tchnologies
launched in recent years by big tech companies. Even those in poor contries
running on cheaper hardware can take the software, adapt it and use it, instead
of being marginalized by companies who don't see profit and thus reason to adapt
new shiny tech for such community of cheap old hardware.

Re: [External] : A peek to the other side

[Stefan Monnier via Users list for the GNU Emacs text editor]

> But for "private", of which "internal" is Elisp
> version, there are no such compatibility guarantee.

Actually, in some cases there may still be an implicit guarantee of
backward compatibility.  But it also means "if you need to use this,
please get back to us".


        Stefan

Re: [External] : A peek to the other side

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

Drew Adams wrote:

> The tendency to think in strong black-&-white,
> internal/external, baked/fluid, closed/open terms comes also
> (I think) from the fact that developers come to Emacs and
> Elisp from working with other, more static/structured
> languages and environments - worlds where there really can
> be a strong use and need for an inside/outside separation
> and protecting coders from themselves and code from itself
> (beyond purposes of abstraction).

If nothing in terms of technology separates them, no need to
invent something artificial that pretends to do that, if
that's what happens.

If an alien race of super-hackers conquered Earth, beings
that were totally ignorant about humans but could immediately
and fully understand any piece of code they were looking at
... would they see the same thing two times, or different
things one time each?

Interestingly we, who are still humans most of us, should use
the same method ...

-- 
underground experts united
https://dataswamp.org/~incal

Re: A peek to the other side

[Samuel Banya]

The only good thing about VS Code was that it created more LSP servers for LSP Mode.

Otherwise, spyware by default is not good for anyone (and yes, it is not easy for the average person to remove).

Still grateful for LSP Mode :) 

On Tue, Feb 22, 2022, at 2:11 AM, emacsq via Users list for the GNU Emacs text editor wrote:
> I tried making a Visual Studio Code extension to see how it could be make more emacs-like if I had to use it for something.
> 
> If you didn't you don't know how lucky you are with the integrated Elisp manual. It doesn't have an integrated manual, you have to browse a huge HTML file to find some API call :
> 
> https://code.visualstudio.com/api/references/vscode-api
> 
> And as usual with APIs (unlike Emacs' open system) you can only access what the developers expose via the API which is very limiting compared to Emacs.
> You can't change everything, so you don't shoot yourself in the foot. I prefer Emacs' approach where I can even break the system, which is a great learning experience.

Re: A peek to the other side

[Philip Kaludercic]

"Samuel Banya" <sbanya@fastmail.com> writes:

> The only good thing about VS Code was that it created more LSP servers for LSP Mode.
>
> Otherwise, spyware by default is not good for anyone (and yes, it is not easy for the average person to remove).

Not only that, but it pushes non-free "plug-ins" that break if you
decided to use a De-Microsofted version of the editor (I believe the
live-collaboration package, and remote access are examples of such
plug-ins, but there are also LSP servers like pylance that per license
are only allowed to be used with MS VS Code).

> Still grateful for LSP Mode :) 
>
> On Tue, Feb 22, 2022, at 2:11 AM, emacsq via Users list for the GNU Emacs text editor wrote:
>> I tried making a Visual Studio Code extension to see how it could be make more emacs-like if I had to use it for something.
>> 
>> If you didn't you don't know how lucky you are with the integrated Elisp manual. It doesn't have an integrated manual, you have to browse a huge HTML file to find some API call :
>> 
>> https://code.visualstudio.com/api/references/vscode-api
>> 
>> And as usual with APIs (unlike Emacs' open system) you can only access what the developers expose via the API which is very limiting compared to Emacs.
>> You can't change everything, so you don't shoot yourself in the foot. I prefer Emacs' approach where I can even break the system, which is a great learning experience.
>

-- 
	Philip Kaludercic

Re: A peek to the other side

[Samuel Banya]

Even to add to this though, all of these kind of token 'look at me' features that VS Code pushes has already been in use by things like 'tmux' for a while now.

They're just trying to make it 'simple' for the average person to just give in to using it within their ecosystem.

Good point though, I forgot about VS Codium, but that's kind of like the Ungoogled Chromium debate.

If you can't trust the main project, then, can you truly trust the forked one?

Anyway, just some things to think about.

On Tue, Feb 22, 2022, at 2:17 PM, Philip Kaludercic wrote:
> "Samuel Banya" <sbanya@fastmail.com> writes:
> 
> > The only good thing about VS Code was that it created more LSP servers for LSP Mode.
> >
> > Otherwise, spyware by default is not good for anyone (and yes, it is not easy for the average person to remove).
> 
> Not only that, but it pushes non-free "plug-ins" that break if you
> decided to use a De-Microsofted version of the editor (I believe the
> live-collaboration package, and remote access are examples of such
> plug-ins, but there are also LSP servers like pylance that per license
> are only allowed to be used with MS VS Code).
> 
> > Still grateful for LSP Mode :) 
> >
> > On Tue, Feb 22, 2022, at 2:11 AM, emacsq via Users list for the GNU Emacs text editor wrote:
> >> I tried making a Visual Studio Code extension to see how it could be make more emacs-like if I had to use it for something.
> >> 
> >> If you didn't you don't know how lucky you are with the integrated Elisp manual. It doesn't have an integrated manual, you have to browse a huge HTML file to find some API call :
> >> 
> >> https://code.visualstudio.com/api/references/vscode-api
> >> 
> >> And as usual with APIs (unlike Emacs' open system) you can only access what the developers expose via the API which is very limiting compared to Emacs.
> >> You can't change everything, so you don't shoot yourself in the foot. I prefer Emacs' approach where I can even break the system, which is a great learning experience.
> >
> 
> -- 
> Philip Kaludercic
> 
> 

Re: A peek to the other side

[Arthur Miller]

emacsq via Users list for the GNU Emacs text editor <help-gnu-emacs@gnu.org>
writes:

> I tried making a Visual Studio Code extension to see how it could be make more emacs-like if I had to use it for something.
>
> If you didn't you don't know how lucky you are with the integrated Elisp
> manual. It doesn't have an integrated manual, you have to browse a huge HTML
> file to find some API call :
>
> https://code.visualstudio.com/api/references/vscode-api
>
> And as usual with APIs (unlike Emacs' open system) you can only access what the
> developers expose via the API which is very limiting compared to Emacs.  You
> can't change everything, so you don't shoot yourself in the foot. I prefer
> Emacs' approach where I can even break the system, which is a great learning
> experience.

I definitely agree with you, and just the info manual, but the entire concept of
built-in help. Just having cursor somewhere in an s-expression and pressing C-h
f/v is for me really a time saver.

I think I have personally used Helpful a lot, which is another help package.
I think I have learned a lot from just looking at source code, since it displays
the source code of functions by default. I know you can press a button in
built-in help and be thrown into the source code, but it is much more convenient
to just see it without asking for it. As well as symbol property-list when
debugging, so I really suggest it as addition to built-in help.