Documentatio markup

[Jan Skibinski]

> > Malcolm said:
> > 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.)
>
> Simon said: 
> 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.

	Playing the devil's advocate again (I am only referring
	to source markups, not to the interim "raw" format
	mentioned in one of the Henrik's posts)....

	Examples:
	---------------------------------------------------------
	-- Blah blah... See module ForeignPtr.

	-- Blah blah... See type-constructor ForeignPtr.
	-- or       ... See tycon ForeignPtr.

	-- Blah blah... See data-constructor ForeignPtr.
	-- or		See con ForeignPtr.

	-- Blah blah... See function someFunction.
	-- or           See function someFunction, module SomeModule.
	----------------------------------------------------------

	So far we have _zero_ formatting noise in any of the above. 
	I intentionally left out any rendering or content markups
	because the possibilities are countless. 

	Suppose that we agreed that "See" or "@See", or whatever its
	markup should be, is a reserved keyword which signifies a link
	from _start_ to the _end_ of the sentence. Let's assume that the
	rendering markups, such as any of "*", "_", etc. are stripped
	first, so they do not affect the link parsing. The keywords
	"module", "function", "type-constructor" (or "tycon"), etc.
	could be the reserved keywords - but only locally, just to
	the end of the sentence.

	If the sentence cannot be correctly parsed because of the
	spelling mistakes ("noodle" instead of "module", missing
	punctuations, etc.) then tough luck - the link will not be
	produced. But no real harm will come from the lack of this
	missing non-essential information.
	---------------------------------------------------------

	But the ambiguity "module vs. tycon vs. con" could be always
	resolved by other means, even if the above mechanism
	was not implemented. A browser, for example, could produce
	a menu from which user could browse any of the above
	-- if all three were known to the browser. A tool producing
	HTML page could insert a list of links, instead of just
	one link, etc.

	Jan