As announced by Michael Snoyman a couple weeks ago, we are going to be releasing an open source version of the School of Haskell! The SoH provides interactive documentation and tutorials for newcomers and advanced haskellers alike. This interactivity comes in the form of editable code, inline in the webpage, letting you try things out as you learn them.
We are dedicated to supporting the community with excellent Haskell tools and infrastructure. As this is a community project, I’m writing this post to explain our plans, and to ask for feedback and ideas.
We are focused on eliminating any obstacles which have historically discouraged or prevented people from contributing to the School of Haskell. In particular, here are the changes we’re planning:
Open Source! We’ll encourage community participation on improving the service, via the bug tracker and pull requests. Anyone will be free to host their own version of the site.
Creative Commons license! While our old license was not intended to be restrictive, it turned away some potential contributors.
Git! Git will be used to store the SoH markdown pages. The core school repo will be hosted on GitHub. This means that editing, history, organization, and collaboration will all be based on a system that many people understand well.
Interactive code on any website! Any website will be able
to include editable and runnable Haskell code. All you’ll need to
do is include a script tag like <script
src="https://www.schoolofhaskell.com/soh.js">. When run,
this script will replace code divs with the editor.
This means that haddocks could potentially have examples that you
can play with directly in the browser!
Please help us guide this work to best serve you and the community!
Should all user content be licensed under the Creative Commons
license? One option is to relicense all user content when it gets
moved to the soh-migration-snapshot repo. Another
option is to add a footnote to each page noting that its license is
the SoH 1.0 license. After users migrate to their own repo, they
are free to remove this footnote.
Should the markdown format change? We’re considering switching to CommonMark, but perhaps having a stable format for migration is more important?
Does the system of git repos sound good (it’s described below)? One issue is that it will require a little bit of setup for users to continue editing their SoH content. Is this acceptable to folks? Should we seek to streamline the process via the GitHub API?
Any other ideas? We’ve already got a fair amount of work cut out for us, but we’d love to hear more ideas, particularly of the low-hanging-fruit variety.
The editor service will allow Haskell to be edited in the browser and run on the server. This service is independent of the markdown rendering service, described below.
Our plan is to support the following features in the SoH code editor / runner:
Standard input / output will use a console emulator in the browser. This means that things like ncurses apps will work!
GHCI support. Initially this will likely be a bit of a hack, directly running ghci rather than using ide-backend.
Type information will be available for sub-expressions, simply by selecting a sub-expression in the code.
-fdefer-type-errors will be used by default. This
will likely be setup such that type errors still prevent running
the code, but using this flag this means that type info is still
yielded by GHC.
Support for looking up the haddocks associated with an identifier. Info from GHC will be used for this, and open the results in an IFrame.
Go-to-definition will tell you where an identifier is bound.
The capability to serve websites. This will work by detecting of when the user’s code is acting as an HTTP server, and opening an IFrame / separate window for interacting with it.
This new version is going to be offering quite a lot of information! In order to have somewhere to put it all, there will be a tabbed info pane at the bottom of the snippet (much like the pane at the bottom of FPHC).
We’ve learned a lot about writing this sort of application since the initial creation of the School of Haskell. In particular, we’re planning on making the following changes, although things aren’t quite set in stone yet:
Using GHCJS instead of Fay. Back when the SoH was created, GHCJS wasn’t quite ready, and so Fay was picked. Fay was quite nice for the task, but having full-blown GHC Haskell is even nicer.
Using Docker for managing Linux containers and images.
Using Ace instead of CodeMirror. Our experience with using Ace for stackage-view was quite positive. This will address a number of open bugs, and allow us to reuse some existing GHCJS bindings to Ace.
Using websockets instead of HTTP requests. Due to usage of Amazon’s Elastic Load Balancer, in the past we couldn’t use websockets.
The protocol will likely be based on ide-backend-client.
The markdown rendering service allows rendering of SoH markdown into documentation / tutorials which contain active Haskell code. We hope to make this largely backwards compatible with the old markdown format, as we’ll be migrating content from the old site.
Our plan is to have a central GitHub repo which hosts the
main “school”
section. For example, it might be placed at
https://github.com/schoolofhaskell/school. This will
be a central place to put Haskell educational content, and we will
heartily encourage pull requests.
You’ll also be able to give the server a URL to your own
publicly accessible git repo. The contents of this repo will then
be served as SoH pages, possibly with a URL like
https://schoolofhaskell.com/user/user-name/tutorial-name.
To facilitate the migration, we’ll provide a tarball of your
current SoH pages, in a form readable by the new
implementation.
All existing SoH URLs at https://fpcomplete.com
will redirect to https://schoolofhaskell.com. In order
to do this, we need to migrate the content to the new system. The
current plan for this is to have a repo, possibly at
https://github.com/schoolofhaskell/soh-migration-snapshot,
which will be used as a fallback for users who haven’t yet
specified a repo for their account.
Subscribe to our blog via email
Email subscriptions come from our Atom feed and are handled by Blogtrottr. You will only receive notifications of blog posts, and can unsubscribe any time.
