Documentatio markup

[Simon Marlow]

> > > Jan propses to use conventions like 'xxx' for variable names
> > > and "zzz" for emphasis (I think). 
> > > other lightweight emphasis conventions like _yyy_ or *zzz*
> > 
> > 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.
> 
> Would there be any difficulty in permitting _all_ of the common ASCII
> emphasis styles?  For instance, "name" and _name_ could be italic,
> *name* could be bold, 'name' and @name@ could be hyperlinked bold,
> or some such.  In fact, it wouldn't really matter which style was
> rendered in what manner - different tools could do it differently if
> they chose.  (Ok, except maybe hyperlinking would have to be defined.)

The real problem is that you need at least three forms of hyperlinked
markup:  eg, what should @ForeignPtr@ link to - the type constructor,
the constructor, or the module?  I suppose there's always @...@, |...|,
<...>, <<...>>, etc.

Would this be too heavyweight: @module M@, @con C@, @class C@, @tycon
T@?  Perhaps the keywords could be left out when the meaning is
non-ambiguous, as is usually the case with variable and function names.

Cheers,
	Simon