Replace ppmtouil with pamtouil for Motif UIL Icons

You will finish with a working command that converts a PNM or PAM image into a Motif UIL icon file, while avoiding the misleading name of the old ppmtouil command. On this machine, Netpbm 2:11.05.02-1.1build1 installs ppmtouil as a symbolic link to pamtouil. The old command name is retained for compatibility, but the maintained interface is pamtouil.

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 that the program was renamed to pamtouil in May 2002. Do not look for a separate modern ppmtouil feature set.

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 changes only /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

Replace /tmp/uil-test.pbm with the path to your real PNM or PAM file when you are ready. PNM covers the common PBM, PGM and PPM formats. PAM can also carry grayscale or colour transparency. A PAM pixel that is more than half transparent is rendered 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 output 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 are assigned the closest named colour. The resulting file contains 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 are derived from the input filename when you do not supply a name. They are not a promise that the name your application expects will 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 in the UIL output. Choose a simple identifier-like value and inspect the generated declarations before wiring them into a build. If input comes 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

Shell redirection truncates its destination before pamtouil starts. That is destructive if the destination already contains a useful UIL file. Write to a temporary name, check the exit status and output, then replace the old file only when the new one is sound:

$ 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 changes the destination only after a successful conversion and a non-empty output check. The final replacement is still a state change, so make a backup first if the old file is difficult to regenerate. The temporary file can be removed safely after a failed run. Do not run the conversion as root merely to write into a directory; fix ownership or choose 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

If the output contains unexpected colours, remember that 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. If transparency matters, use PAM input with the appropriate transparency channel and verify how the consumer renders it; a conversion success status does not prove that a particular Motif widget displays the icon as intended.

If a build cannot find the generated icon, check both the filename and the declarations inside it. A name inferred from source.ppm is different from an explicitly selected -name. Also check that the build is reading the file you just generated, rather than a stale copy in another directory.

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, retain the previous file or restore its backup rather than deleting it during diagnosis.