Improve README with features, prompt docs, and directives#512
Merged
Conversation
- Add a Features section highlighting key capabilities (completion, syntax highlighting, Lwt/Async auto-eval, #typeof, short paths, auto toplevel printers, Lambda-term/Zed) - Document the prompt structure (time, command number, macro counter, key sequence) and how to switch prompt styles - Add a Directives table listing all utop-specific directives - Split the old Usage section into Prompt, Completion bar, and Directives subsections - Streamline the Customization/Prompt section to avoid duplication - Fix anchor tag (href -> id) for Emacs usage section - Fix documentation URL to use https - Fix dune file code block language tags (elisp -> dune) - Remove outdated opam < 2.1 instructions - Rename "Common error" to "Troubleshooting"
Octachron
reviewed
Mar 6, 2026
| Features | ||
| -------- | ||
|
|
||
| - **Context-sensitive completion** — utop uses the compiler internals to |
Member
There was a problem hiding this comment.
compiler internals ⇒ compiler libraries (because fortunately utop is not using a fork of the compiler source code)
Octachron
reviewed
Mar 6, 2026
| UTop.set_show_box false | ||
| ``` | ||
| `UTop.prompt`. Several built-in prompt styles are available via | ||
| directives — see the [Directives](#directives) table above. |
Member
There was a problem hiding this comment.
I have the impression that it might be useful to keep mentioning the init file as a way to customize the prompt.
Contributor
Author
There was a problem hiding this comment.
My bad - seems I deleted here a bit more than I should have. I've pushed a commit addressing this.
Octachron
approved these changes
Mar 6, 2026
Octachron
left a comment
Octachron
left a comment
Member
There was a problem hiding this comment.
Overall, I agree that this is a good improvement of the utop readme.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A while ago I came across https://ocaml.org/news/about-utop and I felt it explained some aspects of utop better than the README does — things like the prompt structure, the completion system, Lwt/Async auto-evaluation, and the
#typeofdirective. I wanted to incorporate those items here so they're easier to discover.I also noticed a few other small things worth fixing, so I tackled those as well — I'm a big believer in kaizen (small improvements).