chore: add documentation targets (manpage, PDF, plain text)

.editorconfig

@@ -17,6 +17,9 @@ indent_size = 4
 indent_size = 4
 trim_trailing_whitespace = false
 
+[*.yaml]
+trim_trailing_whitespace = false
+
 eclint_indent_style = unset
 
 [Dockerfile]

.github/workflows/golang-build-debug.yml

@@ -12,13 +12,20 @@ jobs:
     name: build-debug
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-go@v5
+      - name: Set up Go
+        uses: actions/setup-go@v5
         with:
           go-version: 1.25.1
           cache: false
+
       - name: Checkout code
         uses: actions/checkout@v4
+
+      - name: Clean the environment
+        run: make clean
+
       - name: Vendor the application for debug
         run: make vendor
+
       - name: Build the application for debug
         run: make debug

.github/workflows/golang-build.yml

@@ -12,15 +12,23 @@ jobs:
     name: build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-go@v5
+      - name: Set up Go
+        uses: actions/setup-go@v5
         with:
           go-version: 1.25.1
           cache: false
+
       - name: Checkout code
         uses: actions/checkout@v4
+
+      - name: Clean the environment
+        run: make clean
+
       - name: Vendor the application for production
         run: make vendor
+
       - name: Build the application for production
         run: make zipfuse
+
       - name: Build the application helper for production
         run: make mount.zipfuse

.github/workflows/golang-coverage.yml

@@ -12,14 +12,21 @@ jobs:
     name: coverage
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-go@v5
+      - name: Set up Go
+        uses: actions/setup-go@v5
         with:
           go-version: 1.25.1
           cache: false
+
       - name: Checkout code
         uses: actions/checkout@v4
+
+      - name: Clean the environment
+        run: make clean
+
       - name: Run all Go tests
         run: make test-coverage
+
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
         with:

.github/workflows/golang-tests.yml

@@ -12,11 +12,17 @@ jobs:
     name: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-go@v5
+      - name: Set up Go
+        uses: actions/setup-go@v5
         with:
           go-version: 1.25.1
           cache: false
+
       - name: Checkout code
         uses: actions/checkout@v4
+
+      - name: Clean the environment
+        run: make clean
+
       - name: Run all Go tests
         run: make test

.github/workflows/golangci-lint.yml

@@ -12,12 +12,19 @@ jobs:
     name: lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-go@v5
+      - name: Set up Go
+        uses: actions/setup-go@v5
         with:
           go-version: 1.25.1
           cache: false
-      - uses: actions/checkout@v4
-      - name: golangci-lint run
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Clean the environment
+        run: make clean
+
+      - name: Run all Go linters
         uses: golangci/golangci-lint-action@v8
         with:
           skip-cache: true

.github/workflows/zipfuse-cli.yml

@@ -13,20 +13,24 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-
-    - name: Set up Go
-      uses: actions/setup-go@v5
-      with:
-        go-version: '1.25.1'
-
     - name: Install FUSE
       run: |
         sudo apt-get update
         sudo apt-get install -y fuse3
         sudo sed -i 's/#user_allow_other/user_allow_other/' /etc/fuse.conf
 
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: 1.25.1
+        cache: false
+
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Clean the environment
+      run: make clean
+
     - name: Vendor dependencies
       run: make vendor
 

.github/workflows/zipfuse-docs.yml

@@ -0,0 +1,28 @@
+name: zipfuse-docs
+on:
+  push:
+    branches:
+      - master
+      - main
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  zipfuse:
+    name: docs
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Install Asciidoc
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y asciidoc w3m
+
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Clean the environment
+      run: make clean
+
+    - name: Build the documentation
+      run: make docs

.github/workflows/zipfuse-fstab.yml

@@ -13,18 +13,22 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
+    - name: Install FUSE
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y fuse3
 
     - name: Set up Go
       uses: actions/setup-go@v5
       with:
-        go-version: '1.25.1'
+        go-version: 1.25.1
+        cache: false
 
-    - name: Install FUSE
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y fuse3
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Clean the environment
+      run: make clean
 
     - name: Vendor dependencies
       run: make vendor
@@ -173,7 +177,7 @@ jobs:
     - name: Unmount filesystem
       if: always()
       run: |
-        if ! sudo fusermount3 -u mountpoint; then
+        if ! sudo umount mountpoint; then
           echo "ERROR: Filesystem unmount has failed"
           exit 1
         fi

.goreleaser.yaml

@@ -4,9 +4,11 @@ project_name: zipfuse
 
 before:
   hooks:
+    - make clean
     - make vendor
     - make lint
     - make test
+    - make docs
 
 builds:
   - id: zipfuse
@@ -59,6 +61,16 @@ archives:
     files:
       - LICENSE
       - INSTALL
+      - docs/zipfuse.pdf
+      - docs/mount.zipfuse.pdf
+      - src: docs/zipfuse.text
+        dst: docs/zipfuse.txt
+      - src: docs/mount.zipfuse.text
+        dst: docs/mount.zipfuse.txt
+      - src: docs/zipfuse.1
+        dst: man/zipfuse.1
+      - src: docs/mount.zipfuse.8
+        dst: man/mount.zipfuse.8
 
 signs:
   - artifacts: checksum

INSTALL

@@ -3,82 +3,41 @@ Installing the filesystem
 
 You will need to ensure that you have FUSE (libfuse, fuse3...) installed on
 the system that you are planning to use zipfuse on. The only hard dependency
-of zipfuse is the fusermount3 binary, so ensure that it exists in your $PATH.
+of zipfuse is the "fusermount3" binary, so ensure that it exists in your $PATH.
 
 The recommended location to install FUSE filesystems to can differ between Linux
 distributions. Most important is that you install the binaries to a location
 that is covered in your $PATH environment variable. A common and relatively
-portable solution would be installing the zipfuse binary into /bin and the
-mount.zipfuse binary into /sbin on your system. You have to ensure that the
+portable solution would be installing the "zipfuse" binary into "/bin" and the
+"mount.zipfuse" binary into "/sbin" on your system. You have to ensure that the
 files have the appropriate permissions set for users intending to execute them,
-specifically the executable bit needs to be set on both binaries (chmod +x).
+specifically the executable bit needs to be set on both binaries ("chmod +x").
 
-As can be derived from the recommended paths above, the zipfuse binary itself
-does not need elevated permissions. In contrast, the mount.zipfuse is usually
-executed by the system as root (when processing /etc/fstab), but will (when
+As can be derived from the recommended paths above, the "zipfuse" binary itself
+does not need elevated permissions. In contrast, the "mount.zipfuse" is usually
+executed by the system as root (when processing "/etc/fstab"), but will (when
 configured to do so) execute the filesystem binary as a given unprivileged user.
 
-Mounting the filesystem
-========================
-
-Mounting with command-line or systemd service (recommended):
--------------------------------------------------------------
-
-The zipfuse filesystem binary runs as a foreground process and is ideal for
-systemd wrapping, or use directly from command-line as either a foreground or
-background (paired with nohup and/or &) process. For continous usage,
-integration into the larger systemd framework is recommended and preferable.
-
-For mounting using the command-line:
-
-    zipfuse <source> <mountpoint> [flags]
-
-<source> is the root of the underlying filesystem to expose.
-<mountpoint> is the mountpoint where the FUSE filesystem will appear.
-
-For mounting using a systemd service unit:
+You can install the documentation manpages by simply copying the bundled manpage
+files from the "man" directory to the location observed by your man(1) program.
+If unsure about the target paths, executing of "man --path" should reveal them.
 
-    [Unit]
-    Description=ZipFUSE
-    [Service]
-    Type=simple
-    ExecStart=/usr/local/bin/zipfuse /home/alice/zips /home/alice/zipfuse --webserver :8000
-    Restart=on-failure
-    RestartSec=5
-    TimeoutStartSec=30
-    TimeoutStopSec=30
-    KillSignal=SIGTERM
-    User=alice
-    Group=alice
-    [Install]
-    WantedBy=multi-user.target
+Using the filesystem
+=====================
 
-It is not recommended to use a .mount unit over a .service unit.
-The reason is that a .mount unit would again rely on the FUSE mount helper.
-For more complex orchestration with systemd, see also inside the examples folder.
+For information on how to use the filesystem, please refer to the bundled
+documentation found in the "docs" folder, the bundled manpages found in the
+"man" folder, or the project website: https://github.com/desertwitch/zipfuse
 
-The above are the recommended and modern approaches for almost all use cases.
-
-Mounting with mount(8) and /etc/fstab:
----------------------------------------
-
-For users not able to use systemd, a FUSE mount helper is provided, so the
-filesystem can be used with mount(8) or also /etc/fstab entry. This usually
-requires putting the mount.zipfuse binary into /sbin or another location
-that the mount(8) program examines for the filesystem helper binaries.
-
-For mounting using the mount(8) program:
-
-    sudo mount -t zipfuse /home/alice/zips /home/alice/zipfuse -o setuid=alice,allow_other,webserver=:8000
-
-For mounting using an entry in the /etc/fstab file:
-
-    # <file system>   <mount point>   <type>   <options>   <dump>   <pass>
-    /home/alice/zips   /home/alice/zipfuse   zipfuse   setuid=alice,allow_other,webserver=:8000   0  0
+Updating the filesystem
+========================
 
-As you can see, program options (read more in README) need format conversion:
+You can update the filesystem by simply replacing any installed files
+in the locations you have installed them to with their new counterparts.
+This is best done when no instances of the filesystem are currently mounted.
 
-    --allow-other --webserver :8000 => allow_other,webserver=:8000
+Uninstalling the filesystem
+============================
 
-Note that FUSE mount helper events are printed to standard error (stderr).
-Any filesystem events are printed to /var/log/zipfuse.log (if it is writeable).
+To uninstall the filesystem, ensure that all instances are unmounted and
+then remove any installed files from the locations you have installed to.