Vladistone patch 1: Update user-guide.adoc (images & TOC & :sectnumlevels: up to 3)

[Vladistone]

Multiple minor changes in:

• TOC revision, divided into the unnumeric chapters:
  ** basics;
  ** Reference (part 1) for Main panel;
  ** Reference (part 2) for Mapping panel;
• Increased numbering section titles level with :sectnumlevels:;
  Added:
• Description of a couple of new button functions.
• in the doc body, a lot of "back-to-Top" & "backs to References" buttons of the parent sections.
• Lots of screenshots of Realearn panels as well as screenshots of drop down menus and combo boxes.

This was a compromise between continuous chapter numbering and a deeper level of table of contents numbering up to 3 (rather than level 5 - what was be easy for you and me ealry moment). This made it possible not to clutter up the description and table of contents with a digital hierarchy. But at the same time - should to hepl for facilitate navigation through the sections of that serios manual (especially in the monotonous detail of the "Reference".

• Sorry for using a private VSTi REalearn setup with undescribed external controllers and add-ons for your own needs of the private Reaper project.
• This is my first experience on Github integration. I hope this helps to guide noobs like me in this user guide navigation, to facilitate the learning curve!

[helgoboss]

Hi @Vladistone. Thanks for this big PR! I really appreciate you updated all these screenshots and the thought you have put into making these user guide modifications. Must have been much work.

That said, I have a list of comments:

• Most screenshots expose something that appears to be a bug: Some icons are question signs, in particular the "right arrow" icon. Which macOS version do you use? I better fix this. While this is probably still better than outdated screenshots, it's still ugly.
• The screenshots are JPGs, I would prefer PNGs.
• There are quite some spelling errors in mapping names and so on.
• Why not leave the top-level numbering? This makes things harder to find in my opinion. I don't understand the reasoning behind that decision. For me, the numbering has the purpose to roughly navigate to the particular section of the document. Omitting the top-level section numbers destroys that purpose. Having numbers for each super small section adds a lot of noise.
• The breadcrumbs (back to top, back to main panel) are nice but they are hard to maintain. This is something that a developer would usually not like to write by hand, it could be generated.
• Describing the main panel using a table instead of arrows (SVG) breaks easily. The height of the rows can vary greatly depending on the device on which you read the documentation.

Some things I really like:

• The kbd: thing! I didn't know this feature.
• Also the collapsible parts

For the next time, it would be good if we could talk about the changes beforehand (before you actually make them). That would save you and me some work. Also, it would be better to make the PRs step by step. One huge PR is much less likely to be completely accepted than many small PRs.

I would suggest that we do this step by step if you have the time. One type of change, one PR.

[Vladistone]

Hi @helgoboss, this is my first attemption on this site and even more so with ASCIIdoc in principle! therefore, I was not familiar with the procedures for processing changes and introducing them into the master code. So I take all your critics and am ready to fix the errors. Further - I answer on the points of comments:

1. MacOS 10.13.6 (Reaper 6.75.OSX64, realearn 2.14.3/x86_64 rev. 68c524)

2. screenshots - can be converted to .PNG, but I would like to get an answer - do all of the original sketches satisfy the examples and correspond to the topics of the sections (some of them are repeated and can be formatted as links to the firsty sections)

3. spelling errors - maybe you're right, English is not my native language; and I want to note that in the names of the screenshots, I adhered to the names according to the hierarchical belonging to the sections, which would make it easier to group the pictures in a folder for further work with them. they are located in a separate folder "images 2")

4. I agreed with you and your concept of partitioning early on. But when I delved into the study of "Reference", I got lost there in such a volume of textual information and the lack of lower numbering only exacerbates the situation! There it is necessary "like air"! Otherwise, the essence of the instructions falls apart and leads to a state of "silly confusion in the head" (information does not fit in the brains, confusion and rejection from the presentation are created). especially when there is no elementary navigation:

• in which section the reader is located after 1-2 clicks on the inner links?..
  Therefore, my first desire was an elementary increase in numbering levels :sectnumlevels: up to 5...
  But when I looked at the intermediate result, I was disappointed (if everything became clear in the details, then the abundance of numbering levels led to despondency). had to choose bitween:
• or a harmonious picture with a through sequence of numbering from the beginning to the end.
• either provide markers/orientation at a low level? where there is a too much of information and [discrete] sections too...

I had to choose the second option.
(the third option could be transferring the description in the "Reference" section to a separate file - but this can also break the integrity of the perception of information and complicate the cross-references between the chapters of the manual. But all serious manuals are built this way - For example, from Korg Kronos:

• quick start (as a first level)
• User manual (middle level)
• Parameter guide (deep pro level)
  and further for those who are especially interested
• MIDI imlementation...

5. The breadcrumbs are essential, it's not difficult. but gives the text an additional navigational tool besides the table of contents:

• "where am I?" and "where can go up to parent level?"
  Would have been perfect if the TOC had been placed in the sidebar of the user guide! But apparently GigHub doesn't give this opportunity to use the ASCIIdoc toolkit to its full potential? Or have I not studied this tool thoroughly in 3 days? )).

6. I agree with you that it is possible to implement SVG arrows, instead of cardboard tabular layout and shematic description of the main panels with inner links. But in this way I tried to organize the subheading sui generis. To be able to move in the description of the sections "from panels to panels" and at the same time not go back up to the TOC. In order not to get stuck in the space of the manual. a similar rough solution is in the description of the Sources category of Mapping panel (there is a list with hyperlinks, but the numbering had to be inserted manually to match the subsections listed below, see fig.
   

Please give me idea to do it to another way...
once again, excuse me for my english;

[helgoboss]

Hi @Vladistone!

Hi @helgoboss, this is my first attemption on this site and even more so with ASCIIdoc in principle! therefore, I was not familiar with the procedures for processing changes and introducing them into the master code. So I take all your critics and am ready to fix the errors. Further - I answer on the points of comments:

1. MacOS 10.13.6 (Reaper 6.75.OSX64, realearn 2.14.3/x86_64 rev. 68c524)

Okay, I will try to identify the source of this error and fix it. We should wait with the screenshot stuff until this is fixed.

2. screenshots - can be converted to .PNG, but I would like to get an answer - do all of the original sketches satisfy the examples and correspond to the topics of the sections (some of them are repeated and can be formatted as links to the firsty sections)

At some point, I will go through the screenshots step by step and mark them accordingly. Repeated screenshots must be avoided, this should be solved using cross references to those images.

3. spelling errors - maybe you're right, English is not my native language; and I want to note that in the names of the screenshots, I adhered to the names according to the hierarchical belonging to the sections, which would make it easier to group the pictures in a folder for further work with them. they are located in a separate folder "images 2")

In the process of marking the screenshots, I can also fix the spelling.

4. I agreed with you and your concept of partitioning early on. But when I delved into the study of "Reference", I got lost there in such a volume of textual information and the lack of lower numbering only exacerbates the situation! There it is necessary "like air"! Otherwise, the essence of the instructions falls apart and leads to a state of "silly confusion in the head" (information does not fit in the brains, confusion and rejection from the presentation are created). especially when there is no elementary navigation:

• in which section the reader is located after 1-2 clicks on the inner links?..
  Therefore, my first desire was an elementary increase in numbering levels :sectnumlevels: up to 5...
  But when I looked at the intermediate result, I was disappointed (if everything became clear in the details, then the abundance of numbering levels led to despondency). had to choose bitween:
• or a harmonious picture with a through sequence of numbering from the beginning to the end.
• either provide markers/orientation at a low level? where there is a too much of information and [discrete] sections too...

I had to choose the second option. (the third option could be transferring the description in the "Reference" section to a separate file - but this can also break the integrity of the perception of information and complicate the cross-references between the chapters of the manual. But all serious manuals are built this way - For example, from Korg Kronos:

• quick start (as a first level)
• User manual (middle level)
• Parameter guide (deep pro level)
  and further for those who are especially interested
• MIDI imlementation...

AsciiDoc has a feature named Book Parts (when using :doctype: book). I think we should use this feature. "Reference" can then be a part instead of a section.

:!chapter-number: could be used to reset the chapter number on each section, avoiding too high numbers. However, this makes cross-referencing harder, it's not standard.

5. The breadcrumbs are essential, it's not difficult. but gives the text an additional navigational tool besides the table of contents:

• "where am I?" and "where can go up to parent level?"
  Would have been perfect if the TOC had been placed in the sidebar of the user guide! But apparently GigHub doesn't give this opportunity to use the ASCIIdoc toolkit to its full potential? Or have I not studied this tool thoroughly in 3 days? )).

GitHub limits the AsciiDoc features, that's correct. I'm not even sure if it supports doctype book, must try it. Breadcrumbs are something that I don't want to add manually. It's not just about writing them once, it's about maintaining them. This should definitely be a responsibility of the renderer of the AsciiDoc document. The official AsciiDoc docs also don't add breadcrumbs manually. In our case, the renderer is GitHub and it doesn't generate any breadcrumbs, nothing we can do about it. So the only option would be to change the renderer, generating a HTML document or even a lower-level AsciiDoc document ourselves, as part of the ReaLearn build process. Let's skip breadcrumbs for now. It's a topic for another day.

6. I agree with you that it is possible to implement SVG arrows, instead of cardboard tabular layout and shematic description of the main panels with inner links. But in this way I tried to organize the subheading sui generis. To be able to move in the description of the sections "from panels to panels" and at the same time not go back up to the TOC. In order not to get stuck in the space of the manual. a similar rough solution is in the description of the Sources category of Mapping panel (there is a list with hyperlinks, but the numbering had to be inserted manually to match the subsections listed below, see fig.
   

Please give me idea to do it to another way... once again, excuse me for my english;

I'm not sure I understand that. What's wrong with creating an image that contains arrows or numbers to name the specific parts?

Something else: You have created another PR and now all screenshots are SVGs (instead of PNGs). And the number of changes is very high. That's unfortunately nothing I can merge. Really, we need to do it step by step, small PRs that do one thing only, and talk about it before actually doing it. Otherwise you put so much work into it and I have to say "no", which makes both of us feel bad ;)

[Vladistone]

Hi @helgoboss!
I propose to move the discussion to a new PR: #823
so as not to be distracted by this version of the documents; reason - for not actuality that PR