docrev 0.6.13 → 0.7.7

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

@@ -6,180 +6,213 @@
 [![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)
 
-A CLI for writing scientific papers in Markdown while collaborating with Word users.
+A CLI for writing documents in Markdown while collaborating with Word users.
 
-You write in Markdown under version control. Your collaborators use Word. docrev converts between the two, preserving track changes, comments, equations, and cross-references.
+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.
 
-## Install
+## The Problem
 
-```bash
-npm install -g docrev
-brew install pandoc
+You've been here before:
+
+```
+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
 ```
 
-Pandoc is required for document conversion. On Windows use `winget install JohnMacFarlane.Pandoc`, on Linux use `apt install pandoc`.
+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.
 
-## Getting Started
+**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.
 
-### Starting from a Word Document
+## Highlights
 
-If you have an existing manuscript in Word:
+- **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
-rev import manuscript.docx
+npm install -g docrev
 ```
 
-This converts your document to markdown, splitting it into sections:
+Requires [Node.js](https://nodejs.org) 18+, [Pandoc](https://pandoc.org) 2.11+, and [LaTeX](#installing-dependencies) for PDF output.
 
-```
-my-paper/
-├── introduction.md
-├── methods.md
-├── results.md
-├── discussion.md
-├── references.bib
-└── rev.yaml
-```
+## Quick Example
 
-Track changes and comments from the Word document are preserved as annotations in the markdown files (see below).
+Write in Markdown with citations and cross-references:
 
-### Starting from Scratch
+```markdown
+Climate change poses significant challenges [@IPCC2021]. As shown in
+@fig:temperature, global temperatures have risen steadily.
 
-To start a new paper in markdown:
+![Temperature anomalies](figures/temperature.png){#fig:temperature}
 
-```bash
-rev new my-paper
-cd my-paper
+The relationship follows $\Delta T = \lambda \cdot \Delta F$ (@eq:forcing).
 ```
 
-This creates the same project structure with empty section files. Write your paper in the markdown files, then build Word documents to share with collaborators.
+Build and share:
 
-## The Revision Cycle
-
-### 1. Build and Share
+```bash
+rev build docx    # → paper.docx (for collaborators)
+rev build pdf     # → paper.pdf  (for journals)
+```
 
-Generate a Word document from your markdown:
+When collaborators return the Word doc with track changes:
 
 ```bash
-rev build docx
+rev sync reviewed.docx    # their comments → your markdown
+```
+
+## How It Works
+
+```
+┌─────────────┐     rev build docx      ┌─────────────┐
+│             │ ───────────────────────→│             │
+│  Markdown   │                         │    Word     │  → collaborators
+│   (you)     │     rev build pdf       │   / PDF     │  → journals
+│             │ ───────────────────────→│             │
+└─────────────┘                         └─────────────┘
+       ↑                                       │
+       │              rev sync                 │
+       └───────────────────────────────────────┘
+              their feedback → your files
 ```
 
-Send this to your collaborators. They review it in Word, adding comments and track changes as usual.
+You stay in Markdown. Collaborators use Word. Journals get PDF. Everyone works in their preferred format.
 
-### 2. Import Feedback
+## The CLI Review Cycle
 
-When collaborators return the reviewed document, import their feedback:
+When reviewers send back a Word document with track changes and comments:
 
 ```bash
-rev sections reviewed.docx
+rev sync reviewed.docx            # import feedback into markdown
 ```
 
-This updates your markdown files with their comments and track changes, converted to inline annotations.
+Track changes appear inline - accept or reject by editing:
 
-### 3. Review Track Changes
+```markdown
+The sample size was {--100--}{++150++} participants.
+```
 
-Track changes appear as inline annotations in your markdown:
+Handle comments without opening Word:
 
-```markdown
-The sample size was {--100--}{++150++} individuals.
-We collected data {~~monthly~>weekly~~} from each site.
+```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
 ```
 
-- `{++text++}` — inserted text
-- `{--text--}` — deleted text
-- `{~~old~>new~~}` — substitution
+Reviewers who annotate PDFs instead of Word? That works too:
 
-To accept a change, keep the new text and delete the markup. To reject it, keep the old text. When you're done, the file is clean markdown.
+```bash
+rev sync annotated.pdf            # extract PDF comments
+rev pdf-comments annotated.pdf --append methods.md
+```
 
-### 4. Respond to Comments
+Your entire revision cycle stays in the terminal. `final_v3_REAL_final.docx` is over.
 
-Comments appear inline in your markdown:
+## Getting Started
 
-```markdown
-We used a random sampling approach.
-{>>Reviewer 2: Please clarify the sampling method.<<}
-```
+### Starting a New Document
 
-List all comments in a file:
+Create a new project:
 
 ```bash
-rev comments methods.md
+rev new my-report
+cd my-report
 ```
 
-Reply from the command line:
+You'll be prompted to enter your section names, or press Enter to use the default structure. You can also specify sections directly:
 
 ```bash
-rev config user "Your Name"    # one-time setup
-rev reply methods.md -n 1 -m "Added clarification in paragraph 2"
+rev new my-report -s intro,methods,results,discussion
 ```
 
-Your reply threads beneath the original:
+Or set your preferred default sections once:
 
-```markdown
-We used a random sampling approach.
-{>>Reviewer 2: Please clarify the sampling method.<<}
-{>>Your Name: Added clarification in paragraph 2.<<}
+```bash
+rev config sections "intro,methods,results,discussion"
 ```
 
-Mark comments as resolved:
+This creates a folder with your chosen sections:
 
-```bash
-rev resolve methods.md -n 1
+```
+my-report/
+├── intro.md
+├── methods.md
+├── results.md
+├── discussion.md
+├── references.bib
+└── rev.yaml
 ```
 
-### 5. Rebuild with Comment Threads
-
-Generate both a clean version and one showing the comment threads:
+Write your content in the markdown files. When ready to share:
 
 ```bash
-rev build --dual
+rev build docx
 ```
 
-This produces:
-- `paper.docx` — clean, for submission
-- `paper_comments.docx` — includes comment threads as Word comments
+This produces `my-report.docx` with citations resolved, equations rendered, and cross-references numbered. Use `rev build pdf` for PDF output instead.
 
-Your collaborators see the full conversation in the comments pane.
+### Starting from an Existing Word Document
 
-### 6. Repeat
+If you have a Word document to convert:
 
-Send the updated Word document. Import new feedback with `rev sections`. Continue until done.
+```bash
+rev import manuscript.docx
+```
 
-## Before Submission
+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.
 
-### Validate Your Bibliography
+### Configuration
 
-Check that DOIs in your bibliography resolve correctly:
+Layout is controlled in `rev.yaml`:
 
-```bash
-rev doi check references.bib
+```yaml
+title: "My Document"
+output:
+  docx:
+    reference-doc: template.docx   # your Word template
+  pdf:
+    documentclass: article
+    fontsize: 12pt
 ```
 
-Find DOIs for entries missing them:
+Configure your name for comment replies:
 
 ```bash
-rev doi lookup references.bib
+rev config user "Your Name"
 ```
 
-Add a citation directly from a DOI:
+## Annotation Syntax
 
-```bash
-rev doi add 10.1038/s41586-020-2649-2
+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
 ```
 
-### Run Pre-Submission Checks
+## Writing Tips
 
-Check for broken references, missing citations, and common issues:
+Track word count changes between versions:
 
 ```bash
-rev check
+rev diff                    # compare against last commit
+#  methods.md     +142 words  -38 words
+#  results.md      +89 words  -12 words
 ```
 
-## Writing in Markdown
-
-### Citations
-
-Add references to `references.bib`:
+Add references to `references.bib` (BibTeX format):
 
 ```bibtex
 @article{Smith2020,
@@ -191,61 +224,86 @@ Add references to `references.bib`:
 }
 ```
 
-Cite in text:
+Cite with `[@Smith2020]` or `[@Smith2020; @Jones2021]` for multiple sources.
 
-```markdown
-Previous work [@Smith2020] established this relationship.
-Multiple sources support this [@Smith2020; @Jones2021].
-```
+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".
 
-### Equations
+## Command Reference
 
-Inline equations use single dollar signs: `$E = mc^2$`
+| Task | Command |
+|------|---------|
+| 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` |
+| 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` |
 
-Display equations use double dollar signs:
+Run `rev help` to see all commands, or `rev help <command>` for details on a specific command.
 
-```markdown
-$$
-\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i
-$$
-```
+Full command reference: [docs/commands.md](docs/commands.md)
 
-### Figures and Cross-References
+## Claude Code Skill
 
-```markdown
-![Study site locations](figures/map.png){#fig:map}
+Install the docrev skill for [Claude Code](https://claude.ai/code):
 
-Results are shown in @fig:map.
+```bash
+rev install-cli-skill      # install to ~/.claude/skills/docrev
+rev uninstall-cli-skill    # remove
 ```
 
-The reference `@fig:map` becomes "Figure 1" in the output. Numbers update automatically when figures are reordered.
+Once installed, Claude understands docrev commands and can help navigate comments, draft replies, and manage your revision cycle.
 
-Tables and equations work the same way with `@tbl:label` and `@eq:label`.
+## Installing Dependencies
 
-## Useful Commands
+### Pandoc
 
-| Task | Command |
-|------|---------|
-| Start new project | `rev new my-paper` |
-| Import Word document | `rev import manuscript.docx` |
-| Import feedback | `rev sections reviewed.docx` |
-| List comments | `rev comments methods.md` |
-| Reply to comment | `rev reply methods.md -n 1 -m "response"` |
-| Build Word | `rev build docx` |
-| Build PDF | `rev build pdf` |
-| Build both clean and annotated | `rev build --dual` |
-| Check DOIs | `rev doi check references.bib` |
-| Find missing DOIs | `rev doi lookup references.bib` |
-| Word count | `rev word-count` |
-| Pre-submission check | `rev check` |
-| Watch for changes | `rev watch docx` |
+[Pandoc](https://pandoc.org) handles document conversion.
 
-Full command reference: [docs/commands.md](docs/commands.md)
+| 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)
 
-## Requirements
+| 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` |
 
-- Node.js 18+
-- Pandoc 2.11+
+Alternatively, [TinyTeX](https://yihui.org/tinytex/) provides a minimal distribution that downloads packages on demand.
 
 ## License