Update EN source formats and sync JA translations up to 4d259bf

[hkuroki8450]

This PR includes two updates:

1. UG9 en: use common block separator
   (Note: Some trailing whitespaces are intentionally kept to prevent formatting issues when generating translated .adoc files from .po files.)

2. UG9 ja: sync up with changes until 4d259bf including newly added .adoc.po files

[emteelb]

Thank you for this contribution, Hiroshi-san. The changes in one of the commits in this PR, UG9 en: use common block separator seem problematic.

For example, in UG9/en/linstor-administration.adoc change on line 3442:

+======================================================|

Based on output from running a linstor resource-definition list-properties --pastable command in a test environment, that line should be as it was before the commit:

|======================================================|

As another example, in UG9/en/linstor-kubernetes.adoc, the commit changes line 348 to:

|-====================================================================|

when it should be what it was before:

|=====================================================================|

There is also an empty line introduced at 628 in UG9/en/linstor-kubernetes.adoc and an extra space at the end of line 1168.

These are just some examples of issues I see w/ the UG9 en: use common block separator commit in this PR.

Should we drop that commit from the PR and focus on the updated Japanese translations?

Checking in w/ @rck for another opinion also.

[hkuroki8450]

Hi @emteelb, Thank you for reviewing the PR and pointing this out! You are absolutely right. The changes in the UG9 en: use common block separator commit were actually a local workaround we used on our end to prevent formatting/rendering issues when generating translated .adoc files from the .po files. I understand now that they break the proper AsciiDoc formatting upstream. I completely agree with your proposal to drop that commit and focus only on the Japanese translations. Would you like me to remove the EN commit and force-push to update this PR, or is it easier for you to just drop that commit on your end during the merge process? Thank you for your help and cooperation! Hiroshi Kuroki

[hkuroki8450]

Hi Michael-san, Please accept my apologies, but I need to correct my previous message after consulting with my staff who created this patch. It turns out that the changes in the UG9 en: use common block separator commit (such as changing |=== to +=== and keeping certain trailing spaces) are a strictly necessary workaround for po4a (the tool we use for generating translations). If we drop these changes and revert to the original formatting, po4a fails to parse those specific blocks correctly, which completely breaks the rendering and layout of the generated Japanese .adoc files. Because dropping this commit will result in broken Japanese documentation, we would really like to keep this EN patch if at all possible. If these specific formatting workarounds are absolutely unacceptable for the upstream EN repository, could you advise on an alternative AsciiDoc syntax for these tables/blocks that satisfies both the upstream formatting rules and works seamlessly with po4a? Sorry for the confusion and the back-and-forth! Thank you for your understanding and support. Hiroshi Kuroki.

[emteelb]

Thanks for the explanation and context, Hiroshi-san. Sorry that you have needed a workaround on your end when preparing translations.

The LINSTOR client table output shown in the LINSTOR User Guide was made by adding the --pastable option to LINSTOR client commands. This was done for historical reasons and might not be necessary or preferred now, after discussing this issue with LINBIT colleagues.

Newer (default) LINSTOR client table output uses UTF8 and looks like this:

╭──────────────────────────────────────────────────────────╮
┊ Node   ┊ NodeType  ┊ Addresses                  ┊ State  ┊
╞══════════════════════════════════════════════════════════╡
┊ kube-0 ┊ SATELLITE ┊ 172.16.145.84:3366 (PLAIN) ┊ Online ┊
┊ kube-1 ┊ SATELLITE ┊ 172.16.126.82:3366 (PLAIN) ┊ Online ┊
┊ kube-2 ┊ SATELLITE ┊ 172.16.79.141:3366 (PLAIN) ┊ Online ┊
╰──────────────────────────────────────────────────────────╯

We can change all LINSTOR client table output that used --pastable output in the LINSTOR User Guide to instead use the UTF8 table output. Are your back ends UTF8-capable? Would this solve your issues? If so, we should wait to merge this PR until after I change the tables in the LINSTOR User Guide, and then rebase this PR and drop the one commit mentioned earlier.

I can likely do that in the next day or two if this sounds like a good solution to you.

[hkuroki8450]

Hi @emteelb,

Thank you so much for the detailed explanation and for proposing this excellent solution!

Switching to the default UTF8 table output sounds like the right path forward. Our backend should be UTF8-capable, but to be absolutely safe (so we don't accidentally break the Japanese build and have to revert everything), our technical staff suggested testing the new formatting on just one or two files first.

Since our current patch only touches UG9/en/linstor-administration.adoc and UG9/en/linstor-kubernetes.adoc, could you please update just these two files with the new UTF8 tables first?

Once you push those changes, we will pull them, run our po4a and PDF/HTML generators locally, and confirm everything renders perfectly. If it works as expected, we will give you the green light to update the rest of the LINSTOR User Guide, and we will update this PR to drop our workaround commit.

Does this step-by-step approach sound good to you?

Thank you again for your incredible support and flexibility!

Hiroshi Kuroki

[emteelb]

Does this step-by-step approach sound good to you?

Sounds good to me. I changed LINSTOR client tables in UG9/en/linstor-administration.adoc and UG9/en/linstor-kubernetes.adoc to the UTF8 style that LINSTOR client shows by default.

See Commit f68f52c.

When you have a chance to test, let me know if this fixes your need for a po4a workaround. Thanks!

[hkuroki8450]

Hi @emteelb,

I have great news! We fetched your commit and successfully generated the Japanese PDF. Our po4a tool handled the new UTF8 tables perfectly, and the formatting looks great without needing any of our previous workarounds.

Please feel free to go ahead and update the remaining EN files in the LINSTOR User Guide. Could you please let me know once you have finished and merged those changes upstream?

After the EN updates are fully complete, I plan to rebuild the Japanese translation files (.po) from scratch to match the new formatting, and then I will create a brand new JA patch.

Therefore, I propose that we just close/discard this current PR. Once you notify me that the EN files are ready, I will work on the new translations and submit a fresh PR.

Thank you again for your fantastic support and cooperation!

Hiroshi Kuroki.

[emteelb]

Hello Hiroshi-san. Glad to hear that the changes worked for you and that you no longer need the po4a workaround.

I changed the remaining LINSTOR client tables in the LINSTOR User Guide w/ Commit 4b2abf9
.

I propose that we just close/discard this current PR. Once you notify me that the EN files are ready, I will work on the new translations and submit a fresh PR.

Sounds like a good plan to me. Thanks you for all the work here. I will close this PR.