sdk: SDK manpages bad-whatis-entry

After trying this myself, I found that it wasn’t quite as simple as I thought. The dsc file also contains hashes and sizes of the archive files. After manually updating that with the new hash and file size, I was able to run it. The result shows all the bad-whatis-entry messages gone, with only the groff-message remaining, all mostly the same, as well as one new one for dotnet.1.gz.

W: dotnet-sdk-manpages: groff-message usr/share/man/man1/dotnet-new.1.gz (line 1) 312: warning [p 2, 1.2i, div '3tbd19,3', 0.0i]: cannot adjust line
W: dotnet-sdk-manpages: groff-message usr/share/man/man1/dotnet-new.1.gz (line 2) 389: warning [p 2, 1.2i, div '3tbd26,3', 0.0i]: cannot adjust line
W: dotnet-sdk-manpages: groff-message usr/share/man/man1/dotnet.1.gz (line 1) page 3: table text block will not fit on one page
W: dotnet-sdk-manpages: groff-message usr/share/man/man1/dotnet-new-sdk-templates.1.gz (line 1) 258: warning [p 1, 3.0i, div '3tbd19,3', 0.0i]: cannot adjust line
W: dotnet-sdk-manpages: groff-message usr/share/man/man1/dotnet-new-sdk-templates.1.gz (line 2) 335: warning [p 1, 3.0i, div '3tbd26,3', 0.0i]: cannot adjust line
W: dotnet-sdk-manpages: groff-message usr/share/man/man1/dotnet-new-sdk-templates.1.gz (line 3) 434: warning [p 1, 3.0i, div '3tbd36,1', 0.0i]: cannot adjust line

I’m not sure how much of an issue these are. They all appear to be related to tables possibly being too large for a display. However, with the rather large terminal screen size that I have, I don’t see any issue with the pages. Even when using XTerm in order to get a smaller terminal screen size (as I’m not sure how native terminal can be resized, and, for some reason, I can’t resize QTerminal), it is still legible enough.

Here is the source package, made up of three files. The two .zip files are not actually zip files, I just added the extension to it so that it could be uploaded. The dotnet-sdk-manpages_1.0.0.orig.tar.gz file contains the manpages from source build 6.0.102 with the patch from the PR applied. Ideally, you would replace that with a file with the same name and same internal directory layout with updated files. I was able to run sbuild with only these three files by running sbuild dotnet-sdk-manpages_1.0.0-1.dsc -d unstable, while already having an sbuild schroot of Debian unstable already set up. Alternatively, you can extract the contents of dotnet-sdk-manpages_1.0.0.orig.tar.gz and dotnet-sdk-manpages_1.0.0-1.debian.tar.xz into the same directory and just run sbuild from that directory. I’m sure you can also use another build system, such as debuild, pbuild, or dpkg-buildpackage. If lintian is not automatically run after the build, you can manually run lintian specifying the produced deb package. dotnet-sdk-manpages_1.0.0.orig.tar.gz dotnet-sdk-manpages_1.0.0-1.debian.tar.xz.zip dotnet-sdk-manpages_1.0.0-1.dsc.zip

After building with the manpage patch, the warning list from lintian when doing a documenation/manual check has been reduced significantly.

W: dotnet-sdk-6.0: bad-whatis-entry usr/share/man/man1/dotnet-environment-variables.1.gz
W: dotnet-sdk-6.0: bad-whatis-entry usr/share/man/man1/dotnet-install-script.1.gz
W: dotnet-sdk-6.0: bad-whatis-entry usr/share/man/man1/dotnet-new-sdk-templates.1.gz
W: dotnet-sdk-6.0: bad-whatis-entry usr/share/man/man1/dotnet-new-update.1.gz
W: dotnet-sdk-6.0: groff-message usr/share/man/man1/dotnet-new-sdk-templates.1.gz (line 1) 255: warning [p 1, 2.5i, div '3tbd19,3', 0.0i]: cannot adjust line
W: dotnet-sdk-6.0: groff-message usr/share/man/man1/dotnet-new-sdk-templates.1.gz (line 2) 332: warning [p 1, 2.5i, div '3tbd26,3', 0.0i]: cannot adjust line
W: dotnet-sdk-6.0: groff-message usr/share/man/man1/dotnet-new-sdk-templates.1.gz (line 3) 431: warning [p 1, 2.5i, div '3tbd36,1', 0.0i]: cannot adjust line
W: dotnet-sdk-6.0: groff-message usr/share/man/man1/dotnet-new.1.gz (line 1) 313: warning [p 2, 1.3i, div '3tbd19,3', 0.0i]: cannot adjust line
W: dotnet-sdk-6.0: groff-message usr/share/man/man1/dotnet-new.1.gz (line 2) 390: warning [p 2, 1.3i, div '3tbd26,3', 0.0i]: cannot adjust line

As far as the groff-message tag, it appears to me this is caused by the tables in the manpage. Not really sure if there is a fix for this. As far as the remaining bad-whatis-entry warnings, four entries remain, and, from what I can tell, these are the issues. First, with dotnet-environment-variables and dotnet-new-sdk-templates, there does not appear to be a name section. Also, these do not appear to be user commands, thus, would be more appropriate to put then in section 7 rather than 1. Not sure how difficult that would be. Also, when I checked a few man pages that I already had installed in section 7 (apparmor(7) and deb-version(7)), they both had name sections, with the same formatting. Thus, it is probably a good idea to still have a name section generated, even though there is no command to run. The issue with dotnet-install-scripts is that it is documenting multiple different commands with the same description, and is being separated by a |, whereas the recommendation in this case is to separate the entries with , . Finally, with dotnet-new-update, the - between the commands and descriptions is missing. Not sure if these fixes can be done by updating the script, or if this requires changes to the source documentation, or if, ultimately, it is decided these fixes aren’t warranted, in which case, I will add an ignore for the tag in these specific cases.

Also, one oddity I noticed with choosing to use - to separate subcommands, using dotnet-new-list as an example, as the command is dotnet new --list, the name appears as dotnet-new---list. I don’t consider this a problem, but I raise it just in case anyone else does.

Also, I think I may have a way to quickly test for this by setting up a debian source package containing only the man pages. This should allow quickly building the pages into a deb package using either sbuild, debuild, pbuild, or whatever is your prefered debian package builder, and then run lintian (possibly automatically) on the resulting package. As it does not have to deal with a 2 hour build time, as well as not having to check some 100k files, I would say this method would be much quicker and more iterative. I should be able to create a quick source package that will do that if it will help with testing and development.

I believe these are all generated via a pandoc script that was contributed to the repo. @omajid is this something you can look into? would it be a matter of extending the python scrubber script?

@TheJayMann is there an easy way to run debmake/sbuild so that we could prevent regressions in this area? or is it something that we’d have to leave to the dotnet/installer level?