[Slackbuilds-users] templates and guidelines

[B Watson]

On 5/30/17, David Spencer <baildon.research at googlemail.com> wrote:

> As I said above, it would be great if other people could add to the
> list of things that need guidelines please!

Ran across this recently: http://jbr.me.uk/linux/esl.html

It's geared towards Debian, but it's a pretty good set of guidelines for
how to write package descriptions. For us, that's slack-desc and README
files. Also, my own short version:

Don't blindly copy/paste from upstream's README or web site. Their
description usually makes a good starting point, but you should fix
any spelling/grammar errors, get rid of any hyperbole (anything that
reads more like advertising copy than a factual description), and get
rid of excessive detail: We don't need to know the whole history of the
software, or the list of 10 platforms it's been ported to. Or, rather,
users browsing the SBo package repo don't need that much detail, just
to decide whether or not the package looks like something they might
want to install. The place for the extra detail is inside the package,
in /usr/doc/$PRGNAM-$VERSION.

Also, I think these really should be rules:

- README and .info file must be either plain ASCII, or UTF-8, *without BOM*!
  If in doubt, use the 'file' command.

- The only reason to make README or .info files UTF-8 would be if there's
  a proper name that requires non-ASCII characters (maintainer's name,
  or possibly the name of the software itself, like "LÖVE"). Cute Unicode
  bullets, or emdashes, or "smart quotes", should be replaced with ASCII
  equivalents (asterisk for bullets, plain hyphen for dashes, plain single
  or double quotes instead of “these† or ‘these’ quotes).

- slack-desc needs to be ASCII. It's going to get catted to the user's terminal
  when the package is installed, and there's NO WAY TO TELL what character set
  and encoding the user's terminal expects.

Guidelines about file locations: I'd say you should only use /opt when
your build is for something that might conflict with stock Slackware
packages. Example, mozjpeg installs libraries and binaries with the same
names as stuff from Slack's libjpeg-turbo package.

If your build is a game, put the executable in /usr/games, any data files
in /usr/share/games/$PRGNAM (though I've broken this "rule" myself,
plenty of them install to /usr/share/$PRGNAM). Man pages for games go
in section 6, /usr/man/man6, which might mean you need to patch or sed
the man pages themselves (since the man page section appears in the file).

If it's a game ported from Windows, which expects to be run from its
own directory (which it expects to be able to write to), use a wrapper
script in /usr/games, place the real game binary in /usr/libexec/$PRGNAM/.
Again, plenty of examples of this "rule" being broken if you look through
my builds. In fact I should go through and fix them...

David doesn't want to post "bad" submissions for fear of embarrassing
anyone, and I agree with that... but, I don't mind using my own "bad"
builds for examples, so I may write up a little "why this was broken
and how I fixed it" post pretty soon.