Man: update manpages

[amikan]

To pass lintian check in Debian every binary installed in the system should have its man page. I've used --help output as a reference to create all of them. But for some of the runners it was just the same as nrunner, so I've put the descriptions from source comments there. We need it just to have tests passing, but I will appreciate if anyone would like to prepare real (more detailed) manpages.

Also provide correct line adjustment in man/avocado.rst to pass syntax checks.

[ana]

Hi! As mentioned in https://github.com/avocado-framework/avocado/pull/5044 :

The avocado runners don’t need to have manpages. You can link all the avocado-runner to show avocado’s manpage in the Debian packaging. Or if you prefer, you can write a manpage for all the runners explaining they’re part of avocado and the differences between them. I'm afraid the manpages you've include don’t add a lot of value and I wouldn't want to carry them as part of avocado.

[beraldoleal]

Hi! As mentioned in #5044 :

The avocado runners don’t need to have manpages. You can link all the avocado-runner to show avocado’s manpage in the Debian packaging. Or if you prefer, you can write a manpage for all the runners explaining they’re part of avocado and the differences between them. I'm afraid the manpages you've include don’t add a lot of value and I wouldn't want to carry them as part of avocado.

Although I see some value on those, yes, I agree with @ana here. If we could at least generate those manuals automatically then it would be fine. Without this automation, they are static it is just more pages to update.

[clebergnu]

Bitrot is real... and we've suffered with the main avocado man page. As much as Avocado should have man pages for all runners, it does feel like this will bitrot very easily.

@amikan please believe that your help and contribution here is greatly appreciated... having said that, any chances you could spare a few more cycles an look into the auto generation of those? Just as a reference, I did something similar a long time ago for Autotest/arc that may be useful.

[amikan]

Bitrot is real... and we've suffered with the main avocado man page. As much as Avocado should have man pages for all runners, it does feel like this will bitrot very easily.

@amikan please believe that your help and contribution here is greatly appreciated... having said that, any chances you could spare a few more cycles an look into the auto generation of those? Just as a reference, I did something similar a long time ago for Autotest/arc that may be useful.

I've tried autogeneration (with help2rst.py tool from nghttp2) before doing that by hand, but was not satisfied with the result. Sure it's better to use autogeneration, but now it's all up to tool.