diff --git a/README.md b/README.md index 713cf10..ed09054 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,15 @@ A minimal commandline utility for reviewing notes. 'Flashcards' can be written i - [Installation](#installation) - [Usage](#usage) - [Cards](#cards) - - [Definition](#definition) - - [Multiple choice](#multiple-choice) - - [Multiple answer](#multiple-answer) - - [Open question](#open-question) - - [Reorder question](#reorder-question) + - [Card Types](#card-types) + - [Definition](#definition) + - [Multiple choice](#multiple-choice) + - [Multiple answer](#multiple-answer) + - [Open question](#open-question) + - [Reorder question](#reorder-question) + - [Including files](#including-files) + - [LaTeX](#latex) + - [Miscellaneous info](#miscellaneous-info) ## Installation @@ -80,9 +84,12 @@ _de même_ with the command `hascard import input.txt output.txt -r`. More info can be found in the help text at `hascard import --help`. ## Cards -Decks of cards are written in `.txt` or `.md` files. Cards are seperated with a line containing three dashes `---`. For examples, see the [`/cards`](https://github.com/Yvee1/hascard/tree/master/cards) directory. In this section the 5 different types of cards are listed, with the syntax and how it is represented in the application. +Decks of cards are written in `.txt` or `.md` files. Cards are seperated with a line containing three dashes `---`. For examples, see the [`/cards`](https://github.com/Yvee1/hascard/tree/master/cards) directory. -### Definition +### Card Types +In this section the 5 different types of cards are listed, first the text representation is given and after a gif of it is represented in the application. + +#### Definition This is the simplest card, it simply has a title and can be flipped to show the contents. For example the following card ``` # Word or question @@ -93,7 +100,7 @@ will result in

-### Multiple choice +#### Multiple choice This is a typical multiple choice question. The question starts with a `#` and the choices follow. Only one answer is correct, and is indicated by a `*`, the other questions are preceded by a `-`. As an example, the following text ``` @@ -109,7 +116,7 @@ gets rendered as

-### Multiple answer +#### Multiple answer Multiple choice questions with multiple possible answers is also possible. Here again the question starts with `#` and the options follow. Preceding each option is a box `[ ]` that is filled with a `*` or a `x` if it is correct. For example ``` @@ -125,7 +132,7 @@ results in

-### Open question +#### Open question Open questions are also supported. The words that have to be filled in should be surrounded by underscores `_`. Underscores can also be escaped by `\_` if they are part of the text, like is done in [`cards/analysis3.txt`](https://github.com/Yvee1/hascard/blob/48b5c0751ac72df791402b88c033e05488c9350d/cards/analysis3.txt#L34-L37t). Multiple answer possibilities can also be given by seperating them with vertical bars `|`. As an example, the card ``` @@ -138,7 +145,7 @@ behaves like this

-### Reorder question +#### Reorder question This is a question where you have to put the elements in the correct order. Each element is preceded by a number indicating their correct place. The elements are rendered in the same order as they are written. For example the card ``` @@ -153,5 +160,30 @@ will look like

+### Including files +You might want to include an image with a question. Rendering images in the terminal itself is not well supported, so instead an option is made available to let a file be opened automatically when a question is encountered. This can for example be used to include an image or pdf, which is then opened in the default application for that file type (internally the `xdg-open` command is used for linux, and the `open` command for mac). The syntax for including files is similar to how you include images in markdown, and should be placed directly under the header. For example: +``` +# What type of fruit is this? +![](pear.jpeg) +- Apple +* Pear +- Orange +- Banana +``` +references the image `pear.jpeg` in the directory of the text file containing the cards. Files can be added to any of the previously listed card types. + +#### LaTeX +For reviewing content with mathematical symbols, functionality is included such that LaTeX can be used. Because LaTeX cannot be rendered in the terminal directly, it is first converted to a pdf file with the `pdflatex` command (the pdf is placed in a temporary directory), and then opened in the default pdf viewer application as if the pdf were included directly like mentioned above. LaTeX can be written between three backticks, and should be placed right below the header. For example, the card +`````` +# The l^p metric space +``` +The space $(\ell^p, d)$ is a metric space, when $d:\ell^p \times \ell^p \rightarrow \mathbb{R}$ is defined as +$$d(x, y) = \left(\sum_{n=1}^\infty |x_n-y_n|^p\right)^{1/p}$$ +``` +`````` +is an empty definition card and just opens a pdf file containing the mathematical statement in another window. + +Note that no `\begin{document}`, `\end{document}` or `\documentclass[]{}` should be specified; this is already done automatically. The LaTeX packages "amsfonts", and "mathtools" are currently the only ones that are loaded. + ## Miscellaneous info Written in Haskell, UI built with [brick](https://github.com/jtdaugherty/brick) and parsing of cards done with [megaparsec](https://github.com/mrkkrp/megaparsec). Recordings of the terminal were made using [terminalizer](https://github.com/faressoft/terminalizer). The filebrowser widget was mostly copied from the brick [filebrowser demo program](https://github.com/jtdaugherty/brick/blob/master/programs/FileBrowserDemo.hs). Homebrew and Travis configurations were made much easier by [the tutorial from Chris Penner](https://chrispenner.ca/posts/homebrew-haskell).