Docrev

---
name: docrev
description: "Document revision workflow tool (CLI: `rev`). Use when working with Word documents containing reviewer comments, importing track changes to markdown, replying to reviewer comments, building PDF/DOCX outputs, generating response letters, validating citations/DOIs, or any document revision task."
---

# docrev - Document Revision Tool

`rev` is a CLI tool for document workflows with Word ↔ Markdown round-trips.

Works for any document that goes through Word-based review: scientific papers, contracts, reports, proposals, manuals.

## Content and Layout, Separated

In Markdown, you focus on content. Write text, add citations with `[@key]`, insert equations with `$...$`, reference figures with `@fig:label`. No fiddling with fonts or styles.

Layout is controlled in `rev.yaml`:

```yaml
title: "My Document"
output:
  docx:
    reference-doc: template.docx
```

Change the template, rebuild, and every document gets the new formatting.

## Core Workflow

### 1. Create or import a project

```bash
rev new my-document          # Start from scratch
rev import manuscript.docx   # Start from existing Word doc
```

### 2. Build and share

```bash
rev build docx               # Generate Word document
```

Send to reviewers. They add comments and track changes in Word.

### 3. Import feedback

```bash
rev sync reviewed.docx       # Updates markdown with annotations
rev sync                     # Auto-detect most recent .docx
```

### 4. View and address comments

```bash
rev status                   # Project overview
rev todo                     # List all pending comments
rev next                     # Show next pending comment
rev comments methods.md      # List all comments with context
```

### 5. Reply to reviewer comments

**Always use the non-interactive reply mode:**

```bash
rev reply methods.md -n 1 -m "Added clarification about sampling methodology"
rev reply results.md -n 3 -m "Updated figure to include 95% CI"
```

Replies appear as: `{>>Reviewer: Original<<} {>>User: Reply<<}`

### 6. Resolve addressed comments

```bash
rev resolve methods.md -n 1  # Mark comment #1 as resolved
```

### 7. Rebuild with comment threads

```bash
rev build docx --dual        # Produces clean + annotated versions
```

- `paper.docx` — clean, for submission
- `paper_comments.docx` — includes comment threads as Word comments

### 8. Archive reviewer files

```bash
rev archive                  # Move reviewer files to archive/
```

### 9. Generate response letter

```bash
rev response                 # Generate point-by-point response letter
```

## Annotation Syntax (CriticMarkup)

- `{++inserted text++}` - Additions
- `{--deleted text--}` - Deletions
- `{~~old~>new~~}` - Substitutions
- `{>>Author: comment<<}` - Comments
- `{>>Author: comment [RESOLVED]<<}` - Resolved comment

## Quick Commands

| Task | Command |
|------|---------|
| Create project | `rev new my-project` |
| Create LaTeX project | `rev new my-project --template latex` |
| Import Word doc | `rev import manuscript.docx` |
| 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` |
| Append PDF comments | `rev pdf-comments annotated.pdf --append methods.md` |
| Project status | `rev status` |
| Next pending | `rev next` |
| List pending | `rev todo` |
| Filter by author | `rev comments file.md --author "Reviewer 2"` |
| Reply to all pending | `rev reply file.md --all -m "Addressed"` |
| Accept all changes | `rev accept file.md -a` |
| Build Word | `rev build docx` |
| Build PDF | `rev build pdf` |
| Build clean + annotated Word | `rev build docx --dual` |
| Build clean + annotated PDF | `rev build pdf --dual` |
| Show contributors | `rev contributors` |
| Lookup ORCID | `rev orcid 0000-0002-1825-0097` |
| Archive reviewer files | `rev archive` |
| Word count per section | `rev word-count` |
| Project dashboard | `rev stats` |
| Search all sections | `rev search "query"` |
| Pre-submission check | `rev check` |
| Validate citations | `rev citations` |
| Check grammar/style | `rev grammar` |
| Check spelling | `rev spelling` |
| Open PDF preview | `rev preview pdf` |
| Auto-rebuild on changes | `rev watch` |
| Check for updates | `rev upgrade --check` |

## DOI Management

```bash
rev doi check references.bib         # Validate DOIs
rev doi lookup references.bib        # Find missing DOIs
rev doi add 10.1234/example          # Add citation from DOI
```

## Validation

```bash
rev validate --journal nature        # Check journal requirements
rev validate --list                  # List 21 available journal profiles
rev lint                             # Check broken refs, missing citations
```

## Cross-References

Use in markdown files:
- `@fig:label` - Figure reference (becomes "Figure 1" in Word)
- `@tbl:label` - Table reference
- `@eq:label` - Equation reference
- `{#fig:label}` - Anchor for figures

## Template Variables

Available in section files (processed during build):
- `{{date}}` - Current date (YYYY-MM-DD)
- `{{date:MMMM D, YYYY}}` - Custom format
- `{{title}}` - Document title
- `{{author}}` - First author
- `{{word_count}}` - Total word count

## Project Structure

```
my-document/
├── rev.yaml           # Project config
├── introduction.md    # Section files with annotations
├── methods.md
├── results.md
├── discussion.md
├── references.bib     # Bibliography
├── figures/           # Images
└── paper.docx         # Built output
```

## PDF Comment Workflow

For reviewers who annotate PDFs instead of Word documents:

### 1. Extract comments from PDF

```bash
rev pdf-comments annotated.pdf              # Display all comments
rev pdf-comments annotated.pdf --by-author  # Group by reviewer
rev pdf-comments annotated.pdf --json       # Output as JSON
```

### 2. Import into markdown

```bash
rev sync annotated.pdf                      # Auto-import to sections
rev pdf-comments annotated.pdf --append methods.md  # Append to specific file
```

### 3. Build PDF with margin notes

```bash
rev build pdf --dual
```

Produces:
- `paper.pdf` — clean version for submission
- `paper_comments.pdf` — comments rendered as LaTeX margin notes

**Supported PDF Annotations:**
- Sticky notes, text boxes, highlights, underlines, strikethrough, squiggly

## When Helping Users

1. **Setup**: Ensure `rev config user "Name"` is set for replies
2. **Sync phase**: Run `rev sync` to get feedback (works with both Word and PDF)
3. **Review phase**: Use `rev todo` and `rev next` to navigate comments, `rev reply` to respond
4. **Accept phase**: Use `rev accept -a` or `rev review` to handle track changes
5. **Build phase**: Run `rev build docx --dual` or `rev build pdf --dual` for annotated versions
6. **Archive phase**: Run `rev archive` to move reviewer files
7. **Validation phase**: Run `rev check` before submission
8. **Response letter**: Use `rev response` to generate point-by-point responses

## Critical: Ask Questions When Unsure

When addressing reviewer comments or editing documents:

- **Never guess methods or numbers** - If a comment asks for clarification about methodology, sample sizes, statistical parameters, dates, or any quantitative information, ASK the user rather than inventing values
- **Placeholders are acceptable** - Use `[???]` or `[TODO: specify X]` when information is missing rather than fabricating data
- **Search online for references** - When comments request citations, use web search to find appropriate references rather than guessing
- **Clarify ambiguous requests** - If a reviewer comment could be interpreted multiple ways, ask the user which interpretation they prefer
- **Verify existing values** - When editing numbers that already exist in the document, confirm changes with the user if there's any doubt

Example scenarios requiring user input:
- "Add a reference for this claim" → Search online OR ask user for specific citation
- "Clarify the sample size" → Ask user for the correct number
- "Specify the statistical test used" → Ask user which test was actually used
- "Add the date of data collection" → Ask user for the actual date

For complete command reference, see [REFERENCE.md](REFERENCE.md).