On Sat, Aug 19, 2023 at 07:21:58PM +0200, Ingo Schwarze wrote: > Hi, > > Stuart Henderson wrote on Fri, Aug 18, 2023 at 05:52:07PM -0000: > > On 2023-08-18, [email protected] <[email protected]> wrote: > > >> Also, what is the reason the quirks package does not have a man page? > > Usually, there is no manual page documenting a package as a whole. > > >> I believe it should have one, just like any other program. > > The quirks package certainly isn't a program. > Right now, i fail to see any evidence that it even *contains* any program. > > >> Is this something that is desired? > > The following is certainly not a good syllogism: > "There is no manual page documenting this package" > => "We need a manual page documenting this package" > > Even the folliwing, weaker syllogism may occasionally be false: > "This package contains no manual page" > => "We should write a manual page to include in the package" > > Is information about the quirks package missing from the manual pages? > Maybe, it doesn't seem unlikely to me, but i'm far from sure. > > >> If so, I would gladly model one after the package description. > > What a terrible idea. Most of that information is already contained > in the manual page sthen@ mentioned: > > > packages(7) - overview of the binary package system > > I think what packages(7) says is also easier to understand than > what the quirks package description says. > > > not sure what such a manpage would be named. > > Given that manual pages are named after programs, functions, devices, > or file formats, > > $ pkg_info -L quirks > > tells me that a manual page to be included in the quirks package > could be named: > > OpenBSD::Quirks(3p) > > - that one would document the Perl API of the OpenBSD::Quirks > Perl package, similar to e.g. OpenBSD::PackingElement(3p) > or OpenBSD::State(3p) > > or > > update.db(5) > > - that one would document the file format of the file > /usr/local/share/update.db and explain how that file > is used, similar to mandoc.db(5) or locate(1) -- > by the way, it does look like we are missing a > locate.database(5) manual page > > > it is already described here though: > > $ man -k any=quirks > > packages(7) - overview of the binary package system > > Right, any information about the quirks package that doesn't > belong into OpenBSD::Quirks(3p) or update.db(5) probably > belongs into packages(7) or pkg_add(1). > > Yours, > Ingo > from my phone so bear with me for the poor formatting.
the whole point of quirks is to deal with unforeseen upgrade issues. So there's no point in documenting an api that's meant to evolve and be abused as needs arise.
