docrev - Document Revision Tool

rev

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]

$...$

@fig:label

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

rev new my-project

rev new my-project --template latex

rev import manuscript.docx

rev sync reviewed.docx

rev sync annotated.pdf

rev pdf-comments annotated.pdf

rev pdf-comments file.pdf --with-text

rev pdf-comments annotated.pdf --append methods.md

rev status

rev next

rev todo

rev comments file.md --author "Reviewer 2"

rev reply file.md --all -m "Addressed"

rev accept file.md -a

rev build docx

rev build pdf

rev build docx --dual

rev build pdf --dual

rev contributors

rev orcid 0000-0002-1825-0097

rev archive

rev word-count

rev stats

rev search "query"

rev check

rev citations

rev grammar

rev spelling

rev preview pdf

rev watch

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

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.