Hi, David and Peter! On 6/10/22 11:01, David Hildenbrand wrote:
On 09.06.22 22:13, Peter Xu wrote:Alex, Do you think we could add some of the semantic newline requirement into CONTRIBUTING file explicitly?
I plan to add something there by the end of this year more or less, when groff-1.23.0 is released. See below.
Although there's a pointer to man7 man-pages but the semantic newlines rules seem to be easily overlooked. IMHO there can even be examples as you quoted in the link on "UNIX For Beginners": https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/man-pages.7?h=alx/main&id=6ff6f43d68164f99a8c3fb66f4525d145571310c
Yes, I think I'll point to the 'UNIX for Beginners::Hints for Preparing Documents' thing from man-pages(7) with a link. Good idea.
Maybe that'll ease both the maintainers and the contributors?Maybe something similar checkpatch in Linux/qemu could point out a lot of these possible issues and reduce Maintainer overhead. Nobody reads docs after all if not forced to ;)
Actually, I was working on something like that. I didn't tell because it's under development, and requires to build groff(1) from source from their git HEAD (I will probably make it more public when groff-1.23.0 is released).
It even runs checkpatch(1) (or a fork of it that I did to make it standalone)[1] for the EXAMPLES programs.
[1]: <http://www.alejandro-colomar.es/src/alx/linux/checkpatch.git/>You can run `make -i lint` in the man-pages source tree _before_ applying your patch, to ignore all warnings not caused by you, and then run `make lint` _after_ your patch to see some warnings caused by your patch. You'll also see warnings not created by you but that are in the same file that you modified, but you can ignore them.
It's not perfect, and currently it doesn't detect semantic newline problems, I think, but I guess it could be improved in the future.
There's also another make(1) target to compile and link the EXAMPLES programs, in case you want to try it, but I'm also working on it and still has many issues. But if you want to try it, it's `make -i build-ld`, and then `make build-ld`.
You can try it, and maybe it helps you a bit. Those (lint and build) targets also have subtargets, so you can use autocomplete to see what subtargets there are, and run only the ones you're interested in. The Makefile may be too cryptic to try to read it from there, but you can try. :) You'll also see a lot of EXTRA_*FLAGS to modify commands.
Since I expect groff-1.23.0 to be released by the end of this year, I think I'll wait for then to make these features public, and that'll give me some time to polish them.
Cheers, Alex -- Alejandro Colomar Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
