Contributing

Annotate with hypothes.is overlay

_images/annotate.gif

Join the yampa-book group on hypothes.is.

Comment using issues

You can also add comments with gitlab issues.

Fork GIT and create pull request

Fork the git repository, change the text and create a pull requests.

>>> git clone https://gitlab.com/gerold.meisinger/yampa-book

If you want to build the docs to see the final result before sending pull requests you need to install the sphinx documentation generator.

  • Install python3

  • Install sphinx and then build the docs via:

>>> pip install sphinx sphinx-rtd-theme sphinx-comments
>>> cd docs
>>> make html

If you want to edit SVGs they use the Computer Modern Unicode font which is also bundled with some Latex distributions and is used in a lot of scientific papers.

Windows: install manually from link

Linux:

>>> apt install cm-super

Housekeeping tasks

Some housekeeping task everyone can contribute without knowledge on Haskell and Yampa:

  • Correct typos

  • Rewrite sentences with proper english (I’m not native speaker after all)

  • Research links (papers, tutorial, examples etc.) and add RST markup

  • Retrieve archive.org wayback machine versions for important links (papers) to make them permanent

  • Fill in the glossary terms with description and citations from papers where the terms are mentioned

  • Record screenshots and gif animations of graphical example outputs

  • Work on todo list (see below)

  • Run und test examples, add comments

  • Add or answer FAQs

  • Answer issues

Add content

  • See roadmap in readme

  • Good enough is good, better to have more content

  • Keep the examples as simple as possible and self-contained

    • Is it really necessary to start up an SDL or OpenGL context to talk about animation or is the console with ASCII art sufficient

    • Is it really necessary to use a 3 dimensional vector to talk about stateful positions or is 1 dimension sufficient

    • Is it really necessary to use point-free super sections or is a verbose lambda with explicit type signature more comprehendable

  • Scope

    • Yampa FRP meaning everything based on Dunai, BearRiver, Yampa (old), Euterpea(?), Rhine(?). It’s okay to add comparisons to other libraries like Reactive-Banana, Elm, Elera etc. though.

    • Don’t teach fundamentals about Haskell, Monads, computer game programming, computer graphics, physics programming etc.. It’s okay to recall concepts required for a specific example.

Restructured Text

Use doctext >>> syntax for bash and ghci examples because it doesn’t get marked when copying to clipboard and can be pasted as-is without changes.

doctext:

>>> echo hello world
# hello world

codeblock:

$ echo hello world
# -bash: $: command not found

Todos

Todo

Add discussion for feedback function

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/embed.rst, line 164.)

Todo

what’s the point? why not just pass the config as a value?

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/embed.rst, line 182.)

Todo

? why does that matter? m is a free variable, so we cannot use it for anything specific. we might as well set it to Identity? but I’m getting “Couldn’t match expected type: IO t0 with actual type: Identity [Int]”

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/embed.rst, line 260.)

Todo

use mtl MonadReader variant on reader and writer examples

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/embed.rst, line 374.)

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/embed.rst, line 395.)

Todo

Complete history of FRP based on papers

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/intro.rst, line 28.)

Todo

Timeline of FRP

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/intro.rst, line 29.)

Todo

add simple arrow combinator examples

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/intro.rst, line 152.)

Todo

split up technical papers and tutorials

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/links.rst, line 91.)

Todo

where is the 2000 version of Generalising monads to arrows online?

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/links.rst, line 116.)

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/links.rst, line 152.)

Todo

add english translation of switching diagrams from master thesis

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/latest/docs/yampa.rst, line 163.)