docrev 0.9.13 → 0.9.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/.claude/settings.local.json +9 -9
  2. package/.gitattributes +1 -1
  3. package/CHANGELOG.md +149 -149
  4. package/PLAN-tables-and-postprocess.md +850 -850
  5. package/README.md +391 -391
  6. package/bin/rev.js +11 -11
  7. package/bin/rev.ts +145 -145
  8. package/completions/rev.bash +127 -127
  9. package/completions/rev.ps1 +210 -210
  10. package/completions/rev.zsh +207 -207
  11. package/dev_notes/stress2/build_adversarial.ts +186 -186
  12. package/dev_notes/stress2/drift_matcher.ts +62 -62
  13. package/dev_notes/stress2/probe_anchors.ts +35 -35
  14. package/dev_notes/stress2/project/discussion.before.md +3 -3
  15. package/dev_notes/stress2/project/discussion.md +3 -3
  16. package/dev_notes/stress2/project/methods.before.md +20 -20
  17. package/dev_notes/stress2/project/methods.md +20 -20
  18. package/dev_notes/stress2/project/rev.yaml +5 -5
  19. package/dev_notes/stress2/project/sections.yaml +4 -4
  20. package/dev_notes/stress2/sections.yaml +5 -5
  21. package/dev_notes/stress2/trace_placement.ts +50 -50
  22. package/dev_notes/stresstest_boundaries.ts +27 -27
  23. package/dev_notes/stresstest_drift_apply.ts +43 -43
  24. package/dev_notes/stresstest_drift_compare.ts +43 -43
  25. package/dev_notes/stresstest_drift_v2.ts +54 -54
  26. package/dev_notes/stresstest_inspect.ts +54 -54
  27. package/dev_notes/stresstest_pstyle.ts +55 -55
  28. package/dev_notes/stresstest_section_debug.ts +23 -23
  29. package/dev_notes/stresstest_split.ts +70 -70
  30. package/dev_notes/stresstest_trace.ts +19 -19
  31. package/dev_notes/stresstest_verify_no_overwrite.ts +40 -40
  32. package/dist/lib/build.d.ts +38 -1
  33. package/dist/lib/build.d.ts.map +1 -1
  34. package/dist/lib/build.js +68 -30
  35. package/dist/lib/build.js.map +1 -1
  36. package/dist/lib/commands/build.d.ts.map +1 -1
  37. package/dist/lib/commands/build.js +38 -5
  38. package/dist/lib/commands/build.js.map +1 -1
  39. package/dist/lib/commands/utilities.js +164 -164
  40. package/dist/lib/commands/word-tools.js +8 -8
  41. package/dist/lib/grammar.js +3 -3
  42. package/dist/lib/pdf-comments.js +44 -44
  43. package/dist/lib/plugins.js +57 -57
  44. package/dist/lib/pptx-themes.js +115 -115
  45. package/dist/lib/spelling.js +2 -2
  46. package/dist/lib/templates.js +387 -387
  47. package/dist/lib/themes.js +51 -51
  48. package/eslint.config.js +27 -27
  49. package/lib/anchor-match.ts +276 -276
  50. package/lib/annotations.ts +644 -644
  51. package/lib/build.ts +1300 -1251
  52. package/lib/citations.ts +160 -160
  53. package/lib/commands/build.ts +833 -801
  54. package/lib/commands/citations.ts +515 -515
  55. package/lib/commands/comments.ts +1050 -1050
  56. package/lib/commands/context.ts +174 -174
  57. package/lib/commands/core.ts +309 -309
  58. package/lib/commands/doi.ts +435 -435
  59. package/lib/commands/file-ops.ts +372 -372
  60. package/lib/commands/history.ts +320 -320
  61. package/lib/commands/index.ts +87 -87
  62. package/lib/commands/init.ts +259 -259
  63. package/lib/commands/merge-resolve.ts +378 -378
  64. package/lib/commands/preview.ts +178 -178
  65. package/lib/commands/project-info.ts +244 -244
  66. package/lib/commands/quality.ts +517 -517
  67. package/lib/commands/response.ts +454 -454
  68. package/lib/commands/section-boundaries.ts +82 -82
  69. package/lib/commands/sections.ts +451 -451
  70. package/lib/commands/sync.ts +706 -706
  71. package/lib/commands/text-ops.ts +449 -449
  72. package/lib/commands/utilities.ts +448 -448
  73. package/lib/commands/verify-anchors.ts +272 -272
  74. package/lib/commands/word-tools.ts +340 -340
  75. package/lib/comment-realign.ts +517 -517
  76. package/lib/config.ts +84 -84
  77. package/lib/crossref.ts +781 -781
  78. package/lib/csl.ts +191 -191
  79. package/lib/dependencies.ts +98 -98
  80. package/lib/diff-engine.ts +465 -465
  81. package/lib/doi-cache.ts +115 -115
  82. package/lib/doi.ts +897 -897
  83. package/lib/equations.ts +506 -506
  84. package/lib/errors.ts +346 -346
  85. package/lib/format.ts +541 -541
  86. package/lib/git.ts +326 -326
  87. package/lib/grammar.ts +303 -303
  88. package/lib/image-registry.ts +180 -180
  89. package/lib/import.ts +911 -911
  90. package/lib/journals.ts +543 -543
  91. package/lib/merge.ts +633 -633
  92. package/lib/orcid.ts +144 -144
  93. package/lib/pdf-comments.ts +263 -263
  94. package/lib/pdf-import.ts +524 -524
  95. package/lib/plugins.ts +362 -362
  96. package/lib/postprocess.ts +188 -188
  97. package/lib/pptx-color-filter.lua +37 -37
  98. package/lib/pptx-template.ts +469 -469
  99. package/lib/pptx-themes.ts +483 -483
  100. package/lib/protect-restore.ts +520 -520
  101. package/lib/rate-limiter.ts +94 -94
  102. package/lib/response.ts +197 -197
  103. package/lib/restore-references.ts +240 -240
  104. package/lib/review.ts +327 -327
  105. package/lib/schema.ts +417 -417
  106. package/lib/scientific-words.ts +73 -73
  107. package/lib/sections.ts +335 -335
  108. package/lib/slides.ts +756 -756
  109. package/lib/spelling.ts +334 -334
  110. package/lib/templates.ts +526 -526
  111. package/lib/themes.ts +742 -742
  112. package/lib/trackchanges.ts +247 -247
  113. package/lib/tui.ts +450 -450
  114. package/lib/types.ts +550 -550
  115. package/lib/undo.ts +250 -250
  116. package/lib/utils.ts +69 -69
  117. package/lib/variables.ts +179 -179
  118. package/lib/word-extraction.ts +806 -806
  119. package/lib/word.ts +643 -643
  120. package/lib/wordcomments.ts +817 -817
  121. package/package.json +137 -137
  122. package/scripts/postbuild.js +28 -28
  123. package/skill/REFERENCE.md +431 -431
  124. package/skill/SKILL.md +258 -258
  125. package/tsconfig.json +26 -26
  126. package/types/index.d.ts +525 -525
package/README.md CHANGED
@@ -1,391 +1,391 @@
1
- # docrev
2
-
3
- [![npm](https://img.shields.io/npm/v/docrev)](https://www.npmjs.com/package/docrev)
4
- [![npm downloads](https://img.shields.io/npm/dm/docrev)](https://www.npmjs.com/package/docrev)
5
- [![node](https://img.shields.io/node/v/docrev)](https://nodejs.org)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
- [![CI](https://github.com/gcol33/docrev/actions/workflows/ci.yml/badge.svg)](https://github.com/gcol33/docrev/actions/workflows/ci.yml)
8
-
9
- A CLI for writing documents in Markdown while collaborating with Word users.
10
-
11
- You write in Markdown under version control. Your collaborators use Word (or PDF). docrev converts between the two, preserving track changes, comments, equations, and cross-references.
12
-
13
- ## The Problem
14
-
15
- You've been here before:
16
-
17
- ```
18
- manuscript_v1.docx
19
- manuscript_v2_john_comments.docx
20
- manuscript_v2_jane_comments.docx
21
- manuscript_v3_merged_final.docx
22
- manuscript_v3_merged_final_REAL.docx
23
- manuscript_v3_merged_final_REAL_submitted.docx
24
- ```
25
-
26
- Three reviewers send back three Word files. You manually compare changes, copy-paste between documents, lose track of who said what. A week later, you can't remember which version has the figure updates.
27
-
28
- **docrev fixes this.** You write in plain text. Reviewers use Word. Their feedback flows back into your files automatically. One source of truth, full version history, no more file chaos.
29
-
30
- ## Highlights
31
-
32
- - **Markdown → Word/PDF** with citations, figures, equations, cross-references
33
- - **Round-trip sync**: import Word track changes and comments back to Markdown
34
- - **CLI review workflow**: reply to comments, accept/reject changes from terminal
35
- - **DOI tools**: validate, lookup, and auto-add references from DOIs
36
- - **21 journal styles**: Nature, Science, PNAS, and more
37
- - **Version control friendly**: plain text source, full git history
38
-
39
- ## Install
40
-
41
- ```bash
42
- npm install -g docrev
43
- ```
44
-
45
- Requires [Node.js](https://nodejs.org) 18+. [Pandoc](https://pandoc.org) is needed for building DOCX/PDF output. [LaTeX](#installing-dependencies) is additionally needed for PDF.
46
-
47
- ## Quick Example
48
-
49
- Write in Markdown with citations and cross-references:
50
-
51
- ```markdown
52
- Climate change poses significant challenges [@IPCC2021]. As shown in
53
- @fig:temperature, global temperatures have risen steadily.
54
-
55
- ![Temperature anomalies](figures/temperature.png){#fig:temperature}
56
-
57
- The relationship follows $\Delta T = \lambda \cdot \Delta F$ (@eq:forcing).
58
- ```
59
-
60
- Build and share:
61
-
62
- ```bash
63
- rev build docx # → paper.docx (for collaborators)
64
- rev build pdf # → paper.pdf (for journals)
65
- ```
66
-
67
- When collaborators return the Word doc with track changes:
68
-
69
- ```bash
70
- rev sync reviewed.docx # their comments → your markdown
71
- ```
72
-
73
- ## How It Works
74
-
75
- ```
76
- ┌─────────────┐ rev build docx ┌─────────────┐
77
- │ │ ───────────────────────→│ │
78
- │ Markdown │ │ Word │ → collaborators
79
- │ (you) │ rev build pdf │ / PDF │ → journals
80
- │ │ ───────────────────────→│ │
81
- └─────────────┘ └─────────────┘
82
- ↑ │
83
- │ rev sync │
84
- └───────────────────────────────────────┘
85
- their feedback → your files
86
- ```
87
-
88
- You stay in Markdown. Collaborators use Word. Journals get PDF. Everyone works in their preferred format.
89
-
90
- ## The CLI Review Cycle
91
-
92
- When reviewers send back a Word document with track changes and comments:
93
-
94
- ```bash
95
- rev sync reviewed.docx # import feedback into markdown
96
- ```
97
-
98
- Track changes appear inline - accept or reject by editing:
99
-
100
- ```markdown
101
- The sample size was {--100--}{++150++} participants.
102
- ```
103
-
104
- Handle comments without opening Word:
105
-
106
- ```bash
107
- rev comments # list all comments
108
- rev reply methods.md -n 1 -m "Added clarification"
109
- rev resolve methods.md -n 1 # mark as resolved
110
- rev build docx --dual # clean + annotated versions
111
- ```
112
-
113
- Reviewers who annotate PDFs instead of Word? That works too:
114
-
115
- ```bash
116
- rev sync annotated.pdf # extract PDF comments
117
- rev pdf-comments annotated.pdf --append methods.md
118
- ```
119
-
120
- Multiple reviewers sending back separate files? Merge them:
121
-
122
- ```bash
123
- rev merge reviewer_A.docx reviewer_B.docx # three-way merge
124
- ```
125
-
126
- The merge command uses the original document (auto-saved in `.rev/base.docx` on build) to detect what each reviewer changed, identifies conflicts when reviewers edit the same text differently, and lets you resolve them interactively.
127
-
128
- Your entire revision cycle stays in the terminal. `final_v3_REAL_final.docx` is over.
129
-
130
- ## Getting Started
131
-
132
- ### Starting a New Document
133
-
134
- Create a new project:
135
-
136
- ```bash
137
- rev new my-report
138
- cd my-report
139
- ```
140
-
141
- You'll be prompted to enter your section names, or press Enter to use the default structure. You can also specify sections directly:
142
-
143
- ```bash
144
- rev new my-report -s intro,methods,results,discussion
145
- ```
146
-
147
- Or set your preferred default sections once:
148
-
149
- ```bash
150
- rev config sections "intro,methods,results,discussion"
151
- ```
152
-
153
- This creates a folder with your chosen sections:
154
-
155
- ```
156
- my-report/
157
- ├── intro.md
158
- ├── methods.md
159
- ├── results.md
160
- ├── discussion.md
161
- ├── references.bib
162
- └── rev.yaml
163
- ```
164
-
165
- Write your content in the markdown files. When ready to share:
166
-
167
- ```bash
168
- rev build docx pdf
169
- ```
170
-
171
- After building, your project structure looks like:
172
-
173
- ```
174
- my-report/
175
- ├── intro.md
176
- ├── methods.md
177
- ├── results.md
178
- ├── discussion.md
179
- ├── references.bib
180
- ├── rev.yaml
181
- ├── paper.md ← combined sections (auto-generated)
182
- ├── my-report.docx ← output for collaborators
183
- └── my-report.pdf ← output for journals
184
- ```
185
-
186
- The output filename is derived from your project title in `rev.yaml`. Citations are resolved, equations rendered, and cross-references numbered.
187
-
188
- ### Starting from an Existing Word Document
189
-
190
- If you have a Word document to convert:
191
-
192
- ```bash
193
- rev import manuscript.docx
194
- ```
195
-
196
- This creates a project folder and splits the document into section files. Images are extracted to `figures/`, equations are converted to LaTeX, and track changes/comments are preserved as markdown annotations.
197
-
198
- ### Configuration
199
-
200
- Layout is controlled in `rev.yaml`:
201
-
202
- ```yaml
203
- title: "My Document"
204
- output:
205
- docx:
206
- reference-doc: template.docx # your Word template
207
- pdf:
208
- documentclass: article
209
- fontsize: 12pt
210
- ```
211
-
212
- Configure your name for comment replies:
213
-
214
- ```bash
215
- rev config user "Your Name"
216
- ```
217
-
218
- ### Table Formatting
219
-
220
- For PDF output, configure columns that should not wrap:
221
-
222
- ```yaml
223
- tables:
224
- nowrap:
225
- - Prior # column headers to keep on one line
226
- - "$\\widehat{R}$"
227
- ```
228
-
229
- Distribution notation in nowrap columns is auto-converted to LaTeX math:
230
- `Normal(0, 0.5)` → `$\mathcal{N}(0, 0.5)$`
231
-
232
- ### Postprocess Scripts
233
-
234
- Run custom scripts after output generation:
235
-
236
- ```yaml
237
- postprocess:
238
- pdf: ./scripts/fix-tables.py # runs after PDF
239
- docx: ./scripts/add-meta.js # runs after DOCX
240
- all: ./scripts/notify.sh # runs after any format
241
- ```
242
-
243
- Scripts receive environment variables: `OUTPUT_FILE`, `OUTPUT_FORMAT`, `PROJECT_DIR`, `CONFIG_PATH`.
244
-
245
- Use `--verbose` to see script output:
246
-
247
- ```bash
248
- rev build pdf --verbose
249
- ```
250
-
251
- ### Journal Profiles
252
-
253
- Journal profiles provide both validation rules and build formatting defaults. Set in `rev.yaml`:
254
-
255
- ```yaml
256
- journal: nature
257
- ```
258
-
259
- Or pass on the command line:
260
-
261
- ```bash
262
- rev build pdf -j nature # applies Nature's CSL style + PDF settings
263
- ```
264
-
265
- When a journal is set, its formatting defaults (CSL citation style, font size, margins, line spacing) are applied automatically. Your explicit `rev.yaml` settings always take priority.
266
-
267
- Six profiles include formatting: `nature`, `science`, `cell`, `pnas`, `plos-one`, `elife`. All 21 profiles support validation. Custom profiles can include formatting too — see [docs/configuration.md](docs/configuration.md).
268
-
269
- ```bash
270
- rev validate --list # see all profiles ([formatting] tag = build support)
271
- rev profiles --fetch-csl apa # download a CSL style to cache
272
- rev profiles --list-csl # list cached CSL styles
273
- ```
274
-
275
- ## Annotation Syntax
276
-
277
- Track changes from Word appear as [CriticMarkup](http://criticmarkup.com/):
278
-
279
- ```markdown
280
- The sample size was {--100--}{++150++} participants. # deletion + insertion
281
- Data was collected {~~monthly~>weekly~~}. # substitution
282
- {>>Reviewer 2: Please clarify.<<} # comment
283
- ```
284
-
285
- ## Writing Tips
286
-
287
- Track word count changes between versions:
288
-
289
- ```bash
290
- rev diff # compare against last commit
291
- # methods.md +142 words -38 words
292
- # results.md +89 words -12 words
293
- ```
294
-
295
- Add references to `references.bib` (BibTeX format):
296
-
297
- ```bibtex
298
- @article{Smith2020,
299
- author = {Smith, Jane},
300
- title = {Paper Title},
301
- journal = {Nature},
302
- year = {2020},
303
- doi = {10.1038/example}
304
- }
305
- ```
306
-
307
- Cite with `[@Smith2020]` or `[@Smith2020; @Jones2021]` for multiple sources.
308
-
309
- Equations use LaTeX: inline `$E = mc^2$` or display `$$\sum_{i=1}^{n} x_i$$`.
310
-
311
- Cross-references: `@fig:label`, `@tbl:label`, `@eq:label` → "Figure 1", "Table 2", "Equation 3".
312
-
313
- ## Command Reference
314
-
315
- | Task | Command |
316
- |------|---------|
317
- | Create project | `rev new my-project` |
318
- | Create LaTeX project | `rev new my-project --template latex` |
319
- | Import Word document | `rev import manuscript.docx` |
320
- | Extract Word equations | `rev equations from-word doc.docx` |
321
- | Build DOCX | `rev build docx` |
322
- | Build PDF | `rev build pdf` |
323
- | Build clean + annotated | `rev build docx --dual` |
324
- | Sync Word feedback | `rev sync reviewed.docx` |
325
- | Sync PDF comments | `rev sync annotated.pdf` |
326
- | Extract PDF comments | `rev pdf-comments annotated.pdf` |
327
- | Extract with highlighted text | `rev pdf-comments file.pdf --with-text` |
328
- | Project status | `rev status` |
329
- | Next pending comment | `rev next` |
330
- | List pending comments | `rev todo` |
331
- | Filter by author | `rev comments file.md --author "Reviewer 2"` |
332
- | Accept all changes | `rev accept file.md -a` |
333
- | Reject change | `rev reject file.md -n 1` |
334
- | Reply to comment | `rev reply file.md -n 1 -m "response"` |
335
- | Reply to all pending | `rev reply file.md --all -m "Addressed"` |
336
- | Resolve comment | `rev resolve file.md -n 1` |
337
- | Show contributors | `rev contributors` |
338
- | Lookup ORCID | `rev orcid 0000-0002-1825-0097` |
339
- | Merge reviewer feedback | `rev merge reviewer_A.docx reviewer_B.docx` |
340
- | Archive reviewer files | `rev archive` |
341
- | Check DOIs | `rev doi check references.bib` |
342
- | Find missing DOIs | `rev doi lookup references.bib` |
343
- | Add citation from DOI | `rev doi add 10.1038/example` |
344
- | Word count | `rev wc` |
345
- | Pre-submission check | `rev check` |
346
- | Check for updates | `rev upgrade --check` |
347
-
348
- Run `rev help` to see all commands, or `rev help <command>` for details on a specific command.
349
-
350
- Full command reference: [docs/commands.md](docs/commands.md)
351
-
352
- ## Claude Code Skill
353
-
354
- Install the docrev skill for [Claude Code](https://claude.ai/code):
355
-
356
- ```bash
357
- rev install-cli-skill # install to ~/.claude/skills/docrev
358
- rev uninstall-cli-skill # remove
359
- ```
360
-
361
- Once installed, Claude understands docrev commands and can help navigate comments, draft replies, and manage your revision cycle.
362
-
363
- ## Installing Dependencies
364
-
365
- ### Pandoc
366
-
367
- [Pandoc](https://pandoc.org) handles document conversion.
368
-
369
- | Platform | Command |
370
- |----------|---------|
371
- | macOS | `brew install pandoc` |
372
- | Windows | `winget install JohnMacFarlane.Pandoc` |
373
- | Debian/Ubuntu | `sudo apt install pandoc` |
374
- | Fedora | `sudo dnf install pandoc` |
375
-
376
- Other platforms: [pandoc.org/installing](https://pandoc.org/installing.html)
377
-
378
- ### LaTeX (for PDF output)
379
-
380
- | Platform | Command |
381
- |----------|---------|
382
- | macOS | `brew install --cask mactex` |
383
- | Windows | `winget install MiKTeX.MiKTeX` |
384
- | Debian/Ubuntu | `sudo apt install texlive-full` |
385
- | Fedora | `sudo dnf install texlive-scheme-full` |
386
-
387
- Alternatively, [TinyTeX](https://yihui.org/tinytex/) provides a minimal distribution that downloads packages on demand.
388
-
389
- ## License
390
-
391
- MIT
1
+ # docrev
2
+
3
+ [![npm](https://img.shields.io/npm/v/docrev)](https://www.npmjs.com/package/docrev)
4
+ [![npm downloads](https://img.shields.io/npm/dm/docrev)](https://www.npmjs.com/package/docrev)
5
+ [![node](https://img.shields.io/node/v/docrev)](https://nodejs.org)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
+ [![CI](https://github.com/gcol33/docrev/actions/workflows/ci.yml/badge.svg)](https://github.com/gcol33/docrev/actions/workflows/ci.yml)
8
+
9
+ A CLI for writing documents in Markdown while collaborating with Word users.
10
+
11
+ You write in Markdown under version control. Your collaborators use Word (or PDF). docrev converts between the two, preserving track changes, comments, equations, and cross-references.
12
+
13
+ ## The Problem
14
+
15
+ You've been here before:
16
+
17
+ ```
18
+ manuscript_v1.docx
19
+ manuscript_v2_john_comments.docx
20
+ manuscript_v2_jane_comments.docx
21
+ manuscript_v3_merged_final.docx
22
+ manuscript_v3_merged_final_REAL.docx
23
+ manuscript_v3_merged_final_REAL_submitted.docx
24
+ ```
25
+
26
+ Three reviewers send back three Word files. You manually compare changes, copy-paste between documents, lose track of who said what. A week later, you can't remember which version has the figure updates.
27
+
28
+ **docrev fixes this.** You write in plain text. Reviewers use Word. Their feedback flows back into your files automatically. One source of truth, full version history, no more file chaos.
29
+
30
+ ## Highlights
31
+
32
+ - **Markdown → Word/PDF** with citations, figures, equations, cross-references
33
+ - **Round-trip sync**: import Word track changes and comments back to Markdown
34
+ - **CLI review workflow**: reply to comments, accept/reject changes from terminal
35
+ - **DOI tools**: validate, lookup, and auto-add references from DOIs
36
+ - **21 journal styles**: Nature, Science, PNAS, and more
37
+ - **Version control friendly**: plain text source, full git history
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ npm install -g docrev
43
+ ```
44
+
45
+ Requires [Node.js](https://nodejs.org) 18+. [Pandoc](https://pandoc.org) is needed for building DOCX/PDF output. [LaTeX](#installing-dependencies) is additionally needed for PDF.
46
+
47
+ ## Quick Example
48
+
49
+ Write in Markdown with citations and cross-references:
50
+
51
+ ```markdown
52
+ Climate change poses significant challenges [@IPCC2021]. As shown in
53
+ @fig:temperature, global temperatures have risen steadily.
54
+
55
+ ![Temperature anomalies](figures/temperature.png){#fig:temperature}
56
+
57
+ The relationship follows $\Delta T = \lambda \cdot \Delta F$ (@eq:forcing).
58
+ ```
59
+
60
+ Build and share:
61
+
62
+ ```bash
63
+ rev build docx # → paper.docx (for collaborators)
64
+ rev build pdf # → paper.pdf (for journals)
65
+ ```
66
+
67
+ When collaborators return the Word doc with track changes:
68
+
69
+ ```bash
70
+ rev sync reviewed.docx # their comments → your markdown
71
+ ```
72
+
73
+ ## How It Works
74
+
75
+ ```
76
+ ┌─────────────┐ rev build docx ┌─────────────┐
77
+ │ │ ───────────────────────→│ │
78
+ │ Markdown │ │ Word │ → collaborators
79
+ │ (you) │ rev build pdf │ / PDF │ → journals
80
+ │ │ ───────────────────────→│ │
81
+ └─────────────┘ └─────────────┘
82
+ ↑ │
83
+ │ rev sync │
84
+ └───────────────────────────────────────┘
85
+ their feedback → your files
86
+ ```
87
+
88
+ You stay in Markdown. Collaborators use Word. Journals get PDF. Everyone works in their preferred format.
89
+
90
+ ## The CLI Review Cycle
91
+
92
+ When reviewers send back a Word document with track changes and comments:
93
+
94
+ ```bash
95
+ rev sync reviewed.docx # import feedback into markdown
96
+ ```
97
+
98
+ Track changes appear inline - accept or reject by editing:
99
+
100
+ ```markdown
101
+ The sample size was {--100--}{++150++} participants.
102
+ ```
103
+
104
+ Handle comments without opening Word:
105
+
106
+ ```bash
107
+ rev comments # list all comments
108
+ rev reply methods.md -n 1 -m "Added clarification"
109
+ rev resolve methods.md -n 1 # mark as resolved
110
+ rev build docx --dual # clean + annotated versions
111
+ ```
112
+
113
+ Reviewers who annotate PDFs instead of Word? That works too:
114
+
115
+ ```bash
116
+ rev sync annotated.pdf # extract PDF comments
117
+ rev pdf-comments annotated.pdf --append methods.md
118
+ ```
119
+
120
+ Multiple reviewers sending back separate files? Merge them:
121
+
122
+ ```bash
123
+ rev merge reviewer_A.docx reviewer_B.docx # three-way merge
124
+ ```
125
+
126
+ The merge command uses the original document (auto-saved in `.rev/base.docx` on build) to detect what each reviewer changed, identifies conflicts when reviewers edit the same text differently, and lets you resolve them interactively.
127
+
128
+ Your entire revision cycle stays in the terminal. `final_v3_REAL_final.docx` is over.
129
+
130
+ ## Getting Started
131
+
132
+ ### Starting a New Document
133
+
134
+ Create a new project:
135
+
136
+ ```bash
137
+ rev new my-report
138
+ cd my-report
139
+ ```
140
+
141
+ You'll be prompted to enter your section names, or press Enter to use the default structure. You can also specify sections directly:
142
+
143
+ ```bash
144
+ rev new my-report -s intro,methods,results,discussion
145
+ ```
146
+
147
+ Or set your preferred default sections once:
148
+
149
+ ```bash
150
+ rev config sections "intro,methods,results,discussion"
151
+ ```
152
+
153
+ This creates a folder with your chosen sections:
154
+
155
+ ```
156
+ my-report/
157
+ ├── intro.md
158
+ ├── methods.md
159
+ ├── results.md
160
+ ├── discussion.md
161
+ ├── references.bib
162
+ └── rev.yaml
163
+ ```
164
+
165
+ Write your content in the markdown files. When ready to share:
166
+
167
+ ```bash
168
+ rev build docx pdf
169
+ ```
170
+
171
+ After building, your project structure looks like:
172
+
173
+ ```
174
+ my-report/
175
+ ├── intro.md
176
+ ├── methods.md
177
+ ├── results.md
178
+ ├── discussion.md
179
+ ├── references.bib
180
+ ├── rev.yaml
181
+ ├── paper.md ← combined sections (auto-generated)
182
+ ├── my-report.docx ← output for collaborators
183
+ └── my-report.pdf ← output for journals
184
+ ```
185
+
186
+ The output filename is derived from your project title in `rev.yaml`. Citations are resolved, equations rendered, and cross-references numbered.
187
+
188
+ ### Starting from an Existing Word Document
189
+
190
+ If you have a Word document to convert:
191
+
192
+ ```bash
193
+ rev import manuscript.docx
194
+ ```
195
+
196
+ This creates a project folder and splits the document into section files. Images are extracted to `figures/`, equations are converted to LaTeX, and track changes/comments are preserved as markdown annotations.
197
+
198
+ ### Configuration
199
+
200
+ Layout is controlled in `rev.yaml`:
201
+
202
+ ```yaml
203
+ title: "My Document"
204
+ output:
205
+ docx:
206
+ reference-doc: template.docx # your Word template
207
+ pdf:
208
+ documentclass: article
209
+ fontsize: 12pt
210
+ ```
211
+
212
+ Configure your name for comment replies:
213
+
214
+ ```bash
215
+ rev config user "Your Name"
216
+ ```
217
+
218
+ ### Table Formatting
219
+
220
+ For PDF output, configure columns that should not wrap:
221
+
222
+ ```yaml
223
+ tables:
224
+ nowrap:
225
+ - Prior # column headers to keep on one line
226
+ - "$\\widehat{R}$"
227
+ ```
228
+
229
+ Distribution notation in nowrap columns is auto-converted to LaTeX math:
230
+ `Normal(0, 0.5)` → `$\mathcal{N}(0, 0.5)$`
231
+
232
+ ### Postprocess Scripts
233
+
234
+ Run custom scripts after output generation:
235
+
236
+ ```yaml
237
+ postprocess:
238
+ pdf: ./scripts/fix-tables.py # runs after PDF
239
+ docx: ./scripts/add-meta.js # runs after DOCX
240
+ all: ./scripts/notify.sh # runs after any format
241
+ ```
242
+
243
+ Scripts receive environment variables: `OUTPUT_FILE`, `OUTPUT_FORMAT`, `PROJECT_DIR`, `CONFIG_PATH`.
244
+
245
+ Use `--verbose` to see script output:
246
+
247
+ ```bash
248
+ rev build pdf --verbose
249
+ ```
250
+
251
+ ### Journal Profiles
252
+
253
+ Journal profiles provide both validation rules and build formatting defaults. Set in `rev.yaml`:
254
+
255
+ ```yaml
256
+ journal: nature
257
+ ```
258
+
259
+ Or pass on the command line:
260
+
261
+ ```bash
262
+ rev build pdf -j nature # applies Nature's CSL style + PDF settings
263
+ ```
264
+
265
+ When a journal is set, its formatting defaults (CSL citation style, font size, margins, line spacing) are applied automatically. Your explicit `rev.yaml` settings always take priority.
266
+
267
+ Six profiles include formatting: `nature`, `science`, `cell`, `pnas`, `plos-one`, `elife`. All 21 profiles support validation. Custom profiles can include formatting too — see [docs/configuration.md](docs/configuration.md).
268
+
269
+ ```bash
270
+ rev validate --list # see all profiles ([formatting] tag = build support)
271
+ rev profiles --fetch-csl apa # download a CSL style to cache
272
+ rev profiles --list-csl # list cached CSL styles
273
+ ```
274
+
275
+ ## Annotation Syntax
276
+
277
+ Track changes from Word appear as [CriticMarkup](http://criticmarkup.com/):
278
+
279
+ ```markdown
280
+ The sample size was {--100--}{++150++} participants. # deletion + insertion
281
+ Data was collected {~~monthly~>weekly~~}. # substitution
282
+ {>>Reviewer 2: Please clarify.<<} # comment
283
+ ```
284
+
285
+ ## Writing Tips
286
+
287
+ Track word count changes between versions:
288
+
289
+ ```bash
290
+ rev diff # compare against last commit
291
+ # methods.md +142 words -38 words
292
+ # results.md +89 words -12 words
293
+ ```
294
+
295
+ Add references to `references.bib` (BibTeX format):
296
+
297
+ ```bibtex
298
+ @article{Smith2020,
299
+ author = {Smith, Jane},
300
+ title = {Paper Title},
301
+ journal = {Nature},
302
+ year = {2020},
303
+ doi = {10.1038/example}
304
+ }
305
+ ```
306
+
307
+ Cite with `[@Smith2020]` or `[@Smith2020; @Jones2021]` for multiple sources.
308
+
309
+ Equations use LaTeX: inline `$E = mc^2$` or display `$$\sum_{i=1}^{n} x_i$$`.
310
+
311
+ Cross-references: `@fig:label`, `@tbl:label`, `@eq:label` → "Figure 1", "Table 2", "Equation 3".
312
+
313
+ ## Command Reference
314
+
315
+ | Task | Command |
316
+ |------|---------|
317
+ | Create project | `rev new my-project` |
318
+ | Create LaTeX project | `rev new my-project --template latex` |
319
+ | Import Word document | `rev import manuscript.docx` |
320
+ | Extract Word equations | `rev equations from-word doc.docx` |
321
+ | Build DOCX | `rev build docx` |
322
+ | Build PDF | `rev build pdf` |
323
+ | Build clean + annotated | `rev build docx --dual` |
324
+ | Sync Word feedback | `rev sync reviewed.docx` |
325
+ | Sync PDF comments | `rev sync annotated.pdf` |
326
+ | Extract PDF comments | `rev pdf-comments annotated.pdf` |
327
+ | Extract with highlighted text | `rev pdf-comments file.pdf --with-text` |
328
+ | Project status | `rev status` |
329
+ | Next pending comment | `rev next` |
330
+ | List pending comments | `rev todo` |
331
+ | Filter by author | `rev comments file.md --author "Reviewer 2"` |
332
+ | Accept all changes | `rev accept file.md -a` |
333
+ | Reject change | `rev reject file.md -n 1` |
334
+ | Reply to comment | `rev reply file.md -n 1 -m "response"` |
335
+ | Reply to all pending | `rev reply file.md --all -m "Addressed"` |
336
+ | Resolve comment | `rev resolve file.md -n 1` |
337
+ | Show contributors | `rev contributors` |
338
+ | Lookup ORCID | `rev orcid 0000-0002-1825-0097` |
339
+ | Merge reviewer feedback | `rev merge reviewer_A.docx reviewer_B.docx` |
340
+ | Archive reviewer files | `rev archive` |
341
+ | Check DOIs | `rev doi check references.bib` |
342
+ | Find missing DOIs | `rev doi lookup references.bib` |
343
+ | Add citation from DOI | `rev doi add 10.1038/example` |
344
+ | Word count | `rev wc` |
345
+ | Pre-submission check | `rev check` |
346
+ | Check for updates | `rev upgrade --check` |
347
+
348
+ Run `rev help` to see all commands, or `rev help <command>` for details on a specific command.
349
+
350
+ Full command reference: [docs/commands.md](docs/commands.md)
351
+
352
+ ## Claude Code Skill
353
+
354
+ Install the docrev skill for [Claude Code](https://claude.ai/code):
355
+
356
+ ```bash
357
+ rev install-cli-skill # install to ~/.claude/skills/docrev
358
+ rev uninstall-cli-skill # remove
359
+ ```
360
+
361
+ Once installed, Claude understands docrev commands and can help navigate comments, draft replies, and manage your revision cycle.
362
+
363
+ ## Installing Dependencies
364
+
365
+ ### Pandoc
366
+
367
+ [Pandoc](https://pandoc.org) handles document conversion.
368
+
369
+ | Platform | Command |
370
+ |----------|---------|
371
+ | macOS | `brew install pandoc` |
372
+ | Windows | `winget install JohnMacFarlane.Pandoc` |
373
+ | Debian/Ubuntu | `sudo apt install pandoc` |
374
+ | Fedora | `sudo dnf install pandoc` |
375
+
376
+ Other platforms: [pandoc.org/installing](https://pandoc.org/installing.html)
377
+
378
+ ### LaTeX (for PDF output)
379
+
380
+ | Platform | Command |
381
+ |----------|---------|
382
+ | macOS | `brew install --cask mactex` |
383
+ | Windows | `winget install MiKTeX.MiKTeX` |
384
+ | Debian/Ubuntu | `sudo apt install texlive-full` |
385
+ | Fedora | `sudo dnf install texlive-scheme-full` |
386
+
387
+ Alternatively, [TinyTeX](https://yihui.org/tinytex/) provides a minimal distribution that downloads packages on demand.
388
+
389
+ ## License
390
+
391
+ MIT