Re: Lua Programming wikibook

[Mark Otaris <mark.otaris@...>]

You’re right that coverage of the C API wouldn’t fit with the rest of
the chapters: there’s no place one can reasonably put it in the flow,
except at the end, because you cannot understand the C API without
first having understood everything else except the standard libraries.
In fact, the Lua Reference Manual does exactly this: it puts
discussion of the C API in the last chapter before standard libraries.

I think coverage of the C API would be very valuable, and the best
place to include such coverage is in an appendix that could be
referred to from various places in the book. Regardless, I do not
think I have the knowledge required to write such an appendix.

I agree that variables should be discussed in the chapter about
expressions. I described them there because there was not much that
could be said about them before covering assignment. I don’t know how
to split the assignment section to put the coverage of variables in
the chapter about expressions.

The bit on chunks and blocks was added because they’re often mentioned
in the reference manual, Programming in Lua, and other places. Had it
not been because they are often referred to, I would probably have
omitted them completely, because I find them a bit confusing.

The chapter about the standard libraries was added because I needed a
place to discuss things I had no other place to cover, so you are very
right in saying that it could be called "Miscellany". Ideally, all of
the functions provided by Lua would be described conceptually in
various places in the book. However, this is not possible or desirable
in all cases, so having a separate chapter can be useful for some
things.

Finally, you’re also right about the introduction, although I’m not
sure what you mean by "history text" (but I think I get the idea). It
is a bit different from the rest of the book: it introduces and
describes Lua, and, at the same time, attempts to explain what a
programming language is, and attempts to give a good understanding of
how syntax, programming or the like work. The point is that explaining
these things correctly to a non programmer is difficult. The
introduction is clearly not ideal, but I could rewrite it twenty
times, get a very different result every time, and still not have an
introduction that is ideal.

If you want more theory from this book, I suggest you look at the
glossary; it's theory, but in a condensed form.

On Thu, Jun 19, 2014 at 6:50 PM, Aaron Faanes <dafrito@gmail.com> wrote:
> On Thu, Jun 19, 2014 at 2:47 PM, Mark Otaris <mark.otaris@gmail.com> wrote:
>>
>> I have started writing, in January 2013, a book I have called "Lua
>> Programming", which I have published on Wikibooks. This book is now
>> complete, and I am announcing it here to make it known to people who
>> could be interested in reading it or contributing to it. Since
>> Wikibooks is a collaborative project (in many ways like Wikipedia, but
>> with, as its purpose, to create educative textbooks), anyone can
>> contribute to the books it hosts, and this includes this book.
>>
>> Many other languages (Haskell, Python, Java, PHP, JavaScript, Ruby,
>> and others) have a textbook on Wikibooks, and I wanted Lua to have one
>> as well. I think this book is valuable in particular because it is
>> available to read for free on the web and is released under a free
>> license (Creative Commons Attribution-ShareAlike), because it has a
>> general focus, and because it does not assume any programming
>> experience, while containing content meant for people of all levels.
>>
>> At the moment, the focus is given to the usage of the language itself
>> (the syntax and the libraries) because that's what I know best. There
>> is no documentation of the C API or of more internal or technical
>> details; this is something that is really missing and I hope someone
>> will fill this gap one day.
>>
>> The book is available at this address:
>> https://en.wikibooks.org/wiki/Lua_Programming
>>
>
> Wow! This is impressive work. :)
>
> Having read (or at least skimmed vigorously) the whole thing, it really does
> seem well done. The organization is clear, and the chapters cover their
> material well. I was disappointed initially when you mentioned you didn't
> cover the C API, but after having seen the whole thing, I don't think it
> would fit well with the rest.
>
> --- Introduction
> Informative, but it reads a bit like a history text. I ended up wishing it
> would be closer to the style of the rest of the book.
>
> --- Expressions
> I liked this chapter, because I like the discussion around the types and
> what can be done with them, rather than just listing them out. There's also
> good reference here and some code examples, which keeps things interesting.
>
> --- Statements
> I enjoyed this chapter for the same reasons I enjoyed "Expressions" but this
> chapter covers way more ground than Statements, but seems to be around the
> same length. It seems things could be reorganized to allow for this to be as
> thorough as the previous. Perhaps the discussion on variables could be
> pulled into "Expressions", and "Statements" could be devoted entirely to
> assignments and flow control?
>
> This chapter discusses more theory behind things like assignment, rather
> than being confined to covering Lua. I like this because I wish Lua's
> reference manual had more theory and "how to actually use this" in it.
>
> The final bit on chunks is good to read, but doesn't fit with the rest of
> the chapter. I would consider moving it or even leaving it out altogether.
>
> ---Functions
> This is a decent chapter on functions, but it doesn't really capture the
> richness that functions afford the programmer. Lua is also somewhat unusual
> in that it treats functions as first-class functions, allows closures, has
> explicit support for tail-call optimization, and comes builtin with a
> coroutine library for even more ridiculous flow-control options.
>
> But I digress. This does a good job of explaining how functions work at a
> ground-level. I would just love to have this chapter have the same level of
> detail as the stuff you did on assignment.
>
> --- Tables
> This is a solid chapter. Probably my favorite of the book. I feel like the
> balance between practical demonstration and theoretical explanation is
> spot-on.
>
> --- Standard libraries
> I like this chapter, especially the stuff on garbage collection and
> coroutines, but I feel like it could have a better chapter name. Miscellany,
> perhaps? "Other topics"?
>
> ---
>
> All in all, I really enjoyed reading it, and I hope my commentary is helpful
> to you. :) The book could serve both as a supplement to the official
> reference, and independently as book to learn programming concepts. There's
> also a taste of theory, which I appreciate (but always want more of from the
> books I read ;) )
>
> --  Aaron
>
> --
> Aaron Faanes <dafrito@gmail.com>