Documenting the Language

[Vance Shipley]

<grump>
There really does need to be a document which definetivly 
decribes the core langauge.  Now I know there is the 
"Reference Manual" but it is dated February 9, 1999 and is
"DRAFT (0.7)".  It's the Erlang 4.7.3 reference manual and
we're currently on 5.2.  It's also only available as a 
postscript file and I haven't had any luck text searching it.

A case in point is the collection of boolean BIFs:

	is_atom/1, is_constant/1, is_float/1,
	is_integer/1, is_list/1, is_number/1,
	is_pid/1, is_port/1, is_reference/1,
	is_tuple/1, is_binary/1, is_function/1,
	is_record/1

The closest these come to being documented is in the ERTS
User's Guide under Match Specifications in Erlang.  Other than
this they were mentioned in the release notes of the compiler
and there is a passing mention in Erlang Extensions Since 4.4 
under Boolean expressions in guards.

Another issue is in what is allowed in a guard.  I found through
trial and error that is_process_alive/1 is not allowed in a guard 
despite it's encouraging name.  There is a function exported from 
erl_internal, and documented, which tests if a function is valid
in a guard:

     guard_bif(Name, Arity) -> bool()

     Types: 
     Name = atom()
     Arity = integer()

     Returns true if Name/Arity is an Erlang BIF which is allowed
     in guards, otherwise false. 


That was a little hard to find though and it still doesn't give
me a list, it only allows me to test what the compiler will 
complain about later.

When try & cond show up will they only be mentioned in the release
notes?  There has been a lot of talk about promoting Erlang here.
I think having a definitive list of BIFS would be a good start.

I would do it myself but I don't appear to be qualified as I tried
but quickly got lost in categorizing bifs,operators,guards,tests,etc.
</grump>

	-Vance