In the two exercises just above this section, when you click for the first solution, it instead shows you the second solution.

I think the fix would be to change here from solution = to const solution = or let solution = , for proper lexical scope. I'm not confident enough in my JS to make a PR, though.

The last two builds (#12162723, #12202289) were broken to due the use of f-strings in pybtex. This has been fixed in the most recent release, so a rebuild should work. This is the last release to support Python 2, though, so the book may need to be migrated to 3.6+ soon.

I am going through the book and on the first exercise, there is nothing clickable on the 'Solution (click to show)' section.

https://futhark-book.readthedocs.io/en/latest/irregular-flattening.html

I am using Google Chrome.

Martin and I have decided that it would be more useful for the book to be written primarily with browser-based access in mind, rather than the current setup which produces a PDF. While we may want to publish a traditional book eventually, it is clear that the vast majority of readers currently do not print the book. Since LaTeX is not useful for producing nice browser-readable output, we have to decide on a new formatting system. I have looked at some of the options.

Gitbook

GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc).

The Rust Programming Language is personally my main inspiration for what I would like the Futhark Book to be, and it is written with Gitbook (specifically, a reimplementation written in Rust). Gitbook supports LaTeX math via MathJax, but I am not certain that is enough for our needs.

Sphinx

Sphinx was originally designed as a documentation writing tool for Python projects, but has grown into a flexible and extensible system. It supports both Markdown and ReStructuredText (RST) as the formatting language. We already use Sphinx with RST for the Futhark reference manual, for which it works quite well, and my plan is for futhark-doc to also interpret documentation comments as RST. There may be value in using the same formatting system everywhere. Sphinx supports LaTeX math fairly well, rendering it to SVG or PNG during compilation. In fact, I found a textbook on theoretical physics written with Sphinx.

I will say Sphinx is the strongest contender, but we should ensure that I have not missed some crucial flaw that motivated Gitbook. I am also open to other options (but not Texinfo - I wasted enough of my youth on that mess).

We use futhark-test to test the larger examples in the src/ directory, but it's unfortunate that we don't have something similar for the smaller in-line snippets, since they occasionally break.

Breaking changes to the language are slowing down, so it probably won't happen as often in the future, but it would still be nice to have that extra safety.

For the code in the example to run with the previously compiled shared library. I had to change line in luser.c from futhark_entry_dotprod(ctx, &res, x_arr, y_arr) to futhark_entry_main(ctx, &res, x_arr, y_arr).

#include <stdio.h>

#include "dotprod.h"
int main() {
  int x[] = { 1, 2, 3, 4 };
  int y[] = { 2, 3, 4, 1 };
  struct futhark_context_config *cfg = futhark_context_config_new();
  struct futhark_context *ctx = futhark_context_new(cfg);
  struct futhark_i32_1d *x_arr = futhark_new_i32_1d(ctx, x, 4);
  struct futhark_i32_1d *y_arr = futhark_new_i32_1d(ctx, y, 4);
  int res;
  futhark_entry_dotprod(ctx, &res, x_arr, y_arr); -- THIS LINE
 -- Should be 
 -- futhark_entry_main(ctx, &res, x_arr, y_arr);
  futhark_context_sync(ctx);
  printf("Result: %d\n", res);
  futhark_free_i32_1d(ctx, x_arr);
  futhark_free_i32_1d(ctx, y_arr);
  futhark_context_free(ctx);
  futhark_context_config_free(cfg);
}

I was using the C backend but I believe this would still be an issue with OpenCL backend compilation.

The previous section (7.1) defines sgm_scan, but the definition of replicated_iota uses a function called segmented_scan that, in addition to having a different name, has the order of the flags and values arguments reversed.

If you check e.g.

https://futhark-book.readthedocs.io/en/latest/parallel-cost-model.html#futhark-the-language

you see 𝚛𝚎𝚍𝚞𝚌𝚎\_𝚌𝚘𝚖𝚖. The reason is that in the source that is done as (roughly)

\texttt{reduce\_comm}

and Mathjax doesn't handle text mode macros; see e.g.

https://docs.mathjax.org/en/latest/input/tex/differences.html

in particular:

First and foremost, the TeX input processor implements only the math-mode macros of TeX and LaTeX, not the text-mode macros.

You could fix it in the HTML by just removing the \, but it will then be incorrect in the LaTeX version (not sure if that's a concern). More involved solutions seem to involve things like putting

\usepackage{underscore}
\usepackage[T1]{fontenc}

into the preamble so that the bare _ works in LaTeX too. (Suggested here mathjax/MathJax#1770).

In language.rst, "Module Types" section says "The module systems in Standard ML and OCaml support both opaque and transparent ascription, but in Futhark we support only opaque ascription." But in fact, while SML 97 supports both opaque and transparent ascription, OCaml supports only opaque ascription as Futhark does.