Following up to myself after an offlist query about whether "admin-guide.txt" was some sort of pkgsrc requirement. Sorry for being unclear and implying that a sugestion of how to deal with missing upstream docs is to create a particular file locally, meant that this was somewhow a rule. It isn't. What I meant is: Things that belong in documentation should not be in MESSAGE. For complicated packages that have install/config documentation provided by upstream, the expectation is that the user will read that documentation. Information that would be obtained by doing that does not belong in MESSAGE. The presence of MESSAGE should be unusual, for exceptional circumstances. One of the core principles of pkgsrc is a regularization of installation locations of documentation and examples, and having the example config file installed as an example and then linked via CONF_FILES to etc. This package looks like it does all of that right. As for docs/examples in general. If upstream ships installable documentation, it should be installed. This is already normal and I think not controversial If upstream has documentation on the web that they think shouldn't be installed, then I think the notion is that users should be expected to go find that and read it. (pkgsrc wraps upstream, and doesn't in general fix it more than we have to.) If pkgsrc needs to create documentation because upstream's documetnation is lacking, then that belongs in share/doc/PKGNAME. Examples (bits that are not used by the installed programs) belong in share/examples/pkgname. These are the standard locations and people are expected to look there without being told by MESSAGE. It follows that if for some good reason examples are elsewhere than the examples dir, a README there with a pointer to where they really are would be helpful (but we do not have any kind fo rule that says that, and if usptream docs say they are elsewhere, that's good enough). For complicated packages, a user can be expected to use "pkg_info -L" together with reading upstream's docs. This is not about bareos -- the abuse of MESSAGE is a widespread issue, and I was just speaking up because of the suggestion that MESSAGE be used to explain to people how to configure syslog and newsyslog for logging. That's a generic sysadmin skill, not about any package. I can certainly understand how people would get the idea that each package should have a mini-HOWTO written in MESSSAGE, as this has happened more recently, compared to long ago. But in discussions on the list over time, multiple people have spoken about over-use of MESSAGE. Part of the issues is that when people built packages one at a time, MESSAGE was more useful. With bulk installation tools of any kind, as are almost universally used (pkgin, pkg_rolling-replace, etc.) MESSAGE ends up lost. Thus, I look at each use of MESSAGE as a workaround for a bug in upstream docuementation. Agreed that this is not really documented correctly; it's on my todo list to fix.
Attachment:
signature.asc
Description: PGP signature