[Template-haskell] new TH tutorial (request for comments)

[Johannes Ahlmann]

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