Installing the manpages (and keeping them up-to-date) after installing the released binary

Support
1

I was disconnected from the internet a few hours ago, and I needed to read the Syncthing documentation because of a synchronization issue that showed up at the time, only to find out that you don’t get manpages when you install from a release binary.

The manpages are actually released in a separate file such as syncthing-source-v1.27.12.tar.gz.

As Syncthing upgrades itself automatically, even if I install the documentation files myself, eventually they’re going to be outdated.

One way to solve this, I think, is building the docs locally — and setup email notifications for new releases, so we can manually install them.

Or I could install the outdated package my distribution provides.

How do YOU read the docs offline?

2

I use the Debian+Ubuntu packages from https://apt.syncthing.net/, which include up to date manpages alongside an up to date syncthing binary and systemd service files.

1 Like
3

I’m running Void Linux on this desktop; and Alpine Linux on the home server, and Fedora on a laptop. That makes the release binaries very convenient.

Thanks for the input.

4

I just noticed there is a refresh.sh script in the man folder.

#!/bin/bash

base=https://docs.syncthing.net/man/
pages=(
	syncthing.1
	stdiscosrv.1
	strelaysrv.1
	syncthing-config.5
	syncthing-stignore.5
	syncthing-device-ids.7
	syncthing-event-api.7
	syncthing-faq.7
	syncthing-networking.7
	syncthing-rest-api.7
	syncthing-security.7
	syncthing-versioning.7
	syncthing-bep.7
	syncthing-localdisco.7
	syncthing-globaldisco.7
	syncthing-relay.7
)

for page in "${pages[@]}" ; do
	curl -sLO "$base$page"
done

I wonder if that URL supports versioning, so that we can request a specific version of the manual.

Anyway, that might be an easy solution for my problem.

5

I just made some changes to refresh.sh and moved it to my PATH (as syncthing-refresh-docs); this script will fetch and install the updated files directly into ~/.local/share/man.

#!/bin/bash

base=https://docs.syncthing.net/man/

pages1=(
        syncthing.1
        stdiscosrv.1
        strelaysrv.1
)

pages5=(
        syncthing-config.5
        syncthing-stignore.5
)

pages7=(
        syncthing-device-ids.7
        syncthing-event-api.7
        syncthing-faq.7
        syncthing-networking.7
        syncthing-rest-api.7
        syncthing-security.7
        syncthing-versioning.7
        syncthing-bep.7
        syncthing-localdisco.7
        syncthing-globaldisco.7
        syncthing-relay.7
)

cd ~/.local/share/man/man1
for page in "${pages1[@]}"; do
        curl -sLO "${base}${page}"
done

cd ~/.local/share/man/man5
for page in "${pages5[@]}"; do
        curl -sLO "${base}${page}"
done

cd ~/.local/share/man/man7
for page in "${pages7[@]}"; do
        curl -sLO "${base}${page}"
done

# rebuild apropos database
makewhatis ~/.local/share/man

Make sure that path is added to the man path (see man.conf(5)). Append this line to /etc/man.conf:

manpath /home/MYUSER/.local/share/man
6

Yes, it does. Go to the page in a browser and watch how the URL changes when you select a different version from the drop-down at the top, e.g.

https://docs.syncthing.net/v1.27.10/

1 Like