Repository navigation
Expand file tree
/
Copy pathdiadem.el
More file actions
598 lines (484 loc) · 20.3 KB
/
Copy pathdiadem.el
File metadata and controls
598 lines (484 loc) · 20.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
; Copyright 2010 Dominic Cooney. All Rights Reserved.
; Writing tools. Use one of the following to start:
; - DD-SPJ-WRITE-A-GREAT-PAPER to review Simon Peyton Jones' advice.
; - DD-TPP-BUILD-PYRAMID to interactively build a structured argument.
; - DD-REVISE-PARAGRAPH to edit a paragraph for coherence and flow.
; - DD-REVISE-BY-RULES to edit at a word level for common malapropisms.
;
; Diadem uses functions in paragraph.el heavily, so consider
; customizing variables like SENTENCE-END-DOUBLE-SPACE and so on.
;; TODO:
;; - Add a way to iterate by paragraph, by sentence, by bigram, etc.
;; - Add a way to iterate noun phrases, etc.
;; - Add something for structural composition and checks (maybe based on
;; org-mode?)
(require 'cl)
(defgroup dd-faces nil
"Faces used in Diadem Mode"
:group 'diadem
:group 'faces)
(defface dd-primary-face
'((t (:foreground "Pink")))
"Face for the text primarily being scrutinized."
:group 'dd-faces)
(defconst dd-advice-buffer "*DD-Advice*"
"Buffer to use to display long form prompts.")
(defvar dd-current-session nil
"State tracking what's currently being revised.")
(defstruct dd-session
"The target of revisions."
window
buffer
overlay)
(defun dd-new-session ()
"Starts a new session.
If there is an existing session in DD-CURRENT-SESSION, deletes its overlay."
(if dd-current-session
(let ((overlay (dd-session-overlay dd-current-session)))
(if (overlayp overlay)
(delete-overlay overlay))))
(setq dd-current-session (make-dd-session :buffer (current-buffer)
:window (selected-window))))
(defun dd-select-session-for-editing (session)
"Selects the window and buffer of SESSION."
(select-window (dd-session-window session))
(set-buffer (dd-session-buffer session)))
;; Rules.
(defstruct dd-rule
"A writing rule.
DETECTOR searches the current buffer to see where the rule can be applied.
PROMPT is displayed when the detector matches."
detector
prompt)
;; Prompts.
(defstruct dd-prompt-button
"Creates a button labeled TEXT that does ACTION.
Interpreted by DD-PROMPT-PART."
text
action)
(defun dd-prompt-paragraph (&rest stuff)
"Outputs the prompts in STUFF, then formats a paragraph."
`(paragraph ,stuff))
(defun dd-prompt (&rest parts)
"Displays a prompt containing PARTS.
DD-PROMPT-PART defines how parts are handled."
(select-window (or (get-buffer-window dd-advice-buffer)
(split-window (selected-window))) t)
(switch-to-buffer (get-buffer-create dd-advice-buffer))
(erase-buffer)
(dd-prompt-part parts)
(goto-char (point-min)))
(defun dd-prompt-part (part)
"Interprets PART to generate prompt output."
(cond ((stringp part) (insert part))
((dd-prompt-button-p part)
(insert-text-button (dd-prompt-button-text part)
'action (dd-prompt-button-action part)))
((and (consp part) (eq 'paragraph (car part)))
(dd-prompt-part (cdr part))
(fill-paragraph))
((listp part)
(mapcar 'dd-prompt-part part))))
;; Things from "Line by Line."
(defun dd-lbl-cite (page)
"Generates a string citation of Line by Line.
PAGE is the page to cite."
(concat "Cook, Claire Kehrwald (1985) Line by Line (p. "
(number-to-string page) ") Boston, MA: Houghton Mifflin Harcourt."))
(defvar dd-rule-lbl-general-consensus
(make-dd-rule
:detector "general consensus"
:prompt `("Since consensus means \"general agreement\" it is redundant
to write \"general consensus\". Just use \"consensus.\"\n\n"
,(dd-prompt-paragraph (dd-lbl-cite 180)))))
(defvar dd-rule-lbl-while
(make-dd-rule
:detector "while\\W"
:prompt `(
"\"while\" seems ludicrous when it is meant as \"although\" or
\"whereas\" but contradicts the notion of simultaneity:
(Avoid) \"While our ancestors took months to cross the continent,
we do it in five hours.\"
Consider \"although\".\n\n"
,(dd-prompt-paragraph (dd-lbl-cite 202)))))
;; Things from "Plain Words."
(defun dd-pw-cite (page)
"Generates a string citation of Gowers' Plain Words.
PAGE is the page to cite."
(concat "Gowers, Earnest & Gowers, Rebecca (2015) Plain Words (p. "
(number-to-string page) ") UK: Penguin Books."))
(defvar dd-rule-pw-and-which
(make-dd-rule
:detector "\\(and\\|but\\|or\\)\\W+\\(which\\|who\\|where\\)"
:prompt `("It is wrong to write:
and which, and who, and where, but which, or which
except by way of introducing a second relative clause with the
same antecedent as the one that just preceded it.\n\n"
,(dd-prompt-paragraph (dd-pw-cite 176)))))
;; Things from "The Pyramid Principle."
(defun dd-tpp-cite (page)
"Generates a string citation of The Pyramid Principle.
PAGE is the page to cite."
(concat "Minto, Barbara (2009) The Pyramid Principle (3rd ed. revised. p. "
(number-to-string page) ") Essex, UK: Pearson Education."))
(defun dd-tpp-build-pyramid (&optional button)
"The process from Chapter 3, \"How to build a Pyramid Structure.\""
(interactive)
(dd-new-session)
(dd-prompt
(make-dd-prompt-button :text "Next" :action #'dd-tpp-build-pyramid-step-2)
"\n\n"
"Fill in the \"top box\":
1. What Subject are you discussing?
2. What Question are you answering in the reader's mind?
3. What is the Answer?\n\n"
(dd-prompt-paragraph (dd-tpp-cite 26))))
(defun dd-tpp-build-pyramid-step-2 (button)
(dd-prompt
(make-dd-prompt-button :text "Prev" :action #'dd-tpp-build-pyramid)
" "
(make-dd-prompt-button :text "Next" :action #'dd-tpp-build-pyramid-step-3)
"\n\n"
"Match the Answer to the Introduction:
4. What is the Situation?
Make the first non-controversial statement you can make about
the Subject.
5. What is the Complication?
Ask yourself, \"So what?\" Think of something in the Situation
to raise the Question.
6. Do the Question and Answer still follow?
Change the Question to the one raised by the Complication, or
use a different Complication."))
(defun dd-tpp-build-pyramid-step-3 (button)
(dd-prompt
(make-dd-prompt-button :text "Prev" :action #'dd-tpp-build-pyramid-step-2)
" "
(make-dd-prompt-button :text "Next" :action #'dd-tpp-build-pyramid-step-4)
"\n\n"
"Aside: Situation, Complication, Solution order:
You can vary the order of these parts to affect a change in tone.
CONSIDERED: Situation, Complication, Solution
DIRECT: Solution, Situation, Complication
CONCERNED: Complication, Situation, Solution\n\n"
(dd-prompt-paragraph (dd-tpp-cite 44))))
(defun dd-tpp-build-pyramid-step-4 (button)
(dd-prompt
(make-dd-prompt-button :text "Prev" :action #'dd-tpp-build-pyramid-step-3)
" "
(make-dd-prompt-button :text "Next" :action #'dd-tpp-check-order)
"\n\n"
"Find the Key Line:
7. What new Question is raised by the Answer?
The Key Line not only gives the answer to the Question, but
indicates the plan of the document.
8. Will you answer inductively or deductively?
If inductively, what is your plural noun?"))
(defun dd-tpp-check-order (&optional button)
(dd-prompt
(make-dd-prompt-button :text "Prev" :action #'dd-tpp-build-pyramid-step-4)
" "
(make-dd-prompt-button :text "Next" :action #'dd-done)
"\n\n"
"If the group is inductive, it must either deal with cause and
effect and should be ordered by time; or divide a whole into its
parts and be ordered by structure; or classify like things and be
ordered by rank.
Time order: Ask yourself, \"What would I do first if I were doing
this? What second? etc.\"
Structural: Are the pieces mutually exclusive and collectively
exhaustive (MECE) in terms of the whole? How do you order the
pieces? To reflect a process, use time order; to emphasize
location, use structural order (for example, geography);
otherwise rank them (by whatever is relevant--size, priority,
etc.)
Ranking: What do you label the points as? (What is the \"group
noun\"?) Can you find anything more specifically the same about
them? Can you justify their order on that basis? Are there any
missing?\n\n"
(dd-prompt-paragraph (dd-tpp-cite 91))))
(defun dd-spj-write-a-great-paper (&optional button)
"Simon Peyton Jones' \"How to write a great research paper\"."
(interactive)
(dd-new-session)
(dd-prompt
(make-dd-prompt-button :text "Done" :action #'dd-done)
"\n\n"
"Seven suggestions by Simon Peyton Jones, from
https://www.microsoft.com/en-us/research/academic-program/write-great-research-paper/
1. Write first.
2. Identify your key idea. Your goal is to convey a useful and
re-usable idea. You want to infect the mind of your reader
with your idea, like a virus.
Write a paper, and give a talk, about any idea, no matter how
weedy and insignificant it may seem to you. It usually turns
out to be more interesting and challenging than it seemed at
first.
The paper should have just one \"ping\": one clear, sharp
idea. You may not know what it is when you start writing; but
you must know when you finish.
If you have lots of ideas, write lots of papers.
Be 100% specific: \"The main idea of this paper is ...\"
3. Tell a story. Imagine you're at a whiteboard:
- Here is a problem.
- It's an interesting problem.
- It's an unsolved problem.
- Here's my idea.
- My idea works (details, data).
- Here's how my idea compares to other people's approaches.
Example structure (conference paper):
- Title (1000 readers)
- Abstract (4 sentences, 100 readers)
- Introduction (1 page, 100 readers)
- The problem (1 page, 10 readers)
- My idea (2 pages, 10 readers)
- The details (5 pages, 3 readers)
- Related work (1-2 pages, 10 readers)
- Conclusions and further work (0.5 pages)
4. Nail your contributions to the mast: The introduction should
describe the problem and state your contributions--and that is
all--in one page.
Use an example to introduce the problem. \"Molehills not
mountains.\"
Write the list of contributions first; this drives the entire
paper, which substantiates the claims you have made. The
reader thinks \"gosh, if they can really deliver this, that'd
be exciting; I'd better read on.\"
Use a bulleted list.
Contributions should be refutable.
The body of the paper should provide evidence to support each
claim in the contributions. Check each claim, identify the
evidence, and forward-reference it from the claim, thus
avoiding the \"the rest of this paper is structured as
follows. Section 2 ...\" \"Evidence\" can be analysis and
comparison, theorems, measurements, case studies.
5. Put related work later, before conclusions. Don't put another
barrier between the reader and your idea. This also avoids the
#include jargon problem which makes ideas inaccessible to
beginners.
Be generous with credit: Warmly acknowledge people who have
helped; be generous to the competition; acknowledge weaknesses
in your approach.
6. Put your readers first.
Structure, this the \"the problem/my idea/the details\" part.
Present the idea as if you were explaining the problem to
someone using a whiteboard. Conveying the intuition is
primary. Once the reader has the intuition she can follow the
details, but not vice versa; even if she skips the details she
can take away something valuable.
Convey intuition using examples and only then present the
general case. (\"Is there any typewriter font?\")
Do not recapitulate your personal journey of discovery; it is
not interesting to the reader.
7. Listen to your readers: Solicit feedback from experts and
non-experts, including competitors. (\"Could you help me
ensure that I describe your work fairly?\")
Be grateful for reviews, especially criticism. Read every
criticism as a positive suggestion for something you could
explain more clearly. Thank them warmly; do not respond to the
criticism but fix the paper so that it is obvious."))
;; Things from "Technical Writing and Professional Communication."
(defun dd-twpc-cite (page)
"Generates a string citation of the Technical Writing book.
PAGE is the page to cite."
(concat "Olsen, Leslie A., & Huckin, Thomas N. (1991) Technical "
"Writing and Professional Communication (2nd ed.). (p. "
(number-to-string page) ") New York, NY: McGraw-Hill."))
(defun dd-twpc-procedure ()
"Technical Writing's \"procedure for producing more readable texts\"."
(dd-prompt
(make-dd-prompt-button :text "Next" :action #'dd-twpc-procedure-step-3)
"\n\n"
"Read the paragraph. Is there an adequate topic statement clear
pattern of organization? If not, rewrite the topic statement
and/or paragraph as necessary.\n\n"
(dd-prompt-paragraph (dd-twpc-cite 462)))
(dd-select-session-for-editing dd-current-session))
(defun dd-twpc-procedure-step-3 (button)
; "Consider the first sentence."
(with-current-buffer (dd-session-buffer dd-current-session)
(mark-end-of-sentence 1)
(let ((overlay (make-overlay (point) (mark))))
(setf (dd-session-overlay dd-current-session) overlay)
(overlay-put overlay 'face 'dd-primary-face)))
(dd-twpc-procedure-step-4 nil))
(defun dd-twpc-procedure-step-4 (button)
(dd-prompt
(make-dd-prompt-button :text "Next" :action #'dd-twpc-procedure-step-5)
"\n\n"
"Does the sentence meet the given-new criterion? (Does given
information come before new?)
* Sometimes it will not be possible to rewrite a sentence to meet
all of the desired criteria.
* This may not be relevant for the first sentence of a paragraph.\n\n"
(dd-prompt-paragraph (dd-twpc-cite 462))))
(defun dd-twpc-procedure-step-5 (button)
(dd-prompt
(make-dd-prompt-button :text "Rewritten!"
:action #'dd-twpc-procedure-step-4)
" "
(make-dd-prompt-button :text "Next"
:action #'dd-twpc-procedure-step-6)
"\n\n"
"Does the sentence put topical information (the subject of the
paragraph) in subject position (the subject of the sentence)?
1. Identify noun phrases in the sentence.
2. If the sentence has a passive verb, identify the hidden actor
and consider that noun phrase too.
3. Is one of the noun phrases the subject of the paragraph? Make
it the subject of the sentence.
4. Look at the subjects of other sentences. Are they similar? If
not it may indicate the subject of the paragraph needs to be
revised.
* Sometimes it will not be possible to rewrite a sentence to meet
all of the desired criteria.
* This may not be relevant for the first sentence of a paragraph.\n\n"
(dd-prompt-paragraph (dd-twpc-cite 462))))
(defun dd-twpc-procedure-step-6 (button)
(dd-prompt
(make-dd-prompt-button :text "Rewritten!"
:action #'dd-twpc-procedure-step-4)
" "
(make-dd-prompt-button :text "Next"
:action #'dd-twpc-procedure-step-7)
"\n\n"
"Does the sentence put light noun phrases before heavy ones?
Noun phrases vary in length, complexity and precision. Light noun
phrases are short and simple; heavy noun phrases are long and
complex. The preferred ordering is light noun phrases before
heavy noun phrases. Putting light noun phrases first packs more
of the sentence structure at the front of the sentence.
Ideally the entire structure of the sentence should fit within
about nine words. If that is not possible, at least the subject
and the verb should fit within nine words. Introductory units
don't count to this nine word limit but they should also follow
the light-before-heavy rule.
1. Identify noun phrases and count the number of words in each.
2. Restructure the sentence to put shorter phrases first. If
necessary you can use \"it\" to shift a heavy subject noun
phrase to the end of the sentence.
3. Count nine words into each unit. Does this include at least
the subject and verb?
* Put a heavy noun phrase first, in violation of this rule, to
convey topical information or emphasis.
In summary (S=Subject, V=Verb, _=Noun Phrase):
S ___ V ___________. Preferred.
S ______ V ________. Acceptable if the subject is not too long.
\"Balanced.\"
S ___________ V ___. Avoid, except for special effects.
* Sometimes it will not be possible to rewrite a sentence to meet
all of the desired criteria.\n\n"
(dd-prompt-paragraph (dd-twpc-cite 462))))
(defun dd-twpc-procedure-step-7 (button)
; Go to the next sentence.
; This assumes the author left point within the sentence being edited.
(with-current-buffer (dd-session-buffer dd-current-session)
(let ((overlay (dd-session-overlay dd-current-session)))
(setf (point) (overlay-end overlay))
(forward-char)
(if (eq (point) (point-max))
; TODO: Do TWPC Section 26.1 here to combine sentences.
(dd-done button)
(progn
(mark-end-of-sentence 1)
(move-overlay overlay (point) (mark))
(deactivate-mark)
(dd-twpc-procedure-step-4 nil))))))
(defun dd-done (button)
"Finishes an editing session."
(dd-prompt "Thanks for revising.")
(dd-select-session-for-editing dd-current-session)
(delete-overlay (dd-session-overlay dd-current-session))
(widen)
(setq dd-current-session nil))
(defun dd-revise-paragraph ()
"Interactively revises the current paragraph.
This resets the restriction."
(interactive)
(dd-new-session)
(mark-paragraph)
(narrow-to-region (point) (mark))
(deactivate-mark)
(dd-twpc-procedure))
(defvar dd-rules
(list
dd-rule-lbl-general-consensus
dd-rule-lbl-while
dd-rule-pw-and-which))
(defun dd-revise-by-rules ()
"Interactively revises based on word-level rules."
(interactive)
(dd-new-session)
(with-current-buffer (dd-session-buffer dd-current-session)
(let ((overlay (make-overlay (point) (point))))
(setf (dd-session-overlay dd-current-session) overlay)
(overlay-put overlay 'face 'dd-primary-face)))
(dd-revise-by-rules-next nil))
(defun dd-revise-by-rules-next (button)
(let (next-rule start end)
;; Find the rule that triggers closest.
(with-current-buffer (dd-session-buffer dd-current-session)
(setf start (point-max))
(dolist (rule dd-rules)
(save-excursion
(if (and (search-forward-regexp (dd-rule-detector rule) nil t)
(< (match-beginning 0) start))
(setf next-rule rule
start (match-beginning 0)
end (match-end 0))))))
(if next-rule
(progn
(with-current-buffer (dd-session-buffer dd-current-session)
;; Highlight the match.
(move-overlay (dd-session-overlay dd-current-session) start end)
;; Move to the start of the match.
(goto-char start))
;; Show the prompt.
;; TODO: Have some facility to skip rules. This just keeps revising
;; from point.
(apply #'dd-prompt
(cons (make-dd-prompt-button
:text "Next"
:action #'dd-revise-by-rules-next)
(cons "\n\n"
(dd-rule-prompt next-rule)))))
(dd-done nil))))
(defvar dd-mode
nil
"The diadem mode variable.")
(make-variable-buffer-local 'dd-mode)
(defvar dd-after-change-timer
nil
"The timer responding to quiescence after editing.")
(make-variable-buffer-local 'dd-after-change-timer)
(defvar dd-after-change-timer-delay
0.2
"The time, in seconds, to delay before reparsing the buffer.")
(defun dd-after-change ()
(message "Somewhere, a dog barked."))
(defun dd-after-change-immediate (begin end old-length)
(dd-reschedule-timer)
(message "dd: %d %d %d" begin end old-length))
(defun dd-reschedule-timer ()
(if dd-after-change-timer
(cancel-timer dd-after-change-timer))
(setq
dd-after-change-timer
(run-with-idle-timer dd-after-change-timer-delay nil #'dd-after-change)))
(defun dd-mode (&optional arg)
"Toggles Diadem writing support tools minor mode.
With ARG, turn Diadem on if ARG is positive."
(interactive "P")
(let ((old-dd-mode dd-mode))
(setq dd-mode
(if (null arg)
(not dd-mode)
(> (prefix-numeric-value arg) 0)))
(if (not (equal dd-mode old-dd-mode))
(progn
(if dd-mode
(add-hook 'after-change-functions
#'dd-after-change-immediate nil t)
(remove-hook 'after-change-functions #'dd-after-change-immedate t))
(message "Diadem %s." (if dd-mode "activated" "deactivated")))
(message "Diadem already %s." (if dd-mode "active" "inactive")))))
(provide 'diadem)