Positional cues or not

[Marcin 'Qrczak' Kowalczyk]

Tue, 13 Feb 2001 11:04:58 -0500 (EST), Jan Skibinski <jans@numeric-quest.com> pisze:

> ----------------------------------------------------
> ---- 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