Optimize docs

[hansu]

Some optical fixes:

1. The default asciidoctor CSS scales the font up the window width > 768px, this looks too big --> revert this rule.
2. Align the caption of images according to the alignment of the image itself, default center align images .
3. Remove the "Chapter ###" from the PDF sidebar TOC, set inline level to so that we get a flat list of the man pages there
4. Set image width for images that doesn't fit into the default 75% scheme
5. Fix formatting of those block which renders as quote with asciidoctor

    ____
   ...
    ____ 
   

[hansu]

I think the chapters on the main docs page should be collapsed by default as they were before. Otherwise one have to scroll a lot. And as the javascript was removed, one have to scroll every time...

I added an corresponding commit.

[BsAtHome]

I think the chapters on the main docs page should be collapsed by default as they were before. Otherwise one have to scroll a lot. And as the javascript was removed, one have to scroll every time...

I think you should have at least the first one open. Having all collapsed does not give the user an indication that these are foldable structures. Having one (the first) open is a visual cue indicative of an action possible (together with the arrow; which should be styled a bit).

(the removal of javascript has not changed anything in the behaviour because open/closed state was not saved afaik)

FWIW, we need to rethink the front page IMO to support a more logical organisation. Regardless of the current open/closes list, it is difficult to find the information you want (because there is too much). The focus should be the user's perspective and how a user thinks.

[hansu]

I think the chapters on the main docs page should be collapsed by default as they were before. Otherwise one have to scroll a lot. And as the javascript was removed, one have to scroll every time...

I think you should have at least the first one open. Having all collapsed does not give the user an indication that these are foldable structures. Having one (the first) open is a visual cue indicative of an action possible

Good point 👍
Or have them underlined as classic link style (but a little bit ugly).

(together with the arrow; which should be styled a bit).

The old plus was more clear in this relation

(the removal of javascript has not changed anything in the behaviour because open/closed state was not saved afaik)

It rememberes the opened trees, you can still compare with the 2.9 docs: https://linuxcnc.org/docs/html/

FWIW, we need to rethink the front page IMO to support a more logical organisation. Regardless of the current open/closes list, it is difficult to find the information you want (because there is too much). The focus should be the user's perspective and how a user thinks.

Getting started and general information are on top. I don't think it's that bad. What do you have in mind?
Only a chapter "supported hardware" could be of interest. I have had this idea earlier but forgot about that: #2292

[BsAtHome]

(the removal of javascript has not changed anything in the behaviour because open/closed state was not saved afaik)

It rememberes the opened trees, you can still compare with the 2.9 docs: https://linuxcnc.org/docs/html/

Well, I am not completely against using js. I just require it not necessary for any normal operation of the pages. Anything should be completely functional and visible using standard html. So, we can hook a listener and use local storage (for the poor souls who cannot live without a js kick ;-))

FWIW, we need to rethink the front page IMO to support a more logical organisation.

Getting started and general information are on top. I don't think it's that bad. What do you have in mind? Only a chapter "supported hardware" could be of interest. I have had this idea earlier but forgot about that: #2292

If I had the answer, I'd tell you right away. There are too many things on my mind right now to redesign the documentation content. It is just that my own use of the pages always was accompanied with frustration and that is a sure sign that it is off (when you browse through the 1400 page PDF you also know that something is amiss). I need to do a deep dive and inventory before I can make a proper proposal.