Gcol33 Docrev Skill

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"
docx:
  reference: 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
rev sync reviewed.docx --comments-only  # Insert comments only; never modify prose
rev verify-anchors reviewed.docx    # Report which anchors still match current prose

Use --comments-only when the markdown has been revised between sending the docx out and receiving it back. Without the flag, track changes from a stale draft would clobber newer edits. With it, only comments are imported, placed at fuzzy-matched anchors against the current prose. Run rev verify-anchors first to see which comments will land cleanly and which need manual placement.

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
rev build docx --show-changes         # Single DOCX with visible track changes
rev build docx --dual --show-changes  # One DOCX: tracked changes + threaded comments

--dual produces:

• output/<title>.docx — clean, for submission
• output/<title>_comments.docx — comment threads as Word comments

--show-changes produces a single audit DOCX (<title>-changes.docx) where every accepted/rejected revision is rendered as a visible Word track change. Useful when a co-author wants to see what changed since the last shared version.

--dual --show-changes combines both into one <title>-changes.docx: my {++..++}/{--..--} edits as tracked changes and the reviewer's {>>..<<} comments with my threaded replies. This is the file a supervisor opens, reviews next to each other, and hands back. Add --reference <docx> to realign comment anchors against a reviewer's copy first.

Outputs land in output/ by default; set outputDir: null in rev.yaml to keep them alongside paper.md (legacy layout). The basename is derived from title: unless overridden — set output: { docx: foo.docx, pdf: foo.pdf } in rev.yaml or pass -o, --output <path> on the CLI. See REFERENCE.md → "Choosing output filenames".

For pandoc flags rev doesn't surface directly (Lua filters, custom variables, templates), use --pandoc-arg (repeatable) or pandoc-args: in rev.yaml (both top-level and per-format). Run with --verbose to see the exact pandoc invocation. See REFERENCE.md → "Passing custom pandoc args" for details.

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 22 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

Insert a figure with the format-portable syntax (renders in both PDF and Word):

![Caption text.](figures/foo.pdf){#fig:foo width=80%}

Raw \begin{figure}...\end{figure} LaTeX blocks are PDF-only. For docx builds, rev auto-translates the common shape (single \includegraphics with optional \caption{...} and \label{...}) to the markdown form above so figures still render. Exotic blocks (\subfloat, \rotatebox, multiple \includegraphics) are left alone and warned about — convert them by hand or supply a custom Lua filter via --pandoc-arg. Opt out of auto-translate with docx.translateRawFigures: false in rev.yaml.

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.md           # Combined sections (auto-generated)
└── output/            # Built artefacts
    ├── my-document.docx
    └── my-document.pdf

Set outputDir: null in rev.yaml to write outputs alongside paper.md instead.

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.

Source: gcol33/docrev — distributed by TomeVault.