This document contains a brief overview of HDF, the hybrid document format – what it is, what is isn't, why you might want to use it, and how to get started.
# Hybrid Documents Format – an Overview
The **Hybrid Document Format** is a document format for creating interactive books. Its posterchild use case (and origin) is [pseuCo Book](https://book.pseuco.com/#/), an interactive textbook centered around concurrent programming and [pseuCo.com](https://pseuco.com/).
It allows authors to write books in an intermediate, XML-based (and HTML-like) format, which can be compiled to a PDF (through an intermediate TeX representation), but can also be compiled to a JSON representation that can be rendered by a web app.
The HDF can contain quizzes and references to interactive elements which will be embedded into the webapp. The interactive elements are arbitrary React components.
The HDF framework has been published alongside a to-be-published ITiCSE 2022 paper.
## What HDF Is
Compared to similar systems, with HDF, you get:
- support for basic text formatting, lists, images, etc.
- support for code listings
- support for math (as implemented by [KaTeX](https://katex.org/))
-**full control over the web app**
- fully customizable (landing page, service worker, additional features, …) – _you_ provide the reader app, using components of the HDF ecosystem to handle document rendering
- interactive elements are arbitrary React components
- open source – full access to the compiler and reading web app
## What HDF Is Not
Depending on what you want, the HDF ecosystem may not be right for you. Here's a few things you *won't* get, and alternatives to look into:
-**No fancy TeX.**
With HDF, you cannot use arbitrary TeX features. If you find the HDF format lacks an advanced typesetting feature you need, you have to implement it yourself.
If full control over the PDF is more important than customizing the web app, check out [PreTeXt](https://pretextbook.org/).
-**No authoring tools for hand-crafted exercises.**
Besides quizzes (which are fully defined in the HDF markup), HDF supports arbitrary hand-crafted interactive elements, but you have to build these yourself. Besides support for state persistence, the HDF ecosystem provides no additional support here – you are implementing the components from scratch. (pseuCo Book shares some code with pseuCo.com.)
If you want a more guided approach, and you only need _programming_ exercises, [Codio](https://www.codio.com/) (commercial) may work for you.
## Components of the HDF Ecosystem
-`hybrid-documents`, in this repository, is the HDF compiler.
-[Hybrid Documents Reader Core](https://dgit.cs.uni-saarland.de/fefrei/hybrid-documents-reader-core) is a set of React components that can render HDF books.
-[HDF Demo](https://dgit.cs.uni-saarland.de/fefrei/hdf-demo) is a demo book that shows you how the components fit together, and can serve as a template for new HDF books.
-[`pseuco-shared-components`](https://dgit.cs.uni-saarland.de/pseuco/pseuco-shared-components) is a library shared between pseuCo.com and related applications. It's used in the HDF ecosystem to borrow the text editor, used to render source code listings in the web app.
-[pseuCo Book](https://book.pseuco.com/#/) is the posterchild of the HDF ecosystem. Use it to get an idea how a HDF book can look like.
## Questions?
If you have questions or would like to discuss whether HDF may be the right framework for your book, feel free to send me an email at freiberger@depend.uni-saarland.de.
