2

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:

  1. 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.

  2. A formal specification of the language's syntax and semantics, both in English and in a suitable formal mathematical notation.

  3. A tutorial.

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...

  1. What parts of a language specification are usually omitted in a language reference?

  2. 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?

  3. 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?

Improve this question
3
  • I would say that it's impossible to provide too much documentation. That said, it helps to organize documentation well so that you find exactly what you're looking for, no more, no less.
    – Neil
    May 9, 2012 at 9:25
  • 1
    I think first you need to answer who is going to use this language? what is it for?
    – jk.
    May 9, 2012 at 10:50
  • @jk: My language is mainly aimed at systems programming, but in a very type-safe manner. Starting from C++, I removed what I think are the features that make it an insane language (type casts, untagged unions, three inconsistent ways to do polymorphism) and replaced it with Haskell-inspired features (very strong typing, tagged unions, typeclass-based polymorphism (though my version is not exactly equal to Haskell's), a lazy pure functional subset on top of the core strict impure imperative language).
    – isekaijin
    May 9, 2012 at 11:10

1 Answer 1

Reset to default
4

Personally, I would suggest not doing a tutorial, and instead make a reference with plenty of examples. The C# spec has this sort of thing at the beginning. It provides enough meat to get the idea without having to translate from the dry specification parts. It also provides your mechanism to describe how the language differs from C++ , which should help your target audience. For your specific sub-questions:

  1. A lot of the mathematical notation, a lot of the exceptional case handling (such as the detailed order of initializers for example), a lot of the common behaviors (such as mathematical order of operations), the BNF, and probably more I'm overlooking.

  2. I would say yes for two reasons. Firstly, there are a lot of not good programmers in the world. Your language won't get much traction if only people who can stomach reading programming language design docs can use it. Secondly, good 'definitive sources' are not necessarily good learning sources.

  3. It should be clear that the specification is the definitive definition of the language. Errors can be corrected, and if you have problems writing simple documentation for the language, that seems like a symptom of a larger problem.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.