docs(html): KiCAD-inspired topbar, side TOC, language switcher, admonition tints

[grandixximo]

Re-implements the docs topbar on top of the merged docs/build/ layout (#4081). Supersedes the pre-#4081 prototype (766f2d9103).

What it adds

• Sticky topbar with the LinuxCNC logo on every page, matching asciidoctor's footer palette. Logo at docs/src/lcnc-docs.svg, copied into docs/build/html/ by the shared-asset rule.
• Side TOC via asciidoctor :toc=left; auto-hides below 800px.
• Language switcher (top-right), built from po4a.cfg plus a LANG_LABEL_<lang> map so po4a.cfg stays the single source of truth. Works on regular pages and manpages.
• Admonition tints (note/tip/warning/caution/important) with Unicode icons mapped onto asciidoctor's icons=font output, no FontAwesome dependency.

Per-page translation status

lang_switcher_postprocess.py walks the built tree, looks up each page's coverage in the per-language .po, and greys out switcher entries (and dead manpage-index links) below the POKEEP threshold (default 80%). POKEEP=30 on the make line surfaces in-progress translations; documented in contributing-to-linuxcnc.adoc, building-linuxcnc.adoc, and docs/README.adoc.

Notes

• Build-time injection only: docinfo-header.html from a .html.in template via docinfo=shared; gcode.html becomes gcode.html.in (po4a master) with per-language topbar fragments; the stale hardcoded Translations: list in index.tmpl is dropped in favour of the switcher.
• Verified with a full translated build (8 languages, 2387 translated pages).

[BsAtHome]

You are hiding translations and doing grayed out presentation? The data is still there and you deliberately restrict access to it. That is IMO a Bad Move^TM and user unfriendly.

If a translation is not worthy to show, then it should be removed entirely. Any cutoff level is always an arbitrary value and you have no idea which part you will hit. The large translation file may be only 10% done, but that can cover a complete section of the documentation, which you now are hiding.

The better way is to start splitting the translations into smaller units so that it becomes much easier to do a full translation for a part. At the moment, you just see a huge mountain of stuff to translate with no end in sight. Smaller units solve that. But it is for the future.

[grandixximo]

You are hiding translations and doing grayed out presentation? The data is still there and you deliberately restrict access to it. That is IMO a Bad MoveTM and user unfriendly.

Also this one, wasn't sure what to go for, mostly trying to avoid broken links, I'm not sure what you are proposing here, the only way is a % and it is arbitrary, but it's the standard as far as I looked around, the chapter split for translation does not belong here, is the bad move a blocker? What's the alternative for this PR?

[BsAtHome]

Per your comment:

lang_switcher_postprocess.py walks the built tree, looks up each page's coverage in the per-language .po, and greys out switcher entries

Why do this at all? If a language was translated and enabled in po4a.cfg, then it will be there. No buts, the config states it is available, then it is available.

You worry about (external) links? This is the devel tree doc, not a release, and there are no guarantees in development. How else can we reorganize? Reorgs break things.

(and dead manpage-index links)

Don't hide it. This stuff needs fixing, not hiding.

What's the alternative for this PR?

It is not about "alternative". The redesign is great. The details are being discussed.

[hansu]

It would be cool if we could get the whole TO in the left panel, like

And I would move the Navigation to the top, like the style of the Numpy docs

You are hiding translations and doing grayed out presentation? The data is still there and you deliberately restrict access to it. That is IMO a Bad MoveTM and user unfriendly.

But if a language has a translation status of 10% or I would even say <50%, I would tend to hide this language. I think a mix of languages is more irritating than a complete English doc. Then you cannot really use the browser translation function.

Would be nice if we could suppress this when only building for one language:

file:///home/cnc/linuxcnc-master-docs/docs/build/html/de/gcode.html
  Line: 57
  Code: 404 File `/home/cnc/linuxcnc-master-docs/docs/build/html/de/gcode.html' does not exist
 To do: The link is broken. Double-check that you have not made any typo,
        or mistake in copy-pasting. If the link points to a resource that
        no longer exists, you may want to remove or fix the link.

[BsAtHome]

You are hiding translations and doing grayed out presentation? The data is still there and you deliberately restrict access to it. That is IMO a Bad MoveTM and user unfriendly.

But if a language has a translation status of 10% or I would even say <50%, I would tend to hide this language. I think a mix of languages is more irritating than a complete English doc. Then you cannot really use the browser translation function.

You are undermining your argument by using "browser translation function". If you want the browser to translate, then you always should use the master (untranslated) documentation language (English) as the base for any automated translations... Not doing so would create Babel in extended fashion with aliens from Mars pitching in.

That actually touches the reason why or why not to do (full) documentation translations at all. The automated translations work very well for "casual" texts. However, highly technical documents range from usable to mediocre to poor to outright misleading when auto-translated. Secondly, this stuff is often running on systems that are isolated and no access to Internet or advanced tools. Local information is still relevant for these systems.

Hiding stuff is simply not the right way to solve the problem.

[hansu]

You are undermining your argument by using "browser translation function".

I mean if you have a text where one paragraph is English and the next one is in some other language and so on.
So if you are a person who have is very hard to read English you would enable browser translation. But I assume it gets problems when it expects English s source and there is text in other languages in between. So for that person this partly translated docs would not be very helpful.

But forget that idea. If we hide the partly translations, it is hard so see the status and what needs to be translated.
Maybe add a note/warning "This language is only XX% translated"

That actually touches the reason why or why not to do (full) documentation translations at all.

But how would you mark the chapters which are translated completely?

[BsAtHome]

That actually touches the reason why or why not to do (full) documentation translations at all.

But how would you mark the chapters which are translated completely?

That is a good question. Probably by separating or grouping (some of) the chapters in translation. But any change here needs to wait because it should be accompanied by rethinking and moving around much of the documentation (content) to make a more logical and coherent story.

[grandixximo]

@hansu doesn't the TOC already render on the left panel with this PR? Or am I missing something?

[hansu]

@hansu doesn't the TOC already render on the left panel with this PR? Or am I missing something?

With whole I mean the whole documentation or at least the chapter and not only the toc of the regarding adoc document.
So currently it's only like this and that brings not much benefit.

[grandixximo]

@hansu in the other picture you changed the LinuxCNC Home Page link for Documentation, but the top left logo already links back to Documentation main page, I think it should stay linking back to linuxcnc.org not documentation, or you were thinking something different?