"how do people consider a "language reference" as a good documentation?"
"when I'm picking up a new language or a new tool, the most important things is to have examples on how to use the language to get things done"
You look for different things when you think about how to implement the language. In a sense, the implementation doesn't really care about the use cases: it merely cares that the behavior matches the stated behavior in the documentation.
the IDEAL documentation for a developer is a proper PEG/LALR grammar for the language. That way you can properly parse expressions. Clearly they didnt provide it.
The documentation gives enough information to reduce an abstract expression from the GUI down to a mathematica expression, which is enough to build an AST. From there, it's a matter of building up each component to match the semantics.
"Another problem I have with mathematica is that although the different functions are extensively referenced (I won't use the word documented), the language itself is not very well explained, and by language I mean how to piece all the functions together and more into one coherent piece of software."
That's the job of the programmer. The documentation should explain how each bit works and the rules for combining the bits, but it's up to you to take the pieces and build something.
Think about Legos: you have a pile of bricks, and no one is going to tell you how to build a rocket ship using those pieces. That's up to you :)
"Take the unix manual for instance. The first thing I do when checking the manual is to search for example. Reading the list of switches is useless to me unless I have a working example of how the thing works."
The manpages do a poor job of explaining the zen of unix. Once you start thinking of operations as transforming streams of text, then you start thinking of tasks in terms of smaller units.
For example, a few minutes ago I needed a way to upgrade all global `npm` modules. I knew there was a way to get JSON lists (npm list -g --parseable --json), which lines I wanted (the ones starting with ' "'), and what I want to do with those (get the name and install). Putting it together, one straightforward way is
npm list -g --parseable --json 2>/dev/null | grep '^ "[a-z-]*": {' | sed 's/^ *"//;s/".*$//' | while read x; do sudo npm install -g $x; done
Now, the documentation doesn't explain that this is a way to do what I want. But the documentation gives enough information to know where to look.
"when I'm picking up a new language or a new tool, the most important things is to have examples on how to use the language to get things done"
You look for different things when you think about how to implement the language. In a sense, the implementation doesn't really care about the use cases: it merely cares that the behavior matches the stated behavior in the documentation.
the IDEAL documentation for a developer is a proper PEG/LALR grammar for the language. That way you can properly parse expressions. Clearly they didnt provide it.
The documentation gives enough information to reduce an abstract expression from the GUI down to a mathematica expression, which is enough to build an AST. From there, it's a matter of building up each component to match the semantics.
"Another problem I have with mathematica is that although the different functions are extensively referenced (I won't use the word documented), the language itself is not very well explained, and by language I mean how to piece all the functions together and more into one coherent piece of software."
That's the job of the programmer. The documentation should explain how each bit works and the rules for combining the bits, but it's up to you to take the pieces and build something.
Think about Legos: you have a pile of bricks, and no one is going to tell you how to build a rocket ship using those pieces. That's up to you :)
"Take the unix manual for instance. The first thing I do when checking the manual is to search for example. Reading the list of switches is useless to me unless I have a working example of how the thing works."
The manpages do a poor job of explaining the zen of unix. Once you start thinking of operations as transforming streams of text, then you start thinking of tasks in terms of smaller units.
For example, a few minutes ago I needed a way to upgrade all global `npm` modules. I knew there was a way to get JSON lists (npm list -g --parseable --json), which lines I wanted (the ones starting with ' "'), and what I want to do with those (get the name and install). Putting it together, one straightforward way is
Now, the documentation doesn't explain that this is a way to do what I want. But the documentation gives enough information to know where to look.