diff options
Diffstat (limited to 'naming.txt')
| -rw-r--r-- | naming.txt | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/naming.txt b/naming.txt new file mode 100644 index 0000000..19bdec9 --- /dev/null +++ b/naming.txt @@ -0,0 +1,206 @@ +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"). |