lexi-lambda
commented
5 years ago It’s not immediately obvious why, but this change does a different thing.
Under the ordinary Racket reader, | is a special character for escaping symbols. When you write |foo bar baz|, you get a symbol that is equivalent to (string->symbol "foo bar baz"). This means that || is a valid symbol… but it is actually the empty symbol, aka (string->symbol "").
In practice, I find the bar escapes are not very useful, so Hackett uses its own reader that treats | just like any other character. This means that in Hackett, || reads as the symbol (string->symbol "||"), as you’d expect. But Scribble uses the Racket reader, and in Racket, the correct way to write (string->symbol "||") as a literal symbol is \|\|.
All that’s fine, but the problem here is that, as far as I can tell, when Scribble prints a symbol for documentation purposes, it always uses the Racket printing conventions. So no matter how it’s written in the source code, if it’s the symbol (string->symbol "||"), it will end up in the HTML looking like \|\|. This PR changes it to use the empty symbol, which does print the right way, but it’s ultimately the wrong identifier, so it will break cross-references: links to Hackett’s || operator will not work because Scribble thinks that documentation is for a non-existent binding named the empty symbol.
The right thing to do is to fix/extend Scribble to make it possible to typeset identifiers using language-specific conventions, but that’s a task I didn’t deem worth the effort unless Hackett ever becomes more usable.
On the documentation page: https://lexi-lambda.github.io/hackett/reference-datatypes.html#%28def._%28%28lib.hackett%2Fmain..rkt%29.~7c~7c%29%29 the
||s in the examples look right with the backslash escapes, but the backslashes in the title render wrong