91 lines
4.8 KiB
Org Mode
91 lines
4.8 KiB
Org Mode
#+TITLE: exepub: A Flexible Emacs-Based Publication Workflow
|
|
#+AUTHOR: Emmanuele Somma
|
|
#+DATE: 2025-07-10
|
|
#+DESCRIPTION: A complete introduction to the design, concepts and usage
|
|
of the exepub package for Emacs, supporting academic-quality article
|
|
production, embargo management and multi-channel dissemination.
|
|
|
|
* Purpose
|
|
exepub was conceived to bridge the gap between rigorous academic writing
|
|
and modern multi-platform publication. It provides Emacs users with a
|
|
coherent set of commands and directory conventions to author, track,
|
|
export and disseminate digital assets—be they full-length articles,
|
|
short essays or multimedia derivatives—while preserving bibliographic
|
|
references, embargo rules and distribution metadata in a single Org-mode
|
|
workflow.
|
|
|
|
* Core Concepts
|
|
At its heart exepub treats every piece of writing as an “asset” that
|
|
passes through well-defined stages: draft, dissemination (archive) and
|
|
manifestation. A draft lives in a dedicated directory, named with a
|
|
timestamp, a sanitized slug and a set of keywords. When it is ready
|
|
for delivery to a publisher or platform, the `exepub/disseminate`
|
|
command moves it into an archive folder organized by year and updates
|
|
its `#+PUBLISHED:` date and `#+STATUS:`. Downstream, each format-and-channel
|
|
combination is a “manifestation” housed in its own subdirectory, allowing
|
|
HTML, PDF, audio or video versions to coexist alongside the original
|
|
Org source.
|
|
|
|
* Directory Layout
|
|
Upon initialization exepub creates a base container with seven subdirectories
|
|
named by keyword:
|
|
:base holds overall configuration
|
|
:drafts contains in-progress assets
|
|
:archive stores finalized assets, year-by-year
|
|
:attic archives abandoned drafts
|
|
:template keeps reusable snippets and option templates
|
|
:logs publishes a machine-readable log of each dissemination event
|
|
:trash receives permanently deleted items
|
|
|
|
This structure ensures that every file lives in its assigned place, enabling
|
|
simple Dired navigation via `exepub/open-drafts`, `exepub/open-archive` and so on.
|
|
|
|
* Authoring Workflow
|
|
Writing begins with `exepub/article-create`, which prompts for a slug and
|
|
keywords, generates a new `draft.org` prefilled with default headers
|
|
(`#+TITLE:`, `#+CREATED:`, `#+STATUS: draft`, `#+SLUG:` and `#+KEYWORDS:`)
|
|
and imports shared `#+OPTIONS:` from a template. Authors then compose
|
|
in Org mode, inserting headings, citations and figures in the usual way.
|
|
|
|
When the manuscript is mature, `exepub/disseminate` atomically renames and
|
|
moves the draft into the archive, updating its slug, setting `#+STATUS: ready`
|
|
or `manifestation`, stamping the publication date and moving the folder
|
|
under `archive/<year>/`. This operation can be rolled back automatically
|
|
if any step fails, preserving data integrity.
|
|
|
|
* Generating Manifestations
|
|
Each dissemination may require multiple exported formats. The
|
|
`exepub/export-to` command creates a `manifestation/<format>-<channel>/`
|
|
folder, copies the Org source (stripped of noexport sections), disables
|
|
the inline title, sets `#+STATUS: manifestation` and appends a license footer.
|
|
Supported formats include HTML, Markdown and LaTeX/PDF; unsupported formats
|
|
produce a placeholder file. Metadata such as `DELIVERED`, `EMBARGO` and
|
|
custom properties defined under a top-level `* Manifestations :noexport:`
|
|
section are read and updated automatically.
|
|
|
|
* Customization and Extensions
|
|
All directory paths live in the `exepub--dirs` alist and can be re-initialized
|
|
via `exepub--dirs-setup` using `exepub/home-directory`. Default header values
|
|
(`CREATED`, `STATUS`, `PUBLISHED`, `KEYWORDS` etc.) are exposed as Emacs
|
|
custom variables. Export options (`#+OPTIONS:`) are injected by advice on
|
|
`org-export-insert-default-template` from a customizable alist. Hooks on
|
|
`before-save` regenerate slugs and rename directories, while export filters
|
|
and custom CSS allow fine-tuning of HTML output.
|
|
|
|
* Getting Started
|
|
To begin using exepub, add its directory to your `load-path`, require it in
|
|
your init file and set `exepub/home-directory` to your container path.
|
|
Evaluate `(exepub--dirs-setup exepub/home-directory)` and ensure your
|
|
`template/options.org` defines any shared `#+OPTIONS:`. You are then ready
|
|
to create your first draft with `M-x exepub/article-create`.
|
|
|
|
* Conclusion
|
|
exepub unifies rigorous academic workflows with the flexibility of Org mode and
|
|
Emacs Lisp. By encoding every step—drafting, embargo management, multi-format
|
|
export and channel-specific dissemination—into a programmable structure, it
|
|
empowers authors to focus on content while the system manages metadata,
|
|
versioning and delivery. Whether you publish in peer-reviewed journals, blogs,
|
|
social networks or private logs, exepub provides a single, extensible pipeline
|
|
from idea to audience.
|
|
::contentReference[oaicite:0]{index=0}
|