 |
lua-l archive |
|
|
||
|
I think good search engines, Stack Overflow, code-parsing IDEs, better local doc nav, and significant bodies of bloggy code fragments have changed the way many of us interact with half-familiar languages and bodies of code. I generally don't need a deep understanding of an environment to start hacking in it. People talk about write-only languages; C++ has always been a "patch-only" language for me.
Local doc navigation was particularly important to me. The first doc tool I saw significantly change my interaction style was /usr/bin/info. This is the standalone Texinfo viewer, and it had a significant advantage over traditional Emacs info-mode: incremental search worked over the entire document, not limited to the current chunk. If you ran "info libc" you could type "C-s c o n v e r" and start browsing every kind of converter and conversion in the library. It worked on manpages too, and better navigation inside bash(1) is welcome. On OS X, I've been using Dash.app, which gives lightning-fast entry search; after you hit space, it switches to in-page text search.
The Lua manual is not well-suited to this kind of navigation. The manual is concise because the language is, and vice-versa. Dash.app works fine for looking up argument order. But for a language tourist, the concise, orthogonal nature of Lua may be difficult. Manpages and platform SDKs have extensive "see also" links which help a lot.
(I'm sure the fault is in me but I find the modern Python manual to be not only counter-intuitive but ANTI-intuitive: I can think of a topic, guess where it would be discussed, and then look *somewhere else*.)
One of the better ideas I've seen is the (for example) MySQL manual's comment-thread-per-page. People who are confused or feel burned by a page will often add to the gloss out of annoyance. However, creating a message thread creates another Internet-writable text which must be de-spammed at the least. Not free.
The cheapest thing I can think of is to link to the lua-users wiki from each segment of the lua.org online manuals. "The wiki may have more information on string.gsub." I don't know if this would be used, but it incurs little cost or commitment at the lua.org side. Indexing into PiL is more difficult for a number of reasons, unfortunately.
Jay
To ressurect an old thread:
Does the Lua web site need a page "Getting Started with Lua",
along the lines of http://python.org/about/gettingstarted/ ?
I've tried again and wrote the page below
http://www.tecgraf.puc-rio.br/~lhf/tmp/start.htm
but I'm not sure I can find the right tone or level of detail, nor whether
that page is indeed useful, or whether Google and the site map are enough:
http://www.lua.org/map.html
I welcome suggestions, including "no, we don't need this". Thanks.
--lhf