Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
kylegoetz opened this issue Oct 23, 2024 · 1 comment

Comments

@kylegoetz
Copy link
Contributor

kylegoetz commented Oct 23, 2024

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

```ucm
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.

@kylegoetz kylegoetz changed the title I would like to be able to write docs in a library that does not have base installed Enhancement: be able to write docs in a library that does not have base installed Oct 23, 2024
@ceedubs
Copy link
Contributor

ceedubs commented Oct 23, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants