Documentation on cmd:PATTERN, so:PATTERN etc. missing from apk-search.8

I'm not sure where I learnt that apk-search(8) could accept cmd:PATTERN but it seems it was not the man page.

Upon trying to learn which prefixes are available the documentation is missing.

the prefixes don't mean anything (to apk) and have nothing to do with apk- they're just arbitrary virtual tags added by abuild. cutekitten: would be a valid tag too, added by abuild metadata

(and then apk's search includes searching such tags, of course)

What's the path of discovery for this? i.e. How does a person who first doesn't know how this works come to know how it works?

for 'custom' patterns themselves, i don't think there is one, unless some part of apk docs mentions them (so there isn't). for alpine-specific things like cmd:, they aren't mentioned anywhere except perhaps somewhere on the wiki?

so, there isn't one

I can see why the apk-* man pages don't contain info about the custom prefixes in question because they aren't tightly coupled, but surely they're related enough to have a See Also entry in apk-search.8 to some other man page with this info like, idk aports.8? Even just to explain this as not being part of apk...

apk tries to not be specific to anything- alpine is not the only distro user. a see-also would have to be patched in on alpine's side. but it does make sense.

as for the specials/specifics, they could be written in something like a alpine-apk.7 (7 for misc). not sure what i'd really call it. and someone would have to write it, of course

generally though, there's nothing that says manpages have to exist at all. i think https://docs.alpinelinux.org/user-handbook/0.1a/Working/apk.html contains most of this, though nobody is working in this anymore (it is/was unfinished). we don't really have an active docs team working on documentation all the time.

someone would have to devote a lot of time to finish just that (already started); manpages are yet another story. at the end of the day, the documentation in general falls short in a lot of places, but writing it is hard and nobody has simultaneously the time, motivation, and knowledge to actually do it (in terms of making it even better than it already is; what we have is not zero, haha).

Agreed, this is something that should be distro specific documentation as the automatically created virtual provides depend on the package generation tooling. @ncopa @ariadne any suggestions where and how to document these? Create apk-distro place holder man page that the distribution can override?

changed milestone to %backlog

I think apk-distro place holder man page could work, but I don't think this needs to be documented in apk-tools.