Format online documentation

[albinahlback]

Main goal to be more readable. Specifically:

• Make pages look more paper-like by

  • having margins for the text on the "paper" and

  • applying a maximum width for the "paper".

  Here the maximum width of the text were set such code blocks of 79 column width were generated without any scroll to the sides. Moreover, the margins were set such that they can get smaller when the screen size is reduced (in order to not have half the screen consisting of margins).

• Change fonts to the system defaults in order to let readers use their favorite fonts.

• Change to:

  • Serif in body text.

  • Sans-serif almost everywhere else.

  I did this as I think it is easier to read texts with serif in comparison to sans-serif, and since it looks better when switching to and from the math Computer Modern Roman used by MathJax which is of serif-type.

• Reduce size of large texts. Most apparent example is the headers as they used to be overwhelmingly large.

• Remove box around inline code. As the documentation is written as a text, code should only be considered as another font family, similar to how italic/oblique is used to emphasize things and how italic symbols are used in mathematics: It is simply another "mode" in the text.

• Insert spacing between items in the sidebar as they were too close to each other.

• Make "Note"-boxes have justified text, like the body text.

• Make MathJax have a similar font size as regular text.

NOTE: Some things in the documentation should be changed in order to look the best. One of these is to use monospace/inline code when referring to a computer variable. Another thing is to use monospace for C-files (*.c, *.h) in the headers. Optionally, one can also start using monospace when referring to websites and emails; I need to think about how to do this in practice first (there are multiple options).

Now, let me know if there is anything you do not like and I will try to fix it. I really enjoy typesetting, but perhaps these are only my preferences.

[fredrik-johansson]

It looks nice, but the custom fonts more than double the size of the source distribution (!).

[albinahlback]

Do you test it locally? I can't seem to get the size of a local website on Firefox, only seems to work when loading a remote website.

Anyway, does this reduce the website enough?

[fredrik-johansson]

I'm not primarily concerned about the website bandwidth, though that could be an issue as well. The issue is that git archive --format zip is 3.4 MB on the master branch, 7.5 MB with the fonts added.

The new fonts look great, but not enough to be worth that.

[albinahlback]

Yeah, I see. I think it should be optimized now.

[albinahlback]

If you do not think this work, I will go back to using built-in fonts.

[albinahlback]

Now it seems to be 3.36 MB for me. Let me know if you find anything else that needs a fix. I've looked through all the pages, but perhaps I've missed something.

Edit: I force-pushed to make the merge the commit messages after these updates.

[albinahlback]

I completely removed the fonts in order to favor peoples own favorite font in their browsers. I also adjusted the margins of the paper to have a maximum width, but reducing them when screen size gets smaller.

I also reduced the width of the paper (one can still display a code block with 79 column width without generating a sideways-scrollbar).

This is final.