RFC: A new Cabal user guide

Haskell Foundation
#1

Hello Everyone!

I’ve created a new repo for an exciting new prospect that the HF is trying to find volunteers for: a Cabal User Guide. The Cabal maintenance team acknowledges that the current state of docs is… not the best, to put it lightly. More concretely, the Cabal documentation reads more like a reference and a wall of text, rather than an actual guide. We are seeking to remedy this by excising the relevant quickstart/guide content from the documentation, keeping the rest of the documentation as a reference, and creating a new Rustbook-style mdBook effort to satisfy this gap in the documentation. I’ve created the new repo here, and raised its first issue, which is an RFC for content structure. I’d love for you all to be involved. To be clear: HF would love for volunteers to help drive this effort! We want your input, and your contributions.

The below text is redundant with the issue.

This repository intends to create a new Quickstart and User guide for the Cabal build tool. The Cabal team acknowledges that the current state of documents, located at cabal.readthedocs.io, serves more as a reference, and less as a guide for getting started or gathering intuition about how to effectively use the tool on projects. We would like to change this.

Tools

Rust has had a very successful, community-driven book built on mdbook, which allows users to contribute markdown to a codebase which may be compiled into a nice, legible and locally hostable book format. I propose we adopt this style, and contribute the missing content for this book in that format.

Content

There are two major areas of content that I’d like to cover:

  1. Quickstart. How does a user come up to speed in as quickly a manner as possible, such that they can get hacking with minimal fuss. The sample out line for this content would look something like the following:
  • Installation
  • Creating a project from scratch
  • Working with an existing project, considering existing tooling like stack, or otherwise.
  • Hello world! Building and running a small project to output. This section would probably list a small subset of useful commands.
  1. User guide. Given a sample project, with a contrived object, how would the user go about:
  • Creating the project from scratch. Discussing naming conventions, the anatomy of a simple .cabal and its components/vocabulary/syntax at a high level
  • Modifying a project: adding modules exposed or otherwise, adding dependencies, warnings, etc etc. at a high level, and discussing good practice for naming conventions and managing bounds.
  • Building a project: this section could discuss the basic commands used to build a project once a selection of modules has been described, and mention cabal.project and local cabal.project configuration commands, syntax, and multiproject management. Here, we could add some content regarding remote source repositories like git.
  • Testing a project
  • Benchmarking a project
  • Profiling a project
  • Working with extra-build-tools and the more exotic parts of the .cabal ecosystem
  • How to package a project and work with Hackage to release

Goals

The goals of this project, in my opinion, should achieve the following:

  1. We want a quick reference to cite to beginners for getting up and running with a project that prints “Hello, World!” in as few commands as possible.
  2. We want a user-guide that can serve as a hand-holding exercise for beginners and more casual haskellers, who can follow along with a relatively simple, contrived project that slowly builds up some complexity into something publishable by the end.
  3. We want to delineate best practices for maintaining a cabal file, so that there is less confusion
  4. We want to show people how to publish and release.
  5. We would like people to walk away with a general understanding of how to do the most fundamental aspects of project maintenance, ranging from module additions, to testing, benchmarking, and profiling, as well as an understanding of how to work in general with dependencies, bounds, and remote source repos.
  6. We should aim to be as friendly and high level as possible, while also achieving these goals.

I’m interested to hear from @JonathanLorimer, @Mikolaj, @fgaz, @gbaz, and anyone else who has time to hash out an outline for this book. I’d love to have a public record here of our discussions for posterity.

Cheers!
Emily

22 Likes
#2

I’m very happy to see this initiative!

Do you think setting up CI for a cabal project is something that should be covered in this guide as well?

7 Likes
#3

Great addition @gilmi! Absolutely. I think introducing haskell-ci and haskell/actions would be incredibly useful. You should comment :wink:

4 Likes
#4

Hi Emily,

As you may know, I’ve been poking around in cabal, looking at how to do things that I used to do in stack.

As an avid reader of the docs, I say, unfair! They are very well-written but just suffer from being behind current development, which is muy rapido. Maybe a bit of structural refactoring.

Big picture, I would like to see a clear description of what cabal is, and how it fits in with everything else. If we have to live with the confusions of what is Cabal, cabal & cabal-install (and then, out of scope, the poor user has to work out what stack is) then we should at least write a good apology and move on. We cannot say Cabal (resp. cabal-install) forever.

The end result of not covering the basics is then mis-understanding mid-level docs. An example is that I don’t know what “nix-style local builds” are, so I can’t work out what cabal builds are.

Related to this are all the various cabal prefixed libraries, some you mention below, some like cabal-bounds forgotten, some like cabal-extras with lots of interesting tidbits but where future direction is uncertain (for me). What’s in scope?

Your concept of tool documentation describing the environment it manipulates, a Haskell project eventually shipped to Hackage, is a wonderful structure. The community will fill that in. If a package fails on Hackage, what do I do next, if it compiles locally. Do I still need “Setup.hs”? etc etc

A toy project with a library, an app, tests and benchmark, hlinted, formatted by Ormolu, and wired up for CI and HLS is a big template, and may not be a toy.

5 Likes
#5

As Apple does each June, they reinvent something(s). This year it’s documentation. They claim they will open source their documentation generator in a few months. It integrates tutorials with online docs.
I have no idea if this is useful; but somebody who actually understands the problem domain might give this Apple application a quick perusal.

#6

I hate to be a format grouch — the overall idea here is really good. especially that references and guides are both needed and one will not suffice without the other.

But having looked at and worked on https://doc.rust-lang.org/book/ and also https://nixos.org/manual/nix/unstable/, I wanted to say I’m a bit sour on mdbook. As a user, the fact that it only makes a TOC entry for a separate pages seems to lead to these really small pages, which makes browsing with ones eyes, rather annoying. The Sphinx/read-the-docs we have now (and which we also use for GHC) avoids that problem in particular, and frankly just looks much better to me, presentation-wise.

I would be sad if we improved the content only to downgrade the presentation.

2 Likes
#7

I’m totally for this, since I still don’t “get” cabal most of the time.
I’ll wait until the new documentation/guides are in a somewhat complete-ish state to have a fresh “moving from stack” experience to later on give some comments on what is still unclear or could be improved.

#8

The first item has got to be - what is Cabal, and how does it relate to Stack. Then an explanation of the two kinds of Cabal, v1 and v2, and what the difference is. I got into difficulties with the last point.

How do I contribute to this project? (It may be obvious to some, not to me).

2 Likes
#9

See the call for contributors here.

#10

:100: This would be really nice to clarify for new haskellers beginning their journey!

2 Likes