Setup for PDF-Viewer (Okular) for Stata Manuals (Linux)

[Dirk Enzmann]

I found a way to setup the use of Okular as an alternative PDF-Viewer specifically for Stata manuals in Linux operating systems (while preserving the setup of Okular for other documents "outside" of Stata use). It solves long-time problems I had with Evince (e.g. correctly jump to manual sections; remember the size, position and zoom of the window).

The solution is contained in a longer markdown file (alternatively a less optimal PDF file) I would like to share with the community, but I don't know how to share it because file attachments are not welcome to the Forum (which I understand perfectly) and using code-delimiters would not preserve the advantage of markdown documents. Any idea how to share the solution?

[Manh Hoang Ba]

Thanks, Dirk, for sharing.

By the way, I have a question about opening Stata documentation files in a web browser, such as MS Edge. Although I have set Edge as the default application for opening PDF files in Windows, when I open a help file from Stata’s Help window, I get an error message saying that no PDF reader can be found.

Any advice would be greatly appreciated.

[Dirk Enzmann]

Manh Hoang Ba : I didn't yet share anything (my question is how to share the document appropriately) and your question requires a new topic, although related.

If this FAQ doesn't answer your question (Stata does not use your browser but a separate PDF-viewer you have to install separately), open a new topic with your problem.

[Dirk Enzmann]

Well, I think this is a solution for sharing the Markdown document that explains how to set up Okular so that it can be used within Stata on Linux as a PDF viewer for PDF documents (Stata help manuals). Copy the entire contents of the code block and paste them into a text file (e.g., “stata-okular-setup.md”).

After following the instructions, you can use links to sections in the manuals and open / view them with Okular. You can then customize Okular’s settings, and Okular will restore the window size, position, and zoom level you selected for the displayed document the next time you open it. The configuraton of Okular for standard use to open / view documents on your machine outside of Stata will not be affected by the Stata specific settings for Okular.

# Using Okular as Stata's PDF Viewer (with a separate window/zoom setup)

This guide explains how to make Stata (Linux) open its PDF documentation with
Okular instead of Evince, including automatic jump-to-section links, and how
to give Okular a *different* window size/position/zoom when launched from
Stata than your normal everyday Okular sessions — without touching your
regular Okular configuration.

NOTE: In this document, you must replace all instances of ```<stata>``` with
the name of your current Stata installation, such as ```stata19```.

---

## 1. Background: how Stata launches its PDF viewer

On Linux, when you click a documentation link in Stata's help system, Stata
runs a shell script called `stata_pdf`, located in your Stata installation
directory (e.g. `/usr/local/<stata>/stata_pdf`). Stata calls it as:

```
stata_pdf                          "<path/to/manual.pdf>"
stata_pdf -page    <#>            "<path/to/manual.pdf>"
stata_pdf -section <sectionname>  "<path/to/manual.pdf>"
```

The script reads the environment variable `$PDFVIEWER` to decide which
program to launch, and translates the `-page`/`-section` arguments into
whatever syntax that viewer needs. By default it only knows how to handle
`evince` and `acroread` — anything else falls through to a generic
Acrobat-style syntax that doesn't work for most other viewers, including
Okular.

---

## 2. Step 1 — Add an `okular` case to `stata_pdf`

**Back up the original script first:**

```bash
sudo cp /usr/local/<stata>/stata_pdf /usr/local/<stata>/stata_pdf.orig
```

Edit `/usr/local/<stata>/stata_pdf` and add a new `"okular")` case **before**
the generic `*)` fallback case near the bottom of the file:

```sh
"okular")
        cmd="env XDG_CONFIG_HOME=~/.config-stata-okular okular"
        case "$1" in
        "-page")        pagenum=$2
                        fname=$3
                        wharg="--page $pagenum"
                        ;;
        "-section")     section=$2
                        fname="$3#$section"
                        wharg=""
                        ;;
        *)              fname="$1"
                        wharg=""
                        ;;
        esac
        ;;
```

Notes on this block:

- `--page N` jumps to a specific page number.
- Okular's named-destination syntax is `okular "file.pdf#destname"` — the
  destination is appended to the filename with `#`, not passed as a
  separate flag, so it's folded into `$fname` rather than `$wharg`.
- The script's final line (`exec $cmd $wharg "$fname" > /dev/null 2>&1`)
  works unchanged with this new case.
- The `env XDG_CONFIG_HOME=...` prefix is what gives Stata-launched Okular
  windows their own separate settings — see Section 4 below.

---

## 3. Step 2 — Tell Stata to use Okular (`PDFVIEWER` variable)

Stata (and `stata_pdf`) needs the `PDFVIEWER` environment variable set to
`okular` *before* Stata starts, so it's inherited into Stata's process
environment.

### Two files that look similar but do very different things

| File | Purpose | When it runs |
|---|---|---|
| `~/.bashrc` | Shell startup file | Every time you open a new **terminal** window |
| `~/.profile` | Session/login startup file | Once, when you **log in** to your desktop session (covers both terminal and GUI-launched apps) |
| `/ado/personal/profile.do` | **Stata's own** startup script | Runs *inside* Stata, after Stata has already started — too late to affect Stata's own process environment |

Since Stata may be launched either from a terminal or from a desktop
icon/menu, **`~/.profile`** is the safer, more universal choice — it's read
at login and applies to the whole graphical session.

### What to do

Open `~/.profile` (it's a hidden dotfile — in a file-open dialog like
Kate's, either type the path directly, e.g. `~/.profile`, or toggle "show
hidden files" with `Ctrl+H`).

Add this as its own line, **outside** any `if ... fi` block, e.g. at the
very end of the file:

```sh
export PDFVIEWER=okular
```

Save the file.

### Applying the change

- **Full effect (covers desktop-launched apps too):** log out and log back
  in. `.profile` is only read at session login, not by opening a new
  terminal.
- **Quick test in one terminal only:**
  ```bash
  source ~/.profile
  echo $PDFVIEWER   # should print: okular
  ```
  then launch Stata from that same terminal. This does **not** affect
  Stata launched from a desktop icon.

---

## 4. Step 3 — Give Stata-launched Okular its own window/zoom settings

Okular saves its window size, position, and view settings (zoom, sizing
mode, etc.) automatically when you close it — no explicit "save as default"
action needed. The trick to having *different* settings for Stata-opened
documents versus your everyday Okular use is to point Stata's Okular
instances at a **separate configuration directory**, using the
`XDG_CONFIG_HOME` environment variable (KDE/Qt apps read all their settings
relative to this).

### 4.1 Create an isolated config directory

```bash
mkdir -p ~/.config-stata-okular/config
```

(No need to pre-populate it — Okular creates its config files there
automatically on first run.)

### 4.2 Set your desired window/zoom once, under the isolated config

```bash
XDG_CONFIG_HOME=~/.config-stata-okular okular /usr/local/<stata>/utilities/r.pdf
```

While this instance is open:

- Resize and reposition the window as desired.
- Set the zoom level you want.
- Close the window (this triggers Okular to save the current state into
  `~/.config-stata-okular/config/okularrc` and `okularpartrc`).

### 4.3 Verify it actually persisted

Run the exact same command again:

```bash
XDG_CONFIG_HOME=~/.config-stata-okular okular /usr/local/<stata>/utilities/r.pdf
```

It should reopen at the same size/position/zoom you just set. Repeat this
check — Evince turned out to be unreliable at this in earlier testing, so
it's worth confirming Okular actually holds the setting consistently across
several open/close cycles before relying on it.

### 4.4 Confirm your normal Okular usage is unaffected

Open a PDF the normal way (double-click, file manager, or plain
`okular somefile.pdf` with no `XDG_CONFIG_HOME` override) — it should still
use your regular `~/.config/okularrc` and behave exactly as it always has,
completely independent of the Stata-specific config directory.

### 4.5 This is already wired into the `stata_pdf` script

The `cmd=` line in the `"okular")` case shown in Section 2 already includes
this override:

```sh
cmd="env XDG_CONFIG_HOME=~/.config-stata-okular okular"
```

So once your isolated config is set up as above, every PDF Stata opens via
this script will automatically use it — no further changes needed.

---

## 5. Alternative: launching Stata from a desktop icon (`.desktop` file)

If you launch Stata via an application menu/icon rather than a terminal,
`.bashrc` is not read, and even `.profile` (read at login) may not always
be the most reliable path depending on your desktop environment. As a more
direct alternative, you can bake the environment variable straight into the
launcher itself.

1. Find the relevant `.desktop` file:
   ```bash
   find /usr/share/applications ~/.local/share/applications -iname "*stata*" 2>/dev/null
   ```
2. Edit the `Exec=` line, prefixing it with `env`:
   ```
   Exec=env PDFVIEWER=okular /usr/local/<stata>/xstata-se
   ```
3. **Commenting out a line in a `.desktop` file** (e.g. to temporarily
   disable the original `Exec=` line while testing a replacement): prefix
   the entire line with `#`, on its own line:
   ```
   #Exec=/usr/local/<stata>/xstata-se
   ```
   Comments can't be appended after a real `key=value` on the same line —
   they must be full lines starting with `#`. Make sure exactly one
   uncommented `Exec=` line remains active.
4. If changes don't seem to take effect, refresh the desktop database:
   ```bash
   update-desktop-database ~/.local/share/applications
   ```
   (use `sudo` for the system-wide `/usr/share/applications` equivalent).

---

## 6. Testing everything end-to-end

1. Confirm `echo $PDFVIEWER` prints `okular` in the environment Stata will
   actually launch from.
2. From a terminal, manually simulate what Stata does:
   ```bash
   /usr/local/<stata>/stata_pdf -section rregress /usr/local/<stata>/utilities/r.pdf
   ```
   This should open Okular, jumped to the `rregress` section, sized and
   positioned exactly as you configured in Section 4.
3. From within Stata itself, click a documentation link (e.g. type
   `help regress` and click the `[R] regress` link) and confirm the same
   behavior.

---

## 7. Quick reference

| Task | File/command |
|---|---|
| Tell Stata to use Okular | `export PDFVIEWER=okular` in `~/.profile` |
| Teach `stata_pdf` how to call Okular | Add `"okular")` case in `/usr/local/<stata>/stata_pdf` |
| Give Okular a separate window/zoom setup for Stata | `XDG_CONFIG_HOME=~/.config-stata-okular` prefix in that case |
| Alternative for desktop-launched Stata | Edit `Exec=` line in Stata's `.desktop` file |
| Apply `.profile` changes | Log out/in, or `source ~/.profile` in current terminal |

[Dirk Enzmann]

Add on:

Step ##4 of the Markdown document does not explain how you can modify the .desktop file so that Stata launches with the Okular configuration for Stata. If you have a desktop icon to launch Stata, edit the .desktop file and comment out the “Exec=...” line (for example

Exec=/usr/local/stata19/xstata-se

if your Stata installation folder is "/stata19" and replace it with

Exec=env PDFVIEWER=okular /usr/local/stata19/xstata-se

Assuming the name of your Stata installation folder is "/stata19", the two lines then should look like

# Exec=/usr/local/stata19/xstata-se
Exec=env PDFVIEWER=okular /usr/local/stata19/xstata-se

[Dirk Enzmann]

Add-on:

Ignore #5 -- the problem is already treated in the document (see #4 above) at ##5.

Additionally, I asked AI (Claude / Anthropic) how to to ran "standard" and "Stata" Okular as two independent singe-instance PDF viewers. Here the answer (how to convert the text between the code delimiters to "stata-okular-dual-instance.md" see #4 above):

# Running "Standard" and "Stata" Okular as Two Independent Single-Instance Viewers

## Problem

Okular's default launch (`okular --unique ...`, as used by most desktop
associations) uses D-Bus to enforce a single running instance: any new
invocation gets handed off to the already-running process instead of
starting a new one. If Stata's `stata_pdf` script launches Okular with a
separate `XDG_CONFIG_HOME` (to keep its Stata-manual settings — page
layout, recent files, zoom, etc. — separate from your everyday PDF
reader), that separate config is ignored whenever a "standard" Okular is
already running: the new manual just gets pulled into the existing
window, which uses the *standard* config's window geometry/zoom instead.

## Solution

Give the "Stata" Okular its own **private, persistent D-Bus session
bus**, separate from your normal desktop login session bus. Since
`--unique` activation is scoped to whichever bus the process is
connected to:

- "Standard" Okular (opened via file manager, etc.) uses your normal
  login session bus → stays single-instance among themselves.
- "Stata" Okular uses its own private bus, remembered across
  invocations → also single-instance among *its own* invocations.
- Neither can see or interfere with the other, so each keeps its own
  window, geometry, zoom, and config file.

## Terminology note

There isn't a special word for this — it's just "the user's home
directory." In shell scripts the portable way to refer to it is the
`$HOME` environment variable (tilde `~` expansion isn't reliably safe in
all `sh`/`dash` assignment contexts). Documentation conventions usually
write it generically as `$HOME` or `/home/<username>`.

## Implementation

File edited: `STATADIR/stata_pdf` (e.g. `/usr/local/stata19/stata_pdf`),
inside the `case "$PDFVIEWER" in ... esac` block, replacing the
`"okular")` branch:

```sh
"okular")
        BUSFILE="$HOME/.cache/stata-okular-dbus"
        mkdir -p "$HOME/.cache"

        if [ -f "$BUSFILE" ]; then
                . "$BUSFILE"
        fi
        if [ -z "$DBUS_SESSION_BUS_PID" ] || ! kill -0 "$DBUS_SESSION_BUS_PID" 2>/dev/null; then
                eval "$(dbus-launch --sh-syntax)"
                echo "DBUS_SESSION_BUS_ADDRESS='$DBUS_SESSION_BUS_ADDRESS'" > "$BUSFILE"
                echo "DBUS_SESSION_BUS_PID=$DBUS_SESSION_BUS_PID" >> "$BUSFILE"
        fi
        export DBUS_SESSION_BUS_ADDRESS
        XDG_CONFIG_HOME="$HOME/.config-stata-okular"
        export XDG_CONFIG_HOME

        cmd="okular --unique"
        case "$1" in
        "-page")        pagenum=$2
                        fname=$3
                        wharg="--page $pagenum"
                        ;;
        "-section")     section=$2
                        fname="$3#$section"
                        wharg=""
                        ;;
        *)              fname="$1"
                        wharg=""
                        ;;
        esac
        ;;
```

Everything else in `stata_pdf` (other viewer branches, the trailing
`exec $cmd $wharg "$fname" > /dev/null 2>&1`) is unchanged.

### How it works

1. First manual opened: no bus file yet → `dbus-launch` starts a fresh,
   persistent private D-Bus daemon; its address and PID are saved to
   `$HOME/.cache/stata-okular-dbus`.
2. Every later manual: the bus file is sourced, `kill -0 $PID` confirms
   the daemon is still alive, and that same private bus is reused.
   `--unique` then folds the new manual into the existing Stata-Okular
   window instead of opening a new one.
3. The private daemon keeps running in the background between Okular
   sessions (until logout/reboot or manual kill) — this is intentional,
   so subsequent manuals reuse it instantly.

## Testing checklist

1. Open a manual from Stata → creates `$HOME/.cache/stata-okular-dbus`
   and opens the first Stata-Okular window.
2. Open a second, different manual from Stata → should open as a new
   tab in the *same* window, not a second window.
3. Open an ordinary PDF via your file manager while Stata's Okular is
   open → should behave completely independently (own window, own
   geometry), unaffected by the Stata instance.

If step 2 doesn't collapse into one window, check that `dbus-launch` is
installed and on `PATH` (`which dbus-launch`).