chore: migrate hardware manual to Markdown (part 2)

[acolombier]

Follow up on #867, extracted from #855

[JoergAtGithub]

Please fix the build check fails!
Are there any significiant sections taken from the Wiki?

[acolombier]

Please fix the build check fails!

Just forced pushed a fix, looks like some syntax messed sneaked in.
PDF is still borken, I will investigate later.

Are there any significiant sections taken from the Wiki?

None! This aims to be a "content perfect" migration, so we can simplify the review of #855 later.
For disclosure, I have used an agentic approach and used Playwright MCP for the success loop. It would compare the rendering of the local server (using sphinx-autobuild) and the 2.6 server.

Note that it isn't perfect. I could see some mild discrepancy so it will still need a human review to catch those regressions that we consider problematic.

[ronso0]

just some fixes for broken links I noticed

[acolombier]

Thanks @ronso0 !

I spend a good three hours to do a side by side comparison and update small details to get a near pixel perfect migration (+ fixing rendering issues in the live version).

I had to do two side chnages which are:

• Integrate a temporary fix for Line block not correctly parsed return42/linuxdoc#44
• Create a hook to circumvent the MyST footnote's behaviour (MyST always render footnote at the bottom, where as previous RST was rendered when defined)

Out of the thirty manual updates, here are my notes for future content improvement

hercules_dj_console_4_mx: Need some care for better rendering (likely automat-able with agentic workflow)
hercules_dj_console_rmx: Fixed random spaces in words
hercules_dj_console_rmx: Need some care for better rendering, especially hwlabel (likely automat-able with agentic workflow)
hercules_p32_dj: fixed image not correctly defined
numark_mixtrack: Need some care for better rendering (likely automat-able with agentic workflow)
numark_mixtrack_platinum: not exactly the same rendering as the original rendering, fixed some issues with bottom lists

Note that I found some content that had been changed by the AI beside the strict rules around respecting a perfect content migration. I have removed those.

Something remains wrong with the PDF build but not sure what. I need to investigate further.
Edit: seem to be failing on 2.6 already?

[ronso0]

I spend a good three hours to do a side by side comparison and update small details to get a near pixel perfect migration (+ fixing rendering issues in the live version).

Thank you!

So, in terms of review, we'd do just a quick side-by-side check?

And the wiki pages are postponed until we figure the license situation? (as @JoergAtGithub proposed)

[acolombier]

So, in terms of review, we'd do just a quick side-by-side check?

Yep! I have done it already, but a quick check would be good to confirm I didn't miss anything!

And the wiki pages are postponed until we figure the license situation? (as @JoergAtGithub proposed)

Absolutely, once I will have rebased the wiki migration PR, we should see much clearer as it will reduce the diff set quite a bit and we then decide if there is info worth keeping in (e.g with a AI-enabled rewrite) or simply noise/redundant and drop it, thus consider the Wiki entry as not adding any value (disclaimer, I think this is the case for +90% of it :D )

[acolombier]

Ok, everything is fixed. Had to make some fixes to l10n and latex rendering engine since the Markdown plugin (MyST) is more strict about certain errors (e.g not tolerating invalid roles).
We could probably disable those, but I thought this was a great opportunity to clean it up.
Also, only 2 dead link (which aren't actually dead, but blocked because coming from GH CIDR), which is the smallest I have ever seen on the repo 😆

[JoergAtGithub]

Does it work to edit translated strings here? Wouldn't the next tranifex update overwrite them with the old string again?

[acolombier]

I think it would, I believe we would need to import those fix back into Transifex, before further edits are made!
At the moment, since there were breaking the build, I was left with no choice but fixing it, but we should do the import as fast as possible so no community edit occurs.
Not sure how to do that?

[ronso0]

I think it would, I believe we would need to import those fix back into Transifex, before further edits are made!
At the moment, since there were breaking the build, I was left with no choice but fixing it, but we should do the import as fast as possible so no community edit occurs.
Not sure how to do that?

It is the wrong appraoch to change the .po files manually. It should suffice to change the sources only (.rst files), then update/regerate the tr templates and push to Transifex.
I think the process is described here https://github.com/mixxxdj/manual#maintaining-translations

[acolombier]

The problem is there was strings that where translated in Transiflex already, which should remain in English.

Example:

• :menuselection:`Preferences ...` -> :menuselectie:`Voorkeuren...` (see the role :menuselection: has been translated)
• |ic_lib_computer| This mode works... -> |ic_lib_ordinateur| Ce mode fonctionne... (see the icon role has been translated)

Happy to revert the commit otherwise but this will fail the build. I can perhaps try to filter the error with suppress_warnings or similar tho but note that translation breaks the page rendering currently anyway.

Happy to also report those fixes to Transiflex but I don't think I have access.

[daschuer]

Happy to also report those fixes to Transiflex but I don't think I have access.

Anyone has access. I just went ahead and fixed it there for all Versions.
For updating it to 2.6, we need to merge #708 first.

[acolombier]

Good to know! I am really not familiar with the setup regarding i18n