Tue, 13 Feb 2001 11:04:58 -0500 (EST), Jan Skibinski
---------------------------------------------------- ---- Subsection blah ---------------------------------------------------- The first and the third line are just visual ASCII hints but they have no real meaning. A formatter will use its own means of presentation, so they could be safely stripped off. My extractor currently arbitrarily ignores any top level sequence of 8 dashes or more.
This is exactly how my proposal treats it. A sequence of comment lines is logically a single comment, so after stripping the comment mark from each line we get ["", "Subsection blah", ""]. Empty paragraphs are removed. The first comment mark had more than 8 (or 4?) dashes so it's a section header. Finally we get <H1>Subsection blah</H1>.
OK, I see your point about the SEE business. But the second part of my previous suggestion can be rephrased using your caps idea:
To clarify, FUNCTION doesDirectoryExist returns True ... or To clarify, FUNCTION 'doesDirectoryExist' returns True ...
Hmm, although Manuel's (EXPORTED) looks nice - it's like a graphical icon - emphasizing *that* word in a sentence looks not so nice :-( When talking about Haskell on mailing lists, I tend to write "defined in class Monad" or "imported from module List", even though "defined in the Monad class" and "imported from the List module" is probably more correct English. But the phrases "class Monad" and "module List" are used in the actual Haskell's syntax, so this can be treated as more like a Haskell's keyword than an English word. So perhaps this way of disambiguating identifiers would do. It works for modules, classes, and types (where type 'Int' is a type constructor and type 'a' is a type variable). There is no keyword for value variables, but this is the obvious default for lowercase identifiers. There is no keyword for value constructors, but we can make it the default for uppercase identifiers, such that if there is both a type called Id and a value constructor called Id, they can be referred to as type 'Id' and 'Id' respectively.
BTW, I see Malcolm's point about single quote; but (') just looks lighter in plain ascii and it maybe worthwhile supporting it by a careful parsing.
Technically it can work without escaping: 'class'' is unambiguously a quoted class-prime. An identifier cannot _begin_ with a prime. Primed identifiers are IMHO rarely used at the toplevel so they are rarely referenced - it should not be a problem in practice that the reference looks confusing. They are most common for local variables and variables in function argument patterns: (x:+y) / (x':+y') = (x*x''+y*y'') / d :+ (y*x''-x*y'') / d where x'' = scaleFloat k x' y'' = scaleFloat k y' k = - max (exponent x') (exponent y') d = x'*x'' + y'*y'' Unfortunately 'x' can be used as a character literal in a comment. We can probably live with that: toplevel definitions are rarely single-letter identifiers. What about operators? They can be one character long and we probably more often talk about punctuation as character constants than letters as character constants, so '^' is really ambiguous. Live with that and treat it as a hyperlink if ^ is defined? Or use (^) instead? Single quotes work also for short expressions embedded in the text, but not for multiline code snippets. I remember Turbo Pascal's convention for help files: indented text is presented verbatim, and text written at the first column is formatted into lines to the window's width, ignoring the original line breaks. I'm sure it will be good idea for comments, as in the example above. There is no need for markup yet! This fails only when someone tries to write enumerated or bulleted list. -- __("< Marcin Kowalczyk * qrczak@knm.org.pl http://qrczak.ids.net.pl/ \__/ ^^ SYGNATURA ZASTÊPCZA QRCZAK