pkgsrc-Users archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

Re: Bareos in pkgsrc / Web Console?

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

  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

Home | Main Index | Thread Index | Old Index