Niori ¶
Niori is a medical information manager. This manual documents its installation, configuration, features and operation.
If Emacs is new to you, start with Introduction to the Emacs Way (Appendix A): it explains how the key bindings in this manual are written, the words Emacs uses for everyday things, and what GPG and EasyPG are. If you are already familiar with Emacs, you can skip this appendix. For more about Emacs itself, see the GNU Emacs web site.
Copyright © 2026 Igor Anikeev.
This manual documents Niori, a medical information manager.
Table of Contents
1 Overview ¶
This chapter introduces Niori, its purpose and its main concepts.
1.1 What is Niori ¶
Niori is a personal medical information manager for GNU Emacs. It keeps your medications, visits, lab tests and vaccinations in a single local SQLite database, presented through a dashboard that surfaces what needs attention: upcoming appointments, abnormal results and boosters that are due. The reports and scans behind those records (PDF, DOCX, images) live in the same data directory, attached to the record they belong to.
Rather than reimplementing UI toolkits, it composes the
platform Emacs already provides: tabulated-list-mode rosters,
widget forms, the built-in sqlite binding, Modus themes
and transient menus.
It runs as a package inside your Emacs, or as a standalone application
on a stock, configuration-free Emacs (see Installing as a standalone application). Your data stays yours: one data directory holds the
database and every attached document, offline by default, with an
optional GPG-encrypted Org export and automatic revision snapshots you
can diff with ediff (see History and revisions). Niori is
free software under GPL-3.0-or-later, uses lexical binding everywhere
and depends on GNU ELPA packages only. This manual describes version
0.1.0 of niori.el.
If Emacs is new to you, start with Introduction to the Emacs Way (Appendix A): it explains how the key bindings in this manual are written, the words Emacs uses for everyday things, and what GPG and EasyPG are. If you are already familiar with Emacs, you can skip this appendix. For more about Emacs itself, see the GNU Emacs web site.
1.2 Features ¶
Niori tracks four kinds of clinical records. Each is an independent module with its own roster, form and dashboard section:
| Module | What you track | Dashboard section |
|---|---|---|
| Medications | name, dosage, form, dates, prescriber, instructions | active medications list |
| Visits | date, doctor, facility, reason, diagnosis, notes | upcoming visits (next 30 days) |
| Lab tests | date, name, result, unit, reference range, flag | latest result per test, abnormal flags |
| Vaccinations | date, vaccine, dose, route, lot, provider, next due | boosters due / overdue |
Several features cut across all modules:
- Rosters (sortable
tabulated-list-modebuffers), forms (validatedwidgetbuffers with date checks) and detail views with buttons. - Documents: attach any file (PDF, DOCX, image, …) to a
record; it is copied into the data directory and opened with
doc-view,image-modeor an external viewer (see Documents). - Letters composed from visit records, with
flyspellspell-checking and optionalyasnippettemplates (see Visits and letters). - Exports: Org (optionally encrypted), CSV and FHIR JSON (see Exporting data).
- History: every change or deletion is snapshotted, and any record can be diffed against its previous revision (see History and revisions).
- Backups: one keystroke copies the database to a timestamped file (see Backups).
- FHIR R4 export plus an authenticated FHIR client (see FHIR interoperability).
1.3 Requirements ¶
Niori needs GNU Emacs 29.1 or later, built with SQLite support. That is the default on major distributions; Niori checks at startup and tells you if SQLite is missing (see No SQLite support).
The following tools are optional; the features they support degrade gracefully without them:
gpgNeeded for the encrypted Org export (see Encryption).
hunspelloraspellNeeded for spell-checking letters (see Visits and letters).
- A system opener
xdg-openon GNU/Linux,openon macOS, the shell’s own associations on MS-Windows, for documents Emacs cannot display (DOCX, XLSX, …) (see Documents).- A FHIR server
Only if you want to retrieve records from one (see FHIR interoperability).
The GNU ELPA dependencies compat, transient,
auto-dark and fontaine are installed automatically when
you install the package (see Installing as a package).
1.4 Concepts ¶
These terms recur throughout the manual:
- Module
A clinical domain (medications, visits, lab tests, vaccinations). A module registers its database schema, roster columns, form fields and dashboard section; a generic view layer renders all of it, so a module file contains no buffer code of its own.
- Roster
A sortable list buffer showing all records of one kind (see Rosters).
- Form
A
widgetbuffer for creating or editing one record, with validated fields and date checks (see Forms).- Detail view
A read-only buffer describing one record, with buttons for the actions that apply to it (see Detail views).
- Dashboard
The central buffer combining each module’s section into one overview of what needs attention (see The dashboard).
- Data directory
The single directory holding the SQLite database, attached documents, backups and exports; the unit of backup, sync and relocation (see The data directory).
- Revision
A JSON snapshot of the previous state of a record, written automatically on every update or delete (see Revisions and audit trail).
2 Installation ¶
This chapter describes how to obtain, install and run Niori.
2.1 Installing as a package ¶
The package is called niori (this repository is
niori.el). Once it is on
MELPA, install it with use-package:
(use-package niori :ensure t :commands (niori niori-dashboard))
To install it straight from a checkout while it is not yet packaged, add the repository to your load path:
(use-package niori :load-path "~/src/niori.el" :commands (niori niori-dashboard))
The GNU ELPA dependencies (compat, transient,
auto-dark, fontaine) are declared in niori.el and
installed automatically; package.el users who prefer
use-package need nothing else. A MELPA recipe ships in
recipes/niori.
2.2 Installing as a standalone application ¶
Niori can run as a full application on a stock, configuration-free
Emacs (emacs -Q; see Running without an init file):
git clone https://github.com/ianikeev/niori.el ./niori.el/bin/niori
That is all. On the first run (when online) the launcher installs the
GNU ELPA dependencies plus vertico, consult,
orderless and which-key; run fully offline it degrades
gracefully to built-ins (Modus themes with day/night switching,
fido-vertical-mode, plain keymap help). Set the environment
variable NIORI_NO_NET to 1 to always start offline
(see Environment variables).
To install it properly, with a desktop entry:
make install # defaults to ~/.local # or: make install PREFIX=/usr/local
This installs bin/niori, the Elisp sources under
share/emacs/site-lisp/niori/, the icon, and
etc/niori.desktop rewritten with the absolute Exec= path.
2.3 First run ¶
The first time Niori opens its database, it creates the data directory
(owner-only, mode 0700, with the .niori-data layout
marker) and the SQLite file inside it, then runs any pending migrations
(see Schema migrations). The database starts empty: there is no
seed data. Open the dashboard with M-x niori and add your first
record (see Starting out). If Emacs is new to you, read the
survival kit in A survival kit first.
2.4 Upgrading ¶
Schema changes run through numbered migrations, recorded in the
schema_migrations table. A new version upgrades your database
in place: you install it and keep using the same data directory. New
tables—like the attachments table of a later
release—appear on the next open without a migration.
3 Using Niori ¶
This chapter explains the application’s features and workflows.
- Starting out
- The dashboard
- Rosters
- Forms
- Detail views
- Medications
- Visits and letters
- Lab tests
- Vaccinations
- Documents
- Exporting data
- History and revisions
- Backups
- FHIR interoperability
3.1 Starting out ¶
Type M-x niori to open the dashboard and enable the key bindings.
The command turns on niori-mode, a global minor mode, so the
C-c M prefix works in every buffer; until then Niori has zero
footprint in your Emacs. Everything is reachable from the dashboard’s
buttons, or from the keyboard:
- C-c M d ¶
Open the dashboard (see The dashboard).
- C-c M m ¶
Medications roster (see Medications).
- C-c M v ¶
Visits roster (see Visits and letters).
- C-c M t ¶
Lab tests roster (see Lab tests).
- C-c M c ¶
Vaccinations roster (see Vaccinations).
- C-c M a module ¶
Start a new record: C-c M a m for a medication, and likewise for visits, lab tests and vaccinations (see Forms).
- C-c M E o ¶
- C-c M E c
- C-c M E j
Export a module as Org, CSV or FHIR JSON (see Exporting data).
- C-c M D ¶
Diff a record against its last revision (see History and revisions).
- C-c M f ¶
Show every document you have attached (see Documents).
- C-c M l ¶
Compose a letter from a visit (see Visits and letters).
- C-c M b ¶
Back up the database (see Backups).
- C-c M ? ¶
Open the transient command menu (when
transientis installed).- C-c M C-h ¶
Show a full overview of every Niori key binding.
CUA bindings (C-x/C-c/C-v cut/copy/paste) are
available for standalone users: set niori-standalone-cua to
t, or type M-x cua-mode anytime. Text size follows the
desktop zoom keys C-=, C-+ and C-- (see Text size).
3.2 The dashboard ¶
The dashboard is Niori’s home screen; M-x niori-dashboard also opens it directly. Each module contributes a section, so one buffer shows, at a glance:
- your active medications;
- upcoming visits, within
niori-visits-upcoming-daysdays (default 30); - the latest result of each lab test, with abnormal results flagged;
- vaccinations whose booster is due or overdue, within
niori-vaccinations-due-daysdays (default 90).
Entries are buttons: follow one to open the record’s detail view. After every write, Niori refreshes any open dashboard, roster and detail buffers for the affected module, so what you see is always current.
3.3 Rosters ¶
A roster lists all records of one kind in a sortable
tabulated-list-mode buffer. Open one from the dashboard or with
C-c M m (medications), C-c M v (visits), C-c M t (lab
tests) or C-c M c (vaccinations).
- RET
Open the record under point in its detail view.
- a
Add a new record (the same form as C-c M a …).
- e
Edit the record under point.
- d
Delete the record under point; Niori asks first (see Attachment safety).
- g
Refresh the roster.
- S
Sort; clicking a column header sorts as well.
- D
Diff the record under point against its previous revision (see History and revisions).
- E
Export the module (see Exporting data).
- L
Compose a letter from the visit under point (visits roster only, see Visits and letters).
3.4 Forms ¶
Records are created and edited in widget forms: buffers with
labelled, validated fields, including checks on dates, so invalid data
never reaches the database.
3.5 Detail views ¶
The detail view describes one record read-only, with buttons for the actions that apply to it. It also accepts the roster keys: e edits, d deletes, D diffs against the previous revision, L composes a letter, and E opens the export menu. In every detail view, A attaches a document to the record (see Documents). After a write, all open buffers of that module refresh automatically.
3.6 Medications ¶
The medications module tracks name, dosage, form, dates, prescriber and instructions for each medication. The dashboard lists your active medications. Open the roster with C-c M m; start a new record with C-c M a m, or with a from the roster.
3.7 Visits and letters ¶
The visits module tracks date, doctor, facility, reason, diagnosis and
notes for each visit; the dashboard lists upcoming visits within the
configured window (see Variable reference). In the visits roster,
L (or C-c M l) composes a letter from the record
under point: a narrative document describing the visit, which you edit
and file as you would any other document. Letters are spell-checked
with flyspell when a hunspell or aspell
binary exists (niori-letter-flyspell), and optional
yasnippet templates ship in snippets/
(see Optional integrations).
3.8 Lab tests ¶
The lab tests module tracks date, name, result, unit, reference range and flag. The dashboard shows the latest result of each test, with abnormal flags, so an out-of-range result surfaces even when it was recorded weeks ago. Open the roster with C-c M t.
3.9 Vaccinations ¶
The vaccinations module tracks date, vaccine, dose, route, lot, provider and next due. The dashboard lists boosters that are due or overdue within the configured window. Open the roster with C-c M c.
3.10 Documents ¶
Any file—a PDF lab report, a DOCX letter, a photograph—can be
attached to a visit, lab test, medication or vaccination. Attach it
with A in the record’s detail view. The file is copied into the
data directory, one folder per record, so copying or syncing the data
directory backs up the whole record (see The data directory);
niori-attachments-import-method can also move or symlink instead
(see Variable reference).
Attached documents open with doc-view (PDF), image-mode
(images) or an external viewer for formats Emacs cannot display, such
as DOCX or XLSX.
C-c M f opens the list of every document you have attached:
- RET
Open the document.
- f
Open it with the external viewer.
- o
Show its folder in Dired.
- r
Retitle it.
- d
Detach it; Niori asks before removing the file.
The safety rules behind these buffers—relative paths, checksums and orphan handling—are described in Attachment safety.
3.11 Exporting data ¶
Three export formats cover the common needs, and the output lands in exports/ inside the data directory (see The data directory):
- C-c M E o
Export as Org (
niori-export-org).- C-c M E c
Export as CSV.
- C-c M E j
Export as FHIR JSON (see FHIR interoperability).
The Org export can be encrypted with EasyPG: invoke it with a prefix
argument, C-u C-c M E o (see Encryption). CSV exports open
in csv-mode automatically when that package is installed. If
you keep narrative notes in Org files of your own, org-ql can
run structured queries over exported Org archives
(see Optional integrations).
3.12 History and revisions ¶
Every update and delete first snapshots the current record, as JSON,
into the revisions table—an audit trail inside the same
database file (see Revisions and audit trail). Whether revisions
are kept at all is controlled by niori-store-keep-revisions
(see Variable reference).
D on any record in a roster, or C-c M D, opens an
ediff between the pretty-printed current record and its previous
revision, so you can see exactly what changed.
3.13 Backups ¶
C-c M b (M-x niori-store-backup) copies the database to a timestamped file in backups/ inside the data directory. Keep a copy on offline media; restoring one is described in Restoring a database. Because the data directory also holds every attached document, the directory itself is the unit of backup and relocation (see Backups and relocation).
3.14 FHIR interoperability ¶
C-c M E j (M-x niori-fhir-export) writes a module as a FHIR R4 collection Bundle:
- Medications
become
MedicationStatementresources;- Visits
become
Encounterresources;- Lab tests
become
Observationresources (numeric results asvalueQuantity, flags asH,LandAinterpretation codes);- Vaccinations
become
Immunizationresources.
The mapping is intentionally minimal—display strings, no code-system translation—which is right for personal export and review.
For retrieval, set niori-fhir-server-url to the server’s base
URL and keep the bearer token in auth-source; then M-x
niori-fhir-fetch issues authenticated requests with the built-in
url library and returns parsed JSON (see Network access).
4 Configuration ¶
This chapter documents application settings and configuration files.
- Customizing Niori
- Variable reference
- Environment variables
- Appearance
- Text size
- Optional integrations
4.1 Customizing Niori ¶
All user options live in the niori customization group: type
M-x customize-group RET niori RET to browse them with
descriptions and types, or set them with setq in your init
file. There is no configuration file of Niori’s own to edit. The
standalone application runs without an init file; it is configured
through its built-in defaults and the environment variables
(see Environment variables).
When Niori runs inside your Emacs it never touches your theme or your fonts; the appearance layer only activates for the standalone application (see Appearance).
4.2 Variable reference ¶
The essentials, all in the niori group:
niori-data-directory¶The data directory: database, documents, backups, exports. Default ~/.local/share/niori, subject to the environment (see Environment variables).
niori-data-file¶Default
nil, meaning the database lives inside the data directory. An absolute path here puts the database elsewhere.niori-documents-directory¶Default
nil, meaning attached documents live inside the data directory. An absolute path here puts them elsewhere.niori-attachments-import-method¶How an attached file enters the data directory:
copy(default),moveorsymlink.niori-attachments-external-opener¶External viewer for formats Emacs cannot display:
xdg-openon GNU/Linux,openon macOS; MS-Windows usesw32-shell-execute.niori-store-tighten-data-directory¶What happens on open when other users can reach the data directory:
t(default) tightens it to owner-only,advisekeeps your modes but reports once per session,nilstays silent (see File permissions).niori-store-keep-revisions¶Keep the revision audit trail; default
t(see Revisions and audit trail).niori-visits-upcoming-days¶Dashboard window for upcoming visits; default 30.
niori-vaccinations-due-days¶Dashboard window for boosters due; default 90.
niori-letter-flyspell¶Whether letters are spell-checked; default
auto, which enables checking when a spell-checking binary exists (see Visits and letters).niori-encryption-recipients¶GPG keys for encrypted exports; default
nil(see Encryption).niori-fhir-server-url¶Base URL of a FHIR server for retrieval; default
nil(see FHIR interoperability).niori-appearance-manage¶Whether Niori manages theme and font; default
nil,tin the standalone application (see Appearance).niori-appearance-font-family¶Monospaced font used when the appearance layer manages fonts; auto-detected by default.
niori-standalone-cua¶Set to
tto give standalone users the usual CUA cut/copy/paste bindings (see Starting out).
4.3 Environment variables ¶
Two environment variables matter most:
NIORI_DATA_DIROverrides
niori-data-directory. Useful for the standalone application, which has no init file to customize.NIORI_NO_NETSet to
1to make the standalone bootstrap skip all package installation and always start offline.
The data directory itself resolves in this order: $NIORI_DATA_DIR
when set; otherwise $XDG_DATA_HOME/niori (usually
~/.local/share/niori); on MS-Windows, %LOCALAPPDATA%\niori.
4.4 Appearance ¶
Inside your Emacs, Niori never touches your theme or your fonts:
niori-appearance-manage is nil by default and the
appearance layer stays out of the way. It only activates for the
standalone application, which presents a complete, coherent look on its
own. There it prefers the GNU ELPA auto-dark package, switching
between the modus-operandi and modus-vivendi themes with
the day/night cycle, and fontaine for font presets, with
built-in fallbacks when those packages are not available. The font
family is auto-detected; set niori-appearance-font-family to
override it.
4.5 Text size ¶
Once niori-mode is enabled (M-x niori, see Starting out), the application follows the usual desktop zoom keys: C-=
and C-+ make the text larger, C-- makes it smaller. Repeat
a key to keep growing or shrinking. The keys work in every buffer,
because niori-mode is a global minor mode; the scale itself is a
per-buffer setting, so a roster, the dashboard and a letter each keep
their own size.
- C-= ¶
- C-+
Increase the text size of the current buffer.
- C-- ¶
Decrease the text size of the current buffer.
- C-x C-0 0 ¶
Reset the text size of the current buffer to the default (
text-scale-adjust, built into Emacs).
Note that C-- shadows the usual negative prefix argument while
niori-mode is enabled; use M-- when a command needs a
negative argument.
4.6 Optional integrations ¶
Niori prefers mature Emacs components over new code, and every optional integration is guarded at runtime: absence is a graceful downgrade, not an error. When installed, the following light up automatically:
transient: the C-c M ? command menu, runtime-defined, with a fallback when absent;which-key: keymap discoverability (built into Emacs 30, GNU ELPA otherwise);vertico,consult,orderless: completion in the standalone application, auto-installed when online, withfido-vertical-modeas the fallback;yasnippet: letter templates from snippets/;csv-mode: CSV exports open in it automatically;org-ql: structured queries over exported Org archives.
MELPA-only packages are never hard requirements: the package header lists GNU ELPA dependencies only (see Requirements).
5 Data and Privacy ¶
This chapter describes how Niori stores and handles information.
- The data directory
- File permissions
- Revisions and audit trail
- Backups and relocation
- Attachment safety
- Encryption
- Network access
- Schema migrations
5.1 The data directory ¶
Everything Niori writes lives in one directory you choose—the unit of
backup, sync and relocation. Its location resolves to
$NIORI_DATA_DIR when set, otherwise to $XDG_DATA_HOME/niori
(usually ~/.local/share/niori), or %LOCALAPPDATA%\niori on
MS-Windows (see Environment variables):
~/.local/share/niori/
|-- .niori-data layout marker ("layout-version: 1")
|-- niori.db the database
|-- documents/ attached files, one folder per record
| `-- visits/42/2026-11-20-lab-report.pdf
|-- backups/ timestamped database copies
|-- exports/ Org / CSV / FHIR output
`-- letters/ reserved for saved letters
The attachments table stores paths relative to the
documents directory (visits/42/2026-11-20-lab-report.pdf), plus
title, size, MIME type and SHA-256 checksum (see Attachment safety).
5.2 File permissions ¶
On POSIX systems everything Niori writes is owner-only: the directory
itself (mode 0700, re-applied on every open—you are told when
an existing loose directory is tightened), the documents inside it, the
database, the backups and exports, and the -journal,
-wal and -shm files SQLite keeps beside the database.
Those sidecar files are created while the process umask is narrowed, so
they are private from the instant they exist, instead of needing a
chmod that would come too late.
On MS-Windows none of that means anything: Emacs maps chmod to
the read-only attribute there, so Niori performs no mode changes at all
and leaves protection to the NTFS permissions of the directory—which
is why the default is the per-user %LOCALAPPDATA% folder rather
than ~/.local.
If you share the directory on purpose,
niori-store-tighten-data-directory decides what happens:
t(default)re-apply mode
0700on open and say so in one line;advisekeep your modes, report once per session and name the fix;
nilkeep your modes, say nothing.
In the latter two cases, M-x niori-store-secure-data-directory
fixes the tree on demand, regardless of the policy. It never follows
symbolic links, so a document imported with the opt-in symlink
method keeps the permissions of the file you own elsewhere. A
deliberately shared folder—a family NAS, a group-readable backup
volume—can therefore stay shared without being silently overridden on
every open.
Write-ahead logging is deliberately not enabled: the data directory is meant to be synced as a whole, and a live -wal file on a Syncthing or network folder is a corruption source rather than a performance win.
5.3 Revisions and audit trail ¶
Medical data is edited rarely, but mistakes matter. Every update or
delete first snapshots the previous record, as JSON, into the
revisions table: a real audit trail inside the same database
file, at the cost of one JSON write per change. The behaviour is
controlled by niori-store-keep-revisions (default t).
To inspect a change, D in a roster or C-c M D diffs the
record against its previous revision with ediff
(see History and revisions).
5.4 Backups and relocation ¶
C-c M b writes a timestamped copy of the database into backups/ (see Backups); keep a copy on offline media. Because attaching copies files by default, the data directory is a complete copy of the record, and “back up this folder” is sufficient advice.
Moving an installation is a directory move plus M-x
niori-store-switch-data-directory: the command closes the connection,
re-points niori-data-directory, reopens the database (running
migrations) and refreshes open buffers. It asks before adopting a
folder that holds no Niori data yet, and keeps using the old directory
if the new one cannot be opened.
5.5 Attachment safety ¶
Documents are treated with care:
- Paths are stored relative to the documents directory, and expanding a stored path refuses anything that would escape it, so a hand-edited row cannot turn into an arbitrary file read.
- Attaching copies the file by default (the original stays where
it was);
niori-attachments-import-methodallowsmoveandsymlinkfor large scans, at the cost of no longer being self-contained. - Detaching asks before removing a file, and never removes one another row still points at.
- Deleting a record asks first and keeps the files. M-x niori-attachments-check lists missing files and documents orphaned by a deleted record; M-x niori-attachments-purge-orphans cleans the orphans up.
5.6 Encryption ¶
The Org export can be encrypted with EasyPG: invoke it with a prefix
argument, C-u C-c M E o, and it is encrypted to the keys in
niori-encryption-recipients. The gpg prerequisite is
listed in Requirements; what GPG and EasyPG actually are is
explained in GPG and EasyPG, written for readers meeting them
for the first time.
If you keep narrative notes in Org files instead, the built-in
org-crypt encrypts subtrees on save—Niori stays out of the way
of both styles.
5.7 Network access ¶
Nothing leaves your machine unless you call the FHIR client. There is no telemetry and no sync service; the data directory is offline by default.
For FHIR retrieval, set niori-fhir-server-url to the server’s
base URL and keep the bearer token in auth-source—a line like
the following in .authinfo:
machine fhir.example.com secret TOKEN
Then M-x niori-fhir-fetch issues authenticated requests with the
built-in url library and returns parsed JSON
(see FHIR interoperability).
5.8 Schema migrations ¶
Schema changes run through numbered migrations recorded in the
schema_migrations table. A new version upgrades the database in
place; new tables appear on the next open without a migration
(see Upgrading). Table and column names come exclusively from the
schema registry, and values are always bound parameters, so the query
surface is injection-safe.
6 Troubleshooting ¶
This chapter covers common problems and their solutions.
- No SQLite support
- Offline fallback
- Permission warnings
- Documents will not open
- Spell-checking does not start
- Encrypted export fails
- FHIR retrieval fails
- Orphaned attachments
- Key binding conflicts
- Restoring a database
6.1 No SQLite support ¶
Niori needs Emacs 29.1 or later built with SQLite support. That is the default on major distributions, and Niori checks at startup and tells you if the binding is missing. Install an Emacs build with SQLite support (see Requirements) and Niori will open its database.
6.2 Offline fallback ¶
If the standalone application starts with plain themes and simple
completion, it could not reach GNU ELPA. This is deliberate: every
optional package is guarded, and the application must start on a bare,
offline Emacs. The first run installs vertico,
consult, orderless and which-key when online; set
NIORI_NO_NET to 1 to always start offline (see Environment variables). On a degraded start you still get Modus themes with
day/night switching, fido-vertical-mode and plain keymap help.
6.3 Permission warnings ¶
If Niori reports a loose data directory on open, either let it tighten
the directory (the default, niori-store-tighten-data-directory
t), or, if you share the directory on purpose, set the option to
advise or nil and run M-x
niori-store-secure-data-directory whenever you want it fixed
(see File permissions).
6.4 Documents will not open ¶
PDFs open with doc-view and images with image-mode; other
formats (DOCX, XLSX, …) go to the external opener: the program in
niori-attachments-external-opener, which defaults to
xdg-open on GNU/Linux, open on macOS, and
w32-shell-execute on MS-Windows. If nothing happens, check that
the opener matches your system (see Variable reference).
6.5 Spell-checking does not start ¶
Letters are spell-checked with flyspell only when a
hunspell or aspell binary exists;
niori-letter-flyspell defaults to auto, which enables
checking only in that case (see Visits and letters). Install
either binary to get spell-checking.
6.6 Encrypted export fails ¶
Encrypted Org export needs two things: gpg installed, and at
least one key in niori-encryption-recipients. Remember that
encryption is requested with a prefix argument (C-u C-c M E o);
without it, the export is written in plain Org (see Encryption).
6.7 FHIR retrieval fails ¶
M-x niori-fhir-fetch needs niori-fhir-server-url and a
bearer token in auth-source for the server’s host: a
.authinfo line such as machine fhir.example.com secret
TOKEN (see Network access).
6.8 Orphaned attachments ¶
Deleting a record keeps its files on purpose (see Attachment safety), so documents can outlive their record. M-x niori-attachments-check lists missing files and orphans; M-x niori-attachments-purge-orphans removes the orphans. Files still referenced by another record are never removed.
6.9 Key binding conflicts ¶
The C-c M prefix was chosen to avoid collisions with other
packages that use popular prefixes (for instance C-c n, used by
deft). niori-mode is a global minor mode with zero footprint
until you run M-x niori. If another package shadows one of the
bindings, C-c M C-h shows the full keymap overview
(see Starting out).
Appendix A Introduction to the Emacs Way ¶
This appendix is for readers who have never used Emacs—perhaps you are coming to Niori as a standalone application, on a computer where Emacs was installed mainly to run it (see Installing as a standalone application). It explains how the key bindings in this manual are written, the small set of keys that gets you out of trouble, the words Emacs uses for everyday things, and what GPG and EasyPG are. If you have used Emacs before, skip this appendix.
- How key bindings are written
- A survival kit
- Words Emacs uses
- GPG and EasyPG
- Running without an init file
A.1 How key bindings are written ¶
Commands in this manual are written as key sequences. C- means the Control key: C-x is “hold Control and type x”. M- means Meta: on most keyboards that is the Alt key, and on keyboards without one, pressing and releasing Esc before the key works as a substitute. M-x is therefore “hold Alt and type x”.
A sequence of several elements is typed in order, one after another. C-c M b, Niori’s backup command, means: hold Control and type c, release everything, then hold Alt and type b. Within one element the keys are held together; between elements they are not.
Letters matter exactly as written: C-a and C-A are
different bindings, and C-A means Control with a shifted
A. A few keys have names instead of symbols: RET is the Enter
key, SPC the space bar, TAB the Tab key. Where this
manual writes M-x customize-group RET niori RET, you type
M-x, the word customize-group, press RET, type
niori and press RET again.
M-x deserves a second look, because every Niori command can be reached through it: M-x asks for a command name in the minibuffer (see Words Emacs uses), and RET runs it. A prefix argument modifies the command that follows: C-u C-c M E o asks the Org export to encrypt itself (see Exporting data).
Emacs documents itself. C-h k asks “what does this key do?”, C-h m describes the current buffer and lists every key binding active in it, and C-h t starts the built-in tutorial. Inside Niori, C-c M C-h shows all Niori bindings at once (see Starting out).
A.2 A survival kit ¶
Ten keys answer almost every first-day question. None of them are Niori’s; they belong to Emacs everywhere.
- C-g ¶
Quit whatever is happening: a half-typed key sequence, a minibuffer prompt, a search, a hung command. When in doubt, type C-g.
- C-x C-c
Leave Emacs.
- C-x C-f ¶
Open a file: Emacs asks for its name in the minibuffer. Use this to look at an exported Org or CSV file.
- C-x C-s
Save the current buffer to its file.
- C-/ ¶
Undo the last change (C-x u also works).
- C-s ¶
Search forward in the buffer; C-r searches backwards. RET stops the search where you are.
- C-v
Scroll down a screenful; M-v scrolls up. The PgDn and PgUp keys do the same.
- M-x
Run any command by name (see How key bindings are written). Every
niori-command mentioned in this manual works here, including those without a key binding.- C-h k
Ask what a key does: type the key after C-h k and Emacs shows its documentation.
- C-h t
The Emacs tutorial: half an hour that repays itself for the rest of the week.
A.3 Words Emacs uses ¶
Emacs calls everyday things by names of its own. These recur throughout the manual:
- Buffer
The content you edit or read—a file, a roster, a form, the dashboard. Niori’s rosters, forms and detail views are buffers.
- Window
A pane showing one buffer. Emacs’s frame is what your desktop calls a window; a window in Emacs is one pane of it, and Emacs shows several buffers side by side by splitting the frame into windows.
- Point
The cursor. Commands act at point: in a roster, RET opens the record under point (see Rosters).
- Minibuffer ¶
The prompt area at the bottom of the frame, where Emacs asks questions and accepts command names after M-x. RET confirms and C-g cancels. One-line messages appear next to it, in the echo area.
- Mode
The active behaviour of a buffer. A major mode says what the buffer is—a
tabulated-list-moderoster,doc-viewfor a PDF—and minor modes layer extra behaviour on top.niori-modeis a global minor mode, active in every buffer, which is why C-c M works everywhere (see Starting out).- Keymap ¶
The table that connects a key to a command; one connection is a key binding. Prefix keys like C-c M select a whole sub-table: the b in C-c M b is looked up inside Niori’s own keymap.
- Init file ¶
The personal startup script Emacs runs at launch (~/.emacs.d/init.el or ~/.emacs), where
setqanduse-packagelines go. The standalone application runs without one (see Running without an init file).- Customize
The built-in settings browser: M-x customize-group RET niori RET lists every Niori option with descriptions and types (see Customizing Niori).
- Package ¶
An installable extension. GNU ELPA is the GNU archive Emacs installs from by default; MELPA is a popular community archive. Niori depends on GNU ELPA packages only (see Requirements).
- Completion ¶
While you type in the minibuffer, Emacs offers matching choices and RET picks one. The standalone application installs
vertico,consultandorderlessfor this (see Optional integrations).
A.4 GPG and EasyPG ¶
Two names appear wherever Niori encrypts something (see Encryption).
GPG, the GNU Privacy Guard, is the free OpenPGP implementation:
a command-line program, gpg, that encrypts data to key
pairs. A key pair has a public half, which you may publish and
which others encrypt to you, and a secret half, protected by a
passphrase, which decrypts. You generate a pair with
gpg --full-generate-key and list the ones you have with
gpg --list-keys; each is identified by a name and an e-mail
address. The niori-encryption-recipients option holds such
identifiers: an encrypted export is encrypted to those public keys, so
only someone holding the matching secret keys—you, or a person you
chose—can read it. A small helper program, gpg-agent,
remembers the passphrase for a while, so you need not retype it.
EasyPG is the Emacs side of the same machinery, built into
Emacs. The EasyPG Assistant manages keys interactively (M-x
epa-list-keys), and epa-file makes Emacs treat any file whose
name ends in .gpg transparently: it decrypts on open,
re-encrypts on save, and asks for the passphrase in the minibuffer
when gpg-agent does not still have it. Niori’s encrypted
export simply hands the file to this layer: open the export in Emacs
and you are reading it; gpg --decrypt does the same outside
Emacs.
A.5 Running without an init file ¶
Emacs normally runs your init file at startup: themes, fonts, key
tweaks and installed packages—everything you have put there. The
-Q flag, short for “quick”, starts Emacs without it: no
personal init file, no site-wide one, no X resources. You get a
pristine, stock editor session that behaves the same on every machine
and every run.
That is exactly how Niori’s standalone launcher works
(see Installing as a standalone application): bin/niori
starts such a stock Emacs, loads Niori into it and lets you open the
dashboard with M-x niori, so the application never
inherits—and never touches—any personal configuration. Two
practical consequences:
- What persists between runs is your data—the data directory
(see The data directory)—not settings. To point the standalone
application at a particular data directory, or to keep it offline, set
the environment variables
NIORI_DATA_DIRandNIORI_NO_NET(see Environment variables); there is no init file to set options in. - Options you change interactively—M-x customize-group RET niori RET, M-x cua-mode for cut/copy/paste keys (see Starting out)—last for the session only. If you later move Niori into your own Emacs, the same settings belong in the init file instead (see Customizing Niori).
If a first contact with Emacs itself feels rough, C-h t (the tutorial) and the survival kit above are the shortest way in.
Index ¶
| Jump to: | A B C D E F G H I K L M N O P R S T U V |
|---|
| Jump to: | A B C D E F G H I K L M N O P R S T U V |
|---|