Contributing

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.

>>> apt install python3 python3-pip

  • Install sphinx

>>> pip install sphinx sphinx-rtd-theme sphinx-comments

  • Build the docs

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

Troubleshooting

Could not install docutils: run pip install pip --upgrade manually

apt install python3-pip

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/main/docs/embed.rst, line 163.)

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/main/docs/embed.rst, line 181.)

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/main/docs/embed.rst, line 259.)

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/main/docs/embed.rst, line 371.)

Todo

incorporate Dunai Issue 245 - using embed with a constant 1.0 MSF to get (printable) results with an example for Yampa

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

Todo

Complete history of FRP based on papers

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

Todo

Timeline of FRP

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

Todo

add simple arrow combinator examples

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

Todo

split up technical papers and tutorials

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/yampa-book/checkouts/main/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/main/docs/links.rst, line 120.)

Todo

include from https://github.com/ivanperez-keera/Yampa/

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

Todo

Research UI architecture design considerations

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

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/main/docs/yampa.rst, line 162.)