[doc] templates

[PavelVozenilek]

Few suggestions for the documentation of templates.

Overall, I would like more small examples (not like the gigant for generics), even incomplete. I can grok code snippets much faster and much more reliably than narrative.

---

A template is a simple form of a macro: It is a simple substitution mechanism that operates on Nim's abstract syntax trees.

1. It has unintentional patronizing tone ("you must be idiot if you do not get it")
2. The term "macro" is unclear. Does it refer it C macros or the Nim macros described only later in the docs?
3. It gives no hint what does it do. Does it insert tokens into the code (ala C macro) or does it generate (inlinable) helper functions (ala C++ templates)?
4. Why should the reader care about templates? The docs already covered procs and generics, what is the difference and advantage? Every advanced feature should, IMHO, justify its existence to the reader.

---

The syntax to invoke a template is the same as calling a procedure.

1. Example just bellow shows an operator. Why cannot it show the promised proc?

---

< the first example >

1. The very first example should be something trivial, w/o stmt and expr. Those words feel like magic, as if the feature is topic only for the wizzards.

---

The "types" of templates ...

1. It should be explained what return value means in text substitution. Whether one can return someting else than expr or nothing. What if I make a mistake (say always returning nothing), what would happen?
2. There should be example for every suggested type: stmt, expr, typedesc, "real type".
3. The sentences These are "meta types", they can only be used in certain contexts. Real types can be used too; this implies that expressions are expected. are vague on the level of medieval alchemists.

---

Section Ordinary vs immediate templates

1. Compiler lingo (overloading resolution) should not be used as familiar-to-everyone reference.
2. There should be example that shows how they differ. "This doesn't work, this does."
3. Is the new term (ordinary) really needed? Ordinary usually does not need to be stressed.
4. The ability to use undefined symbols should be explored a bit deeper. It can be quite suprising (e.g. the possibility to use unexported types). Use cases could be given.

---

Section Passing a code block to a template

1. Why does the name of local variable (f) need to be parameter? The template is intermediate (= unchecked), after all.
2. Another example w/o expr would be handy, say executing given code block N-times.
3. Explicit attention could be drawn to the ability to automate the common init-action-deinit pattern.

---

Section Symbol binding in templates

1. This section reads as from a heavy-handed computer science textbook (binding, hygienic, mixin). I gave up trying to understand. Pairs of small examples would be better than the high jargon: (a) this doesn't work, (b) this fixes it.
2. Btw, mixin keyword is not documented at all (at least in 0.9.6 docs).
3. The hygiene is futher discussed in section down bellow. For me it makes it even more confusing.
4. The second section about hygiene recommends to use otherwise undocumented (as of 0.9.6) "dirty" pragma.

---

Section Identifier construction

1. This section is inserted into the middle of long talk about symbol binding. It seems unrelated.

[PavelVozenilek]

It came to my mind: if templates can have static [T] parameters and when could be used on them. This would make a very powerfull feature.

[Araq]

I surely agree we need to improve the manual tremendously, but I disagree on several minor points:

The term "macro" is unclear. Does it refer it C macros or the Nim macros described only later in the docs?

Obviously to Nim's macros. Nim is not defined in terms of "differences to C".

It gives no hint what does it do. Does it insert tokens into the code (ala C macro) or does it generate (inlinable) helper functions (ala C++ templates)?

Neither, as it operates on abstract syntax trees... And if we need to explain ASTs more why don't we need to do the same for "token"? Ah, because you happen to know what a token is, got it. ;-)

Why should the reader care about templates?

The manual describes what exists, it doesn't give philosophical justifications for why things exist. But to answer your question: Templates give us control flow abstractions, (generic) procs do not. More concrete: Think about what 'return' does in a template and what it does in a proc.

Example just bellow shows an operator. Why cannot it show the promised proc?

Where is the difference? You seem to think that operators are somewhat special in the language. But they are not and this is clearly covered in the manual.

Etc.

My point is: The manual will evolve into a spec, not into some introduction into metaprogramming. You sometimes act like Common Lisp etc are unheard of in the scientific community. ;-)

[PavelVozenilek]

The manual will evolve into a spec

There's language called Mercury (something like typed Prolog with powerful automatic checks against wrong use) which went this way to an extreme. They have complete formal language spec ("wonderfully complete and very logical", someone from the academia said to me) with practically no example inside, none for its advanced constructs. They have something like 2 - 3 real world users in total, after 20 years of development.

My guess is that when Nim 1.0 is announced people who know C or C++ will check it out. They won't care about a spec but would like to see how it looks, where it differs from C++, what is common, what is better. Giving them lots of examples would serve them well.

[Araq]

Yeah well but I hope the spec vs "real book" distinction will help me make money with a real book... But maybe it's totally misguided to expect real money from real work these days when everybody gives everything away for free in the modern software world...

[PavelVozenilek]

@araq: if "real book" means a printed one, through a publisher, then I have a bad news. (I worked on prepress systems, but the industry is half dead now.) A technical author may get something like 5-10% of the book sale price. He is expected to provide material ready for print and find out the reviewers and the publishing process takes months.

Self-publishing (via services like lulu) is probably better way for fringe technical topics but don't expect miracles either.

Many authors publish just to get the name, to establish themselves as consultants.

[Araq]

Most of these things have been reworded.