From 95905429e162cee92ea0d73ddda8cf76ece852b3 Mon Sep 17 00:00:00 2001
From: "Wesley R. Elsberry" <welsberr@gmail.com>
Date: Tue, 7 Oct 2025 05:05:58 -0400
Subject: [PATCH] Added setup/README.md to explain venue system mechanics.

---
 setup/README.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 158 insertions(+)
 create mode 100644 setup/README.md

diff --git a/setup/README.md b/setup/README.md
new file mode 100644
index 0000000..cfd888a
--- /dev/null
+++ b/setup/README.md
@@ -0,0 +1,158 @@
+# PolyPaper `setup/` Directory
+
+This directory contains **Org-Mode setup files** and configuration fragments used by the **PolyPaper** publishing system to generate multiple variants of a research manuscript from a single master source (`paper.org`).
+
+Each variant corresponds to a **VENUE**, such as *arxiv*, *ieee*, or *elsarticle*, representing different submission or publication formats.
+
+
+
+-----------------------------
+
+## 📂 Structure of `setup/`
+
+| File                   | Purpose                                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `venue-arxiv.org`      | Minimalist setup suitable for ArXiv submissions (standard LaTeX `article` class).        |
+| `venue-ieee.org`       | Uses the IEEEtran class; automatically applies 2-column layout and IEEE reference style. |
+| `venue-elsarticle.org` | Elsevier journal format compatible with *elsarticle.cls*.                                |
+| `common-macros.org`    | Shared Org macros and LaTeX definitions loaded by all venues.                            |
+| `README.md`            | This file (generated by tangling `README.org`).                                          |
+|               |                                                                                          |
+
+
+## 🧭 Creating a New Venue File
+
+To add a new publication context, follow these steps:
+
+1. **Copy an existing setup file** as a starting point:
+
+   ```bash
+   cp setup/venue-arxiv.org setup/venue-springer.org
+   ```
+
+2. **Edit the metadata and options** inside the new file:
+
+   ```org
+   #+TITLE: PolyPaper Venue: Springer
+   #+LaTeX_CLASS: article
+   #+LaTeX_CLASS_OPTIONS: [twocolumn]
+   #+LATEX_HEADER: \usepackage{natbib}
+   #+LATEX_HEADER: \bibliographystyle{spbasic}
+   ```
+
+3. **Reference common macros (optional):**
+
+   ```org
+   #+INCLUDE: "common-macros.org"
+   ```
+
+4. **Test the new variant:**
+
+   ```bash
+   make VENUE=springer
+   ```
+
+   or, using Docker:
+
+   ```bash
+   make docker VENUE=springer
+   ```
+
+5. **Verify output:** The resulting PDF will appear as:
+
+   ```
+   paper-springer.pdf
+   ```
+
+
+-----------------------------
+
+## 📂 Structure of `setup/`
+
+| File                   | Purpose                                                                                  |
+| ---------------------- | ---------------------------------------------------------------------------------------- |
+| `venue-arxiv.org`      | Minimalist setup suitable for ArXiv submissions (standard LaTeX `article` class).        |
+| `venue-ieee.org`       | Uses the IEEEtran class; automatically applies 2-column layout and IEEE reference style. |
+| `venue-elsarticle.org` | Elsevier journal format compatible with *elsarticle.cls*.                                |
+| `common-macros.org`    | Shared Org macros and LaTeX definitions loaded by all venues.                            |
+| `README.md`            | This file (generated by tangling `README.org`).                                          |
+| #+end_src              |                                                                                          |
+
+#+name: readme-new-venue
+#+begin_src org :exports none
+-----------------------------
+
+## 🧭 Creating a New Venue File
+
+To add a new publication context, follow these steps:
+
+1. **Copy an existing setup file** as a starting point:
+
+   ```bash
+   cp setup/venue-arxiv.org setup/venue-springer.org
+   ```
+
+2. **Edit the metadata and options** inside the new file:
+
+   ```org
+   #+TITLE: PolyPaper Venue: Springer
+   #+LaTeX_CLASS: article
+   #+LaTeX_CLASS_OPTIONS: [twocolumn]
+   #+LATEX_HEADER: \usepackage{natbib}
+   #+LATEX_HEADER: \bibliographystyle{spbasic}
+   ```
+
+3. **Reference common macros (optional):**
+
+   ```org
+   #+INCLUDE: "common-macros.org"
+   ```
+
+4. **Test the new variant:**
+
+   ```bash
+   make VENUE=springer
+   ```
+
+   or, using Docker:
+
+   ```bash
+   make docker VENUE=springer
+   ```
+
+5. **Verify output:** The resulting PDF will appear as:
+
+   ```
+   paper-springer.pdf
+   ```
+
+
+
+
+-----------------------------
+
+## 🧰 Example Minimal `venue-foo.org`
+
+```org
+#+TITLE: PolyPaper Venue: Foo Journal
+#+LaTeX_CLASS: article
+#+LaTeX_CLASS_OPTIONS: [12pt,twocolumn]
+#+LATEX_HEADER: \usepackage{geometry}
+#+LATEX_HEADER: \geometry{margin=1in}
+#+LATEX_HEADER: \usepackage[backend=biber,style=authoryear]{biblatex}
+#+LATEX_HEADER: \addbibresource{biblio.bib}
+#+INCLUDE: "common-macros.org"
+```
+
+
+-----------------------------
+
+## 🏁 Summary
+
+The `setup/` directory defines how PolyPaper adapts a single Org manuscript to multiple target formats.
+Each `venue-*.org` file overrides class, style, and export parameters while keeping the body text identical — ensuring consistent content across venues with minimal duplication.
+
+---
+
+**PolyPaper Project**
+*“One manuscript, many destinations.”*