Bug#1095082: libsdl3-doc: many warnings regarding man page syntax reported by lintian

[Simon McVittie]

Package: libsdl3-doc
Version: 3.2.0+ds-1
Severity: normal
Tags: upstream help

lintian reports many warnings for the SDL API reference man pages such as
SDL_Keycode(3type).

These man pages are generated from Doxygen doc-comments at build-time
by using SDL-specific tools (build-scripts/wikiheaders.pl, I think),
so patching individual man pages to resolve these warnings is not a
solution. Instead, the generating toolchain should be improved. This
should happen upstream or not at all: I don't consider a Debian-specific
solution to be helpful here, because it would regress as soon as upstream
change their documentation and tools.

Solving this issue is not a high priority for me personally and I am not
able to allocate time for it, but upstream is usually happy to receive
code contributions via Github pull requests. If someone feels strongly
about this issue, please help upstream to improve the situation.

If improvements land upstream but are only included in their development
releases, I would be willing to consider a Debian-specific backport of
those improvements into an older stable-branch if necessary, as long as
it doesn't impose a regression risk or interfere with the stable release
review process.

Thanks,
    smcv