exepub.el/README.org

#+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}