docrev 0.9.14 → 0.9.16

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 (43) hide show
  1. package/README.md +66 -51
  2. package/dist/lib/wordcomments.d.ts.map +1 -1
  3. package/dist/lib/wordcomments.js +25 -2
  4. package/dist/lib/wordcomments.js.map +1 -1
  5. package/docs-src/build.py +113 -0
  6. package/docs-src/extra.css +208 -0
  7. package/docs-src/md-to-html.lua +6 -0
  8. package/docs-src/template.html +116 -0
  9. package/lib/wordcomments.ts +25 -2
  10. package/mkdocs.yml +64 -0
  11. package/package.json +1 -1
  12. package/site/assets/extra.css +208 -0
  13. package/site/commands.html +926 -0
  14. package/site/configuration.html +469 -0
  15. package/site/index.html +288 -0
  16. package/site/troubleshooting.html +461 -0
  17. package/site/workflow.html +518 -0
  18. package/skill/REFERENCE.md +44 -2
  19. package/skill/SKILL.md +20 -4
  20. package/dev_notes/bug_repro_comment_parser.md +0 -71
  21. package/dev_notes/stress2/adversarial.docx +0 -0
  22. package/dev_notes/stress2/build_adversarial.ts +0 -186
  23. package/dev_notes/stress2/drift_matcher.ts +0 -62
  24. package/dev_notes/stress2/probe_anchors.ts +0 -35
  25. package/dev_notes/stress2/project/adversarial.docx +0 -0
  26. package/dev_notes/stress2/project/discussion.before.md +0 -3
  27. package/dev_notes/stress2/project/discussion.md +0 -3
  28. package/dev_notes/stress2/project/methods.before.md +0 -20
  29. package/dev_notes/stress2/project/methods.md +0 -20
  30. package/dev_notes/stress2/project/rev.yaml +0 -5
  31. package/dev_notes/stress2/project/sections.yaml +0 -4
  32. package/dev_notes/stress2/sections.yaml +0 -5
  33. package/dev_notes/stress2/trace_placement.ts +0 -50
  34. package/dev_notes/stresstest_boundaries.ts +0 -27
  35. package/dev_notes/stresstest_drift_apply.ts +0 -43
  36. package/dev_notes/stresstest_drift_compare.ts +0 -43
  37. package/dev_notes/stresstest_drift_v2.ts +0 -54
  38. package/dev_notes/stresstest_inspect.ts +0 -54
  39. package/dev_notes/stresstest_pstyle.ts +0 -55
  40. package/dev_notes/stresstest_section_debug.ts +0 -23
  41. package/dev_notes/stresstest_split.ts +0 -70
  42. package/dev_notes/stresstest_trace.ts +0 -19
  43. package/dev_notes/stresstest_verify_no_overwrite.ts +0 -40
package/site/troubleshooting.html ADDED
@@ -0,0 +1,461 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en" data-bs-theme="light">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>Troubleshooting — docrev</title>
7
+ <meta name="description" content="CLI for writing documents in Markdown while collaborating with Word users.">
8
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootswatch@5.3.3/dist/sandstone/bootstrap.min.css">
9
+ <style>
10
+ html { -webkit-text-size-adjust: 100%; }
11
+ pre > code.sourceCode { white-space: pre; position: relative; }
12
+ pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
13
+ pre > code.sourceCode > span:empty { height: 1.2em; }
14
+ .sourceCode { overflow: visible; }
15
+ code.sourceCode > span { color: inherit; text-decoration: inherit; }
16
+ div.sourceCode { margin: 1em 0; }
17
+ pre.sourceCode { margin: 0; }
18
+ @media screen {
19
+ div.sourceCode { overflow: auto; }
20
+ }
21
+ @media print {
22
+ pre > code.sourceCode { white-space: pre-wrap; }
23
+ pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
24
+ }
25
+ pre.numberSource code
26
+ { counter-reset: source-line 0; }
27
+ pre.numberSource code > span
28
+ { position: relative; left: -4em; counter-increment: source-line; }
29
+ pre.numberSource code > span > a:first-child::before
30
+ { content: counter(source-line);
31
+ position: relative; left: -1em; text-align: right; vertical-align: baseline;
32
+ border: none; display: inline-block;
33
+ -webkit-touch-callout: none; -webkit-user-select: none;
34
+ -khtml-user-select: none; -moz-user-select: none;
35
+ -ms-user-select: none; user-select: none;
36
+ padding: 0 4px; width: 4em;
37
+ color: #aaaaaa;
38
+ }
39
+ pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
40
+ div.sourceCode
41
+ { }
42
+ @media screen {
43
+ pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
44
+ }
45
+ code span.al { color: #ff0000; font-weight: bold; } /* Alert */
46
+ code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
47
+ code span.at { color: #7d9029; } /* Attribute */
48
+ code span.bn { color: #40a070; } /* BaseN */
49
+ code span.bu { color: #008000; } /* BuiltIn */
50
+ code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
51
+ code span.ch { color: #4070a0; } /* Char */
52
+ code span.cn { color: #880000; } /* Constant */
53
+ code span.co { color: #60a0b0; font-style: italic; } /* Comment */
54
+ code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
55
+ code span.do { color: #ba2121; font-style: italic; } /* Documentation */
56
+ code span.dt { color: #902000; } /* DataType */
57
+ code span.dv { color: #40a070; } /* DecVal */
58
+ code span.er { color: #ff0000; font-weight: bold; } /* Error */
59
+ code span.ex { } /* Extension */
60
+ code span.fl { color: #40a070; } /* Float */
61
+ code span.fu { color: #06287e; } /* Function */
62
+ code span.im { color: #008000; font-weight: bold; } /* Import */
63
+ code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
64
+ code span.kw { color: #007020; font-weight: bold; } /* Keyword */
65
+ code span.op { color: #666666; } /* Operator */
66
+ code span.ot { color: #007020; } /* Other */
67
+ code span.pp { color: #bc7a00; } /* Preprocessor */
68
+ code span.sc { color: #4070a0; } /* SpecialChar */
69
+ code span.ss { color: #bb6688; } /* SpecialString */
70
+ code span.st { color: #4070a0; } /* String */
71
+ code span.va { color: #19177c; } /* Variable */
72
+ code span.vs { color: #4070a0; } /* VerbatimString */
73
+ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
74
+ </style>
75
+ <link rel="stylesheet" href="assets/extra.css">
76
+ </head>
77
+ <body>
78
+
79
+ <nav class="navbar navbar-expand-lg fixed-top" aria-label="Site navigation">
80
+ <div class="container">
81
+ <a class="navbar-brand me-2" href="index.html">docrev</a>
82
+ <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar-main" aria-controls="navbar-main" aria-expanded="false" aria-label="Toggle navigation">
83
+ <span class="navbar-toggler-icon"></span>
84
+ </button>
85
+ <div class="collapse navbar-collapse" id="navbar-main">
86
+ <ul class="navbar-nav me-auto">
87
+ <li class="nav-item">
88
+ <a class="nav-link" href="index.html">Home</a>
89
+ </li>
90
+ <li class="nav-item">
91
+ <a class="nav-link" href="workflow.html">Get Started</a>
92
+ </li>
93
+ <li class="nav-item">
94
+ <a class="nav-link" href="commands.html">Commands</a>
95
+ </li>
96
+ <li class="nav-item">
97
+ <a class="nav-link" href="configuration.html">Configuration</a>
98
+ </li>
99
+ <li class="nav-item">
100
+ <a class="nav-link active" aria-current="page" href="troubleshooting.html">Troubleshooting</a>
101
+ </li>
102
+ </ul>
103
+ <ul class="navbar-nav">
104
+ <li class="nav-item">
105
+ <button id="theme-toggle" class="btn btn-link nav-link border-0" aria-label="Toggle dark mode">
106
+ <svg id="icon-sun" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
107
+ <path d="M8 11a3 3 0 1 1 0-6 3 3 0 0 1 0 6m0 1a4 4 0 1 0 0-8 4 4 0 0 0 0 8M8 0a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 0m0 13a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 13m8-5a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2a.5.5 0 0 1 .5.5M3 8a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2A.5.5 0 0 1 3 8m10.657-5.657a.5.5 0 0 1 0 .707l-1.414 1.415a.5.5 0 1 1-.707-.708l1.414-1.414a.5.5 0 0 1 .707 0m-9.193 9.193a.5.5 0 0 1 0 .707L3.05 13.657a.5.5 0 0 1-.707-.707l1.414-1.414a.5.5 0 0 1 .707 0m9.193 2.121a.5.5 0 0 1-.707 0l-1.414-1.414a.5.5 0 0 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707M4.464 4.465a.5.5 0 0 1-.707 0L2.343 3.05a.5.5 0 1 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707"/>
108
+ </svg>
109
+ <svg id="icon-moon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16" style="display:none">
110
+ <path d="M6 .278a.768.768 0 0 1 .08.858 7.208 7.208 0 0 0-.878 3.46c0 4.021 3.278 7.277 7.318 7.277.527 0 1.04-.055 1.533-.16a.787.787 0 0 1 .81.316.733.733 0 0 1-.031.893A8.349 8.349 0 0 1 8.344 16C3.734 16 0 12.286 0 7.71 0 4.266 2.114 1.312 5.124.06A.752.752 0 0 1 6 .278"/>
111
+ </svg>
112
+ </button>
113
+ </li>
114
+ <li class="nav-item">
115
+ <a class="nav-link" href="https://github.com/gcol33/docrev" aria-label="GitHub">
116
+ <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="currentColor" viewBox="0 0 16 16">
117
+ <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.012 8.012 0 0 0 16 8c0-4.42-3.58-8-8-8"/>
118
+ </svg>
119
+ </a>
120
+ </li>
121
+ <li class="nav-item">
122
+ <a class="nav-link" href="https://www.npmjs.com/package/docrev" aria-label="npm">
123
+ <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 16 16">
124
+ <path d="M0 0v16h16V0zm5.333 13.333H2.667V5.333h2.666v5.334H8V5.333h2.667v8H5.333z"/>
125
+ </svg>
126
+ </a>
127
+ </li>
128
+ </ul>
129
+ </div>
130
+ </div>
131
+ </nav>
132
+
133
+ <div class="container template-article">
134
+ <div class="row">
135
+ <main id="main" class="col-md-9">
136
+ <h1 id="troubleshooting">Troubleshooting</h1>
137
+ <p>Common issues and solutions for docrev.</p>
138
+ <h2 id="installation-issues">Installation Issues</h2>
139
+ <h3 id="pandoc-command-not-found">“pandoc: command not found”</h3>
140
+ <p>Pandoc is required for building documents.</p>
141
+ <p><strong>macOS:</strong></p>
142
+ <div class="sourceCode" id="cb1"><pre
143
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="ex">brew</span> install pandoc</span></code></pre></div>
144
+ <p><strong>Windows:</strong></p>
145
+ <div class="sourceCode" id="cb2"><pre
146
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="ex">winget</span> install JohnMacFarlane.Pandoc</span>
147
+ <span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="co"># or download from https://pandoc.org/installing.html</span></span></code></pre></div>
148
+ <p><strong>Linux (Debian/Ubuntu):</strong></p>
149
+ <div class="sourceCode" id="cb3"><pre
150
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="fu">sudo</span> apt install pandoc</span></code></pre></div>
151
+ <p>Verify installation:</p>
152
+ <div class="sourceCode" id="cb4"><pre
153
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="ex">pandoc</span> <span class="at">--version</span></span></code></pre></div>
154
+ <h3 id="pandoc-crossref-command-not-found">“pandoc-crossref:
155
+ command not found”</h3>
156
+ <p>pandoc-crossref is optional but required for figure/table
157
+ cross-references.</p>
158
+ <p><strong>macOS:</strong></p>
159
+ <div class="sourceCode" id="cb5"><pre
160
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="ex">brew</span> install pandoc-crossref</span></code></pre></div>
161
+ <p><strong>Windows:</strong> Download from
162
+ https://github.com/lierdakil/pandoc-crossref/releases</p>
163
+ <p><strong>Linux:</strong></p>
164
+ <div class="sourceCode" id="cb6"><pre
165
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Check your package manager or download from GitHub releases</span></span></code></pre></div>
166
+ <h3 id="latex-not-found-pdf-generation-fails">LaTeX not found (PDF
167
+ generation fails)</h3>
168
+ <p>PDF output requires a LaTeX distribution.</p>
169
+ <p><strong>macOS:</strong></p>
170
+ <div class="sourceCode" id="cb7"><pre
171
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="ex">brew</span> install <span class="at">--cask</span> mactex-no-gui</span>
172
+ <span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="co"># or smaller: brew install --cask basictex</span></span></code></pre></div>
173
+ <p><strong>Windows:</strong> Install MiKTeX from
174
+ https://miktex.org/download</p>
175
+ <p><strong>Linux:</strong></p>
176
+ <div class="sourceCode" id="cb8"><pre
177
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="fu">sudo</span> apt install texlive-latex-base texlive-fonts-recommended</span></code></pre></div>
178
+ <h2 id="build-errors">Build Errors</h2>
179
+ <h3 id="no-section-files-found">“No section files found”</h3>
180
+ <p><strong>Cause:</strong> No <code>.md</code> files in the
181
+ directory, or sections not specified in <code>rev.yaml</code>.</p>
182
+ <p><strong>Solutions:</strong> 1. Create section files:
183
+ <code>rev new</code> 2. Specify sections in <code>rev.yaml</code>:
184
+ <code>yaml sections: - introduction.md - methods.md</code>
185
+ 3. Check you’re in the correct directory</p>
186
+ <h3 id="failed-to-parse-rev.yaml">“Failed to parse rev.yaml”</h3>
187
+ <p><strong>Cause:</strong> Invalid YAML syntax.</p>
188
+ <p><strong>Common fixes:</strong> - Check indentation (use spaces,
189
+ not tabs) - Quote strings with special characters - Validate with:
190
+ <code>rev check</code></p>
191
+ <p><strong>Example of correct YAML:</strong></p>
192
+ <div class="sourceCode" id="cb9"><pre
193
+ class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="fu">title</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;My Paper: A Study&quot;</span><span class="co"> # Quotes needed for colon</span></span>
194
+ <span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a><span class="fu">authors</span><span class="kw">:</span></span>
195
+ <span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="kw">-</span><span class="at"> </span><span class="fu">name</span><span class="kw">:</span><span class="at"> John Doe</span><span class="co"> # 2-space indent</span></span>
196
+ <span id="cb9-4"><a href="#cb9-4" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">affiliation</span><span class="kw">:</span><span class="at"> University</span></span></code></pre></div>
197
+ <h3 id="build-produces-empty-pdf">Build produces empty PDF</h3>
198
+ <p><strong>Causes:</strong> 1. Section files are empty 2. Pandoc
199
+ filter errors (check terminal output) 3. LaTeX errors</p>
200
+ <p><strong>Debug:</strong></p>
201
+ <div class="sourceCode" id="cb10"><pre
202
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> build <span class="at">--verbose</span></span>
203
+ <span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> build tex <span class="co"># Check the .tex file for errors</span></span></code></pre></div>
204
+ <h2 id="import-issues">Import Issues</h2>
205
+ <h3 id="comments-not-imported-from-word">Comments not imported
206
+ from Word</h3>
207
+ <p><strong>Causes:</strong> 1. Document uses older .doc format
208
+ (only .docx supported) 2. Comments are in review mode but not
209
+ finalized</p>
210
+ <p><strong>Solutions:</strong> 1. Save as .docx in Word 2.
211
+ Accept/reject track changes before importing if you want clean
212
+ text</p>
213
+ <h3 id="track-changes-garbled-or-missing">Track changes garbled or
214
+ missing</h3>
215
+ <p><strong>Cause:</strong> Complex nested changes or unsupported
216
+ Word features.</p>
217
+ <p><strong>Solution:</strong></p>
218
+ <div class="sourceCode" id="cb11"><pre
219
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> import document.docx <span class="at">--no-track-changes</span></span>
220
+ <span id="cb11-2"><a href="#cb11-2" aria-hidden="true" tabindex="-1"></a><span class="co"># Then manually review the Word file</span></span></code></pre></div>
221
+ <h3 id="cannot-read-file-errors">“Cannot read file” errors</h3>
222
+ <p><strong>Causes:</strong> 1. File is open in Word (Windows locks
223
+ open files) 2. File path contains special characters 3. Corrupted
224
+ .docx file</p>
225
+ <p><strong>Solutions:</strong> 1. Close the file in Word 2. Rename
226
+ file to remove special characters 3. Try opening in Word and
227
+ re-saving</p>
228
+ <h2 id="comment-issues">Comment Issues</h2>
229
+ <h3 id="comments-not-appearing-in-word-export">Comments not
230
+ appearing in Word export</h3>
231
+ <p><strong>Cause:</strong> Comments marked as resolved are hidden
232
+ by default.</p>
233
+ <p><strong>Solutions:</strong></p>
234
+ <div class="sourceCode" id="cb12"><pre
235
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> comments file.md <span class="at">--resolved</span> <span class="co"># Check resolved comments</span></span>
236
+ <span id="cb12-2"><a href="#cb12-2" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> resolve file.md <span class="at">-a</span> <span class="at">-u</span> <span class="co"># Unresolve all comments</span></span></code></pre></div>
237
+ <h3 id="reply-threading-not-working">Reply threading not
238
+ working</h3>
239
+ <p>Comments must be adjacent (no text between them) to thread in
240
+ Word.</p>
241
+ <p><strong>Works:</strong></p>
242
+ <div class="sourceCode" id="cb13"><pre
243
+ class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb13-1"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a>text{&gt;&gt;Author1: comment&lt;&lt;}{&gt;&gt;Author2: reply&lt;&lt;}</span></code></pre></div>
244
+ <p><strong>Won’t thread:</strong></p>
245
+ <div class="sourceCode" id="cb14"><pre
246
+ class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb14-1"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a>text{&gt;&gt;Author1: comment&lt;&lt;} more text {&gt;&gt;Author2: reply&lt;&lt;}</span></code></pre></div>
247
+ <h3 id="author-name-not-set">Author name not set</h3>
248
+ <div class="sourceCode" id="cb15"><pre
249
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb15-1"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> config user <span class="st">&quot;Your Name&quot;</span></span>
250
+ <span id="cb15-2"><a href="#cb15-2" aria-hidden="true" tabindex="-1"></a><span class="co"># Or per-command:</span></span>
251
+ <span id="cb15-3"><a href="#cb15-3" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> reply file.md <span class="at">--author</span> <span class="st">&quot;Your Name&quot;</span></span></code></pre></div>
252
+ <h2 id="cross-reference-issues">Cross-Reference Issues</h2>
253
+ <h3 id="figurestables-not-numbered">Figures/tables not
254
+ numbered</h3>
255
+ <p><strong>Causes:</strong> 1. pandoc-crossref not installed 2.
256
+ Labels not in correct format</p>
257
+ <p><strong>Correct format:</strong></p>
258
+ <div class="sourceCode" id="cb16"><pre
259
+ class="sourceCode markdown"><code class="sourceCode markdown"><span id="cb16-1"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a><span class="al">![Caption](image.png)</span>{#fig:label}</span>
260
+ <span id="cb16-2"><a href="#cb16-2" aria-hidden="true" tabindex="-1"></a></span>
261
+ <span id="cb16-3"><a href="#cb16-3" aria-hidden="true" tabindex="-1"></a><span class="pp">|</span> Col1 <span class="pp">|</span> Col2 <span class="pp">|</span></span>
262
+ <span id="cb16-4"><a href="#cb16-4" aria-hidden="true" tabindex="-1"></a><span class="pp">|------|------|</span></span>
263
+ <span id="cb16-5"><a href="#cb16-5" aria-hidden="true" tabindex="-1"></a><span class="pp">|</span> a <span class="pp">|</span> b <span class="pp">|</span></span>
264
+ <span id="cb16-6"><a href="#cb16-6" aria-hidden="true" tabindex="-1"></a></span>
265
+ <span id="cb16-7"><a href="#cb16-7" aria-hidden="true" tabindex="-1"></a>: Caption {#tbl:label}</span></code></pre></div>
266
+ <h3 id="references-show-instead-of-numbers">References show “??”
267
+ instead of numbers</h3>
268
+ <p><strong>Causes:</strong> 1. Label doesn’t exist 2. Typo in
269
+ reference 3. pandoc-crossref not running</p>
270
+ <p><strong>Debug:</strong></p>
271
+ <div class="sourceCode" id="cb17"><pre
272
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb17-1"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> refs <span class="co"># List all labels</span></span>
273
+ <span id="cb17-2"><a href="#cb17-2" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> refs <span class="at">--check</span> <span class="co"># Find broken references</span></span></code></pre></div>
274
+ <h2 id="pdf-issues">PDF Issues</h2>
275
+ <h3 id="fonts-missing-or-wrong">Fonts missing or wrong</h3>
276
+ <p><strong>LaTeX errors about fonts:</strong></p>
277
+ <div class="sourceCode" id="cb18"><pre
278
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb18-1"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Install more fonts</span></span>
279
+ <span id="cb18-2"><a href="#cb18-2" aria-hidden="true" tabindex="-1"></a><span class="fu">sudo</span> apt install texlive-fonts-extra <span class="co"># Linux</span></span>
280
+ <span id="cb18-3"><a href="#cb18-3" aria-hidden="true" tabindex="-1"></a><span class="co"># Or use standard fonts in rev.yaml:</span></span>
281
+ <span id="cb18-4"><a href="#cb18-4" aria-hidden="true" tabindex="-1"></a><span class="ex">pdf:</span></span>
282
+ <span id="cb18-5"><a href="#cb18-5" aria-hidden="true" tabindex="-1"></a> <span class="ex">mainfont:</span> <span class="st">&quot;Times New Roman&quot;</span></span></code></pre></div>
283
+ <h3 id="images-not-appearing">Images not appearing</h3>
284
+ <p><strong>Causes:</strong> 1. Image path incorrect (relative to
285
+ project root) 2. Image format not supported by LaTeX</p>
286
+ <p><strong>Solutions:</strong> 1. Use relative paths:
287
+ <code>![](images/fig1.png)</code> 2. Convert to PNG/PDF: LaTeX
288
+ prefers PDF for vector graphics</p>
289
+ <h3 id="pdf-too-large">PDF too large</h3>
290
+ <div class="sourceCode" id="cb19"><pre
291
+ class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb19-1"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a><span class="co"># In rev.yaml</span></span>
292
+ <span id="cb19-2"><a href="#cb19-2" aria-hidden="true" tabindex="-1"></a><span class="fu">pdf</span><span class="kw">:</span></span>
293
+ <span id="cb19-3"><a href="#cb19-3" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">geometry</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;margin=0.75in&quot;</span><span class="co"> # Smaller margins</span></span>
294
+ <span id="cb19-4"><a href="#cb19-4" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">fontsize</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;11pt&quot;</span><span class="co"> # Smaller font</span></span></code></pre></div>
295
+ <h2 id="performance-issues">Performance Issues</h2>
296
+ <h3 id="doi-lookup-slow">DOI lookup slow</h3>
297
+ <p>DOI validation queries external APIs. For large
298
+ bibliographies:</p>
299
+ <div class="sourceCode" id="cb20"><pre
300
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb20-1"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> doi check <span class="at">--no-lookup</span> <span class="co"># Skip online validation</span></span></code></pre></div>
301
+ <h3 id="build-taking-too-long">Build taking too long</h3>
302
+ <div class="sourceCode" id="cb21"><pre
303
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb21-1"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Build only what you need</span></span>
304
+ <span id="cb21-2"><a href="#cb21-2" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> build docx <span class="co"># Skip PDF</span></span>
305
+ <span id="cb21-3"><a href="#cb21-3" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> build <span class="at">--no-toc</span> <span class="co"># Skip table of contents</span></span></code></pre></div>
306
+ <h2 id="encoding-issues">Encoding Issues</h2>
307
+ <h3 id="special-characters-corrupted">Special characters
308
+ corrupted</h3>
309
+ <p><strong>Cause:</strong> File encoding mismatch.</p>
310
+ <p><strong>Solutions:</strong> 1. Ensure files are UTF-8 encoded
311
+ 2. In Word, save with “UTF-8” encoding option 3. Check your
312
+ editor’s encoding settings</p>
313
+ <h3 id="bibtex-entries-with-accents-fail">BibTeX entries with
314
+ accents fail</h3>
315
+ <p>Use LaTeX-style escapes or UTF-8:</p>
316
+ <div class="sourceCode" id="cb22"><pre
317
+ class="sourceCode bibtex"><code class="sourceCode bibtex"><span id="cb22-1"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a><span class="co">author = {M{\&quot;u}ller, Hans}</span></span>
318
+ <span id="cb22-2"><a href="#cb22-2" aria-hidden="true" tabindex="-1"></a><span class="co"># or with UTF-8:</span></span>
319
+ <span id="cb22-3"><a href="#cb22-3" aria-hidden="true" tabindex="-1"></a><span class="co">author = {Müller, Hans}</span></span></code></pre></div>
320
+ <h2 id="getting-help">Getting Help</h2>
321
+ <h3 id="debug-mode">Debug mode</h3>
322
+ <div class="sourceCode" id="cb23"><pre
323
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb23-1"><a href="#cb23-1" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> build <span class="at">--verbose</span> <span class="dv">2</span><span class="op">&gt;&amp;</span><span class="dv">1</span> <span class="kw">|</span> <span class="fu">tee</span> build.log</span></code></pre></div>
324
+ <h3 id="check-system-status">Check system status</h3>
325
+ <div class="sourceCode" id="cb24"><pre
326
+ class="sourceCode bash"><code class="sourceCode bash"><span id="cb24-1"><a href="#cb24-1" aria-hidden="true" tabindex="-1"></a><span class="fu">rev</span> doctor</span></code></pre></div>
327
+ <h3 id="report-issues">Report issues</h3>
328
+ <p>https://github.com/gcol33/docrev/issues</p>
329
+ <p>Include: - <code>rev --version</code> output -
330
+ <code>rev doctor</code> output - Minimal reproducible example</p>
331
+ </main>
332
+ <aside class="col-md-3 d-none d-md-block">
333
+ <nav id="toc" data-toggle="toc" aria-label="On this page">
334
+ <h2 class="h6">On this page</h2>
335
+ <div class="toc"><ul>
336
+ <li><a href="#troubleshooting"
337
+ id="toc-troubleshooting">Troubleshooting</a>
338
+ <ul>
339
+ <li><a href="#installation-issues"
340
+ id="toc-installation-issues">Installation Issues</a>
341
+ <ul>
342
+ <li><a href="#pandoc-command-not-found"
343
+ id="toc-pandoc-command-not-found">“pandoc: command not found”</a></li>
344
+ <li><a href="#pandoc-crossref-command-not-found"
345
+ id="toc-pandoc-crossref-command-not-found">“pandoc-crossref: command not
346
+ found”</a></li>
347
+ <li><a href="#latex-not-found-pdf-generation-fails"
348
+ id="toc-latex-not-found-pdf-generation-fails">LaTeX not found (PDF
349
+ generation fails)</a></li>
350
+ </ul></li>
351
+ <li><a href="#build-errors" id="toc-build-errors">Build Errors</a>
352
+ <ul>
353
+ <li><a href="#no-section-files-found"
354
+ id="toc-no-section-files-found">“No section files found”</a></li>
355
+ <li><a href="#failed-to-parse-rev.yaml"
356
+ id="toc-failed-to-parse-rev.yaml">“Failed to parse rev.yaml”</a></li>
357
+ <li><a href="#build-produces-empty-pdf"
358
+ id="toc-build-produces-empty-pdf">Build produces empty PDF</a></li>
359
+ </ul></li>
360
+ <li><a href="#import-issues" id="toc-import-issues">Import Issues</a>
361
+ <ul>
362
+ <li><a href="#comments-not-imported-from-word"
363
+ id="toc-comments-not-imported-from-word">Comments not imported from
364
+ Word</a></li>
365
+ <li><a href="#track-changes-garbled-or-missing"
366
+ id="toc-track-changes-garbled-or-missing">Track changes garbled or
367
+ missing</a></li>
368
+ <li><a href="#cannot-read-file-errors"
369
+ id="toc-cannot-read-file-errors">“Cannot read file” errors</a></li>
370
+ </ul></li>
371
+ <li><a href="#comment-issues" id="toc-comment-issues">Comment Issues</a>
372
+ <ul>
373
+ <li><a href="#comments-not-appearing-in-word-export"
374
+ id="toc-comments-not-appearing-in-word-export">Comments not appearing in
375
+ Word export</a></li>
376
+ <li><a href="#reply-threading-not-working"
377
+ id="toc-reply-threading-not-working">Reply threading not
378
+ working</a></li>
379
+ <li><a href="#author-name-not-set" id="toc-author-name-not-set">Author
380
+ name not set</a></li>
381
+ </ul></li>
382
+ <li><a href="#cross-reference-issues"
383
+ id="toc-cross-reference-issues">Cross-Reference Issues</a>
384
+ <ul>
385
+ <li><a href="#figurestables-not-numbered"
386
+ id="toc-figurestables-not-numbered">Figures/tables not numbered</a></li>
387
+ <li><a href="#references-show-instead-of-numbers"
388
+ id="toc-references-show-instead-of-numbers">References show “??” instead
389
+ of numbers</a></li>
390
+ </ul></li>
391
+ <li><a href="#pdf-issues" id="toc-pdf-issues">PDF Issues</a>
392
+ <ul>
393
+ <li><a href="#fonts-missing-or-wrong"
394
+ id="toc-fonts-missing-or-wrong">Fonts missing or wrong</a></li>
395
+ <li><a href="#images-not-appearing" id="toc-images-not-appearing">Images
396
+ not appearing</a></li>
397
+ <li><a href="#pdf-too-large" id="toc-pdf-too-large">PDF too
398
+ large</a></li>
399
+ </ul></li>
400
+ <li><a href="#performance-issues"
401
+ id="toc-performance-issues">Performance Issues</a>
402
+ <ul>
403
+ <li><a href="#doi-lookup-slow" id="toc-doi-lookup-slow">DOI lookup
404
+ slow</a></li>
405
+ <li><a href="#build-taking-too-long"
406
+ id="toc-build-taking-too-long">Build taking too long</a></li>
407
+ </ul></li>
408
+ <li><a href="#encoding-issues" id="toc-encoding-issues">Encoding
409
+ Issues</a>
410
+ <ul>
411
+ <li><a href="#special-characters-corrupted"
412
+ id="toc-special-characters-corrupted">Special characters
413
+ corrupted</a></li>
414
+ <li><a href="#bibtex-entries-with-accents-fail"
415
+ id="toc-bibtex-entries-with-accents-fail">BibTeX entries with accents
416
+ fail</a></li>
417
+ </ul></li>
418
+ <li><a href="#getting-help" id="toc-getting-help">Getting Help</a>
419
+ <ul>
420
+ <li><a href="#debug-mode" id="toc-debug-mode">Debug mode</a></li>
421
+ <li><a href="#check-system-status" id="toc-check-system-status">Check
422
+ system status</a></li>
423
+ <li><a href="#report-issues" id="toc-report-issues">Report
424
+ issues</a></li>
425
+ </ul></li>
426
+ </ul></li>
427
+ </ul></div>
428
+ </nav>
429
+ </aside>
430
+ </div>
431
+ </div>
432
+
433
+ <footer class="border-top py-3 mt-auto">
434
+ <div class="container d-flex justify-content-between align-items-center text-muted" style="font-size:.85rem">
435
+ <span>docrev 0.9.15</span>
436
+ <span>Built with <a href="https://pandoc.org" class="text-muted">pandoc</a></span>
437
+ </div>
438
+ </footer>
439
+
440
+ <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
441
+ <script>
442
+ (function () {
443
+ var html = document.documentElement;
444
+ var sun = document.getElementById('icon-sun');
445
+ var moon = document.getElementById('icon-moon');
446
+ function apply(t) {
447
+ html.setAttribute('data-bs-theme', t);
448
+ sun.style.display = t === 'dark' ? 'none' : '';
449
+ moon.style.display = t === 'dark' ? '' : 'none';
450
+ }
451
+ apply(localStorage.getItem('docrev-theme') || 'light');
452
+ document.getElementById('theme-toggle').addEventListener('click', function () {
453
+ var next = html.getAttribute('data-bs-theme') === 'dark' ? 'light' : 'dark';
454
+ localStorage.setItem('docrev-theme', next);
455
+ apply(next);
456
+ });
457
+ })();
458
+ </script>
459
+
460
+ </body>
461
+ </html>