docrev 0.6.7 → 0.7.6

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to docrev will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.1] - 2025-01-02
+
+### Added
+- Writing Markdown guide in docs (tables, equations, citations, cross-refs)
+- Grid table syntax documentation for merged cells
+
+### Changed
+- README restructured for better scannability (490 → 290 lines)
+- Install section moved up for faster onboarding
+- Added Highlights section with quick feature overview
+- Condensed overlapping sections
+
+## [0.7.0] - 2025-01-02
+
+### Added
+- API rate limiting with exponential backoff for Crossref/DataCite/doi.org APIs
+- Windows support in CI matrix
+- Architecture documentation for contributors (`ARCHITECTURE.md`)
+- Exclusion patterns for cross-reference false positives (e.g., "Table of Contents")
+- Timeout support for PDF extraction (30s default)
+
+### Changed
+- Consolidated YAML dependencies (removed `js-yaml`, using `yaml` package only)
+- Improved annotation false positive detection (code blocks, URLs, LaTeX patterns)
+- Enhanced error messages for Word import and PDF extraction
+- Updated User-Agent strings for API requests
+- Improved README with problem statement and quick example
+
+### Fixed
+- CI lint step now checks all command files separately
+- Windows temp directory paths in tests
+
 ## [0.3.2] - 2024-12-29
 
 ### Added

package/README.md

@@ -1,174 +1,309 @@
 # docrev
 
 [![npm](https://img.shields.io/npm/v/docrev)](https://www.npmjs.com/package/docrev)
+[![npm downloads](https://img.shields.io/npm/dm/docrev)](https://www.npmjs.com/package/docrev)
+[![node](https://img.shields.io/node/v/docrev)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/gcol33/docrev/actions/workflows/ci.yml/badge.svg)](https://github.com/gcol33/docrev/actions/workflows/ci.yml)
 
-Write scientific papers in Markdown. Generate Word documents for collaborators. Import their feedback. Repeat.
+A CLI for writing documents in Markdown while collaborating with Word users.
+
+You write in Markdown under version control. Your collaborators use Word (or PDF). docrev converts between the two, preserving track changes, comments, equations, and cross-references.
+
+## The Problem
+
+You've been here before:
 
 ```
-Markdown  ──►  docrev  ──►  Word/PDF  ──►  Collaborators
-    ▲                                           │
-    └───────────  docrev  ◄─────────────────────┘
-                (import feedback)
+manuscript_v1.docx
+manuscript_v2_john_comments.docx
+manuscript_v2_jane_comments.docx
+manuscript_v3_merged_final.docx
+manuscript_v3_merged_final_REAL.docx
+manuscript_v3_merged_final_REAL_submitted.docx
 ```
 
-Scientific papers go through many revision cycles with collaborators and reviewers. Track changes become unreadable, versions multiply, equations break when copying, figures get embedded at wrong resolutions. docrev keeps your source in plain Markdown under version control while generating Word documents for the review cycle. Your collaborators keep using Word as usual. You handle conversion on your end.
+Three reviewers send back three Word files. You manually compare changes, copy-paste between documents, lose track of who said what. A week later, you can't remember which version has the figure updates.
+
+**docrev fixes this.** You write in plain text. Reviewers use Word. Their feedback flows back into your files automatically. One source of truth, full version history, no more file chaos.
+
+## Highlights
+
+- **Markdown → Word/PDF** with citations, figures, equations, cross-references
+- **Round-trip sync**: import Word track changes and comments back to Markdown
+- **CLI review workflow**: reply to comments, accept/reject changes from terminal
+- **DOI tools**: validate, lookup, and auto-add references from DOIs
+- **21 journal styles**: Nature, Science, PNAS, and more
+- **Version control friendly**: plain text source, full git history
 
 ## Install
 
 ```bash
 npm install -g docrev
-brew install pandoc
 ```
 
-## Start a Project
+Requires [Node.js](https://nodejs.org) 18+, [Pandoc](https://pandoc.org) 2.11+, and [LaTeX](#installing-dependencies) for PDF output.
+
+## Quick Example
+
+Write in Markdown with citations and cross-references:
+
+```markdown
+Climate change poses significant challenges [@IPCC2021]. As shown in
+@fig:temperature, global temperatures have risen steadily.
+
+![Temperature anomalies](figures/temperature.png){#fig:temperature}
+
+The relationship follows $\Delta T = \lambda \cdot \Delta F$ (@eq:forcing).
+```
+
+Build and share:
 
-From scratch:
 ```bash
-rev new my-paper
-cd my-paper
+rev build docx    # → paper.docx (for collaborators)
+rev build pdf     # → paper.pdf  (for journals)
 ```
 
-From existing Word document:
+When collaborators return the Word doc with track changes:
+
 ```bash
-rev import manuscript.docx
+rev sync reviewed.docx    # their comments → your markdown
 ```
 
-Project structure:
+## How It Works
+
 ```
-my-paper/
-├── introduction.md
-├── methods.md
-├── results.md
-├── discussion.md
-├── references.bib
-└── rev.yaml
+┌─────────────┐     rev build docx      ┌─────────────┐
+│             │ ───────────────────────→│             │
+│  Markdown   │                         │    Word     │  → collaborators
+│   (you)     │     rev build pdf       │   / PDF     │  → journals
+│             │ ───────────────────────→│             │
+└─────────────┘                         └─────────────┘
+       ↑                                       │
+       │              rev sync                 │
+       └───────────────────────────────────────┘
+              their feedback → your files
 ```
 
-## Markdown Basics
+You stay in Markdown. Collaborators use Word. Journals get PDF. Everyone works in their preferred format.
 
-```markdown
-# Heading
+## The CLI Review Cycle
+
+When reviewers send back a Word document with track changes and comments:
 
-Paragraph text. **Bold** and *italic*.
+```bash
+rev sync reviewed.docx            # import feedback into markdown
+```
 
-- Bullet point
-- Another point
+Track changes appear inline - accept or reject by editing:
 
-1. Numbered item
-2. Second item
+```markdown
+The sample size was {--100--}{++150++} participants.
 ```
 
-### Citations
+Handle comments without opening Word:
 
-references.bib:
-```bibtex
-@article{Smith2020,
-  author = {Smith, Jane},
-  title = {Paper Title},
-  journal = {Nature},
-  year = {2020}
-}
+```bash
+rev comments                      # list all comments
+rev reply methods.md -n 1 -m "Added clarification"
+rev resolve methods.md -n 1       # mark as resolved
+rev build docx --dual             # clean + annotated versions
 ```
 
-In text:
-```markdown
-Previous studies [@Smith2020] demonstrated this.
+Reviewers who annotate PDFs instead of Word? That works too:
+
+```bash
+rev sync annotated.pdf            # extract PDF comments
+rev pdf-comments annotated.pdf --append methods.md
 ```
 
-Output: "Previous studies (Smith 2020) demonstrated this."
+Your entire revision cycle stays in the terminal. `final_v3_REAL_final.docx` is over.
 
-### Equations
+## Getting Started
 
-Inline: `$E = mc^2$`
+### Starting a New Document
 
-Display:
-```markdown
-$$
-\hat{p} = \frac{\sum_d w_d p_d}{\sum_d w_d}
-$$
+Create a new project:
+
+```bash
+rev new my-report
+cd my-report
 ```
 
-### Figures
+You'll be prompted to enter your section names, or press Enter to use the default structure. You can also specify sections directly:
 
-```markdown
-![Study site locations](figures/map.png){#fig:map}
+```bash
+rev new my-report -s intro,methods,results,discussion
+```
 
-Results shown in @fig:map indicate regional variation.
+Or set your preferred default sections once:
+
+```bash
+rev config sections "intro,methods,results,discussion"
 ```
 
-Output: "Results shown in Figure 1 indicate regional variation."
+This creates a folder with your chosen sections:
 
-Figure numbers update automatically when reordered.
+```
+my-report/
+├── intro.md
+├── methods.md
+├── results.md
+├── discussion.md
+├── references.bib
+└── rev.yaml
+```
 
-## Build
+Write your content in the markdown files. When ready to share:
 
 ```bash
-rev build docx          # Word document
-rev build pdf           # PDF
-rev build --dual        # Clean + comments versions
-rev watch docx          # Auto-rebuild on save
+rev build docx
 ```
 
-## Handle Reviewer Feedback
+This produces `my-report.docx` with citations resolved, equations rendered, and cross-references numbered. Use `rev build pdf` for PDF output instead.
+
+### Starting from an Existing Word Document
+
+If you have a Word document to convert:
 
-Import reviewed document:
 ```bash
-rev sections reviewed.docx
+rev import manuscript.docx
 ```
 
-View comments:
-```bash
-rev comments methods.md
+This creates a project folder and splits the document into section files. Images are extracted to `figures/`, equations are converted to LaTeX, and track changes/comments are preserved as markdown annotations.
+
+### Configuration
+
+Layout is controlled in `rev.yaml`:
+
+```yaml
+title: "My Document"
+output:
+  docx:
+    reference-doc: template.docx   # your Word template
+  pdf:
+    documentclass: article
+    fontsize: 12pt
 ```
 
-Reply to comment:
+Configure your name for comment replies:
+
 ```bash
 rev config user "Your Name"
-rev reply methods.md -n 1 -m "Clarified sampling methodology"
 ```
 
-Rebuild with threaded comments:
+## Annotation Syntax
+
+Track changes from Word appear as [CriticMarkup](http://criticmarkup.com/):
+
+```markdown
+The sample size was {--100--}{++150++} participants.   # deletion + insertion
+Data was collected {~~monthly~>weekly~~}.              # substitution
+{>>Reviewer 2: Please clarify.<<}                      # comment
+```
+
+## Writing Tips
+
+Track word count changes between versions:
+
 ```bash
-rev build --dual
+rev diff                    # compare against last commit
+#  methods.md     +142 words  -38 words
+#  results.md      +89 words  -12 words
+```
+
+Add references to `references.bib` (BibTeX format):
+
+```bibtex
+@article{Smith2020,
+  author = {Smith, Jane},
+  title = {Paper Title},
+  journal = {Nature},
+  year = {2020},
+  doi = {10.1038/example}
+}
 ```
 
-Output:
-- `paper.docx` (clean)
-- `paper_comments.docx` (with comment threads)
+Cite with `[@Smith2020]` or `[@Smith2020; @Jones2021]` for multiple sources.
 
-## Commands
+Equations use LaTeX: inline `$E = mc^2$` or display `$$\sum_{i=1}^{n} x_i$$`.
+
+Cross-references: `@fig:label`, `@tbl:label`, `@eq:label` → "Figure 1", "Table 2", "Equation 3".
+
+## Command Reference
 
 | Task | Command |
 |------|---------|
-| New project | `rev new my-paper` |
-| Import Word | `rev import manuscript.docx` |
-| Build Word | `rev build docx` |
+| Create project | `rev new my-project` |
+| Create LaTeX project | `rev new my-project --template latex` |
+| Import Word document | `rev import manuscript.docx` |
+| Extract Word equations | `rev equations from-word doc.docx` |
+| Build DOCX | `rev build docx` |
 | Build PDF | `rev build pdf` |
-| 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` |
-| Pre-submit check | `rev check` |
+| Build clean + annotated | `rev build docx --dual` |
+| Sync Word feedback | `rev sync reviewed.docx` |
+| Sync PDF comments | `rev sync annotated.pdf` |
+| Extract PDF comments | `rev pdf-comments annotated.pdf` |
+| Extract with highlighted text | `rev pdf-comments file.pdf --with-text` |
+| Project status | `rev status` |
+| Next pending comment | `rev next` |
+| List pending comments | `rev todo` |
+| Filter by author | `rev comments file.md --author "Reviewer 2"` |
+| Accept all changes | `rev accept file.md -a` |
+| Reject change | `rev reject file.md -n 1` |
+| Reply to comment | `rev reply file.md -n 1 -m "response"` |
+| Reply to all pending | `rev reply file.md --all -m "Addressed"` |
+| Resolve comment | `rev resolve file.md -n 1` |
+| Show contributors | `rev contributors` |
+| Lookup ORCID | `rev orcid 0000-0002-1825-0097` |
+| Archive reviewer files | `rev archive` |
+| Check DOIs | `rev doi check references.bib` |
+| Find missing DOIs | `rev doi lookup references.bib` |
+| Add citation from DOI | `rev doi add 10.1038/example` |
+| Word count | `rev wc` |
+| Pre-submission check | `rev check` |
+| Check for updates | `rev upgrade --check` |
+
+Run `rev help` to see all commands, or `rev help <command>` for details on a specific command.
+
+Full command reference: [docs/commands.md](docs/commands.md)
+
+## Claude Code Skill
+
+Install the docrev skill for [Claude Code](https://claude.ai/code):
 
-Full reference: [docs/commands.md](docs/commands.md)
+```bash
+rev install-cli-skill      # install to ~/.claude/skills/docrev
+rev uninstall-cli-skill    # remove
+```
 
-## Requirements
+Once installed, Claude understands docrev commands and can help navigate comments, draft replies, and manage your revision cycle.
 
-- Node.js 18+
-- Pandoc
+## Installing Dependencies
 
-```bash
-# macOS
-brew install pandoc
+### Pandoc
 
-# Windows
-winget install JohnMacFarlane.Pandoc
+[Pandoc](https://pandoc.org) handles document conversion.
 
-# Linux
-sudo apt install pandoc
-```
+| Platform | Command |
+|----------|---------|
+| macOS | `brew install pandoc` |
+| Windows | `winget install JohnMacFarlane.Pandoc` |
+| Debian/Ubuntu | `sudo apt install pandoc` |
+| Fedora | `sudo dnf install pandoc` |
+
+Other platforms: [pandoc.org/installing](https://pandoc.org/installing.html)
+
+### LaTeX (for PDF output)
+
+| Platform | Command |
+|----------|---------|
+| macOS | `brew install --cask mactex` |
+| Windows | `winget install MiKTeX.MiKTeX` |
+| Debian/Ubuntu | `sudo apt install texlive-full` |
+| Fedora | `sudo dnf install texlive-scheme-full` |
+
+Alternatively, [TinyTeX](https://yihui.org/tinytex/) provides a minimal distribution that downloads packages on demand.
 
 ## License