Henrik writes:
To that, I also see a need to add some lightweight conventions for markup of explanatory text. E.g. I'd like to be able to mark variable names, emphasize a piece of text, and maybe include small code fragments.
Absolutely. We need a way to include a (hyperlinked) reference to a code entity from the documentation, and that means separate markup for type constructors, data constructors, and module names (and possibly in the future class names; at the moment they share the type constructor namespace), and if we're being really anal about it, variables/type variables.
Jan propses to use conventions like 'xxx' for variable names and "zzz" for emphasis (I think). That's probably reasonable, and I indeed use the 'xxx' convention in my own comments sometimes. But one should be aware that this useage can conflict with the normal meaning of the quote characters. In particular, other lightweight emphasis conventions like _yyy_ or *zzz* spring to mind.
one that springs to mind for me is @Name@, but I don't really mind as long as it's non-ambiguous and doesn't cause parsing headaches. Cheers, Simon