RE: Back to Books

["Andy Stark" <astark@...>]

Peter Hill:-
>I guess it depends somewhat on the nature of the book. As Lua is open
source
>it is reasonable that its manual would be as well. Since Lua is an
embedded
>language it is imperitive that the portion of the manual dealing with the
>language itself would be allowed to be modified & distributed to potential
>embedded-script users.

I had this very same thought myself a few months ago and started work on
something with a suitably pretentious name: the Alternative Lua Annotated
Reference Manual (ALARM). It's important to have a good name first and
then build a project around it, I always think.

Anyway, the ALARM mainly contains material adapted from the official Lua
Reference Manual, but in an encyclopedia-like form. There are entries for
language constructs, library functions, etc. Each entry has information
like:-

Title
One-line abstract
Syntax
Full description
Subtleties (ie, unexpected features, trip-ups, etc)
Code example

For example, the entry for the "if" statement might look like:-

Title: if statement

Abstract: Conditional execution

Syntax:
	if [expression] then
		...statements...
	[else]
	end

Description: The if statement allows... blah, blah

Subtleties: If you use the if statement on a Tuesday then it sometimes
won't work because...

...etc...



This entry-based system is modelled after the excellent online docs for
the REALbasic language. The main format of the data would be XML, which
can be transformed into HTML and PDF using XSLT, XSL-FO and friends.

And now, having built you up...  unfortunately, I never actually finished
the ALARM; in particular, I couldn't think of interesting code examples
since I am really a newcomer to Lua. And it was for Lua 4 rather than 5.
And I wasn't sure about some of the technical information. BUT STILL, I
think the ALARM might lend itself very nicely to a collaborative "open
source" documentation project.

If people could read the entries and contribute "patches", suggest and
write new entries, think of interesting (ideally real-world) code
examples, correct technical errors, etc., then I think the ALARM could be
very useful. And I think its entry based XML format would make it easy to
use only the bits you want (eg, you might embed Lua without the standard
library, so you just remove the standard library entries from the ALARM to
create your docs). I would hope to release the material in XML form but
also HTML and (bookmarked!) PDF and the XSLT and XSL-FO stylesheets for
transforming the data.

Please let me know what you think of this idea. If people are interested
then I will get the existing ALARM material into some respectable form and
release it and accept contributions.

&.