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
Simon Marlow
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.
In the case where a name is actually ambigious it may be acceptable. However, it must be possible to omit the additional information when the name is uniquely defining an entity. Cheers, Manuel
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
participants (3)
-
Jan Skibinski -
Manuel M. T. Chakravarty -
Simon Marlow