[Proposal] Simplified Lua Reference

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

[Proposal] Simplified Lua Reference

Soni "They/Them" L.
The Lua reference manual includes things like BNF everywhere and some
stuff like "they can be used to represent ordinary arrays, lists, symbol
tables, sets, records, graphs, trees, etc."

It seems like a good idea to have a reference manual that translates the
BNF to english in a way that's easy for someone who doesn't know
programming to understand, and maybe omits things like the above, as
they add unnecessary complexity.

And arguably the stuff like "they can be used to represent ordinary
arrays, lists, symbol tables, sets, records, graphs, trees, etc." isn't
a good fit for a reference manual anyway, but mainly this is about the BNF.
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Paul Ducklin
I’m not sure what you are describing is a “reference manual”.

Sounds like you are after an introductory guide, maybe?

There’s the excellent Programming in Lua book for learning about the language, but it’s not free and not brief. (There’s an old version available online for free but it is based on Lua 5.0, which is a bit dated these days.)

There are also various quick reference guides written over the years by contributors on this list... maybe one of those might be helpful?

> On 20 Sep 2020, at 17:24, Soni They/Them L. <[hidden email]> wrote:
>
> The Lua reference manual includes things like BNF everywhere and some
> stuff like "they can be used to represent ordinary arrays, lists, symbol
> tables, sets, records, graphs, trees, etc."
>
> It seems like a good idea to have a reference manual that translates the
> BNF to english in a way that's easy for someone who doesn't know
> programming to understand, and maybe omits things like the above, as
> they add unnecessary complexity.
>
> And arguably the stuff like "they can be used to represent ordinary
> arrays, lists, symbol tables, sets, records, graphs, trees, etc." isn't
> a good fit for a reference manual anyway, but mainly this is about the BNF.
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Marcus Mason
In reply to this post by Soni "They/Them" L.
I do not mean this to sound rude in any way but the reference manual is for people who understand programming. A lot of the content is very technical and this is why there are other resources such as Programming in Lua available for people who want to learn the language. Perhaps a modernization of some of lua's resources like the wiki could help ease newer people into understanding / learning the syntax more easily.

On Sun, Sep 20, 2020 at 5:24 PM Soni "They/Them" L. <[hidden email]> wrote:
The Lua reference manual includes things like BNF everywhere and some
stuff like "they can be used to represent ordinary arrays, lists, symbol
tables, sets, records, graphs, trees, etc."

It seems like a good idea to have a reference manual that translates the
BNF to english in a way that's easy for someone who doesn't know
programming to understand, and maybe omits things like the above, as
they add unnecessary complexity.

And arguably the stuff like "they can be used to represent ordinary
arrays, lists, symbol tables, sets, records, graphs, trees, etc." isn't
a good fit for a reference manual anyway, but mainly this is about the BNF.
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Soni "They/Them" L.


On 2020-09-21 9:48 a.m., Marcus Mason wrote:
> I do not mean this to sound rude in any way but the reference manual
> is for people who understand programming. A lot of the content is very
> technical and this is why there are other resources such as
> Programming in Lua available for people who want to learn the
> language. Perhaps a modernization of some of lua's resources like the
> wiki could help ease newer people into understanding / learning the
> syntax more easily.

Programming in Lua is written for ppl who can follow tutorials, it
doesn't work for a whole bunch of other ppl.

Stripping the reference manual down to the bare minimum, with no BNF
requirements, would help those ppl.

>
> On Sun, Sep 20, 2020 at 5:24 PM Soni "They/Them" L. <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     The Lua reference manual includes things like BNF everywhere and some
>     stuff like "they can be used to represent ordinary arrays, lists,
>     symbol
>     tables, sets, records, graphs, trees, etc."
>
>     It seems like a good idea to have a reference manual that
>     translates the
>     BNF to english in a way that's easy for someone who doesn't know
>     programming to understand, and maybe omits things like the above, as
>     they add unnecessary complexity.
>
>     And arguably the stuff like "they can be used to represent ordinary
>     arrays, lists, symbol tables, sets, records, graphs, trees, etc."
>     isn't
>     a good fit for a reference manual anyway, but mainly this is about
>     the BNF.
>
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Marcus Mason
The reference manual is the technical specification of the language system. There is no other document that goes into those details. A BNF grammar (or any other unambiguous* way of describing a syntax) belongs in such a place.

If you wish to write/propose what amounts to a cheat sheet/quick start (no negative connotations implied here) for people who just want to know quickly a few things to write some code no one would object, I believe a lot of languages nowadays use that to basically advertise to potential users.

On Mon, Sep 21, 2020 at 2:03 PM Soni "They/Them" L. <[hidden email]> wrote:


On 2020-09-21 9:48 a.m., Marcus Mason wrote:
> I do not mean this to sound rude in any way but the reference manual
> is for people who understand programming. A lot of the content is very
> technical and this is why there are other resources such as
> Programming in Lua available for people who want to learn the
> language. Perhaps a modernization of some of lua's resources like the
> wiki could help ease newer people into understanding / learning the
> syntax more easily.

Programming in Lua is written for ppl who can follow tutorials, it
doesn't work for a whole bunch of other ppl.

Stripping the reference manual down to the bare minimum, with no BNF
requirements, would help those ppl.

>
> On Sun, Sep 20, 2020 at 5:24 PM Soni "They/Them" L. <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>     The Lua reference manual includes things like BNF everywhere and some
>     stuff like "they can be used to represent ordinary arrays, lists,
>     symbol
>     tables, sets, records, graphs, trees, etc."
>
>     It seems like a good idea to have a reference manual that
>     translates the
>     BNF to english in a way that's easy for someone who doesn't know
>     programming to understand, and maybe omits things like the above, as
>     they add unnecessary complexity.
>
>     And arguably the stuff like "they can be used to represent ordinary
>     arrays, lists, symbol tables, sets, records, graphs, trees, etc."
>     isn't
>     a good fit for a reference manual anyway, but mainly this is about
>     the BNF.
>
Reply | Threaded
Open this post in threaded view
|

RE: [Proposal] Simplified Lua Reference

colevalleygirl@colevalleygirl.co.uk
In reply to this post by Soni "They/Them" L.
" Stripping the reference manual down to the bare minimum, with no BNF requirements, would help those ppl."

And make life harder for experienced programmers who need the exactitude of the BNF notation.

Sounds like you're asking for a third set of documentation, for people who can't programme and can't follow tutorials.  But reducing the precision of the Lua Reference manual is not the way to go.


-----Original Message-----
From: Soni "They/Them" L. <[hidden email]>
Sent: 21 September 2020 14:03
To: [hidden email]
Subject: Re: [Proposal] Simplified Lua Reference



On 2020-09-21 9:48 a.m., Marcus Mason wrote:
> I do not mean this to sound rude in any way but the reference manual
> is for people who understand programming. A lot of the content is very
> technical and this is why there are other resources such as
> Programming in Lua available for people who want to learn the
> language. Perhaps a modernization of some of lua's resources like the
> wiki could help ease newer people into understanding / learning the
> syntax more easily.

Programming in Lua is written for ppl who can follow tutorials, it doesn't work for a whole bunch of other ppl.

Stripping the reference manual down to the bare minimum, with no BNF requirements, would help those ppl.

Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Roberto Ierusalimschy
In reply to this post by Soni "They/Them" L.
> Programming in Lua is written for ppl who can follow tutorials, it
> doesn't work for a whole bunch of other ppl.
>
> Stripping the reference manual down to the bare minimum, with no BNF
> requirements, would help those ppl.

I am not sure what is your point here. Do you want permission to do
that? You do not need permission. The manual shares the Lua license; you
can fork it freely. If you think that can help some people, by all means,
go ahead.

-- Roberto
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Paul E. Merrell, J.D.
In reply to this post by Soni "They/Them" L.
What I've suggested in the past is another version of the Reference
Manual with, e.g., one section per page, with a commenting system such
that people could post links to wiki pages, example code, concise
tutorials, etc.

Longer tutorials that are an introduction for beginners never seem to
get finished. I've run across five or so on the web that just sit
there, great beginnings all but all neglected afterward.

I couldn't agree more that there is a void here that needs to be
filled. Learning to program with Lua is a pain in the bohunkus if you
don't come to the language with programming skills.

There seems to be an attitude on the list that skilled programmers'
documentation needs must be met but that there is no need to help
those learn to use Lua who lack programming skills. Not meaning to
offend, but it comes across as an elitist attitude, that Lua need not
be user-friendly for the uninitiated.

My 2 cents.

Best regards,

Paul

--
[Notice not included in the above original message:  The U.S. National
Security Agency neither confirms nor denies that it intercepted this
message.]
                                                ¯\_(ツ)_/¯
Reply | Threaded
Open this post in threaded view
|

RE: [Proposal] Simplified Lua Reference

Tom Becker
Teaching people how to program is hard. People's minds work in different ways. Some people are better with abstractions, others are better with concrete examples. People also have different life experiences, talents, and interests. There is no one right way, but rather a need for many ways to enable people to learn. Realistically, we should not expect the creators of a language to also do all the work of teaching it in all possible ways. Lua at least has good documentation explaining its principles of operation. Many languages lack that. It makes the job easier for anyone who wants to create Lua learning materials for new programmers.

Tom

-----Original Message-----
From: Paul Merrell <[hidden email]>
Sent: Monday, September 21, 2020 12:31 PM
To: Lua mailing list <[hidden email]>
Subject: Re: [Proposal] Simplified Lua Reference

EXTERNAL EMAIL - Use caution opening attachments and links.

What I've suggested in the past is another version of the Reference Manual with, e.g., one section per page, with a commenting system such that people could post links to wiki pages, example code, concise tutorials, etc.

Longer tutorials that are an introduction for beginners never seem to get finished. I've run across five or so on the web that just sit there, great beginnings all but all neglected afterward.

I couldn't agree more that there is a void here that needs to be filled. Learning to program with Lua is a pain in the bohunkus if you don't come to the language with programming skills.

There seems to be an attitude on the list that skilled programmers'
documentation needs must be met but that there is no need to help those learn to use Lua who lack programming skills. Not meaning to offend, but it comes across as an elitist attitude, that Lua need not be user-friendly for the uninitiated.

My 2 cents.

Best regards,

Paul

--
[Notice not included in the above original message:  The U.S. National Security Agency neither confirms nor denies that it intercepted this message.]
                                                ¯\_(ツ)_/¯
*******************************************************************
IMPORTANT MESSAGE FOR RECIPIENTS IN THE U.S.A.:
This message may constitute an advertisement of a BD group's products or services or a solicitation of interest in them. If this is such a message and you would like to opt out of receiving future advertisements or solicitations from this BD group, please forward this e-mail to [hidden email]. [BD.v1.0]
*******************************************************************
This message (which includes any attachments) is intended only for the designated recipient(s). It may contain confidential or proprietary information and may be subject to the attorney-client privilege or other confidentiality protections. If you are not a designated recipient, you may not review, use, copy or distribute this message. If you received this in error, please notify the sender by reply e-mail and delete this message. Thank you.
*******************************************************************
Corporate Headquarters Mailing Address: BD (Becton, Dickinson and Company) 1 Becton Drive Franklin Lakes, NJ 07417 U.S.A.
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Paul E. Merrell, J.D.
On Mon, Sep 21, 2020 at 1:01 PM Tom Becker <[hidden email]> wrote:
>
> Teaching people how to program is hard. People's minds work in different ways. Some people are better with abstractions, others are better with concrete examples. People also have different life experiences, talents, and interests. There is no one right way, but rather a need for many ways to enable people to learn. Realistically, we should not expect the creators of a language to also do all the work of teaching it in all possible ways. Lua at least has good documentation explaining its principles of operation. Many languages lack that. It makes the job easier for anyone who wants to create Lua learning materials for new programmers.

The problem is that no one has done that since Lua v. 5.1. Lots of
starts, no finishes. The result: Lua is a programming language for
experienced programmers, not for those who wish to learn to program
using Lua, especially those users whose apps have embedded Lua.

I see it all the time on the NoteCase Pro outliner mailing list.
Despite having an API with 393 functions, 36 event triggers, massive
extensibility, etc., we have only about a half-dozen or so visible
users who script the program with our embedded Lua.

There's a big unmet need here.

Best regards,

Paul


--
[Notice not included in the above original message:  The U.S. National
Security Agency neither confirms nor denies that it intercepted this
message.]
                                                ¯\_(ツ)_/¯
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Robert Burke
In reply to this post by Paul E. Merrell, J.D.
It is troubling that by default, when searching the web for "how do I
do a thing in lua" you are likely to end up on a wiki page that hosts
a debate about how to implement the thing, a collection of
implementations, and criticisms of ways in which those implementations
do not work as expected. Often it would be nicer to end up on the
reference manual or on some resource that provides an implementation
and clearly explains what versions of Lua it works under and what
behavior it has for various cases.

I worry a little that a living collaborative resource would suffer a
similar fate.

On Tue, Sep 22, 2020 at 4:31 AM Paul Merrell <[hidden email]> wrote:

>
> What I've suggested in the past is another version of the Reference
> Manual with, e.g., one section per page, with a commenting system such
> that people could post links to wiki pages, example code, concise
> tutorials, etc.
>
> Longer tutorials that are an introduction for beginners never seem to
> get finished. I've run across five or so on the web that just sit
> there, great beginnings all but all neglected afterward.
>
> I couldn't agree more that there is a void here that needs to be
> filled. Learning to program with Lua is a pain in the bohunkus if you
> don't come to the language with programming skills.
>
> There seems to be an attitude on the list that skilled programmers'
> documentation needs must be met but that there is no need to help
> those learn to use Lua who lack programming skills. Not meaning to
> offend, but it comes across as an elitist attitude, that Lua need not
> be user-friendly for the uninitiated.
>
> My 2 cents.
>
> Best regards,
>
> Paul
>
> --
> [Notice not included in the above original message:  The U.S. National
> Security Agency neither confirms nor denies that it intercepted this
> message.]
>                                                 ¯\_(ツ)_/¯
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Paul E. Merrell, J.D.


On Mon, Sep 21, 2020 at 11:51 PM Robert Burke <[hidden email]> wrote:
It is troubling that by default, when searching the web for "how do I
do a thing in lua" you are likely to end up on a wiki page that hosts
a debate about how to implement the thing, a collection of
implementations, and criticisms of ways in which those implementations
do not work as expected. Often it would be nicer to end up on the
reference manual or on some resource that provides an implementation
and clearly explains what versions of Lua it works under and what
behavior it has for various cases.

I worry a little that a living collaborative resource would suffer a
similar fate.

So 'twould be better that beginners get no guidance at all?

Best regards,

Paul
 
--
[Notice not included in the above original message:  The U.S. National Security Agency neither confirms nor denies that it intercepted this message.]
                                                ¯\_(ツ)_/¯
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Robert Burke
> So 'twould be better that beginners get no guidance at all?
>

Certainly not. It just seems like this proposal is an incremental
improvement to the existing thing, and I would like a much different
thing.
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

Paul E. Merrell, J.D.


On Tue, Sep 22, 2020 at 11:01 PM Robert Burke <[hidden email]> wrote:

Certainly not. It just seems like this proposal is an incremental
improvement to the existing thing, and I would like a much different
thing.

I would love to see another beginners' book written like the one for Lua v. 5.1. [1] But all we have are cursory or abandoned projects for Lua beginners. [2], [3], [4], [5] Another such book would be my ideal. But to my knowledge, no one is working on that. And I've written books before; it's a painful amount of work. I'm not expecting anyone to volunteer for such a task. 

I've been rooting for an annotatable version of the Reference Manual because it would be a lot less work to get started and the work could proceed incrementally. For example, Dirk Laurie has a good start on a glossary that could be linked to terms in the Manual, to make it more understandable for beginners who aren't familiar with the language involved. [6] And there are lots of wiki pages that could be linked, with a lot of example code snippets available scattered around the Web that could also be linked. E.g., [7].

Would it be ideal? Far from it. But it provides an organizing framework for annotations. And I think it would be far more useful to beginners than what we have now. 

Best regards,

Paul




 


[7]. Category: Lua, at RosettaCode.org. Hundreds of Lua code snippets   
Lua Cookbook, at GitHub Social Coding. Still in the planning stages but bookmarked here to check later.  
Lua Snippets at http://snippets.luacode.org/. More than 100 high-quality Lua snippets.
Lua Tutorial Directory at Lua-users.org. Good tutorials, lots of snippets.
MUSHclient Lua forum. Web forum for a game implementation of Lua, with excellent Lua tutorials and a multitude of code snippets.  
Pastebin.com. Include "lua" in your search query. Caution: Some content on Pastebin.com disappears quickly. Clip and save any useful snippets you find there.
Sample Code at the Lua-users.org wiki. Meta-index to sample Lua code on the web site.
Snipplr Lua code snippets.
Stack Overflow. Answers to about 750 Lua questions as of 25 January, 2011, often including Lua snippets. Include "lua" in your site search query.   
--
[Notice not included in the above original message:  The U.S. National Security Agency neither confirms nor denies that it intercepted this message.]
                                                ¯\_(ツ)_/¯
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Simplified Lua Reference

DarkWiiPlayer
In reply to this post by Soni "They/Them" L.
A while ago I attempted to start writing a very simple Lua tutorial, but
didn't get beyond creating a github repo. If anybody feels like writing
a bunch of things down, feel free to create a PR at
github.com/luaScripters/tutorial. There's no need to write whole
sections or full tutorials; if you feel like explaining a single topic,
that also helps. Maybe some day I get around to writing some stuff myself 🤷

On 20/09/2020 18:24, Soni "They/Them" L. wrote:

> The Lua reference manual includes things like BNF everywhere and some
> stuff like "they can be used to represent ordinary arrays, lists, symbol
> tables, sets, records, graphs, trees, etc."
>
> It seems like a good idea to have a reference manual that translates the
> BNF to english in a way that's easy for someone who doesn't know
> programming to understand, and maybe omits things like the above, as
> they add unnecessary complexity.
>
> And arguably the stuff like "they can be used to represent ordinary
> arrays, lists, symbol tables, sets, records, graphs, trees, etc." isn't
> a good fit for a reference manual anyway, but mainly this is about the BNF.