Skip to content

Instantly share code, notes, and snippets.

@NeilPandya
Created September 21, 2024 18:50
Show Gist options
  • Save NeilPandya/5ec47d52a169d9083ad2e6512c0eacc7 to your computer and use it in GitHub Desktop.
Save NeilPandya/5ec47d52a169d9083ad2e6512c0eacc7 to your computer and use it in GitHub Desktop.
A Good Way to Document

A Good Way to Document

I hate that I have to do this, but I've been using Stack Overflow and Stack Exchange for over a decade and I know how negative people can be.

The Problem

I teach children and adults to hack RaspberryPi, Arduino, ESP8266, etc. at multiple Maker Spaces. My issue was with the package libsoxr0:armhf but Google found this to be the most relevant question.

In my case I searched for my exact error message:

files list file for package 'libsoxr0:armhf' is missing final newline

The answers here would not have helped my if I would have done a blind copy/pasta, but luckily I have enough experience to cautiously use the info to resolve my issue. Read on to learn to the skills to do the same.

The Solution

1st define variables so that future readers can copy/pasta

That future reader just might be yourself.

Documentation is a love letter that you write to your future self. - Damian Conway

# Put the name of your package here
pkg='libsoxr0:armhf'

Inspect the file and compare it to something similar

This will show you the content of your file without corrupting (which would only be a temporary until you close and reopen or possibly correct it with tset or reset) your tty ([incorrectly] aka: terminal, shell, bash, etc.)

# To exit the command `less` hit "q"
less /var/lib/dpkg/info/$pkg.list

You'll probably see some non-ascii garbage in there. Compare that to anything else.

less /var/lib/dpkg/info/init.list

In mine I have... (that last line is not IN the file, it's part of the UI of the less command)

/.
/usr
/usr/share
/usr/share/doc
/usr/share/doc/init
/usr/share/doc/init/changelog.gz
/usr/share/doc/init/copyright
/var/lib/dpkg/info/init.list (END)

Note: I chose init.list because it was the smallest file according to ls -lS /var/lib/dpkg/info/*.list, but it your original error had said for package 'init', you'd want to chose another file from the output of that ls command.

Eliminate the problem

Any time you read something on the internet that says "fix your problem by deleting this file/directory" you should instinctively translate that to "move it out of the way and take notes".

# start in your home directory
cd

# create a directory to keep your stuff organized
directory="HACK $(date)"
mkdir "$directory"
cd "$directory"

# remind yourself where you got this [possibly dumb] idea
url="https://raspberrypi.stackexchange.com/a/138679/8375"
echo "$url" >> FROM.url

# finally do the only thing you REALLY needed to do if the instructions you were following were perfect
sudo mv /var/lib/dpkg/info/$pkg.list ./
sudo apt install $pkg --reinstall

# compare the file you just moved the one that got recreated
less /var/lib/dpkg/info/$pkg.list

# write yourself a love letter
history >> HISTORY.txt

# lay it on thick
echo "I think you are awesome." >> README.txt
echo "I know I don't say it as often as you deserve to hear it." >> README.txt
echo "☮️❤️🌈🧘🏽🕉☸️☯️" >> README.txt

Artifacts

Now that everything is working, I can remove the directory I created to clean up. Here is one last peek before it goes away...

pi@openmediavault:~/HACK Sun Aug 14 10:23:51 CDT 2022 $ ls -la
total 32
drwxr-xr-x 2 pi users  4096 Aug 14 11:02 .
drwxr-xr-x 9 pi users  4096 Aug 14 10:47 ..
-rw-r--r-- 1 pi users   128 Aug 14 11:02 FROM.url
-rw-r--r-- 1 pi users 12748 Aug 14 11:02 HISTORY.txt
-rw-r--r-- 1 pi users   124 Aug 14 11:02 README.txt

Oh, who am I kidding? I can't throw that away. I'm just going archive it over on my OpenMediaVault JBOD. Oh wait, it's already there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment