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:

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

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

2. Build and share

rev build docx               # Generate Word document

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

3. Import feedback

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

4. View and address comments

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:

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

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

7. Rebuild with comment threads

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

rev archive                  # Move reviewer files to archive/

9. Generate response letter

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

DOI Management

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

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

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

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

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.