Re: docs: automarkup.py

[Mauro Carvalho Chehab <mchehab@kernel.org>]

Em Wed, 27 Dec 2023 14:20:05 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> Hi Vegard and Mauro,
> 
> Thanks for your assistance.
> (more below)
> 
> 
> On 12/27/23 01:08, Vegard Nossum wrote:
> > 
> > On 27/12/2023 08:55, Randy Dunlap wrote:  
> >> Can anyone explain this?  maybe even suggest a fix for it?
> >>
> >> This has been around for a few weeks AFAIK. I haven't see a patch for it,
> >> but I could have missed it.
> >>
> >> (since 17e02586ed185 in August/2023; oh, that just fixed the move
> >> of files to the Documentation/arch/ subdir, so maybe even longer)
> >>
> >>
> >> In file Documentation/ABI/testing/sysfs-bus-papr-pmem:
> >>
> >>         response to H_SCM_HEALTH hcall. The details of the bit
> >>         flags returned in response to this hcall is available
> >>         at 'Documentation/arch/powerpc/papr_hcalls.rst'. Below are
> >>         the flags reported in this sysfs file:
> >>
> >> kernel-doc reports:
> >>
> >> linux-next-20231222/Documentation/ABI/testing/sysfs-bus-papr-pmem:2: WARNING: unknown document: '/powerpc/papr_hcalls'
> >>
> >> and the output file Documentation/output/admin-guide/abi-testing.html says:
> >>
> >> response to H_SCM_HEALTH hcall. The details of the bit
> >> flags returned in response to this hcall is available
> >> at '<span class="xref std std-doc">/powerpc/papr_hcalls</span>' . Below are
> >> the flags reported in this sysfs file:</p>
> >>
> >>
> >> so the leading "Documentation/arch" is being removed from the filename
> >> AFAICT.
> >>
> >> I tried changing the quoted filename from single quotes to double back quotes
> >> `` and I tried it without any quotes, all with the same results.
> >>  
> > 
> > I don't see that here, there is no warning and it renders properly.
> > 
> > If you go on https://docs.kernel.org/admin-guide/abi-testing.html then
> > it says 6.7.0-rc7 and (AFAICT) it also links/renders properly.  
> 
> Yes, I probably should have checked there earlier. :)
> 
> > Maybe try building in a fresh clone/worktree just to verify there isn't
> > some old file somewhere that didn't get cleaned out/updated?  
> 
> That does work but it made me suspicious.
> 
> I was building in a kernel tree that was built from a tarball
> and linux-next daily patches.  That leaves behind some *.orig files
> (since I use 'patch -b' for "backups").
> 
> If I remove the Documentation/ABI/*.orig files, there is no issue
> like I had erroneously reported here.
> Maybe get_abi.pl is (also) processing the *.orig files and that
> somehow causes it to produce the confusing output.

The logic which parse files at get_abi.pl is this one:

    sub parse_abi {
        my $file = $File::Find::name;

        my $mode = (stat($file))[2];
        return if ($mode & S_IFDIR);
        return if ($file =~ m,/README,);

Currently, it ignores just README and directories.

It wouldn't be hard to add something like:

	return if ($file =~ m,/\.(rej|org|orig|bak)$,);

to ignore certain extensions. On such case, we would need to explicitly
add the extensions to be Ignored.

We could, instead, do a broader regex:

	return if ($file =~ m,/\.,);

to ignore everything that would have a dot at the file name, but that
could be problematic if we ever end adding files with extensions
there.

Regards,
Mauro