Hi Matthew, Matthew King wrote on Tue, May 24, 2022 at 07:57:31AM -0000:
> While writing some documentation I noticed backup files turning up > in my mandoc.db and chased it down to what appears to be an oversight > when checking filename extensions in makewhatis. That is not an oversight be very intentional. > The current behaviour allows anything to follow the section name > part of each page's filename. Perhaps this is to allow compressed > manpages No, that is not related to compressed manual pages. Some other operating systems other than OpenBSD are in the habit of putting some manual pages into places like man1foo/name.1foo man1foo/name.1 man1/name.1foo and some use large numbers of different "foo" suffixes. Examples of such systems include Illumos and some Linux distributions that use mandoc. Since we keep the OpenBSD manual page trees very clean, supporting both clean paths like "man1foo/name.1foo" and unclean paths like "man1foo/name.1" and "man1/name.1foo" does not cause problems on OpenBSD. Also, i like to keep the mandoc code on OpenBSD and the portable version as close together as possible, both to ease maintenance and reduce the risk of bugs and at the same time to allow viewing the manual page trees of all supported systems on any supported system. For example, it is not unusual for me to look at the tree of FreeBSD manual pages, or to look at subtrees of manual pages from Linux distributions, while running OpenBSD. The code to support the various variants of such suffixed directory and file names has seen many iterations and fixes during the last few years. Touching it lightly is not a good idea because testing changes is very hard. It basically requires testing in real-world trees of several different operating systems. > but I couldn't find any overt reference to such a feature > in mandoc's documentation but rather it seemed to imply that the > section in the filename must exactly match that in the directory > name: > > The mandoc.db(5) database is used for looking up manual page > entries. In cases where the database is absent, outdated, or > corrupt, man falls back to looking for files called name.section. That is from the man(1) manual page. You might argue the statement is outdated because some years ago, man(1) also started showing files with suffixes if they exist. Then gain, it is an important goal to not overburden the man(1) manual page with implementation details and instead keep it concise and readable for beginners. So i would hesitate to spell out the full rules here regarding which files are accepted. On top of that, most systems that have unclean names like "man1foo/name.1" and "man1/name.1foo" do not particularly like these names themselves and would probably like to get rid of them and consistently use the clean form "man1foo/name.1foo", in which case the man(1) manual would be exact again. At least, i feel the man(1) manual should not give the impression of encouraging unclean names. > By default, makewhatis creates a database in each dir using > the files mansection/[arch/]title.section and > catsection/[arch/]title.0 in that directory. That is from makewhatis(8). More precise information could probably be added here with no significant downside. > The included patch fixes my issue by warning and rejecting a backup > file alongside a manpage's source but does so by changing the > behaviour of makewhatis to reject all files (by default) without a > precisely matching section name. The patch is not acceptable because it removes features that are intentionally supported and that various systems rely on. Besides, it is usually necessary to keep the makewhatis(8) lookup code in mandocdb.c in sync with the fallback lookup code of man(1) in main.c, and your patch touches only one of the two. It is not possible to make both lookup codes behave in exactly the same way because that would slow down man(1) too much, so there are a few subtle differences that can't be helped, but your change would make the two totally different, resulting in egregious inconsistencies in behaviour with and without mandoc,db files. Yours, Ingo
