Fix unlinked content in documentation

[countvajhula]

One of the nice things about Scribble docs is the seamless dense cross-linking that just happens when you use the simple markup provided by the language.

Unfortunately, the vast majority of Qi's forms don't benefit from this cross-linking at the moment because they are forms of the DSL that exist within the scope of the flow macro, and aren't toplevel forms exported by the collection.

E.g. @soegaard reports, "In the code example for collect in the docs, neither the up nor down pointing triangle is clickable."

And @benknoble suggests "I think it's because they are datum-literals and not bindings"

As a result, Scribble doesn't automatically link them.

This affects all Qi forms, i.e. everything on this page, e.g. ><, feedback, and, etc., except the ones that happen to have an identically-named toplevel export, such as ~> and switch. Even here, though, at the moment, having the toplevel switch means that documenting the Qi-level switch (in the "Qi Forms" page) would cause a duplicate identifier warning, unless the latter is marked with #:link-target? #f. This causes the link to be excluded from the sidebar, so if someone is just scanning the sidebar for the form they need (e.g. in this case, switch), they would not find it there, even though it is present in the file (workaround: click on the "Conditionals" header to navigate there and find the switch form within it).

Related issues: The sketching library has a similar issue where "the identifiers aren't provided from sketching but are inserted into the expansion of the module that uses sketching," and also don't get linked in the Scribble docs.

Attempts so far:

One suggestion (also from @soegaard ) was to provide identifiers corresponding to the Qi forms from a dummy module, e.g. a file doc-helper.rkt in the qi-doc package, and have that export identifiers corresponding to the forms of Qi using a (provide (for-doc ...)), and then (require (for-label qi/doc-helper)) in the Scribble file.

This succeeded in coloring the links, but didn't actually link them to the content and instead underlined them in yellow which I think indicates broken link. I haven't had a chance to try again so I'm creating this issue for now to record progress towards a fix.

[benknoble]

I don't know how to solve the duplicate binding issue in Scribble, and the approach with giving Qi forms bindings may well cause issues with similarly-named syntactic forms from Racket (I'm thinking about and and if, for example).

Using bindings would certainly be "a" standard approach, however. Examples:

• Using syntax parameters: https://www.greghendershott.com/fear-of-macros/Syntax_parameters.html
• More on syntax parameters: http://www.schemeworkshop.org/2011/papers/Barzilay2011.pdf
• Using syntax bindings that are syntax errors except when used as literals in a macro: https://docs.racket-lang.org/try-make-sarna-happy/index.html

Again the binding approach has limitations (standard if would probably break?), but it allows for the documentation links to work correctly (see the last link) and (I think) allows the forms to rename-in'd.