Documentatio markup

[Simon Marlow]

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