Bulat Ziganshin wrote:

i hope that you don't crosspost your answer to maillist by accident :) at least i want to check my imhos with other TH users

sorry for not answering sooner...

i started (and not finished) writing my own TH tutorial. its first version is at http://freearc.narod.ru/th.htm and current version is at http://freearc.narod.ru/th3.htm

i tried linking to your tutorial, but somehow the host "narod.ru" is blacklisted in the wiki.

quasi-quotation is the mechanism which should hide much of this complexity for the real user. but does it accomplish this goal? i think no - any rather complex TH work can't be written without knowledge about Exp, Q and other low-level stuff.

hmm, quasi-quotes aren't all bad, but i agree that for most real applications you'll have to go far beyond what Quasi-Quotes are trying to hide from you.

so imho starting from the low-level stuff really goes to the economy of reader's time and mind. with current state of TH it's better to study it as the AST-generation tool with some help in creating some ASTs rather than macro-generation tool which has some advanced low-level additions.

i don't necessarily disagree, but my "tutorial" was less supposed to explain TH once and for all, but to give a _readable_ account what it can be used for. so maybe our ideas what a tutorial is supposed to do also differ...

i have even more radical offer - just join our tutorials so that my part explains low-level stuff and quasi-quotation mechanism while you say about 'Name/''Name/reification and give all these neat examples of TH usage. plus join our explanations of low-level stuff

i have considered all your criticisms in my tutorial and changed it to that end. but some alterations would have forced me to basically rewrite it and i don't have time for that right now :) i am not sure that low-level first is the right approach for the kind of tutorial i was writing, but i do invite you to do any chnages to the wiki-page you want to. after all i hope that others will improve on my work!

imho, the final goal of this project must be to give one enough explanations that he don't need to read anything more on TH to use all its features and understand all what he does.

i don't see that to be possible in a tutorial style document. there are so many cases to cover that it becomes more of a paper than a casual tutorial. in my mind, looking at the code or some documentation will never be done away by a TH tutorial. but maybe you can do it!

...

...

4. your tutorial does not mention many non-trivial details of TH, [... for] example, difference between mkName and newName.

i was aware of the differences; it's just that all the different ways of name resolution can be quite overwhelming. the difference of mkName and newName is buried somewhere deep down in the tutorial, just not presented in a very structured fashion. maybe it would be better to introduce the reader in a structered way to name resolution in TH! thank you for your criticisms, i tried to address every one of them in the few changes i made to my tutorial, Johannes Ahlmann