restarting the discussion

[Manuel M. T. Chakravarty]

malcolm-hs@cs.york.ac.uk wrote,

> I have another big requirement.  The source code must remain readable
> as source code.  I absolutely loathe so-called "literate programming"
> style, because it breaks this rule horribly.  From my point of view,
> any new documentation standard must be as non-intrusive as possible.
> This almost immediately rules out XML-style tags I'm afraid.  Other
> (less heavy) lexical conventions might be OK though, provided there
> are only a small number of them to be learnt.

I am 100% with you here.  If a documentation standard makes
the code in my editor only the slightest bit less readable,
I won't use it.  This, btw, also means that the tool has to
understand 

  -- bla bla bla
  -- blub blub blub

kind of comments and not only something like

  {- bla bla bla
     blub blub blub
  -}

Nested comments don't go well with syntax highlighting.

> I am intrigued by the use of positional cues (e.g. a comment just
> before or just after a type signature) as a clever way of associating
> documentation with code, whilst avoiding extra syntax.

I like that, too.

> For those who have not yet looked at Armin's HDoc, can I encourage you
> to do so, as a concrete example of how some of these ideas have been
> put into practice.  He develops a "special" kind of comment, introduced
> by {--- rather than {-, and has some small lexical conventions that
> help to generate nice hyperlinked HTML.

Does HDoc also grok ---- for a comment block rather than --?
Maybe it must actually be something like -- -- to make sure
---- is not read as one token by a Haskell compiler (by longest
match rule).

Cheers,
Manuel