docrev 0.6.4 → 0.6.6

package/README.md

@@ -2,132 +2,92 @@
 
 [![npm](https://img.shields.io/npm/v/docrev)](https://www.npmjs.com/package/docrev)
 
-**Write your papers in plain text. Generate Word documents when you need them.**
+**Write papers in plain text. Generate Word when needed.**
 
-## The Problem
+## Why
 
-You're writing a scientific paper. Your supervisor reviews it in Word, adding comments and track changes. You address the feedback, send it back. Another round of reviews. Then journal submission. Then reviewer comments. More Word documents flying back and forth.
+Scientific papers go through many revision cycles. You send a Word document to collaborators, they add comments and track changes, you address the feedback and send it back. Then journal submission, reviewer comments, more revisions. After a few rounds, track changes become unreadable, you have fifteen versions of the same file, and nobody knows which one is current. Equations break when copying between documents. Figures get embedded at the wrong resolution or disappear entirely.
 
-Sound familiar?
+docrev takes a different approach. You write in plain text using Markdown, a simple formatting syntax that takes ten minutes to learn. When you need to share with collaborators or submit to a journal, docrev generates a Word document or PDF. Your collaborators review and comment in Word as usual. When they send it back, docrev imports their feedback into your Markdown files. You address the comments, rebuild the document, and send it back. The cycle continues, but your source files stay clean and under version control.
 
-- Word files get corrupted
-- "Which version is the latest?" confusion
-- Track changes become unreadable after multiple rounds
-- Equations break when copy-pasting
-- Figures get embedded at wrong resolutions
-- Collaborating means emailing files back and forth
-
-## The Solution
-
-**docrev** lets you write in plain text (Markdown) and generate Word/PDF whenever you need to share. Your collaborators keep using Word — they don't need to change anything. You get:
-
-- **Version control** — See exactly what changed, when, and why
-- **No corruption** — Plain text files never break
-- **Equations that work** — Write LaTeX, get perfect equations in Word
-- **Figures stay separate** — Reference images, don't embed them
-- **Automated formatting** — Citations, cross-references, all handled
-
-## How It Works
+Your collaborators do not need to install anything or change how they work. They keep using Word. You handle the conversion on your end. The result is proper version history, equations that never break, figures that stay linked rather than embedded, and automated citation formatting.
 
 ```
-Your text files  ───►  docrev  ───►  Word/PDF for collaborators
-      │                                      │
-      │                                      ▼
-      │                              They add comments
-      │                                      │
-      │                                      ▼
-      └──────────────  docrev  ◄────  They send it back
-                    (imports their feedback)
+Markdown files  -->  docrev  -->  Word/PDF
+      ^                              |
+      |                              v
+      +---- docrev <---- reviewer feedback
 ```
 
-You always work in plain text. Word is just the delivery format.
-
----
-
-## Quick Start
-
-### Install
+## Install
 
 ```bash
 npm install -g docrev
-brew install pandoc    # Required for Word/PDF generation
+brew install pandoc
 ```
 
-### Start a New Paper
+## Start a Project
 
+From scratch:
 ```bash
 rev new my-paper
 cd my-paper
 ```
 
-This creates:
-```
-my-paper/
-├── introduction.md    ← Write your intro here
-├── methods.md         ← Your methods
-├── results.md         ← Your results
-├── discussion.md      ← Your discussion
-├── references.bib     ← Your citations
-└── rev.yaml           ← Paper title, authors
-```
-
-### Or Import from Existing Word Document
-
+From existing Word document:
 ```bash
-rev import my-manuscript.docx
+rev import manuscript.docx
 ```
 
-docrev extracts:
-- Text → Markdown files
-- Comments → Preserved with author names
-- Equations → Converted to LaTeX
-- Images → Saved to figures/
-
----
-
-## Writing in Markdown
-
-Markdown is just text with simple formatting. If you can write an email, you can write Markdown.
+Project structure:
+```
+my-paper/
+├── introduction.md
+├── methods.md
+├── results.md
+├── discussion.md
+├── references.bib
+└── rev.yaml
+```
 
-### Basic Formatting
+## Markdown Basics
 
 ```markdown
-# This is a Heading
+# Heading
 
-This is a paragraph. **Bold text** and *italic text*.
+Paragraph text. **Bold** and *italic*.
 
 - Bullet point
-- Another bullet
+- Another point
 
-1. Numbered list
+1. Numbered item
 2. Second item
 ```
 
 ### Citations
 
-In your `.bib` file:
+references.bib:
 ```bibtex
 @article{Smith2020,
   author = {Smith, Jane},
-  title = {My Paper Title},
+  title = {Paper Title},
   journal = {Nature},
   year = {2020}
 }
 ```
 
-In your text:
+In text:
 ```markdown
-Previous studies have shown this effect [@Smith2020].
-Multiple citations work too [@Smith2020; @Jones2021].
+Previous studies [@Smith2020] demonstrated this.
 ```
 
-→ Becomes: "Previous studies have shown this effect (Smith 2020)."
+Output: "Previous studies (Smith 2020) demonstrated this."
 
 ### Equations
 
-Inline: `$E = mc^2$` → E = mc²
+Inline: `$E = mc^2$`
 
-Display equation:
+Display:
 ```markdown
 $$
 \hat{p} = \frac{\sum_d w_d p_d}{\sum_d w_d}
@@ -137,123 +97,72 @@ $$
 ### Figures
 
 ```markdown
-![Map of study sites across Europe](figures/map.png){#fig:map}
+![Study site locations](figures/map.png){#fig:map}
 
-As shown in @fig:map, our study sites span 12 countries.
+Results shown in @fig:map indicate regional variation.
 ```
 
-→ In Word: "As shown in Figure 1, our study sites..."
+Output: "Results shown in Figure 1 indicate regional variation."
 
-The figure number updates automatically if you reorder figures.
+Figure numbers update automatically when reordered.
 
----
-
-## Build Your Document
-
-```bash
-rev build docx    # Generate Word document
-rev build pdf     # Generate PDF
-rev build --dual  # Both clean + with-comments versions
-```
-
-### Preview While Writing
+## Build
 
 ```bash
-rev watch docx    # Auto-rebuilds when you save
+rev build docx          # Word document
+rev build pdf           # PDF
+rev build --dual        # Clean + comments versions
+rev watch docx          # Auto-rebuild on save
 ```
 
----
-
 ## Handle Reviewer Feedback
 
-### 1. Receive Reviewed Document
-
-Your supervisor sends back `manuscript_reviewed.docx` with comments and track changes.
-
+Import reviewed document:
 ```bash
-rev sections manuscript_reviewed.docx
+rev sections reviewed.docx
 ```
 
-This imports their changes into your Markdown files.
-
-### 2. See Their Comments
-
+View comments:
 ```bash
 rev comments methods.md
 ```
 
-Output:
-```
-#1 [Dr. Smith] line 45
-   "Please clarify the sampling methodology"
-
-#2 [Dr. Smith] line 78
-   "Add a citation here"
-```
-
-### 3. Reply to Comments
-
+Reply to comment:
 ```bash
-rev config user "Your Name"    # Set your name (once)
-rev reply methods.md -n 1 -m "Added detail about random sampling in paragraph 2"
+rev config user "Your Name"
+rev reply methods.md -n 1 -m "Clarified sampling methodology"
 ```
 
-### 4. Rebuild and Send Back
-
+Rebuild with threaded comments:
 ```bash
 rev build --dual
 ```
 
-Creates:
-- `paper.docx` — Clean version
-- `paper_comments.docx` — With threaded comment conversations
-
-Your reply appears under their comment, just like a conversation in Word.
-
----
-
-## Why Separate Files?
+Output:
+- `paper.docx` (clean)
+- `paper_comments.docx` (with comment threads)
 
-Instead of one giant document, docrev uses separate files for each section:
+## Commands
 
-| File | Content |
+| Task | Command |
 |------|---------|
-| `introduction.md` | Background, aims, hypotheses |
-| `methods.md` | Study design, analysis |
-| `results.md` | Findings |
-| `discussion.md` | Interpretation |
-
-**Benefits:**
-- Easier to navigate
-- Work on one section without scrolling
-- Git shows changes per section
-- Collaborators can review specific parts
-
----
-
-## Commands Reference
-
-| What you want to do | Command |
-|---------------------|---------|
-| Create new paper | `rev new my-paper` |
-| Import from Word | `rev import manuscript.docx` |
-| Build Word doc | `rev build docx` |
+| New project | `rev new my-paper` |
+| Import Word | `rev import manuscript.docx` |
+| Build Word | `rev build docx` |
 | Build PDF | `rev build pdf` |
-| Import reviewer feedback | `rev sections reviewed.docx` |
-| See all comments | `rev comments methods.md` |
-| Reply to comment #1 | `rev reply methods.md -n 1 -m "Fixed"` |
-| Check word count | `rev word-count` |
+| Import feedback | `rev sections reviewed.docx` |
+| View comments | `rev comments methods.md` |
+| Reply to comment | `rev reply methods.md -n 1 -m "text"` |
+| Word count | `rev word-count` |
 | Validate DOIs | `rev doi check` |
-| Check before submission | `rev check` |
+| Pre-submit check | `rev check` |
 
-See [full documentation](docs/commands.md) for all commands.
-
----
+Full reference: [docs/commands.md](docs/commands.md)
 
 ## Requirements
 
-- **Node.js 18+** — [Download](https://nodejs.org/)
-- **Pandoc** — Converts Markdown to Word/PDF
+- Node.js 18+
+- Pandoc
 
 ```bash
 # macOS
@@ -266,27 +175,6 @@ winget install JohnMacFarlane.Pandoc
 sudo apt install pandoc
 ```
 
----
-
-## FAQ
-
-**Q: Do my collaborators need to install docrev?**
-No. They keep using Word normally. You handle the conversion.
-
-**Q: Can I use my existing Word document?**
-Yes. `rev import manuscript.docx` converts it to Markdown.
-
-**Q: What about my bibliography?**
-Use a `.bib` file (export from Zotero/Mendeley/EndNote). Citations are handled automatically.
-
-**Q: Will equations look right in Word?**
-Yes. LaTeX equations are converted to native Word equations.
-
-**Q: What if I make a mistake?**
-Plain text + Git means you can always go back. Run `rev backup` before big changes.
-
----
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docrev",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Academic paper revision workflow: Word ↔ Markdown round-trips, DOI validation, reviewer comments",
   "type": "module",
   "types": "types/index.d.ts",