Doubts: Lua basics chapter

[Humberto S. N. dos Anjos]

I've been having doubts about the utility of a separate Lua basics chapter. My main problem with it is that several subjects end up being spread about in different chapters. 

As an example, somebody which wants to embed Lua and has no previous knowledge has to read the Embedding Lua chapter in Part I (which, quoting from the current Table of Contents: "Covers bringing Lua in, not working with API. With a link for the embedding section (which covers API), and with comments on LJ2 specifics where aplicable."), and then skip quite a big chunk of the book to read about embedding Lua in C or other situations. Shouldn't all embedding-related topics be in one big chapter?

Shouldn't these basics just go in the beginning of the respective chapter, instead of splitting them into a separate chapter to hold them all?

The Perl Cookbook, for example, has this ToC:

Foreword 
Preface 
Chapter 1: Strings 
Chapter 2: Numbers 
Chapter 3: Dates and Times 
Chapter 4: Arrays 
Chapter 5: Hashes 
Chapter 6: Pattern Matching 
Chapter 7: File Access 
Chapter 8: File Contents 
Chapter 9: Directories 
Chapter 10: Subroutines 
Chapter 11: References and Records 
Chapter 12: Packages, Libraries, and Modules 
Chapter 13: Classes, Objects, and Ties 
Chapter 14: Database Access 
Chapter 15: User Interfaces 
Chapter 16: Process Management and Communication 
Chapter 17: Sockets 
Chapter 18: Internet Services 
Chapter 19: CGI Programming 
Chapter 20: Web Automation 

The basic stuff goes in an short Introduction section (something two pages, maybe three) at the beginning of each chapter, concentrating as much as possible all subject-related material under one single chapter. 

Adopting this would minimize jumping around for information, especially when one has a specific topic in mind ("where is that table trick again?"), and the introductions for each topic could be fleshed out a bit more; a few pages for each, instead of a few pages for everything. 

I have a few refactorings in mind:

* Lua basics (Part I, chapter 5), would be gone, and each topic would be put in its related chapter in Part II;

* Installing third-party modules (Part I, chapter 4) would become the first topics of Modules and Packaging (Part II, chapter 12);

* Instead of having a part dedicated to Lua C API (Part IV), that part would be called Embedding, and all Embedding-related chapters, such as Embedding Lua in your project (Part I, chapter 3) and Embedding (Part V, chapter 8) would be relocated to there.

What do you guys think?

[steve donovan]

On Sat, Jan 29, 2011 at 3:34 PM, Humberto S. N. dos Anjos
<h.a...@gmail.com> wrote:
> What do you guys think?

There is a lot of sense in this idea. If we have just spent several
pages talking about strings and the string API then it feels very
natural to continue with actual recipes for string manipulation. And
the same would go for tables.

However, consider functions. There are some recipes for using
functions (e.g. functional patterns) but this would be a minor section
as a _recipes chapter_; actually giving some serious background on
functions is important, because everything leans on this - recipes are
usually functions.

Or modules - key concept, but probably poor way to organize recipes.

So some introduction is useful; what it should cover, and what the
level should be, are other questions.

steve d.

[Peter Sommerfeld]

steve donovan wrote:
> So some introduction is useful; what it should cover, andwhat the level

> should be, are other questions.

That depends on what is intended with a Cookbook. I treat ist
as a bunch of informations and recipes regarding common tasks,
idioms and pitfalls, not as intro into the language. That is
covered by PIL quite well. Hence the intro schould wet the
appetite (Keyword: small, fast, embaddable, etc) and give an
overview of the book, not more. May be a condensed description
can be placed into an appendix.

That would mean that the cookbook ist located somewhere between
PIL(intro) and LPG (Lua programming Gems), aimed more to the
width and not that much the depth of the language.

Well, that is what I would expect from a cookbook. But
that are basic design decisions and may be seen very
different by others.

my 2 cents

Peter

[Humberto S. N. dos Anjos]

On Sun, Jan 30, 2011 at 9:31 AM, Peter Sommerfeld <pe...@sommerfeld-stur.at> wrote:

steve donovan wrote:

So some introduction is useful; what it should cover, andwhat the level should be, are other questions.

That depends on what is intended with a Cookbook. I treat ist
as a bunch of informations and recipes regarding common tasks,
idioms and pitfalls, not as intro into the language. That is
covered by PIL quite well. Hence the intro schould wet the
appetite (Keyword: small, fast, embaddable, etc) and give an
overview of the book, not more. May be a condensed description
can be placed into an appendix.

That would mean that the cookbook ist located somewhere between
PIL(intro) and LPG (Lua programming Gems), aimed more to the
width and not that much the depth of the language.

That's what I imagined for the Lua Cookbook as well. 

From Perl Cookbook's Preface:

This book isn't meant to be a complete reference book for Perl, although we do describe some parts of Perl previously undocumented. Having a copy of Programming Perl handy will allow you to look up the exact definition of an operator, keyword, or function. Alternatively, every Perl installation comes with over 1,000 pages of searchable, online reference materials. If those aren't where you can get at them, see your system administrator.

Neither is this book meant to be a bare-bones introduction for programmers who've never seen Perl before. That's what Learning Perl , a kinder and gentler introduction to Perl, is designed for. (If you're on a Microsoft system, you'll probably prefer the Learning Perl on Win32 Systems version.)

Instead, this is a book for learning more Perl. Neither a reference book nor a tutorial book, the Perl Cookbook serves as a companion book to both. It's for people who already know the basics but are wondering how to mix all those ingredients together into a complete program. Spread across 20 chapters and more than 300 focused topic areas affectionately called recipes, this book contains thousands of solutions to everyday challenges encountered by novice and journeyman alike.

(emphasis mine)

Programming in Lua already introduces Lua (like Learning Perl), and Lua's Reference Manual already documents Lua's features (like Programming Perl). What Lua lacks is precisely a cookbook (Lua Programming Gems helps, but it may be too advanced for a novice).

 

Well, that is what I would expect from a cookbook.

Same here.

 

But that are basic design decisions and may be seen very
different by others.

Exactly. Which is why I wanted to gather some feedback before mucking too much with the current Table of Contents :)

 

my 2 cents

Peter

[Humberto S. N. dos Anjos]

On Sun, Jan 30, 2011 at 6:17 AM, steve donovan <steve.j...@gmail.com> wrote:

On Sat, Jan 29, 2011 at 3:34 PM, Humberto S. N. dos Anjos
<h.a...@gmail.com> wrote:
> What do you guys think?

There is a lot of sense in this idea.  If we have just spent several
pages talking about strings and the string API then it feels very
natural to continue with actual recipes for string manipulation. And
the same would go for tables.

However, consider functions. There are some recipes for using
functions (e.g. functional patterns) but this would be a minor section
as a _recipes chapter_;  actually giving some serious background on
functions is important, because everything leans on this - recipes are
usually functions.

I envision the Lua Cookbook as an intermediary between PiL and Lua Gems, so I'm assuming the reader already knows enough to be able to read the examples :) 

What background on functions are you thinking about? What comes to mind right now is lexical scoping, upvalues, declaration (function foo() end == foo = function () end), local declaration (local function foo() end ~= local foo = function() end), mutually recursive local functions and setfenv. All of these can be mentioned in recipe form or in the chapter introduction. I'm not quite sure about the issue here...

 

Or modules - key concept,  but probably poor way to organize recipes.

Not sure what you mean; there are several things one can do with modules, even more now that the module function is considered harmful (at least not recommended :)) and alternatives should be used. Programming in Lua already teaches about the require function and how to create a module; Lua Cookbook could show different ways to create modules, pros and cons of each one, how to get new modules (put them in your LUA_PATH, LuaRocks). and several other module tricks.

Module-related information is currently spread between Installing third-party modules (Part I, chapter 4) and Modules and Packaging (Part II, chapter 12). One of my proposals is to fuse both of these into a single chapter. The end result seems pretty well organized to me, at least...

 

So some introduction is useful; what it should cover, and what the
level should be, are other questions.

My idea is to put a short introduction about specific features in the beginning of the corresponding chapter. An introduction for the whole book, on the other hand, should cover what's the purpose of the cookbook, what niche it fills, its basic organization and redirect the complete newbie to PiL. Only a few pages should be needed; an "enough talk, let's get down to business!" frame of mind, if you will :) 

[steve donovan]

On Sun, Jan 30, 2011 at 4:43 PM, Humberto S. N. dos Anjos
<h.a...@gmail.com> wrote:
> foo = function() end), mutually recursive local functions and setfenv. All
> of these can be mentioned in recipe form or in the chapter introduction. I'm
> not quite sure about the issue here...

I do think that these things need to be put in an introduction, the
question is does that introduction sit in the appropriate recipes
chapter? Can a core concept be explained using a recipe, given that a
recipe has to be useful? For me, a recipe does a job, no matter how
simple, for instance, 'copy a table'. So a recipe that uses a
particular technique to do OOP (such as metatables) must provide a
class that people can copy into programs and use.

I still think that it's sometimes useful to write first and think
second ;) This sounds terribly unscientific - think of it as
'bottom-up' development if it helps. I aim to keep writing, since I
find this more entertaining than talking about structure. Since I am a
professional, I don't particularly mind the content being subsequently
re-arranged into another structure. If there remains introductory
material that doesn't fit, well then it can be put somewhere else.

The relation PiL <= cookbook < LPG is a useful starting point,
however. But there are people who find PiL hard-going in places ...
these are not us, of course, but neither are they fools that shouldn't
be allowed near a computer.

steve d.

[Peter Sommerfeld]

Am 30.01.2011, 16:24 Uhr, schrieb steve donovan
<steve.j...@gmail.com>:

> I aim to keep writing, since I find this more entertainingthan talking
> about structure.

Of course, those who finally make and write the book
have to decide, I'm not one of these. But some feedback
as well as brainstorming was requested, that's all.

Peter

[steve donovan]

On Sun, Jan 30, 2011 at 5:34 PM, Peter Sommerfeld
<pe...@sommerfeld-stur.at> wrote:
> Of course, those who finally make and write the book
> have to decide, I'm not one of these. But some feedback
> as well as brainstorming was requested, that's all.

Sorry, Peter I am not being very helpful. Such brainstorming and
discussions about level & structure are important.

At the moment I like writing, I find it relaxing ;) Nothing more than
that. The order-out-of-chaos part of my brain will probably return in
a few days.

I am interested in how to define the level of the book, because it's
not as easy as saying 'Go away and read PiL and then come back!'. But
on the other hand, we have to assume
people come from _somewhere_.

steve d.

[Humberto S. N. dos Anjos]

On Sun, Jan 30, 2011 at 3:48 PM, steve donovan <steve.j...@gmail.com> wrote:

1:24 PM,

I do think that these things need to be put in an introduction, the
question is does that introduction sit in the appropriate recipes
chapter?  Can a core concept be explained using a recipe, given that a
recipe has to be useful?  For me, a recipe does a job, no matter how
simple, for instance, 'copy a table'.  So a recipe that uses a
particular technique to do OOP (such as metatables) must provide a 

class that people can copy into programs and use.

 

I agree with your recipe definition. What I meant is that core concepts can be quickly explained in the chapter introduction (again, assuming a PiL-literate-newbie) and then some entry-level recipes can be made which take advantage of that core concept. For example, the fact that local function foo() end == local foo; foo = function () end can be exploited to build mutually recursive local functions:

local foo, bar

-- function foo() end is the same as foo = function () end, remember?

function foo() return bar() end

function bar() return foo() end

PiL <= cookbook < Gems means there's a whole spectrum of complexity that recipes can have. Entry-level recipes can be used to demonstrate interesting consequences of how the core concepts work. Lua 5.2's _ENV definitely allows some cool tricks...

The relation PiL <= cookbook < LPG is a useful starting point,
however. But there are people who find PiL hard-going in places ...
these are not us, of course, but neither are they fools that shouldn't
be allowed near a computer.

Which places? That's something a cookbook could definitely help smooth out. 

  

On Sun, Jan 30, 2011 at 3:48 PM, steve donovan <steve.j...@gmail.com> wrote: 

I am interested in how to define the level of the book, because it's
not as easy as saying 'Go away and read PiL and then come back!'.  But
on the other hand, we have to assume
people come from _somewhere_.

I agree; that's why I'm assuming folks came from PiL :)

[Peter Sommerfeld]

Am 30.01.2011, 18:48 Uhr, schrieb steve donovan
<steve.j...@gmail.com>:

> At the moment I like writing, I find it relaxing ;)

Relax Steve! :-)

> I am interested in how to define the level of the book, because it's

> not as easy as saying 'Go away and read PiL and then come back!'.But on

> the other hand, we have to assume people come from _somewhere_.

I think you should assume that people had read PIL before or
at least had a deep look into the manual and already got a
first impression of the language. Probably they have already
tinkered a bit with it and are now looking for *more* infos.
Hence I see no need to introduce into the very basics. I also
think that topics like installation are superfluous for the
same reason.

Personally I find it annoying when I buy a computer book and
1/4 or more of it repeats what other books I have already cover.
To actually sell a book you have to place it carefully

IMHO of course...

Peter

[Humberto S. N. dos Anjos]

On Sun, Jan 30, 2011 at 5:56 PM, Peter Sommerfeld <pe...@sommerfeld-stur.at> wrote:

I also think that topics like installation are superfluous for the
same reason.

Yeah, about that... If we're assuming basic PiL literacy, then Lua is probably already present in the reader's machine. But given that Lua isn't as omnipresent as Perl (the cookbook could assume Perl was just "there"), some words about how to get Lua or build Lua from source would be very useful (a Part 0, if you will). Alternative implementations (LuaJIT, Java, .NET, Flash - didn't know about that one) could be alluded to in the beginning and fleshed out later.

But that's other thread :)

[steve donovan]

On Sun, Jan 30, 2011 at 8:47 PM, Humberto S. N. dos Anjos
<h.a...@gmail.com> wrote:
> I agree with your recipe definition. What I meant is that core concepts can
> be quickly explained in the chapter introduction (again, assuming a
> PiL-literate-newbie) and then some entry-level recipes can be made which
> take advantage of that core concept.

That's a nice example, and does illustrate your point, and I agree.
It's just a question of how much introductory material, then.

> recipes can have. Entry-level recipes can be used to demonstrate interesting
> consequences of how the core concepts work. Lua 5.2's _ENV definitely allows
> some cool tricks...

By necessity we are going to have to highlight the differences - _ENV
versus setfenv, etc. Lua 5.1 remains the main target, if only because
LuaJIT is increasingly going to be the power implementation of Lua,
particularly in production.

> Which places? That's something a cookbook could definitely help smooth out.

I wish I knew! Here we need to canvas the opinion of people who are
new to Lua but no stranger to other languages (Mr Litt, you out there?
;)) There is an (apparently) true story about a Nobel laureate
physicist visiting a biology lab and saying 'assume zero knowledge and
infinite intelligence'. Which says a lot about the arrogance of
physicists, but also indicates a style of introduction where the idea
is to map Lua concepts onto the concepts of other languages.

A survival course, if you like ...

steve d.

[steve donovan]

On Sun, Jan 30, 2011 at 9:56 PM, Peter Sommerfeld
<pe...@sommerfeld-stur.at> wrote:
> Relax Steve! :-)

Good, because maybe I was coming across as being high and mighty!

> I think you should assume that people had read PIL before or
> at least had a deep look into the manual and already got a
> first impression of the language.

Yes, you have to assume _something_ about the level. It is certainly
not an introduction to programming! People already come knowing about
the basic data structures, and we show how tables can cover the lot.
Terms like 'array' or 'dictionary' are foreign terms to Lua, but well
established concepts in computer science.

> Personally I find it annoying when I buy a computer book and
> 1/4 or more of it repeats what other books

Yes, we all know those - I think if one is going to introduce a topic
it has to be rigorous. The goal is achieved when the explanation is
mostly about concrete recipes and does not dominate.

Although, something to think about: we are probably not the core
audience for the book...

steve d.

[Humberto S. N. dos Anjos]

Well, the thread seems to have gently quieted down, so I'll adjust the table of contents as suggested here. It's version controlled, so no worries there :)

[Alexander Gladysh]

On Sun, Jan 30, 2011 at 17:09, Humberto S. N. dos Anjos
<h.a...@gmail.com> wrote:
> That depends on what is intended with a Cookbook.

Саn someone please update this page with the aftermath of this discussion?

https://github.com/lua-cookbook/lua-cookbook/wiki/The-Purpose

(It will later be transformed into abstract or foreword or whatever.)

Thanks,
Alexander.

[Alexander Gladysh]

Please do continue to provide feedback and brainstorming, it is very useful!

Alexander.

[Alexander Gladysh]

Please do not hesitate to do that.

Alexander.

[Alexander Gladysh]

On Mon, Jan 31, 2011 at 11:38, steve donovan <steve.j...@gmail.com> wrote:
>  There is an (apparently) true story about a Nobel laureate
> physicist visiting a biology lab and saying 'assume zero knowledge and
> infinite intelligence'.

Wasn't it Feynman?

Alexander.

[steve donovan]

On Sat, Feb 5, 2011 at 12:59 AM, Alexander Gladysh <agla...@gmail.com> wrote:
> Wasn't it Feynman?

It does sound like the kind of thing he would say...

Feynman of course is also famous for loving bongo drums and Brazil.

He was one of the first concurrent programmers in his young days on
the Manhattan project, although his instruction pipelines consisted of
girls with mechanical calculators.

steve d.

[Alexander Gladysh]

On Sat, Feb 5, 2011 at 10:12, steve donovan <steve.j...@gmail.com> wrote:
> On Sat, Feb 5, 2011 at 12:59 AM, Alexander Gladysh <agla...@gmail.com> wrote:
>> Wasn't it Feynman?

> It does sound like the kind of thing he would say...

Right, Google tells me that it was Leo Szilard. The accurate quote is:
"Assume infinite intelligence and zero prior knowledge". (But Leo
Szilard is not Nobel laureate, according to Wikipedia.)

Feynman could not say this because he did some biology before he got
Nobel prize, so his knowledge could not be zero.

> Feynman of course is also famous for loving bongo drums and Brazil.

> He was one of the first concurrent programmers in his young days on
> the Manhattan project, although his instruction pipelines consisted of
> girls with mechanical calculators.

I like the concurrent punchcards case more. :-)

Alexander.