# \[ANN\] Preface (initial release) **URL:** \ **Category:** Ecosystem\ **Tags:** announce\ **Created:** [April 13, 2021, 1:42pm UTC](https://discuss.ocaml.org/t/ann-preface-initial-release/7669 "2021-04-13T13:42:37Z")\ **Posts on this page:** 1\ **Showing post:** 1
**Author:** ![xvw](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/xvw/32/2041_2.png) [@xvw](https://discuss.ocaml.org/u/xvw)\ **Post date:** [April 13, 2021, 1:42pm UTC](https://discuss.ocaml.org/t/ann-preface-initial-release/7669/1 "2021-04-13T13:42:37Z")
Hello, @d-plaindoux and @pytre and I are very happy to present **Preface** , a project that has occupied part of our free time for almost 2 years. We received a lot of help from various people (as mentioned in the [CREDITS](https://github.com/xvw/preface/blob/master/CREDITS.md#warm-thanks-and-help) page), including some present on this forum (@gasche, @octachron and @snowleopard) > Preface is an opinionated library designed to facilitate the handling of recurring functional programming idioms in [OCaml](https://ocaml.org). Many of the design decisions were made in an attempt to calibrate, as best as possible, to the OCaml language. Trying to get the most out of the module language. _The name “preface” is a nod to “Prelude”_ . - [Github repository](https://github.com/xvw/preface) - [Online documentation](https://ocaml-preface.github.io/preface/Preface/index.html) ### About the project, and motivation When learning functional programming, one is often confronted with constructs derived (or not) from category theory. Languages such as Haskell offer very complete libraries to use them, and thus, facilitate their learning. In OCaml, it often happens that these abstractions are buried in the heart of certain libraries/projects ([Lwt](https://ocsigen.org/lwt/latest/manual/manual), [Cmdliner](https://erratique.ch/logiciel/cmdliner), [Bonsai](https://github.com/janestreet/bonsai), [Dune](https://dune.build) etc.). This is why one of the objectives of Preface is to propose tools for concretising these abstractions, at least as a pedagogical tool. ### Is Preface useful Since OCaml allows for efficient imperative programming, Preface is probably not really useful for building software. However, we (the maintainers) think that Preface can be useful for a few things: - technical experimentation with abstractions (especially those from the Haskell world) that allow programming in a fun style. - As an educational tool. Many teaching aids generally only offer the minimal interfaces to these abstractions. Preface tries to be as complete as possible. - It was a lot of fun to make. The last point is obviously the lightest but building Preface was really fun! So even if some people won’t see the point… **we had fun making it**! Let’s imagine this scenario! Oh, there’s this article that seems to describe quite precisely how to solve `this complex problem`, elegantly, using this `collection of abstractions`. After reading, the article is clear and I know how to use this `collection of abstractions` in practice. I would like to test it. Not having enough RAM to install Cabal, I decided to do it in OCaml. But as one abstraction leads to another, I am obliged to build an armada of things and I abandon my experimentation. So now, rather than doing it, locally, for the understanding of an article, I add it in Preface. # Additional links The [README](https://github.com/xvw/preface#preface) is quite expansive on motivations and some design choices, but we have tried to add some concrete guides: - [Understanding the module breakdown of Preface](https://github.com/xvw/preface/blob/master/guides/option_instantiation.md) - [Effect handling using Freer](https://github.com/xvw/preface/blob/master/guides/freer_effect_handling.md) - [Error handling with Result/Validation and a Free Applicative](https://github.com/xvw/preface/blob/master/guides/error_handling.md) And in addition here is a project, by a friend of ours, that uses Preface, to build static blog generators (very original isn’t it :P), the code is highly documented and can be an entry point into how to use it: [Github repository of the project, which is called Wordpress](https://github.com/xhtmlboi/wordpress) ## Conclusion Preface does not offer much that is new, but we have tried to make it user-friendly and to document as much as possible the code and design choices. It’s a lot of fun to build… and it will probably be just as much fun to maintain. **We are extremely open to contributions and feedback.** And my last words will be a warm thank you to the OCaml ecosystem that has facilitated so much of our development: Testing with [Alcotest](https://github.com/mirage/alcotest) and [QCheck](https://github.com/c-cube/qcheck) is a pleasure. [Dune](https://dune.build) is a fast and pleasant build system. [ODoc](https://github.com/ocaml/odoc) has allowed us to have more control over the generation of documentation, especially with the `@inline` comment (on includes) which allows signatures from different modules to be merged. And [MDX](https://github.com/realworldocaml/mdx) which I did not know at all and which is used extensively for guides. I hope you can find interest in this project! Good luck with the rest of the containment (for those concerned). Regards. Xavier. --- _[View the full topic](https://discuss.ocaml.org/t/ann-preface-initial-release/7669)._