MaraPython

Appearance

Alowree Xu2025-10-16
1963
11.2m
0

zathura ​

zathura 是一个基于命令行的 PDF 查看工具，可以用作 Yazi 和 NeoMutt 的扩展工具。

配置文件 ​

The customization of zathura is be managed via a configuration file called zathurarc. By default zathura will evaluate the following files:

  • /etc/zathurarc
  • $XDG_CONFIG_HOME/zathura/zathurarc (default: ~/.config/zathura/zathurarc)

The zathurarc file is a simple plain text file that can be populated with various commands to change the behavior and the look of zathura which we are going to describe in the following subsections. Each line (besides empty lines and comments which start with a prepended #) is evaluated on its own, so it is not possible to write multiple commands in one single line.

复制文本 ​

有时候，我们希望从 PDF 文件内复制一些信息，比如从一些 UPS shipping labels 上获取 tracking number，然后在浏览器上通过官网提供的界面进行轨迹查询。

注意

经过图片转换的 PDF 通常是无法提取文本的。只有经过文本文档转换过来的 PDF 才更容易提取文字。

如果没有事先进行配置，在 zathura 的查看界面，通过鼠标左键点击、拖动可以高亮文本，底部状态栏显示内容已经复制的提示信息：

bash
Copied selected text to selection primary: Sound Rise II

官方文档说，这时文本已经复制至 PRIMARY 剪贴板，在其他的编辑应用内按下鼠标中键，可以粘贴。但是我的鼠标不行。

打开配置文件，添加：

zathurarc
# Change the X clipboard from PRIMARY to CLIPBOARD
set selection-clipboard clipboard

这时再通过鼠标左键点击、拖动、高亮文本，底部状态栏显示内容已经复制至系统剪贴板的提示信息：

bash
Copied selected text to selection clipboard: Sound Rise II

去到其他的编辑应用，按下 Ctrl + V 就可正常粘贴了。

中文乱码 ​

亚马逊 FBA 贴纸内包含中文的发货地址，在其他的查看器可以正常显示，在 zathura 查看却是乱码。这说明内置的编解码器出现了异常。

完全黑屏 ​

有发现在 NeoMutt 内查看某些 PDF 格式的附件，打开之后呈完全黑屏状态。

MEMO: Fixing Zathura PDF Plugin After Homebrew Upgrade ​

Date: February 24, 2026
Subject: Restoring Zathura PDF viewing capability after brew upgrade

Issue Overview ​

After running brew upgrade, Zathura fails to open PDF files with error:

bash
warning: Found no plugins. Please install at least one plugin.
error: Could not determine file type.

Cause: The plugin symlink at /opt/homebrew/opt/zathura/lib/zathura/libpdf-poppler.dylib points to an old version number in the Cellar path that no longer exists after upgrade.

Quick Fix Steps (2 minutes) ​

Step 1: Find the new plugin location ​

bash
find /opt/homebrew/Cellar -name "*pdf-poppler*" -type f 2>/dev/null | grep dylib

Expected output: /opt/homebrew/Cellar/zathura-pdf-poppler/[NEW_VERSION]/libpdf-poppler.dylib

bash
# Remove old symlink (if exists)
rm -f /opt/homebrew/opt/zathura/lib/zathura/libpdf-poppler.dylib

# Create new symlink with correct version
ln -s /opt/homebrew/Cellar/zathura-pdf-poppler/[NEW_VERSION]/libpdf-poppler.dylib /opt/homebrew/opt/zathura/lib/zathura/libpdf-poppler.dylib

Step 3: Verify ​

bash
# Check symlink is valid
ls -la /opt/homebrew/opt/zathura/lib/zathura/
# Should show: libpdf-poppler.dylib -> /opt/homebrew/Cellar/zathura-pdf-poppler/[NEW_VERSION]/libpdf-poppler.dylib

# Test PDF opening
zathura ~/test.pdf

Use the opt path which always points to current version:

bash
ln -sf /opt/homebrew/opt/zathura-pdf-poppler/libpdf-poppler.dylib /opt/homebrew/opt/zathura/lib/zathura/libpdf-poppler.dylib

Verification Checklist ​

  • Zathura opens PDFs from terminal
  • NeoMutt can open PDF attachments
  • DBus synctex still works (Ctrl+Click in PDF jumps to editor)

Background Context ​

  • Zathura and its PDF plugin are installed from zegervdv/zathura tap
  • Plugin path includes version number in Cellar: /opt/homebrew/Cellar/zathura-pdf-poppler/[VERSION]/libpdf-poppler.dylib
  • Zathura expects plugin at: /opt/homebrew/opt/zathura/lib/zathura/libpdf-poppler.dylib
  • brew upgrade updates the version number, breaking the symlink
  • DBus configuration, mailcap, and mutt settings remain intact

Prevention Note ​

Consider using the version-agnostic symlink (Alternative fix above) to prevent this issue in future upgrades.

Zathura on macOS: Potential Pitfalls and Debugging Guide ​

Based on our extensive troubleshooting session, here are the critical failure points for Zathura on macOS, ranked by likelihood and impact.

1. Plugin Symlink Breakage (Most Common) ​

The Problem: After brew upgrade, the plugin symlink points to a non-existent version in Cellar, causing:

bash
warning: Found no plugins. Please install at least one plugin.
error: Could not determine file type.

Why It Happens:

  • Zathura expects plugins at: /opt/homebrew/opt/zathura/lib/zathura/
  • Plugin is actually at: /opt/homebrew/Cellar/zathura-pdf-poppler/[VERSION]/libpdf-poppler.dylib
  • brew upgrade changes the version number, breaking the symlink

Crucial Debugging Points:

bash
# Check if symlink exists and where it points
ls -la /opt/homebrew/opt/zathura/lib/zathura/

# Find the actual plugin location
find /opt/homebrew/Cellar -name "*pdf-poppler*" -type f | grep dylib

# Test if Zathura can find plugins
zathura -l  # List available plugins

The Fix:

bash
ln -sf /opt/homebrew/Cellar/zathura-pdf-poppler/[CURRENT_VERSION]/libpdf-poppler.dylib /opt/homebrew/opt/zathura/lib/zathura/libpdf-poppler.dylib

2. D-Bus Configuration Syntax Error ​

The Problem: Incorrect syntax in session.conf prevents D-Bus from starting:

bash
dbus[7105]: Failed to start message bus: Attribute "allow_anonymous" is invalid on <auth> element in this context

Why It Happens:

  • The allow_anonymous="yes" attribute belongs on a standalone <allow_anonymous/> element, not on the <auth> tag
  • Users often incorrectly modify the authentication section

Crucial Debugging Points:

bash
# Check if D-Bus is actually running
ps aux | grep dbus-daemon | grep -v grep

# Check for startup errors
cat /tmp/dbus-session.log

# Validate the config file syntax
grep -n "allow_anonymous" /opt/homebrew/opt/dbus/share/dbus-1/session.conf

Correct Configuration (around line 260):

xml
<auth>DBUS_COOKIE_SHA1</auth>
<auth>EXTERNAL</auth>
<!-- <allow_anonymous/> -->  <!-- Standalone tag, not on <auth> -->

3. Missing or Incorrect DBUS_SESSION_BUS_ADDRESS ​

The Problem: Zathura can't communicate with D-Bus for SyncTeX functionality, but basic PDF viewing still works.

Why It Happens:

  • Environment variable not set in shell
  • Session socket doesn't exist or has wrong permissions
  • Launch agent not properly loaded

Crucial Debugging Points:

bash
# Check if socket exists and is valid
ls -la ~/.cache/dbus/session
file ~/.cache/dbus/session  # Should show "socket"

# Check current environment variable
echo $DBUS_SESSION_BUS_ADDRESS

# Test D-Bus communication
dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply /org/freedesktop/DBus org.freedesktop.DBus.ListNames

# Check launch agent status
launchctl list | grep dbus

The Fix:

bash
export DBUS_SESSION_BUS_ADDRESS="unix:path=$HOME/.cache/dbus/session"
# Add to ~/.zshrc for persistence

4. Launch Agent Not Loading Properly ​

The Problem: D-Bus doesn't start automatically at login, even though brew services claims it's loaded.

Why It Happens:

  • Homebrew's service tracking doesn't play well with launchd-managed services
  • The plist file may have incorrect paths or environment variables
  • $HOME expansion issues in plist files

Crucial Debugging Points:

bash
# Check if plist exists and is valid
ls -la ~/Library/LaunchAgents/org.freedesktop.dbus-session.plist
plutil -lint ~/Library/LaunchAgents/org.freedesktop.dbus-session.plist

# Manual load/unload test
launchctl unload ~/Library/LaunchAgents/org.freedesktop.dbus-session.plist
launchctl load ~/Library/LaunchAgents/org.freedesktop.dbus-session.plist

# Check launchd status
launchctl list | grep dbus

Common Plist Issue:

xml
<!-- DON'T use $HOME in plist -->
<string>--address=unix:path=$HOME/.cache/dbus/session</string>

<!-- DO use absolute path -->
<string>--address=unix:path=/Users/username/.cache/dbus/session</string>

5. brew services False Negatives ​

The Problem:

bash
❯ brew services info dbus
Running: ✘
Loaded: ✔
Schedulable: ✘

Why It Happens:

  • Homebrew's service tracker looks for processes by specific PID patterns
  • D-Bus runs under launchd and doesn't match Homebrew's detection criteria
  • This is a cosmetic issue, not a functional one

Crucial Debugging Points (to confirm it's actually working):

bash
# THIS shows actual running process (reliable)
ps aux | grep dbus-daemon | grep -v grep

# THIS shows launchd registration (reliable)
launchctl list | grep dbus

# THIS shows socket accessibility (reliable)
launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET

# THIS tests actual functionality (most reliable)
dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply /org/freedesktop/DBus org.freedesktop.DBus.ListNames

The Truth: If dbus-send works and you have a running process, ignore brew services info completely.

6. Environment Cleanliness When Launched from GUI Apps ​

The Problem: Zathura works from terminal but fails when launched from NeoMutt, Finder, or other GUI apps.

Why It Happens:

  • GUI apps inherit a minimal environment, missing shell settings
  • DBUS_SESSION_BUS_ADDRESS not set
  • PATH may not include Homebrew directories

Crucial Debugging Points:

bash
# Create a test script to see what environment GUI apps see
cat > ~/env-test << 'EOF'
#!/bin/zsh
echo "PATH: $PATH" > /tmp/gui-env.log
echo "DBUS: $DBUS_SESSION_BUS_ADDRESS" >> /tmp/gui-env.log
env >> /tmp/gui-env.log
EOF
chmod +x ~/env-test

# Then associate this with a file type in mailcap temporarily

The Fix (Wrapper Script):

bash
#!/bin/zsh
export ZATHURA_PLUGINS_PATH=/opt/homebrew/opt/zathura/lib/zathura
export DBUS_SESSION_BUS_ADDRESS="unix:path=$HOME/.cache/dbus/session"
exec /opt/homebrew/bin/zathura "$@"

7. SyncTeX Feature Not Built Into Zathura ​

The Problem: Zathura doesn't respond to SyncTeX commands or show "Built without synctex support" errors.

Why It Happens:

  • Zathura must be compiled with --with-synctex flag
  • Pre-built bottles may not include SyncTeX support
  • Installation from zegervdv/zathura tap may need HEAD build

Crucial Debugging Points:

bash
# Check if binary has synctex symbols
strings $(which zathura) | grep -i synctex | head -10

# If output shows "Built without synctex support", you need to reinstall
brew reinstall zegervdv/zathura/zathura --HEAD --with-synctex

Quick Reference: Diagnostic Command Cheat Sheet ​

  • Plugin - Symlink validity

    bash
    ls -la /opt/homebrew/opt/zathura/lib/zathura/

  • Plugin - Actual location

    bash
    find /opt/homebrew/Cellar -name "*pdf-poppler*" | grep dylib

  • D-Bus - Process running

    bash
    ps aux | grep dbus-daemon | grep -v grep

  • D-Bus - Socket exists

    bash
    ls -la ~/.cache/dbus/session

  • D-Bus - Functionality

    bash
    dbus-send --session --dest=org.freedesktop.DBus --type=method_call --print-reply /org/freedesktop/DBus org.freedesktop.DBus.ListNames

  • D-Bus - Launch agent

    bash
    launchctl list | grep dbus

  • D-Bus - Config syntax

    bash
    grep -n "allow_anonymous" /opt/homebrew/opt/dbus/share/dbus-1/session.conf

  • SyncTeX - Feature support

    bash
    strings $(which zathura) | grep -i synctex

  • Environment - Current setting

    bash
    echo $DBUS_SESSION_BUS_ADDRESS

Summary: The Three Critical Components ​

  1. Plugin Symlink - Without this, Zathura can't open any PDFs
  2. D-Bus Running - Without this, Zathura loses SyncTeX functionality
  3. D-Bus Config Syntax - Without correct syntax, D-Bus won't start at all

The plugin symlink is the most frequent failure point after brew upgrade. The D-Bus configuration is the most subtle because errors only appear in logs, not in obvious UI messages.

最近更新