docs: man/man1/*.adoc - review asciidoc formatting (smoe:docs_wording_20240807)

[smoe]

Likely completed review of man/man1.

The second patch was a series of harmless simplifactions for the translations that were still in my git stash.

[hansu]

Thanks for continuing on this!
a2x seems to be a bit buggy in our case. I haven't had the time yet to investigate this further. See #3057
Removing the square bracket changes in the two files and the other one thing makes the build run successfully on my machine.

[petterreinholdtsen]

I do not understand the rationale behind all your changes, but have no objections to them. Most of the changes make sense to me, but some I suspect neither affect the layout nor the po4a splitting of strings. This is just meant as a suggestion for you to make sure the changes do what you believe they are doing, not as a request to change anything in the patches unless you yourself believe they are wrong.

[smoe]

@hansu, the []s are important, pointing to a section of the INI file. I found a small error that with a bit of luck fixes it.
@petterreinholdtsen, yes, I agree, some changes I only made in anticipation of problems with po4a, but I expect also the human eyed to benefit from them, and others just for cosmetic purposes that would not affect the HTML or pdf representation. And sometimes I did not think about what I was doing, it just felt right.

[petterreinholdtsen]

The failing CI test seem to be a problem with Debian unstable (perhaps gcc 14), not with the adoc changes.

[smoe]

Could some good soul please help with a patch that improves the wording of this description?

[hansu]

You have to configure the vfd so that this status bit is mapped to the function "up to frequency"

See https://dl.mitsubishielectric.com/dl/fa/document/manual/inv/sh060014/sh060014engb.pdf

page 458 and pages 61/62:

[smoe]

Same here, I did not get it.

[smoe]

The "fixme"s I came up with aside, I think this can be accepted and the PR closed.

[petterreinholdtsen]

[Steffen Möller]

The "fixme"s I came up with aside, I think this can be accepted and the PR closed.

I had a look and sampled the change, and it look good to me. I have no idea about improved wording of the confusing parts. I did not merge it, in the hope that Andy or someone else might have wording improvements to contribute before it is merged. Perhaps some of the open conversations can be closed in this pull request, to make their status easier to grasp? -- Happy hacking Petter Reinholdtsen

[hansu]

Let me test it with a local build to see if the square brackets are all formatted properly.

[hansu]

The failing CI test seem to be a problem with Debian unstable (perhaps gcc 14), not with the adoc changes.

Sure that this a a CI thingy?

Runtest: 271 tests run, 269 successful, 2 failed + 0 expected, 4 skipped
Failed: 
	./tests/mdi-queue/oword-queue-buster
	./tests/mdi-queue/simple-queue-buster

The result of the first looks like this

trying to connect to linuxcncrsh TOGO=80
Machine configuration file is 'linuxcncrsh-test.ini'
check_config validation failed
LinuxCNC terminated with an error.  You can find more information in the log:
    /home/cnc/linuxcnc_debug.txt
and
    /home/cnc/linuxcnc_print.txt
as well as in the output of the shell command 'dmesg' and in the terminal
trying to connect to linuxcncrsh TOGO=79
trying to connect to linuxcncrsh TOGO=78
trying to connect to linuxcncrsh TOGO=77
trying to connect to linuxcncrsh TOGO=76
...
trying to connect to linuxcncrsh TOGO=4
trying to connect to linuxcncrsh TOGO=3
trying to connect to linuxcncrsh TOGO=2
trying to connect to linuxcncrsh TOGO=1
connection to linuxcncrsh timed out

[hansu]

@smoe I wanted to push some changes on your branch, but it was rejected - did you disable

?

[smoe]

Have not knowingly disabled it but you are right, it was disabled when I just looked. Fixed that.

[smoe]

[Steffen Möller]
The "fixme"s I came up with aside, I think this can be accepted and the PR closed.
I had a look and sampled the change, and it look good to me. I have no idea about improved wording of the confusing parts. I did not merge it, in the hope that Andy or someone else might have wording improvements to contribute before it is merged. Perhaps some of the open conversations can be closed in this pull request, to make their status easier to grasp? -- Happy hacking Petter Reinholdtsen

@andypugh , may I kindly ask to have a quick look at those FIXMEs on https://github.com/LinuxCNC/linuxcnc/pull/3060#:~:text=View%20reviewed%20changes-,docs/src/man/man1/mitsub_vfd.1.adoc,-VFD_NAME**.stat%2Dbit%2D4 ?

[hansu]

Have not knowingly disabled it but you are right, it was disabled when I just looked. Fixed that.

thanks

[smoe]

Just rebased to master and squashed it all. Hansu's changes are still in :-)

[petterreinholdtsen]

Should this wait for better wording on the unclear VFD settings?

[hansu]

See #3060 (comment)

[hansu]

I would suggest something like this

[petterreinholdtsen]

Do you plan to rebase and squash again? I notice there are three commits, and would expect only one if it is squashed.

[smoe]

Do you plan to rebase and squash again? I notice there are three commits, and would expect only one if it is squashed.

Squashed.