I am designing a programming language, and I would like to provide a complete documentation for it.
So far, I have planned to write the following documents:
An initial design outline, mostly as a reminder of the design and proposed changes to it, as well as an aid to construct all the other documents when the design phase has been completed.
A formal specification of the language's syntax and semantics, both in English and in a suitable formal mathematical notation.
I have found that some languages have references, and I have found on Wikipedia that language references and language specifications are not quite the same, references being usually less detailed due to being aimed at users of the language rather than implementors of it.
However, I would like to know...
What parts of a language specification are usually omitted in a language reference?
Is it really useful to provide a language reference when ultimately a good programmer should consult the language specification as their definitive source of information?
In case the answer to the preceding question is "Yes"... Is it really worth the risk of introducing contradictions between the language specification and the language reference?