|
⇤ ← Revision 1 as of 2009-04-09 18:47:45
Size: 945
Comment:
|
← Revision 2 as of 2024-03-05 22:56:23 ⇥
Size: 1253
Comment: Make it clear that the language reference is confusing and most directives are undocumented
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| DomTool is built around standard ideas from statically-typed functional programming. In particular, we expect that anyone who is an expert Haskell and ML programmer will be able to learn the language easily by reading [[DomTool/LanguageReference]]. There is great benefit to learning the language and its type system: while most configuration systems force you to read prose documentation to learn how to use each directive, in DomTool, the type of each directive tells you exactly how it can be used. [[http://hcoop.net/domtool/|The standard library reference]] contains types for all of the directives, and you can save yourself a lot of time in learning new directives by being able to read the types in the reference. | The DomTool language is a statically-typed functional language, like Haskell or ML. Its designers expect that anyone who is an expert Haskell and ML programmer will be able to learn it easily by reading the [[DomTool/LanguageReference|language reference]]. However, you can be a competent Haskell or ML programmer and still find the language reference impenetrable. |
| Line 3: | Line 3: |
| We don't expect most HCoop members to ever understand the DomTool type system, which is why we have [[DomTool/Examples]], but we like to make sure folks are aware of the potential benefits of learning something new. | If you understand the DomTool language and its type system, you can figure out how to make a valid call to a DomTool directive by looking up the directive's type signature in [[http://hcoop.net/domtool/|the standard library reference]]. (You may also need to find directives that produce values of the necessary argument types.) However, the type signature doesn't tell you much about what a directive actually does. Right now, most of the directives are undocumented. The only way to figure out what they do is by making guesses based on their names, combing through the [[DomTool/Examples|examples page]] and the [[DomtoolTwo|secret outdated examples page]], and doing trial and error. We don't expect most HCoop members to ever understand the DomTool type system. If you need to use it for something that isn't described on the [[DomTool/Examples|examples page]]... good luck! |
The DomTool language is a statically-typed functional language, like Haskell or ML. Its designers expect that anyone who is an expert Haskell and ML programmer will be able to learn it easily by reading the language reference. However, you can be a competent Haskell or ML programmer and still find the language reference impenetrable.
If you understand the DomTool language and its type system, you can figure out how to make a valid call to a DomTool directive by looking up the directive's type signature in the standard library reference. (You may also need to find directives that produce values of the necessary argument types.) However, the type signature doesn't tell you much about what a directive actually does. Right now, most of the directives are undocumented. The only way to figure out what they do is by making guesses based on their names, combing through the examples page and the secret outdated examples page, and doing trial and error.
We don't expect most HCoop members to ever understand the DomTool type system. If you need to use it for something that isn't described on the examples page... good luck!