Update user-guide.adoc

[Vladistone]

1st part of changes affected:
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: up to 3; Added:

• a couple description of new button functions.

[Vladistone]

Hi @helgoboss

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.

Deal!

2. screenshots - can be converted to...

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...

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

No problem! it`s fixed at this PR #823 ... Please, try to check this screenshots...

...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.

if you dont mark, I used this parameter (:doctype: book) at first PR #819
:toc:
:toclevels: 5
:doctype: book
:sectnums:
:partnums:
:sectnumlevels: 3
:experimental:
Maybe we misunderstand each other?
Are we talking about the same thing?

Please, pay attention to the concept of that changed new "user guide" format in the "preview" mode!

:!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.

Deal.

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.

I didn't understand anything from the links you provided. But from your comments - it's clear! And how I came to realize that manual activities for the coder are the subject of a particularly irreconcilable disagreement between the writing environment and workflow optimization...

The only thing I can refer to and appeal to is that I noticed the data of the feature from other developers. For example:
Tascam US2400
and it turned out to be convenient for amateurs to use.

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.

With this I fully agree. I would be glad if this was implemented! like on your website!
But in terms of gighub - this is not in my competence ... so the only hope is for you! and your ability to design a manual.html format.

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?

I have already removed this version of the code. and therefore the example described above is not relevant ... skip the comments

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 ;)

Ok, I will follow your advice. but the only thing I ask you to do in advance:

• get acquainted with the concept of PR#823in the "preview" [mode]

And

• give brief instructions on the stages of making changes (what needs to be provided first and what should be left for the long term?)

PS:
IMHO, the first thing you need is first commit bd59d71

1. implementation TOC revision, divided into the parts:

• basics;
• Reference (part 1) for Main panel;
• Reference (part 2) for Mapping panel;
• Reference (part 3) for "target type" discribtion (this is an additional innovation in ecb7b02
  and it is discussed, but desirable from the point of view of amateurs

2. :sectnumlevels: 3 - without taking into account the numbering of parts; as in my example (otherwise, the text of the manual looks like a novel for killing one's own time) sorry for this abstraction

And then maybe you will change your mind... that the manual necessary to draw up specifically for users with a zero level of knowledge about coding (and not for the developer's own needs). IMHO
And all other changes are just "felt-tip pens" as my all possible help in your grandiose project!

Regards, Vladistone