note on Scribble compatibility Per Bothner 28 May 2013 22:06 UTC

A discussion that started on this srfi-11 list led me
to think again about Scribble syntax and compatibility
for SRFI-108.  Specifically with the motivation: If we
swiched to Scribbe-compatible syntax, could the SRFI-108
family get better acceptance?

First, I'm less concerned than I was about how Scribble
reads @{foo bar} as ("foo bar") in contrast to what I think
is the more useful (quasi-)literal "foo bar". The solution
to that is to use a different prefix character for quasi-strings.
For example backquote seems quite readable: `{foo bar}

The big incompatibility in terms of semantics is that
Scribble uses the standard namespace.  Specifically:
   @foo{Hello!}
is read as plain:
   (foo "Hello!")
rather than:
   ($construct$:foo "Hello!")

However, I think being able to distinguish foo and &foo
is a very valuable feature.  Consider a document processing
language wanting to use @list or @format - while still having
the standard definitions available in embedded expressions.
Or even more subtle variations: One might want @T{foo} to
be different from (T "foo") even if both are used to construct
a T object.

One possibility is to use the Scribble prefix syntax @foo, while
still having the reader translate that to ($construct$:foo ...).
But then you get to a more subtle problem.  In Scribble,
the foo is actually an arbitrary Scheme expression.  For
example the standard way to unquote an addition might be:
@(+ a b) - which gets actually evaluated, not quoted.
Identifiers in general expression should *not* be in
the $construct$ "namespace".
Thus we get:
   @foo{bar}   --> ($construct$:foo "bar)
   @(foo bar)  --> (foo bar)
   @foo        --> $construct$:foo or foo ???

Scribble uses vertical bars as delimiter.  That leads to
another question:
   @|foo|      --> $construct$:foo or foo ???

SRFI-108/-109 has various escape sequences for special
characters and other uses:
   &newline;
Scribble instead uses embedded string literals with string escapes:
   @"\n"
This seems a reasonable approach.

It seems possible to work out a decent syntax and semantics
that satisfies the goals of SRFI-108 and SRFI-109, while fully
or mostly remaining compatible with Scribble syntax.  The
question is whether this exercise is worth it at this late
stage of the game.  Scribble appears to be primarily used
for standalone documentation (as far as I know); the goal
SRFI-108 is to in addition support a general "named literal"
feature, meant to be available by default in the Scheme
language, so it's a bit more ambitious.

Question to Scheme implementors:  Would switching SRFI-108/-109
to a (mostly) Scribble-compatible syntax make it more
(or less?) likely you would implement SRFI-108/-109 in your
implementation?

If not, there are some good arguments for sticking with the '&' syntax:
- Using '&' allows compatibility with SRFI-107 (XML literals).
- The semantic incompatibility of $construct$:foo vs plain foo.
- It might be useful to save '@' for a splicing operator.
- SRFI-108 - and -109 can be finalized quickly if we stick to '&'.
--
	--Per Bothner
xxxxxx@bothner.com   http://per.bothner.com/