Beginning Lua Programming (2007)

Chapter 19. Fitting into the Lua Community

You're now familiar with the basics of the Lua language, its core libraries, and a sample of the libraries and applications that developers around the world have made for Lua. The last topic you'll explore in this book involves the vibrant community that has developed around Lua and the resources that can help you with your software development. You'll learn about the following:

· The Lua web site

· The Lua reference manual

· The Lua mailing list

· LuaForge, the principal repository for Lua-based projects

· The Lua wiki

· The Lua chat room

There is a lot of Lua expertise in the community and insight into the way Lua works. Help is available to you in the form of printed and online documents, and discussions on the mailing lists, forums, and chat rooms. The niches these resources fill overlap, sometimes broadly, and you'll find a combination of them is sometimes needed to understand an issue thoroughly. Nevertheless, you can expedite the process of getting over hurdles by selecting the right resources to draw on.

Whether you've got a particular question regarding Lua, you're interested in seeing what people are doing with the language, or you want to contribute in some way to Lua's ongoing success, you'll find a suitable venue among these resources.

The Lua Web Site

The Lua team—Roberto Ierusalimschy, Luiz Henrique de Figueiredo, and Waldemar Celes—maintains a well-organized website at lua.org that serves as the official home of Lua. It's where you should go to do any or all of the following:

· Obtain the most recent source code for Lua

· Read the FAQ (Frequently Asked Questions with answers)

· View various documents such as articles and memorabilia about Lua

· Read about recent milestones such as conferences and publications

· Find links to other websites and resources pertaining to Lua

The Lua website is kept up-to-date, so it's a good place to visit regularly. The community page on the Lua website provides a great launch pad to the sites and resources summarized in this chapter.

The Lua Reference Manual

The terseness and sharp focus of the reference manual are its greatest strengths, but these characteristics can make it a difficult document to read casually. Nevertheless, take the time to read it. Even if you don't absorb all of its details and subtleties the first time through, you'll know where to turn in it later when you want to delve deeper into some topic. If you ever raise a question in one of the dynamic community resources like the chat room or mailing list, it will be assumed that you've studied the manual first.

Although every important facet of Lua and its libraries are covered in the reference manual, sometimes there will be omissions in the corner cases. For example, the documentation for string.sub doesn't state what the return value will be for out-of-bound indexes, a condition that might arise in a loop. Don't sweat things like this. First, you can use the Lua interpreter to find out very quickly what this function does, like this:

a = string.sub("abc", 0, 0) print(a, type(a))

Second, the function's behavior in the current version is almost certainly what it will be in later versions.

The reference manual is not an afterthought. It is an integral part of Lua, and official releases of Lua are not made without an up-to-date manual. Its economy matches that of the language implementation itself, and the Lua authors are to be commended for granting the manual such high significance in the project.

Roberto Ierusalimschy's excellent book Programming in Lua (ISBN 8590379825, published by Lua.org) is filled with practical applications and insights into the concepts presented in the manual.

An online version of the manual in HTML format is included in the source distribution of Lua. You're encouraged to purchase a bound copy as well. It's often more convenient to have a printed book, and the proceeds help the Lua project. Follow the links on the Lua website or LuaForge to order a copy.

Framing Questions

A big part of working through software development problems is knowing not only where to ask but how to ask. Some articles on the web address this head on. For one of these, follow the link on Lua's mailing list page to an article named, “How To Ask Questions The Smart Way,” by Eric Steven Raymond and Rick Moen. Before reporting issues with software, you should read the excellent online article named, “How to Report Bugs Effectively.” written by Simon Tatham (www.chiark.greenend.org.uk/~sgtatham/bugs.html).

A common theme with these articles is to narrow the scope of the problem. Take the time to strip away all extraneous content in order to present the smallest possible program that demonstrates the issue. You may be intimately familiar with every part of your large program, but don't brazenly expect someone else to ferret out a particular problem you are having with it. More often than not, the process of distilling a problem to its bare essentials will allow you to present your question more intelligently if not solve it completely.

The Lua Mailing List

A central and active part of the Lua community is the mailing list. Messages sent to the mailing list are in turn sent to all subscribers electing to receive them. Although the mailing list has steadily grown since Roberto posted the first message in 1997, it is still of a manageable size, handling usually fewer than a few dozen messages per day. The messages themselves are generally focused and friendly, with subjects ranging from beginning to advanced.

Here are a number of ways to read the messages that are sent to the mailing list:

· Receive e-mails from the list server

· Access a web interface site with your web browser

· Access a net news interface site with your newsreader

· Download daily, recent, and full archives of messages for reading offline

Viewing and Searching the Archives

Before subscribing to the Lua mailing list, take a look at the archives to get a feel for the topics that are discussed.

Try It Out

Visiting the Message Museum

Over the years, a huge amount of ground has been covered in the Lua mailing list. You can search through the accumulated messages to see if a particular question you've got has been discussed. Here's how:

1. With your web browser, access www.lua.org.

2. Click the community link, the mailing list link, and finally the search archive link.

3.In the Search field, type the following:

The and is implied so it doesn't have to be specified, but the terms do need to be separated from the parentheses by at least one space.

( ipairs or pairs ) and next

4. Select the Score option as the sorting method. This will place the messages with the greatest algorithmically-determined relevance at the beginning.

5. Click the Go button. The results page highlights the search terms, hyperlinks the subject lines of the retrieved messages, and displays the author, date of post, and the first couple lines of the message contents.

6. Click one of the subject hyperlinks to view the complete message. A diagram showing the context of the post is displayed beneath the message body. It shows, with hyperlinks, the follow-up messages and references to the message as well as index links.

7. Click the Date Index link. This displays a flat list of all messages that were posted in the same month as the message you were reading sorted by date.

8. Click your browser's back button and then click the Thread Index link. The messages that were posted in the same month as the selected message are hierarchically arranged by subject. This view gives you a great way to follow the thread of a discussion and shows you the context of a particular message.

9. Click the back button of your browser a few times to return to the search page. Retry your query with different terms and sorting options.

10.The matrix beneath the search box is a hyperlinked summary showing the number of messages archived by month and year. Click a particular value to bring up a sequential list of hyperlinked message headers for that month.

How It Works

Lua's mailing list server acts not only as a message dispatcher, but also as an archiver. Searching the archives can be done with plain-text terms and Boolean operators, and with wildcards (as in luaP_*) and regular expressions. If you want to restrict your search to particular authors or subject line terms, use +from: and +subject: notation. For example, the following finds messages written by one of the mailing list's top gurus containing the term coroutine:

+from:lake coroutine

Downloading the Archives

The Lua website has a download area from which you can obtain source packages (including older versions) and mailing list archives. The download area is duplicated (or mirrored) regularly by a number of sites around the world to distribute server load. A link to a page listing these mirror sites is available on the mailing list page of Lua's website.

The archives are provided in standard mbox text format so you can view them in an editor and most e-mail programs and can easily process them with Lua itself. A complete archive is available as well as one containing messages from the last month or two and one containing messages from the most recent complete day.

Using a Web Browser to Access the List

The mailing list page on the Lua web site maintains links to sites that host a web interface to the mailing list. The Gmane (the G is silent) site displays posts in threaded form. You can submit messages with this interface, but you have to be a Lua mailing list subscriber for them to be accepted.

Using a Newsreader to Access the List

A huge number of Internet newsgroups are supported by the Usenet system, some of which have been active since the early 1980s. Unlike a mailing list that distributes e-mail, you access newsgroups anonymously with a newsreader, which is a component of many modern e-mail clients. Generally, the newsreader will show you only unread messages and present them in threaded format. A message is posted directly to a news server from which it propagates to other news servers.

Gmane (the same project that provides a web interface to the Lua mailing list) lets you access a large number of mailing lists, including the Lua list, as if they were newsgroups. You might consider this approach if you would rather pull mailing list messages at your convenience than have them pushed at you right after they are posted. Posting to the mailing list through Gmane is easy, but just as with the web interface, you will need to be a list subscriber for your messages to be accepted.

Subscribing to the List Server

If you want to contribute to the mailing list, you'll need to subscribe to it. This assures a certain level of accountability so that any abuse of the system can be tracked and dealt with. Even as a subscriber, you can elect not to receive e-mails if you prefer to access the list by some other means.

To subscribe to the Lua mailing list, visit the community page at the Lua website, and click the Mailing List link and then the Subscribe link. At the mailing list subscription page, you need to provide a valid e-mail address and a password. You will receive a confirmation notice at this address that you'll need to respond to in order to subscribe. By following the link in this confirmation message, you'll be able to configure a number of options such as whether you to receive posts that you submit to the list and whether to receive acknowledgment when you post. Here are two of the more important options:

· Whether you want to receive e-mails: If you'll be unable to collect e-mail for a length of time and don't want your mailbox to fill up, or you intend to read messages by some other means, you should disable e-mail delivery. If you are temporarily disabling message delivery, you can always catch up on messages with one of the other methods of reading posts.

· Whether you want to receive messages bundled into digests: This option lets you reduce the possible disruption of having individual messages trickle in as they are posted. The server can be told to accumulate messages, usually about a day's worth, and send them to you as a single digest.

Posting Messages

When you send a message to the Lua mailing list, it will be promptly dispatched to over a thousand subscribers around the world and will be accessible in searchable archives for the foreseeable future. Before pressing that Send button, make sure you've followed the guidelines as presented on the mailing list page of the Lua website and the web pages it references. These are summarized here:

· If you are submitting a new post rather than a follow-up, make sure that you aren't bringing up something that's covered in the documentation or has been discussed and resolved before. Take the time to search the archives. If the question or subject isn't covered elsewhere, expend the effort to present the smallest possible example that illustrates it.

· Send your message in plain-text format. Formatting in HTML and including multipart MIME attachments adds extraneous baggage to your post. This can be annoying to readers, many of whom use e-mail clients that display markup tags and MIME content verbatim. It can degrade the accuracy of searches on list archives. Your e-mail software may be converting the messages you send to HTML automatically, in which case, it is unlikely that you'll notice that they've been marked up when you read your post. Configure your e-mail software to use plain text when sending messages to the list server.

· Practice netiquette, the art of keeping Internet interactions polite. The Lua mailing list is quite free of damaging flame wars or even extended sidetracks. To do your part in keeping it this way, be sure to “remember the human” when posting.

· Take the extra time to quote material from previous posts properly. Your message will receive more attention if you include only the previous material that directly pertains to your response. If needed for clarity, break up the quoted text into sections with your responses directly beneath. You can configure many e-mail programs to indent and prepend angle brackets to quoted material to make it easier to frame your response.

· Don't depend on mail readers to automatically wrap long lines. Some web interfaces treat messages as preformatted content, requiring the reader to scroll horizontally to read paragraphs. Wrap the text of your message so that lines don't exceed 60 or 70 characters.

· Post your message in the right context. You've seen the hierarchical arrangement of messages in the threaded index view of the list archive and possibly in your e-mail software. This tree format is very helpful for showing where a message fits in a discussion thread. Although it may appear that these threads are based on subject lines and timestamps, they are in fact based on internal message headers named Message-ID, References and, less often, In-Reply-To. There are two rules to follow here. First, when you are starting a new topic, don't reply to an existing message and change the subject thinking that this will begin a new thread. Instead, send a new message to the list server. Second, when posting a response, don't send a new message with a copied-in subject line. Instead, use the reply feature of your e-mail software and let it handle the internal headers.

Joining the Lua mailing list is a great way to participate in the Lua worldwide community. The Lua authors are frequent contributors as are a number of undisputed gurus and other elders of the tribe.

The Lua Chat Room

Lua programmers can get together on Lua's Internet Relay Chat (IRC) channel. The kind of interaction that occurs here is more spontaneous than that on the mailing list. To participate, you'll need an IRC client such as the one integrated into Opera or the Chatzilla extension for Firefox. Follow the irc link from the Lua website's community page for connection details.

Like participation in the mailing list, certain rules apply to the chat room. These include the following:

· If you're asking a question, trim it down to the smallest possible size first. If you need to display source code, you should cut-and-paste it to the designated pasting site. This site will keep your snippet for a limited length of time and give you a temporary URL that you can in turn copy-and-paste to your chat submission. Other participants can then access the URL to examine your code.

· Avoid requesting communication with a participant one-on-one. Private messaging is intrusive.

Long lulls can occur on the Lua IRC channel, but people always seem to be present to step in when an interesting topic comes up.

Forums

A topic that surfaces with some regularity on the Lua mailing list is whether to abandon the mailing list in favor of a forum, which is a website that hosts ongoing discussions in various topics. Ultimately, it's the community itself that decides these things, and the continued activity on the mailing list is a strong indication that the list is the favored means of community interaction.

Nothing prevents a site from hosting a Lua forum, however, and one such site, www.icynorth.com/forums/index.php?c=8, has its share of participants.

The Lua Wiki

The lua-users.org site is maintained by users of Lua and serves as an unofficial repository for all things Lua. In addition to maintaining the mailing list archives, it provides, in the form of a wiki, an extensive collection of web pages devoted to tutorials, code, links, and patches. You can visit these pages at http://lua-users.org/wiki. The wiki pages are contributed and maintained by members of the community, making it a collaborative endeavor.

Navigating the wiki is a matter of clicking the hyperlinks interspersed throughout the content. From the home page, you can explore many pages, including a tutorial on programming in Lua, an unofficial FAQ page, many links for Lua-related projects and libraries, and much more.

You can add and modify wiki pages by clicking the Edit link at the lower-left corner of each page. Rather than editing directly in HTML, your contributions are made in simplified format. The wiki engine behind the scenes takes care of converting it to HTML for use by browsers. To learn how to style your pages, check out the formatting examples page. Click the WikiHelp link on the wiki home page, and then click the WikiFormattingExamples link. The basic rules are as follows:

· Make a large header by surrounding text with three equal signs. For example:

=== Large Header ===

Or, make a smaller header by using two equal signs instead.

· Place a blank line between paragraphs.

· Italicize text by surrounding it with two consecutive single quotes.

· Make text bold by surrounding it with three consecutive single quotes.

· Make text monospace by surrounding it with {{ and }}.

· Add a horizontal rule by putting ---- on a line of its own.

· Create a link to an internal page by referring to its name. Each wiki page has a name that is the concatenation of two or more terms where each term begins with one uppercase letter and is followed by one or more lowercase letters, as in MyPage. This is sometimes referred to ascamelback format.

· Create a new page by using a camelback name that doesn't refer to an already existing page. When you view a page that contains an unresolved page reference, it will be shown with a question mark link. Click this link to edit the new page.

· Refer to an external link by using square brackets as in this example:

[http://www.lua.org/Lua]

· Make a bulleted list by preceding items with an asterisk. Make a sublist by indenting the asterisk with a tab or eight spaces.

· Surround source code with {{{ and }}}, each on their own line. This disables wiki markup handling. For example, identifiers in camelback form will be presented verbatim rather than being treated as internal links. Indent the opening braces to indent the entire code block.

Before you modify a page on the wiki, spend some time getting used to the format and procedure by visiting the sandbox. From the WikiHelp page, click the SandBox link. The sandbox page exists solely for practice of this kind.

LuaForge

Several references to the LuaForge site at luaforge.net have been made throughout this book. This site is managed by Andre Carregal and has been of indispensable value to the Lua community by providing a single repository of many Lua-related projects.

LuaForge's home page shows recent news, lists the most active current projects, and contains links to various pages such as the project catalog tree. Reading the news lets you know of new products and releases, and scanning the activity lists lets you keep a pulse on what people are using Lua for.

Access a project detail page by drilling into the Project Tree page, clicking one of the news or activity links, or using the keyword search field at the top of the home page. This will bring you to the summary page for the project, with information about the project developers, latest file releases, news, source code management, and access to areas associated with the project such as forums and mailing lists. If the project has a home page, there will be a link to it from the summary page.

Some projects such as Kepler maintain one or more mailing lists. Such lists are more appropriate than the general Lua mailing list for discussions related to the project. The participants of these mailing lists are generally quite aware of the project's details and the message topics are focused. When visiting a project summary page, look for a Lists tab or, alternatively, a Mailing Lists link in the Public Areas section. In the page referenced by these links, you can read archived messages and register to participate in the list. Subscribers receive new posts and are able to post their own messages to the list.

If you've got a project that uses Lua, you can host it with LuaForge. You'll be provided with everything you need to give your project a good home on the Internet with great exposure, including web space and the opportunity to host forums, mailing lists, and a source code repository. You'll need to set up an account before registering your project. Even if you choose to host your project on another site, you can still register it with LuaForge for the exposure it can provide.

Annual Workshops

In recent years, Lua enthusiasts have had the chance to get together and actually meet the people behind the names on the mailing list and wiki. By all accounts, these Lua workshops are informative, fun, and worthwhile. Participation is free, but attendees need to register because of seat restrictions.

The stated goals of the Lua workshops are to provide a forum for discussing all aspects of Lua and to increase professional and academic awareness of Lua. Like the mailing list and wiki, participants hail from all parts of the globe. The workshops have so far been two-day events with structured programs comprising presentations by participants, with enough free time to become acquainted with one another and engage in unformatted discussion. Most presentations are 30 minutes and cover a spectrum of topics. Past presentations have included talks by Lua team members, library authors, and other technology professionals.

Summary

This chapter gave you an overview of Lua's community resources. Lua has a rich global support system made possible by enthusiasts who share their time and expertise in a variety of ways, including the following:

· Wiki articles

· Mailing list, forum, and chat room discussions

· Lua-related software projects

· Workshop presentations and participation

In this book, you've gotten to know about Lua itself and the power it can provide to your software projects. Its small size, high speed, and ease of integration make it eminently suitable for an extensive array of applications including, hopefully, yours.