Add check for "bad" HTML links

[fingolfin]

The bug fixed in https://github.com/gap-actions/build-pkg-docs should have been caught by validation -- and indeed, in ReleaseTools, it would have been, because it had this in it:

# basic sanity check
fgrep -q -r '<a href="/' */*.htm* &&
    error "HTML manual contains absolute paths"

I think we should have such a check in this workflow.

And possibly also have it in release-pkg for redundancy.

CC @Joseph-Edwards @stertooy

[fingolfin]

As another layer of defense, the PackageDistro should also check this (and possibly more). In fact there is an old issue there about this: gap-system/PackageDistro#202

[stertooy]

I was going to add this to release-pkg, but I have a few small questions/concerns:

• If a package has no documentation, then fgrep will complain about 'No such file or directory' and throw exit code 2. That might be undesirable? (Such packages do pass the ValidatePackageInfo check if PackageDoc is set to the empty list [].)
• Do we only want to look in subfolders? I don't really see a good reason for html files in the main package directory to have absolute links either...
• Should we also check for hyperlinks starting with file:// instead of just / ?

[limakzi]

Should we also check for hyperlinks starting with file:// instead of just / ?

It is not necessary, I think.

Do we only want to look in subfolders? I don't really see a good reason for html files in the main package directory to have absolute links either...

I agree.
For our case absolute links mostly cause only problems.

If a package has no documentation, then fgrep will complain about 'No such file or directory' and throw exit code 2. That might be undesirable? (Such packages do pass the ValidatePackageInfo check if PackageDoc is set to the empty list [].)

How about skipping test if PackageDoc is empty?

[fingolfin]

So the fgrep I shared was simplistic, and it can and ideally should be improved upon; but already it on its own is a great improvement I'd say.

I guess ideally we'd look at the PackageDoc list or record and the HTMLStart in each book listed there, to figure out in which base directories to look (i.e. if the entry is "htm/chapters.htm" then we should look into the htm dir). And then recursively search all *.htm and *.html files in there.

But I think it would also be fine to just search doc and htm recursively, if they exist (and if not, just don't do anything). We could also search the entire package dir, would also be fine by me.

[fingolfin]

And ideally we'd check this in three places:

1. the build-pkg-doc action -- so pkg authors can notice it while working on their package
2. in the release-pkg action -- to prevent bad releases (when you didn't notice the CI job was failing)
3. in the PackageDistro -- to catch packages that were made by some other means but might nevertheless suffer from the same problme

[limakzi]

@fingolfin , @stertooy So probably, it would be more valuable to build it as simple action that can be included. For example?

test-pkg-docs

Edit.

I approved pull-request, since for now is good enough MVP and improves the action immediately.
Deliver fast, fail fast.