path: root/naming.txt

Guide to Naming and Categorizing SlackBuilds
============================================

Parts of this are requirements, and parts are matters of taste.

Choosing a name
---------------

The easiest thing to do is use the upstream name of the project for
the build name. For most builds, this is fine.

Some of us prefer not to use uppercase in build names (whether
ALLCAPS, MixedCase, or camelCase). It's perfectly OK for the build to
have an all-lowercase name (in which case you'll likely use SRCNAM for
the upstream name and PRGNAM will be your lowercase form). There's no
*requirement* to avoid capitals letters; it's a personal preference.

One thing we *don't* want to happen: Please don't submit a build
that's the same name as another build, but with different case.
We have libreoffice and LibreOffice, and it's a source of great
confusion and annoyance. Eventually one of them will be renamed (to
libreoffice-bin). Please don't make this worse by naming more builds
this way.

We have a few requirements for specific types of build:

- Perl modules (aka libraries) must be in the perl/ category, have the
prefix perl- on the build name, and be named after the module (or
actually the CPAN/MetaCPAN distribution name), with sequences of ::
characters replaced with a dash. For example, if the module on CPAN is
called Ugly::Fruit, your build must be called either perl-Ugly-Fruit
or perl-ugly-fruit. Note that just because something is *written in*
perl, doesn't mean it has to have a perl- prefix or be found in the
perl/ category. Applications belong in their appropriate categories.
For instance, mobiperl is an application that converts between e-book
formats, and it's in the office/ category (where the other e-book
stuff is), and doesn't have the perl- in the name. Another example is
games/pangzero.

- Python modules (aka libraries) must be in the python/ category and
have a python2- or python3- prefix. There are existing exceptions
to this rule, which just have a python- prefix. This probably
means the build installs both python2 and python3 versions of the
module. This is discouraged for new builds, though: Please submit
separate python2- and python3- builds, or just the python3- one if
there's not a specific need for python2 support. As with Perl, just
because something's written in Python, doesn't mean it's a module. As
an example, iotop is written in Python 2, and lives in the system/
category.

- Ruby modules (aka libraries or gems) must be in the ruby/ category,
and if they're gems (installed with "gem install"), must have
a rubygem- prefix on the build name. As with Perl and Python,
applications written in Ruby belong in their appropriate category.

- Haskell libraries are similar: haskell- prefix and haskell/ category.
Applications belong in their appropriate category.

Occasionally, there will be a name conflict. Two completely different
projects will use the same name. If you find an existing build in the
repo with the same name as your proposed new build, you should rename
your build. Made-up example: If e.g. it's a word processor called
FastWord, and there's also a game called FastWord (or fastword) in
the repo, you could rename your build to e.g. "FastWord-wordproc" or
"fastword-wp". You could check repology.org to see how the ambiguity
is resolved there.

Choosing a category
-------------------

For some builds, the category is obvious. Games belong in games/.
Ham radio stuff belongs in ham/.

For some builds, it's not so obvious. We don't have categories for
fonts or emulators, for instance. The catch-all category for
things that don't seem to belong in any category has historically
been system/... though we do have misc/.

Some things seem to fit in more than one category. For instance,
a program that downloads random images from the Internet, applies
filters to them, then sets them as your desktop wallpaper... could
legitimately be thought of as "desktop", "graphics", and "network".
Most likely, this one would be in desktop/, since that's where its
visible effect is.

What you're looking for is the primary purpose of the software. A
programming language that's designed for generating music would be
better in audio/ than development/, even though programming languages
normally go in development/.

Some things have to be in a certain category (Perl, Python, Ruby,
and Haskell libraries, as described above). Libraries that don't
include an application (or that only include a simple "test" or
"demo" command-line tool) belong in libraries/ (and no, a library for
extracting CD audio wouldn't belong in either audio/ or multimedia/;
those are for applications).

The following list of categories shows what kinds of applications
have historically been put in each, for applications we don't yet have
categories for.

academic/
  Equation editors/resolvers.
  Statistical analysis.
  Bioinformatics.
  Astronomy.
  Calculators, especially 'scientific' ones.
  Chemistry.
  Educational.
  Electronics Engineering.

games/
  Emulators for game consoles, or old computers with large game libraries (even
  if they also had other kinds of software).

system/
  Text editors (as opposed to word processors, which go in office/).
  Fonts.
  Emulators, especially for old computers with lots of non-game software.
  Encryption.
  Shells (and shell-related utilities like completion).
  Man pages (for non-English languages, mostly).
  System monitoring.
  Compression (and tools for recovering compressed files).
  Filesystems (FUSE and otherwise).
  Hardware drivers (printers, wireless cards, etc).
  Password managers.
  Terminal emulators (X/Wayland; also the serial port kind).

office/
  Office suites (obviously).
  Speadsheets, word processors, presentation.
  Anything to do with PDF or e-book (.epub, etc) files, whether it's a
  viewer, an editor, or a utility to modify/create such files.

graphics/
  Comic book readers. Though at least one of these has ended up in
  office/ instead... and an app that displays multiple e-book formats
  (PDF/EPUB/etc), only one of which is comic books, should go in office/.
  Image viewers and converters.
  Screenshot creators.
  Font editors.

libraries/
  Do not put applications here. Some libraries ship with a
  config utility (e.g. wx-config for wxWidgets), or a simple
  test app that isn't very useful byt itself; these don't count as
  applications. Most of the time, if the upstream project name begins
  with "lib", it belongs in this category.

The list above is not exhaustive (even though I've gotten exhausted
while writing it). You would benefit from looking at the repo and
clicking on random builds in each category, to get your own idea
of what things have been categorized as. Also note that there are
no category police: there are builds that are probably in the wrong
category. Don't take a single example as authoritative.

Keywords
--------

In addition to the name and category of the build, you can choose a
set of keywords that will be found by the website's search page.

It's hard to guess up-front what people will search for, when they're
looking for software by description/function rather than by name.
This is where you can make up for the lack of a more specific
category. E.g. a font editor that goes in graphics, you can
include "font editor" as a keyword (yes, spaces are allowed).

There is no need to include a build's name as a keyword. This just
wastes a bit of space in our database. The site search will already
find the build by its name.

If you have a keyword, there's no need to include another keyword
that's a substring of the longer one. Example: if you include
"cross assembler", then there's no need to include either "cross" or
"assembler" because the site search uses a substring match (searching
for "cross" will also find "cross assembler").

Specific hints:

For an emulator, you should include "emulator" as a keyword, plus the
name of the system it emulates, possibly with variant spellings (e.g.
"c64", "c-64", "c=64", "commodore 64" for the Commodore 64). If it
emulates a whole line of computers (e.g. atari800 emulates the 400,
800, 800XL, etc), you can include the different models as separate
keywords. You might also want to include the CPU the emulated system
uses (e.g. "6502" for atari800).

For assemblers, "assembler" (or "cross assembler if that's its
purpose), "asm", and the name(s) of the platform(s) it assembles code
for (which should include both the CPU architecture and the system
name(s) if it produces executables for specific systems).

For image or document file viewers/editors/converters, the filename
extensions of the files it supports (e.g. png, gif, webp), if it's
not already part of the build name (e.g. gifsicle doesn't need "gif"
as a keyword, though "gif89a" would be a good one since it's the full
name of the file format). MIME types would also be good candidates,
such as image/gif (though make sure you use MIME types that actually
exist; see the output of "file --mime-type" or the contents of
/usr/share/mime/).

If you're going to include "regular expression" as a keyword, you
should also include "regexp" (which will match searches for either
"regex" or "regexp").