Replace ppmtouil with pamtouil for Motif UIL Icons

ppmtouil converts a PNM or PAM image into a Motif UIL icon file, but the name is misleading: the maintained command underneath is actually pamtouil. On this machine, Netpbm 2:11.05.02-1.1build1 installs ppmtouil as a symbolic link to pamtouil; the old name is kept only for compatibility.

Allow about ten minutes. You need Netpbm, a readable PNM or PAM image, a shell, and a Motif application or build process that consumes UIL. The conversion itself normally needs no elevated privileges. Keep the source image until you have checked the generated file.

1. Confirm which command is installed

Check the package and the two command paths first. This is read-only and does not need sudo:

$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ ls -l /usr/bin/ppmtouil /usr/bin/pamtouil
lrwxrwxrwx ... /usr/bin/ppmtouil -> pamtouil

Your version and file metadata may differ. The useful check is that ppmtouil resolves to the newer program. The ppmtouil(1) manual is deliberately short: it says the program was renamed to pamtouil in May 2002. Do not go looking for a separate, modern ppmtouil feature set; there isn't one.

2. Prepare a small input image

For a safe first run, use an existing image or create a tiny PBM file in a temporary directory. This example only touches /tmp and makes a two-colour test image:

$ printf 'P1\n2 2\n0 1\n1 0\n' > /tmp/uil-test.pbm
$ file /tmp/uil-test.pbm
/tmp/uil-test.pbm: Netpbm image data, size = 2 x 2, ASCII bitmap

Swap /tmp/uil-test.pbm for the path to your real PNM or PAM file once you are ready. PNM covers the common PBM, PGM and PPM formats; PAM can also carry grayscale or colour transparency. A PAM pixel more than half transparent renders as transparent in the UIL output.

3. Convert the image to UIL

pamtouil reads one optional input file and writes UIL to standard output. Redirect that to a new destination:

$ pamtouil /tmp/uil-test.pbm > /tmp/test-icon.uil
pamtouil: computing colormap...
pamtouil: looking up color names, assigning character codes...
pamtouil: generating UIL...

Using the compatibility name produces the same result on this installation:

$ ppmtouil /tmp/uil-test.pbm > /tmp/test-icon-compat.uil
$ cmp /tmp/test-icon.uil /tmp/test-icon-compat.uil

A blank cmp result means the files match. The converter maps image colours to names from Netpbm's RGB database: exact matches use that colour name, other colours get the closest named colour. The resulting file holds a UIL module, a colour table and an exported icon.

$ test -s /tmp/test-icon.uil && sed -n '1,35p' /tmp/test-icon.uil
module /tmp/uil-test
version = 'V1.0'
names = case_sensitive

The module and icon names come from the input filename when you do not supply a name. That is not a promise the name your application expects will actually be used.

4. Set predictable UIL names

Pass -name when the generated identifiers need to be stable or must match a resource reference. The option accepts either an equals sign or a separate value:

$ pamtouil -name=warning_icon /tmp/uil-test.pbm > /tmp/warning-icon.uil
$ sed -n '1,28p' /tmp/warning-icon.uil
module warning
version = 'V1.0'
names = case_sensitive

The value becomes the prefix used throughout the UIL output. Pick a simple identifier-like value and inspect the generated declarations before wiring them into a build. Reading from standard input? Omit the file argument, and the default name is noname unless you set -name:

$ cat /tmp/uil-test.pbm | pamtouil -name=stdin_icon > /tmp/stdin-icon.uil
$ grep -E '^(module|[[:alnum:]_]+ : exported icon)' /tmp/stdin-icon.uil
module stdin

5. Protect existing output

$ pamtouil -name=warning_icon /path/to/source.ppm > /path/to/warning-icon.uil.new
$ status=$?
$ if [ "$status" -eq 0 ] && test -s /path/to/warning-icon.uil.new; then
>     mv /path/to/warning-icon.uil.new /path/to/warning-icon.uil
> else
>     rm -f /path/to/warning-icon.uil.new
>     printf 'conversion failed; existing output was left alone\n' >&2
>     exit "$status"
> fi

The mv only changes the destination after a successful conversion and a non-empty output check. That final replacement is still a state change, so back up the old file first if it would be hard to regenerate. The temporary file can be removed safely after a failed run. Do not run the conversion as root just to write into a directory; fix ownership or pick a writable staging directory instead.

6. Diagnose the likely failures

A missing or unreadable input path is an ordinary filesystem problem. Check it without changing anything:

$ test -r /path/to/source.ppm && echo readable || echo 'cannot read input'
$ ls -l /path/to/source.ppm

• Unexpected colours in the output. UIL uses named colours from the RGB database rather than preserving arbitrary RGB triples exactly. Check the source format and inspect the generated colour table.
• Transparency matters. Use PAM input with the appropriate transparency channel and check how the consumer renders it; a successful exit status does not prove a particular Motif widget displays the icon as intended.
• Build can't find the generated icon. Check both the filename and the declarations inside it. A name inferred from source.ppm differs from an explicitly chosen -name. Also confirm the build is reading the file you just generated, not a stale copy elsewhere.

There is no persistent service to restart and no Netpbm configuration to undo. To abandon a test, remove only the files you created in /tmp. For a production output, keep the previous file or restore its backup rather than deleting it during diagnosis.