Re: improving the Lua manual?

[Jim Whitehead II <jnwhiteh@...>]

On Tue, May 19, 2009 at 3:24 PM, John Hind <john.hind@zen.co.uk> wrote:
> isDeadOrGhost = UnitIsDeadOrGhost(unit) or UnitIsDeadOrGhost("fullname")
>
> I'd not enclose formal names of strings in quotes as that invites confusion
> with string literals and rather than using "or" I'd write this:

This style is chosen specifically to mirror the details given in the
WoW client.  In particular, any parameter that is enclosed in quotes
is in fact a string type.  This is extremely useful to figure out what
parameters (at a glance) are strings or symbolic constants.

> isDeadOrGhost = UnitIsDeadOrGhost(unitid)
> isDeadOrGhost = UnitIsDeadOrGhost(fullname)
> Returns 1 if the player is dead or a ghost, otherwise nil. 'Unitid' is a
> number identifying a unit. 'Fullname' is the name of a player as a string.

That style was again chosen for a specific reason, but the good thing
is I can easily generate it to whatever format is required.  It's just
a Lua table that I process, so making either of your proposed changes
is 1-2 lines of code change, if that.

> I find the main source of confusion for readers of this kind of
> documentation is "level shifting" i.e. understanding which bits of the
> description are parts of the syntax being described and which bits are
> notation used to describe, and you invite confusion by using the same
> symbols in the same context at both levels ('or' and quoted literals in this
> case).

As I said, I agree with you in principle.. but it's better for us to
mirror the style that has already been given for us, and I can
definitely see the benefit of quoted parameters.  As for the "or"
separation, it's better typographically for where we need to use it
and doesn't take much difficulty to understand what it means.

Thanks for the feedback,

- Jim