Re: [PATCH v3] madvise.2: Clarify addr/length and update hugetlb support

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 2952 bytes --]

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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]