SCDoc improvements: 5. Update scdoc.css - make SCDoc more eye-friendly on screen and on paper

[prko]

Purpose and Motivation

I used to teach SC to composers and musicians using only SCD files. Now I use SCDoc as a teaching resource for my Digital Sound Production course for non-musicians (mixed with different majors). Some of my students have asked me to improve the readability of SCDoc, so I have been trying to make SCDoc more readable, and I think it is almost done.
This PR makes the SCnhelp files more readable and print friendly [edited should be: eye-friendly on paper]
. I attach the longest help document in my SuperCollider installation (including some quarks):
'Buffer Granulation' in miSCellaneous Quark by @dkmayer.

• Buffer Granulation _ SuperCollider 3.14.0-dev Help _ with current css.pdf
  

• Buffer Granulation _ SuperCollider 3.14.0-dev Help _ with new css.pdf
  

• Buffer Granulation _ SuperCollider 3.14.0-dev Help _ with new CSS (without background).pdf
  

I hope some of the developers here have time to compare

• the improved readability of the document on screen and
• the improved printability of the PDF files. [edited should be: the improved eye-friendliness of PDF files.]

Strictly speaking, I think all four of my previous related PRs

• SCDoc: add MathJax for rendering math #6260
• SCDoc: add various punctuation marks for non-code text and comments in code #6263
• SCDoc improvements: 3. Some HTML tags are enabled. #6265
• SCDoc: Add subsubsection #6266

should be merged to make SCDoc ideal, but I think none of them seem to be of interest to developers. Only MathJax seems to have some interest, but I think it might not be so easy to get approved either.

I hope that at least this PR can be approved for merging!

Types of changes

• Documentation

To-do list

• Code is tested
• All tests are passing
• Updated documentation
• This PR is ready for review

[JordanHendersonMusic]

What do you mean by readable here?

Because I'd interpret this to mean more accessible both in design and language. However this PR reduces the contrast between the background and the text, a key component of how readable the text is (from an accessibility perspective). Also, the original is more print friendly because it doesn't have the grey scale box covering the page, saving ink and improving contrast.

From a readable/accessible perspective I can understand the font change, but the font should be installed locally and not require an internet connection to download. Also, something like Atkinson Hyperlegible which was commissioned by the Braille institute and designed for readers with vision impairment, would be a more reasonable choice — although I haven't seen any actual research backing up their claims.

In the context of a learning resource for a course, I'd interpret readability as being brief, concise and linking to tangential topics for further study. Many of the help files are quite long, contain a lot of technical information that isn't strictly relevant to the topic, and their code examples are often verbose. In my opinion, changing this would improve readability more than any design change.

— I do prefer looking at your version (its prettier and softer on the eyes), I just don't think its more readable.

[prko]

Before I answer the details, my mind is ready to change the background back to white and remove the grey box. Frankly, these are the things I considered removing from this PR, but for some reason could not. (oh, very contradictory ....). Changing other details is no problem either.

@JordanHendersonMusic

— I do prefer looking at your version (its prettier and softer on the eyes), I just don't think its more readable.

Glad you like my version.

What do you mean by readable here?

As far as I know, the factors that affect the readability of books and screens are as follows

• For both books and screens
  • Design, layout and well-structured and clear content.
  • Taking into account the experience of the reader.
  • Typography and font size:
    • For print, use serif fonts.
    • For screen, sans serif.
    • For code examples, use monospace (on paper and on screen).
  • Line spacing in a paragraph.
  • Appropriate paragraph spacing.
• Screen-specific factors:
  • Screen resolution and font rendering.
  • Colour contrast.
  • Brightness and lighting.
  • Responsiveness and layout: Content should adapt well to different screen sizes.
• Print-specific factors:
  • Paper quality and ink contrast.

In the scdoc.css file in this PR,

• uses multilingual open-source fonts (Noto and Roboto) for Linux, MacOS and Windows. They are automatically installed in the browser's cache folder and can be used by default in the same way on each OS. This means that help documents look almost the same on screen and on paper across all operating systems. Theoretically, they should look in the same way across OSes.
• Content fonts are differentiated for screen (using sans-serif) and print (using serif). Code fonts are monospaced for both screen and print.
• The leading (the space between lines within a paragraph) and the spacing between paragraphs are rearranged to improve readability, at least for my eyes.
• The space between tables, lists, bullets, etc. is rearranged.
• The margins and text width on printed paper are set to A4 size.
• Elements that are not required in printed materials will not appear in a PDF file. The elements can of course be changed if someone requests a change.

So the word 'readable' seems to be the best word for this PR at the moment. I will explain from the simplest to the most complex. If you find a better way to express my explanation, I would change the title of this PR according to your suggestion.

1. The grey box that surrounds text on paper (and in PDF)

Also, the original is more print-friendly because it doesn't have the grey scale box covering the page, saving ink and improving contrast.

I added it because

• some publications on programming languages have this box, and it was convenient for me to read a book;
• Sometimes I need a guide to confirm the final result of a print simulation using PDF.

However, it is not environmentally friendly and wastes ink or toner. It is a big problem.
Um, you are right. The term 'print-friendly' is not appropriate here. I should have said 'eye-friendly printing'.
I will update the title.

2. Readability

However this PR reduces the contrast between the background and the text, a key component of how readable the text is (from an accessibility perspective).

I added the background colour #eaeaea (whisper) because the white background was too bright and blinding. It hurt my eyes.

From a readable/accessible perspective I can understand the font change, but the font should be installed locally

The scdoc.css in this PR begins with the following code:

@import url('https://fonts.googleapis.com/css2?family=Noto+Sans:wght@300;400;500;600;700&family=Noto+Serif:wght@300;400;500;600;700&family=Noto+Sans+Mono:wght@300;400;500;600;700&family=Roboto+Mono:wght@400;700&display=swap');

The scdoc.css file in this PR allows Noto Sans, Noto Serif, Nogo Sans Mono and Roboto Mono to be automatically installed in the browser's cache folder. This means that users do not need to manually install these fonts on their local machine. The first time an SC document is loaded after using the scdoc.css in this PR, the page may take a long time to load, but from the second time the page will no longer load slowly unless a user deletes the cached files.

...(should) ... and not require an internet connection to download.

For offline installation, these fonts can be bundled, but I do not think it would be allowed due to the dependencies. However, an instruction can be included as follows:

When a user opens the SuperCollider help document without an internet connection, please download and install the following fonts from the Google Font Distribution website: Noto Sans, Noto Serif, Noto Sans Mono and Roboto Mono. However, these fonts are automatically installed in the cache folder of the user's web browser when opening SC Help documents with an Internet connection.

However, I am now confused by your mention of an internet connection: Does everyone need an internet connection to download SuperCollider? Of course, you can save it to a removable drive and use that drive. Then the same applies to these fonts.

In the context of a learning resource for a course, I'd interpret readability as being brief, concise and linking to tangential topics for further study. Many of the help files are quite long, contain a lot of technical information that isn't strictly relevant to the topic, and their code examples are often verbose. In my opinion, changing this would improve readability more than any design change.

Thank you for your advice on making learning materials. Since I have almost the same view as you, I will try my best to make learning materials with your tips in mind.

Do you still have doubts about the term 'readability'? Could 'eye-friendly' be better than 'readable'?

(Edited: I changed the title and the corresponding parts in the opening post of the PR.)

[smoge]

I would love a dark theme. Alternatively, a sepia theme, that I enjoy reading more than black on white.

Those colors are easier on the eye, right?

[smoge]

I think for visually impaired persons, sometimes high-contrast helps.

[prko]

@smoge
I loved a sepia theme and a dark theme for a while.

Honestly, for me the eye-friendly colour changes according to circumstances and age (😢). It would be ideal if the colour of the help document could be controlled by preference. There are already three PRs by @capital-G, but it is not approved yet. The most recent version is #6095.

[smoge]

Honestly, for me the eye-friendly colour changes according to circumstances and age (😢). It would be ideal if the colour of the help document could be controlled by preference. There are already three PRs by @capital-G, but it is not approved yet. The most recent version is #6095.

I created a patch of his PR, so it's easy to apply

https://gist.github.com/smoge/57b1fd5375e5cd922757fa716c54c0e1

[prko]

@smoge
Thank you very much! I hope your contribution will help @capital-G's PR get approved and merged faster. @capital-G will also be grateful for your help!

[JordanHendersonMusic]

In my opinion, the approach taken in this pr, of hard coding and changing the values for everyone, is wrong, simply because you will never reach a consensus over what is readable or pleasing.
#6095 seems like the correct approach as it will make the docs respect the theme and efforts should be redirected over there. Or have I misunderstood the aims of this pr: is there anything that this PR offers that isn't achieved in #6095?

[prko]

@JordanHendersonMusic

#6095 is about setting the colour of the SCDoc according to SC-IDE's preferences.
There are some colour-related parts in this PR, but they cannot be the main part of this PR. So they can be completely ignored. After #6095 is approved and merged, I will update any detailed changes in #6095.

This PR covers the following:

• The menu bar does not appear in print or PDF.
• The screen font is Noto San Serif, the print font is Noto Serif, and the font used in code snippets is Noto Mono for screen and print (including PDF). These fonts are all the same in each operating system. Currently the fonts are OS dependent.
• Different font sizes for screen and print.
• Line spacing (leading), paragraph spacing, before/after spaces, tables.
• The margins and text width on printed paper are set to A4 size.
• Elements that are not required in printed materials will not appear in a PDF file. The elements can of course be changed if someone requests a change.

etc.

---

In my opinion, the approach taken in this pr, of hard coding and changing the values for everyone, is wrong, simply because you will never reach a consensus over what is readable or pleasing.

Yes, you are right, I can never reach a consensus on what is readable or pleasing. But it has improved: https://github.com/supercollider/supercollider/pulls?q=scdoc.css+author%3A%40me+is%3Aclosed

There is also a publishing standard. I am not an expert in digital publishing, but I have worked for conferences and journals for several years, and have had meetings with publication designers, so I have some feedback on fonts, leading, and so on. A lot of the details of this PR reflect my experience. So I would say that I will never reach a consensus on what is readable or pleasing to everyone, but many users will be more satisfied with the change in this PR. You also wrote

I prefer looking at your version (it's nicer and easier on the eyes), I just don't think it's more readable.

---

Could you compare other examples?

• The existence of the menu bar and the title of the SCDoc in printed material
  

• Tables in printed material
  

• Tables in HTML view
  

As you can see above, only with this PR are some displays still not optimal, but with other previous PRs (#6260, #6263, #6265, #6266) SCDoc will have almost the same productivity as LaTeX or other code-based professional publishing tools. As far as I know, Martin Neukom's 'Signals, Systems and Sound Synthesis' was first written chapter by chapter in Mathematica, and later combined.

Please have a look at the PDFs below to compare the differences. The result of using this PR's SCDoc.css is much better:

• Array _ SuperCollider 3.14.0-dev Help with default css.pdf
• Array _ SuperCollider 3.14.0-dev Help with custom css.pdf
• Array _ SuperCollider 3.14.0-dev Help with custom css no background.pdf

[JordanHendersonMusic]

@prko gotcha!

So if we remove all changes to colour from this PR, that leaves three things, print support, layout changes, and font.

Personally, I think print support is a no-go because it would imply that supercollider document supports being printed, meaning all future changes to the docs would have to consider their implication for printed media — given the size of this project and the number of developers, this doesn't seem sustainable at the moment. Perhaps if you had support from several people this could change? but having an little patch that can be applied to the css when you need to print might be sufficient?

The layout changes sound like a good idea, but need to be in their own PR, you'd also need to reach some consensus on that as I don't think a single person should have the definitive say on what is quite as large change — literal every user will see this. Perhaps make the PR then post on the forum with some before and after screen shots, like you've been doing, but just for the layout, explicitly asking for opinions, you could also make a poll over on scsynth to make it quicker for people to respond.

I think the font change should be optional and perhaps a setting inside of scide, rather than an opinionated hard coded value, as I for one like my system font. This would also make changing the font for print a manual choice, rather than an enforced decision.

I'm sure others will have different opinions, but the layout changes with evidence of community support would be the only things I'd feel comfortable reviewing.

[prko]

@JordanHendersonMusic
I agree with everything you have written! I already have two posts in the scsynth forum:

1. https://scsynth.org/t/help-document-enhancement-using-improved-scdoc-css-and-latex-with-additional-features-subsubsection-html-tags-and-punctuation-marks/9242

2. https://scsynth.org/t/is-the-sc-help-document-easy-on-the-eyes-font-line-and-paragraph-spacing-tables-punctuation-etc/9443

Some users left comments on MathJax, but not on other things. However, in my previous attempt, which I linked in my last post in this PR, there are some responses. There may be other responses to the current PR.

Um... I think it would not be bad if I (wait a few more weeks and then) change the title of this PR as follows

SCDoc improvements: 5. Update scdoc.css for better layout, font and printing support.

Then after writing with a new post linked to a google form, I will change thread #2 in the forum entitled

Is the SC Help document easy on the eyes (font, line and paragraph spacing, tables, punctuation, etc.)?

to the following title

[Poll] SCD help document layout, font, print support

What do you think?

[JordanHendersonMusic]

Sounds like a good idea!

But I'd:

• make a new post on scsynth, your proposed name is much clearer and sometimes it's good to make a little noise about important things.
• Close this PR for now and start a new one with a more concise title and description dropping the colour and font changes, linking to this one (just to show history) and the scsynth poll. I'd name it ScDoc: CSS layout changes for improved spacing. That way, when it comes to actually reviewing it, there is only the necessary information on the page, making things nice and fast!

You might consider using a GitHub discussion for these big changes in future, it might be a nice half way between the formal review and the completely open forum of scsynth (just an idea though)? You can submit the prs as drafts, but host the wider conversation in a discussion.

There's also the RFC, which, if you really wanted to pursue adding explicit print support, might be the way to go.

[prko]

Thank you so much! I will do so, and will also think about the RFC.