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

| 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

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

Setup: Ensure rev config user "Name" is set for replies
Sync phase: Run rev sync to get feedback (works with both Word and PDF)
Review phase: Use rev todo and rev next to navigate comments, rev reply to respond
Accept phase: Use rev accept -a or rev review to handle track changes
Build phase: Run rev build docx --dual or rev build pdf --dual for annotated versions
Archive phase: Run rev archive to move reviewer files
Validation phase: Run rev check before submission
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.