unisonweb / unison

A friendly programming language from the future
https://unison-lang.org
Other
5.77k stars 269 forks source link

Enhancement: be able to write docs in a library that does not have base installed #5422

Open kylegoetz opened 1 day ago

kylegoetz commented 1 day ago

Is your feature request related to a problem? Please describe. Yes. I have a project that uses very little in the way of built-ins. It's largely types with generic parameters like FingerTree v a = Empty | Single a | Deep v ...

So I created this with an empty project and never added base as a dependency.

I wanted to add simple documentation (like a README), but get errors that things like docSection cannot be found.

For example

```unison
README = {{
# Simple finger tree library

Initially ported from the [Haskell](https://hackage.haskell.org/package/fingertree-0.1.5.0)
}}

yields

finger-tree/main> 

  Loading changes detected in ~/Documents/workspace/unison-code/mvc.u.

  I couldn't figure out what syntax.docSection refers to here:

      2 | # Simple finger tree library

  I think its type should be:

      Doc -> [Doc] -> Doc


**Describe the solution you'd like**
I think this happens because in the TermParser this type of double-braced doc construction is just sugar for `base.syntax.*`.

I would like to see you not need `base` installed in order to use `{{ #docs like this }}`. You run into the same issue creating bullet lists, numbered lists, etc. in docs.

I think a typical user would think of `{{ this }}` as language syntax rather than sugar around non-built-in functions/types, and would be confused/frustrated by syntax requiring a library to be installed.

Now, maybe this isn't a serious issue because the assumption is that almost no one will `create.project-empty`, but I think various tutorials for Unison begin with creating empty projects (I read about the `-empty` command somewhere, and I think it was an official Unison tutorial on the site. Maybe AOC? Something where you start empty and import only Cloud functionality?) So if tutorials help a user create an empty project, it might be nice not to have something that *looks* like syntax fail like this.

**Describe alternatives you've considered**
Install `base`. Or have `base` installed for another library and then `alias.term #hash-of-syntax.docSection up.base.syntax.docSection`. The workaround isn't bad. But I think this shouldn't require a workaround.
ceedubs commented 1 day ago

I agree and this makes it a pain to write transcripts related to docs. Could the relevant doc functions be added by builtins.merge?