|
|
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. |