Topic/more words to help home

[prko]

Purpose and Motivation

I recently compared the help document home pages (or index pages) of SC, Max, pd and Csound, and I found SC's documentation to be the most beginner unfriendly. The following three posts in a thread are relevant to this:

1. https://scsynth.org/t/developing-new-supercollider-tutorials/364/47?u=prko
2. https://scsynth.org/t/developing-new-supercollider-tutorials/364/49?u=prko
3. https://scsynth.org/t/developing-new-supercollider-tutorials/364/50?u=prko

Then I thought we needed more words for the help browser home page, and posted the following thread, where I also compared the SuperCollider 3.4 for Windows (I do not have a Mac to launch SC 3.4 on.) documentation with the current one:
https://scsynth.org/t/more-words-to-supercollider-help-document-home/8492?u=prko

This is the latest version, reflecting all the opinions in the thread above as best I can. I have also changed some links to be more appropriate. You can see these changes in the browser home of this PR in the following video:
https://www.dropbox.com/scl/fi/5531ljvpp1iy9j7uuduq3/sc-documentation-home-draft-4.mov?rlkey=ax82kto7erkn4dm2x056gvl2z&dl=0

As you can see in the video, the SuperCollider on the top left hides the S in the SuperCollider label. This is reported in #6138.

We should also update scdoc.css: the most important thing for this PR is to fix the width of the tables, which is also included in this PR.

The scdoc.js should also be modified to include the class tree in the indexes menu at the top. This is also included in this PR.

Notes

1. To arrange the table more beautifully, I am using soft:: :: for a space placeholder.
   The character between :: and :: is an en space:
   en space | 020002 | 8194 | 0x2002 |  

2. I have not added a link for sclang, as I am not sure which is better for it between Process, Main and Interpreter.

3. Would it be better to show the paths of sclang, scsynth, supernova and scide per OS? Showing these executables in the file explorer seems to help beginners understand the inter-application cooperation.

4. I am not sure what the correct category is for 'Audio device selection'. Would "Basic" in "Get Help" be better than the current category ("Basic" in "Overview")?

Types of changes

• Documentation

To-do list

• I hope that the source files included in this PR (and other files not included in this PR) will be modified by many users to get a better help documentation home for beginners, intermediate and advanced users, as well as for non-SC users who might read the help documentation home from the Internet out of interest. Feel free to change the details of this PR.
• Code is tested
• All tests are passing
• Updated documentation
• This PR is ready for review

[prko]

I hope that the source files included in this PR (and other files not included in this PR) will be modified by many users to get a better help documentation home for beginners, intermediate and advanced users, as well as for non-SC users who might read the help documentation home from the Internet out of interest. Feel free to change the details of this PR.

[capital-G]

Some minor corrections/suggestions from my side :)

The tables are very nice, but maybe maybe there is a way to control its layout more explicitly via css instead of adding some fill characters :)

[mtmccrea]

One final thought after this first read-through:
I nearly always have the Help pane docked in the IDE, occupying about 1/4 of the window’s width. Can you post a screenshot of the tables with a narrow pane width?

[prko]

I have split the "Contributing to SC" section into "Sharing your work" and "Contributing to SC".
I changed the left margin of the unordered list in table td in scdoc.css. As far as I have checked, there seems to be no list in a table in the default installation of SuperCollider. The "Help.schelp" file is the only unique help file.
I also removed soft::    :: which was used to adjust the width of the table cells, but not removed soft:: :: used for other purposes.
The following screenshots are taken with the minimum width of the Help Browser to display the Help Home correctly:

[mtmccrea]

Thanks @prko for the screenshots and making the adjustments to improve the appearance for narrower views!

[capital-G]

@prko maybe it would be best to use css grid layouts for the tables instead? Currently the width of each column is not aligned.

Using grid view allows in an easy way to distribute content equally as well as changing the layout easily on really narrow views (e.g. 200px) through e.g.

@media only screen and (max-width: 200px) {
    .table-content {
        grid-template-columns: 1fr;
    }
}

If you need some help for this I am happy to help :)

[prko]

@capital-G

@prko maybe it would be best to use css grid layouts for the tables instead? Currently the width of each column is not aligned.
...
If you need some help for this I am happy to help :)

This is a great idea. I found the following website:
https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout/Basic_concepts_of_grid_layout

To implement this functionality, a class (according to the page the class "wrapper") should be used in the scdoc.css file and the help.schelp file, if I understand it correctly.

Am I correct?

If I am correct, I can put the following part in scdoc.css:

.wrapper {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;
}

However, I do not know how to put its corresponding counterpart <div class="wrapper"> into the Help.schelp file. The SCDoc.sc file or/and the SCDocRenderer.sc file should seem to be modified, but this is beyond my capabilities.

So I need your help and I would be very grateful if you could help me!

[prko]

@capital-G

The SCDoc.sc file or/and the SCDocRenderer.sc file should seem to be modified,

Some tags seem to be related to .cpp, .hpp, .l, and .y files which are used to build a package of SC:
#6131

[prko]

the table design is changed. seems better?

[prko]

The current design (the smallest width).
The even cell width results in a wider page width.

[prko]

This seems to be the last change from my point of view, but I am willing to change if anyone asks for a change.

• Vertical cell width arrangement is better (still not perfect).
• Horizontal width is now the most compact.
• Links in Contribute and Share have been added and redesigned.

Here is some screenshots on Windows:

@capital-G
I would like to know if you have a solution for the following:

Using grid view allows in an easy way to distribute content equally as well as changing the layout easily on really narrow views (e.g. 200px) through e.g.

@media only screen and (max-width: 200px) {
    .table-content {
        grid-template-columns: 1fr;
    }
}

If you need some help for this I am happy to help :)

As I wrote earlier, I cannot find a way to do this myself, unfortunately...

[capital-G]

I just checked out the code and the problem is that scdoc is not really following best practices regarding DOM construction, so it is not possible to give a namespace to the described tables and therefore adjust only their styling. It also seems not possible to construct a div namespace "on the fly" within the document.

One can create a css selector along "select the table after the heading of title xyz" but this is prone to fail - additionally the individual blocks are not wrapped in a div and the individual blocks are also not divs, which makes alignment really hacky.

I tried to create a similar flow via definitionlist:: but it allows no nesting of lists or linebreaks, so I instead tried to use definitionlist with a list which looks like

definitionlist::
     ## Basics
     || List::
          ## link::Guides/How-to-Use-the-Interpreter::
          ## link::Guides/Understanding-Errors::
     ::
     ## Intermediate
     || List::
          ## link::Guides/Debugging-tips::
          ## link::Guides/Tracing-Processes::
          ## link::Guides/HID_permissions::
          ## link::Guides/LID_permissions::
     ::
     ## Intermediate
     || List::
          ## link::Guides/Internal-Snooping::
     ::
::

While I looked at it I also noticed some strange symbols in the code which should not be there - I think you use them to create spacing, but this is more a hack and one should use CSS instead, but this doesn't work either as stated above.

Generally, scdoc would benefit from a rewrite implementing div namespaces which would allow for improved styling capabilities, but this would be out of scope.

I think its best to use the existing design patterns within scdoc, as this makes a future re-design (or else) easier if there are not too different elements or hacks present.

[prko]

@capital-G
Thank you for your time, effort and kindness!

For me, the design is not that important. I am more satisfied with the current content because

• I can do more things in the help browser, and
• I think I can make SuperCollider more beginner-friendly.

I hope one of this one or the previous one could be accepted with the content based on the current content.

Here is the current state (The numbers '123' with a strikethrough line to the right of the 'Indexes' are relevant to #6207):