* lisp/emacs-lisp/package.el: Revert async package transactions
[emacs.git] / lisp / textmodes / two-column.el
blobea6b52561d65dec9767168377619bd3ffdb99c8f
1 ;;; two-column.el --- minor mode for editing of two-column text
3 ;; Copyright (C) 1992-1995, 2001-2015 Free Software Foundation, Inc.
5 ;; Author: Daniel Pfeiffer <occitan@esperanto.org>
6 ;; Adapted-By: ESR, Daniel Pfeiffer
7 ;; Keywords: wp
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation, either version 3 of the License, or
14 ;; (at your option) any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;;; Commentary:
26 ;;; Komentario: Commentary:
28 ;; Tiu programaro ebligas vin redakti This package gives you the ability
29 ;; dukolumnan tekston. to edit text in a two-column format.
32 ;; Vi havas tri eblecojn por eki tiun You have three ways to start up this
33 ;; mal^cefan modalon. ^Ciu donas al vi minor mode. Each gives you a
34 ;; horizontale disigatan fenestron, si- horizontally split window similar to
35 ;; milan al fina apareco de via teksto: the final outcome of your text:
38 ;; f2 2 asocias novan bufron nomatan associates a new buffer called
39 ;; C-x 6 2 same, sed kun 2C/ anta^u. the same, but with 2C/
40 ;; prepended.
42 ;; f2 b asocias alian bufron. Vi povas associates another buffer.
43 ;; C-x 6 b anka^u asocii dataron, se vi This can be used to associate a
44 ;; ^jus anta^ue faris C-x C-f. file if you just did C-x C-f.
46 ;; f2 s disigas jam dukolumnan tekston splits a two-column text into
47 ;; C-x 6 s en du bufroj ekde la nuna two buffers from the current
48 ;; linio, kaj je la nuna kolumno. line and at the current column.
49 ;; La anta^uaj signoj (ofte The preceding characters (often
50 ;; tabeligilo a^u |) estas la tab or |) are the column
51 ;; kolumna disiganto. Linioj kiuj separator. Lines that don't
52 ;; ne enhavas ilin ne estas have them won't be separated.
53 ;; disigitaj. Kiel la kvara kaj Like the fourth and fifth line
54 ;; la kvina linio se vi disigas if you split this file from
55 ;; ^ci dataron ekde la unua angla the first english word.
56 ;; vorto.
58 ;; Se vi volas meti longajn liniojn If you include long lines, i.e which
59 ;; (ekz. programerojn) en la kunigotan will span both columns (eg. source
60 ;; tekston, ili devas esti en la code), they should be in what will
61 ;; estonte unua kolumno. La alia devas be the first column, with the
62 ;; havi vakajn linion apud ili. associated buffer having empty lines
63 ;; next to them.
65 ;; Averto: en Emacs kiam vi ^san^gas la Attention: in Emacs when you change
66 ;; ^cefan modalon, la mal^cefaj modaloj the major mode, the minor modes are
67 ;; estas anka^u elmemorigitaj. Tiu- also purged from memory. In that
68 ;; okaze vi devas religi la du bufrojn case you must reassociate the two
69 ;; per iu C-x 6-ordono, ekz. C-x 6 b. buffers with any C-x 6-command, e.g.
70 ;; C-x 6 b.
72 ;; Kiam vi estos kontenta de la When you have edited both buffers to
73 ;; rezulto, vi kunmetos la du kolumnojn your content, you merge them with
74 ;; per C-x 6 1. Se vi poste vidas C-x 6 1. If you then see a problem,
75 ;; problemon, vi neniigu la kunmeton you undo the merge with C-x u and
76 ;; per C-x u kaj plue modifu la du continue to edit the two buffers.
77 ;; bufrojn. Kiam vi ne plu volas tajpi When you no longer want to edit in
78 ;; dukolumne, vi eliru el la mal^cefa two columns, you turn off the minor
79 ;; modalo per C-x 6 d. mode with C-x 6 d.
82 ;; Aldone al dukolumna redaktado, ek- In addition to two-column editing of
83 ;; zemple por skribi dulingvan tekston text, for example for writing a
84 ;; flank-al-flanke kiel ^ci tiu, aliaj bilingual text side-by-side as shown
85 ;; interesaj uzoj trovitas por tiu mal- here, other interesting uses have
86 ;; ^cefa modalo: been found for this minor mode:
88 ;; Vi povas disigi la kolumnojn per {+} You can separate the columns with
89 ;; ajna pla^ca ^ceno starigante {+} any string that pleases you, by
90 ;; `2C-separator'. Ekzemple "{+} " {+} setting `2C-separator'. For example
91 ;; por amuzi^gi. f2 s a^u C-x 6 s {+} "{+} " if you'd like to have fun.
92 ;; traktas tiujn kun prefiksa {+} f2 s or C-x 6 s handles these with a
93 ;; argumento kiu signifas la longon {+} prefix argument that means the
94 ;; de tia ^ceno. {+} desired length of such a string.
97 ;; Programistoj eble ^satus la eblecon Programmers might like the ability
98 ;; forspliti la komentarian kolumnon de to split off the comment column of a
99 ;; dosiero kiel la sekvanta. Vi povas file that looks like the following.
100 ;; rearan^gigi la paragrafon. La pro- You can fill-paragraph the comment.
101 ;; blemo estas ke koda^jo tuj lar- The problem is, code quickly gets
102 ;; ^gi^gas, tiel ke vi bezonas pli rather wide, so you need to use a
103 ;; mallar^gan komentarian kolumnon. narrower comment column. Code lines
104 ;; Koda^jaj linioj tra `comment-column' that reach beyond `comment-column'
105 ;; ne problemas, krom ke vi ne vidos are no problem, except that you
106 ;; iliajn finojn dum redaktado. won't see their end during editing.
109 ;; BEGIN -- This is just some meaningless
110 ;; FOR i IN 1..10 LOOP -- code in Ada, that runs foobar
111 ;; foobar( i ); -- once for each argument from one
112 ;; END LOOP; -- to ten, and then we're already
113 ;; END; -- through with it.
115 ;; Pli bone ankora^u, vi povas pozici- Better yet, you can put the point
116 ;; i^gi anta^u "This", tajpi M-3 f2 s before "This", type M-3 f2 s
117 ;; kiu igas "-- " la separigilon inter which makes "-- " the separator
118 ;; senkomentaria Ada bufro kaj nur- between a no-comments Ada buffer,
119 ;; teksta komentaria bufro. Kiam vi and a plain text comment buffer.
120 ;; denove kuni^gos ilin, ^ciu nevaka When you put them back together,
121 ;; linio de l' dua kolumno denove every non-empty line of the 2nd
122 ;; anta^uhavos "-- ". column will again be preceded by
123 ;; "-- ".
126 ;;; Code:
127 (defgroup two-column nil
128 "Minor mode for editing of two-column text."
129 :prefix "2C-"
130 :group 'frames)
132 (defcustom 2C-mode-line-format
133 '("-%*- %15b --" (-3 . "%p") "--%[(" mode-name
134 minor-mode-alist "%n" mode-line-process ")%]%-")
135 "Value of `mode-line-format' for a buffer in two-column minor mode."
136 :type 'sexp
137 :group 'two-column)
139 (defcustom 2C-other-buffer-hook 'text-mode
140 "Hook run in new buffer when it is associated with current one."
141 :type 'function
142 :group 'two-column)
144 (defcustom 2C-separator ""
145 "A string inserted between the two columns when merging.
146 This gets set locally by \\[2C-split]."
147 :type 'string
148 :group 'two-column)
149 (put '2C-separator 'permanent-local t)
151 (defcustom 2C-window-width 40
152 "The width of the first column. (Must be at least `window-min-width'.)
153 This value is local for every buffer that sets it."
154 :type 'integer
155 :group 'two-column)
156 (make-variable-buffer-local '2C-window-width)
157 (put '2C-window-width 'permanent-local t)
159 (defcustom 2C-beyond-fill-column 4
160 "Base for calculating `fill-column' for a buffer in two-column minor mode.
161 The value of `fill-column' becomes `2C-window-width' for this buffer
162 minus this value."
163 :type 'integer
164 :group 'two-column)
166 (defcustom 2C-autoscroll t
167 "If non-nil, Emacs attempts to keep the two column's buffers aligned."
168 :type 'boolean
169 :group 'two-column)
172 (defvar 2C-mode-map
173 (let ((map (make-sparse-keymap)))
174 (define-key map "2" '2C-two-columns)
175 (define-key map [f2] '2C-two-columns)
176 (define-key map "b" '2C-associate-buffer)
177 (define-key map "s" '2C-split)
178 map)
179 "Keymap for commands for setting up two-column mode.")
181 ;;;###autoload (autoload '2C-command "two-column" () t 'keymap)
182 (fset '2C-command 2C-mode-map)
184 ;; This one is for historical reasons and simple keyboards, it is not
185 ;; at all mnemonic. All usual sequences containing 2 were used, and
186 ;; f2 could not be set up in a standard way under Emacs 18.
187 ;;;###autoload (global-set-key "\C-x6" '2C-command)
189 ;;;###autoload (global-set-key [f2] '2C-command)
191 (defvar 2C-minor-mode-map
192 (let ((map (make-sparse-keymap)))
193 (define-key map "1" '2C-merge)
194 (define-key map "d" '2C-dissociate)
195 (define-key map "o" '2C-associated-buffer)
196 (define-key map "\^m" '2C-newline)
197 (define-key map "|" '2C-toggle-autoscroll)
198 (define-key map "{" '2C-shrink-window-horizontally)
199 (define-key map "}" '2C-enlarge-window-horizontally)
200 map)
201 "Keymap for commands for use in two-column mode.")
203 (setq minor-mode-map-alist
204 (cons (cons '2C-mode
205 (let ((map (make-sparse-keymap)))
206 (substitute-key-definition '2C-command 2C-minor-mode-map
207 map (current-global-map))
208 (substitute-key-definition 'enlarge-window-horizontally
209 '2C-enlarge-window-horizontally
210 map (current-global-map))
211 (substitute-key-definition 'shrink-window-horizontally
212 '2C-shrink-window-horizontally
213 map (current-global-map))
214 map))
215 minor-mode-map-alist))
218 ;; Markers seem to be the only buffer-id not affected by renaming a buffer.
219 ;; This nevertheless loses when a buffer is killed. The variable-name is
220 ;; required by `describe-mode'.
221 (defvar 2C-mode nil
222 "Marker to the associated buffer, if non-nil.")
223 (make-variable-buffer-local '2C-mode)
224 (put '2C-mode 'permanent-local t)
226 (setq minor-mode-alist (cons '(2C-mode " 2C") minor-mode-alist))
228 (defvar 2C-autoscroll-start nil)
229 (make-variable-buffer-local '2C-autoscroll-start)
231 ;;;;; base functions ;;;;;
233 ;; The access method for the other buffer. This tries to remedy against
234 ;; lost local variables and lost buffers.
235 (defun 2C-other (&optional req)
236 (or (if 2C-mode
237 (or (prog1
238 (marker-buffer 2C-mode)
239 (setq mode-line-format 2C-mode-line-format))
240 ;; The associated buffer somehow got killed.
241 (progn
242 ;; The other variables may later be useful if the user
243 ;; reestablishes the association.
244 (kill-local-variable '2C-mode)
245 (kill-local-variable 'mode-line-format)
246 nil)))
247 (if req (error "You must first set two-column minor mode"))))
250 ;; function for setting up two-column minor mode in a buffer associated
251 ;; with the buffer pointed to by the marker other.
252 (defun 2C-mode (other)
253 "Minor mode for independently editing two columns.
254 This is set up for two associated buffers by the three commands bound
255 to \\[2C-two-columns] , \\[2C-associate-buffer] and \\[2C-split].
256 Turning on two-column mode calls the value of the variable `2C-mode-hook',
257 if that value is non-nil.
259 These buffers can be edited separately, for example with `fill-paragraph'.
260 If you want to disable parallel scrolling temporarily, use \\[2C-toggle-autoscroll] .
262 If you include long lines that span both columns (e.g., source
263 code), they should be in what will be the first column, with the
264 associated buffer having empty lines next to them.
266 Potential uses are writing bilingual texts, or editing the comments of a
267 source code. See the file lisp/two-column.el for detailed examples.
269 You have the following commands at your disposal:
271 \\[2C-two-columns] Rearrange screen with current buffer first
272 \\[2C-associate-buffer] Reassociate buffer after changing major mode
273 \\[shrink-window-horizontally], \\[enlarge-window-horizontally] Shrink, enlarge current column
274 \\[2C-associated-buffer] Switch to associated buffer at same point
275 \\[2C-newline] Insert newline(s) in both buffers at same point
276 \\[2C-merge] Merge both buffers
277 \\[2C-dissociate] Dissociate the two buffers
279 These keybindings can be customized in your init file by
280 `2C-mode-map', `2C-minor-mode-map' and by binding `2C-command' to
281 some prefix.
283 The appearance of the screen can be customized by the variables
284 `2C-window-width', `2C-beyond-fill-column', `2C-mode-line-format' and
285 `truncate-partial-width-windows'."
286 (add-hook 'post-command-hook '2C-autoscroll nil t)
287 (setq fill-column (- 2C-window-width
288 2C-beyond-fill-column)
289 mode-line-format 2C-mode-line-format
290 2C-mode other)
291 (run-hooks '2C-mode-hook))
294 ;;;###autoload
295 (defun 2C-two-columns (&optional buffer)
296 "Split current window vertically for two-column editing.
297 \\<global-map>When called the first time, associates a buffer with the current
298 buffer in two-column minor mode (use \\[describe-mode] once in the mode,
299 for details.). It runs `2C-other-buffer-hook' in the new buffer.
300 When called again, restores the screen layout with the current buffer
301 first and the associated buffer to its right."
302 (interactive "P")
303 ;; first go to full width, so that we can certainly split into two windows
304 (unless (window-full-width-p)
305 (enlarge-window 99999 t))
306 (split-window-right
307 (max window-min-width (min 2C-window-width
308 (- (frame-width) window-min-width))))
309 (if (2C-other)
310 (progn
311 (other-window 1)
312 (switch-to-buffer (2C-other))
313 (other-window -1)
314 (if 2C-autoscroll
315 (2C-toggle-autoscroll t)))
317 (2C-mode (prog1 (point-marker)
318 (other-window 1)
319 (switch-to-buffer
320 (or buffer
321 (generate-new-buffer (concat "2C/" (buffer-name)))))
322 (or buffer
323 (run-hooks '2C-other-buffer-hook))))
325 (2C-mode (prog1 (point-marker)
326 (other-window -1)))))
329 ;;;###autoload
330 (defun 2C-associate-buffer ()
331 "Associate another buffer with this one in two-column minor mode.
332 Can also be used to associate a just previously visited file, by
333 accepting the proposed default buffer.
335 \(See \\[describe-mode] .)"
336 (interactive)
337 (let ((b1 (current-buffer))
338 (b2 (or (2C-other)
339 (read-buffer "Associate buffer: " (other-buffer)))))
340 (setq 2C-mode nil)
341 (with-current-buffer b2
342 (and (2C-other)
343 (not (eq b1 (2C-other)))
344 (error "Buffer already associated with buffer `%s'"
345 (buffer-name (2C-other))))
346 (setq b1 (and (assq '2C-window-width (buffer-local-variables))
347 2C-window-width)))
348 ; if other buffer has a local width, adjust here too
349 (if b1 (setq 2C-window-width (- (frame-width) b1)))
350 (2C-two-columns b2)))
352 (autoload 'scroll-bar-columns "scroll-bar")
353 (eval-when-compile
354 (require 'fringe)) ; fringe-columns defsubst
356 ;;;###autoload
357 (defun 2C-split (arg)
358 "Split a two-column text at point, into two buffers in two-column minor mode.
359 Point becomes the local value of `2C-window-width'. Only lines that
360 have the ARG same preceding characters at that column get split. The
361 ARG preceding characters without any leading whitespace become the local
362 value for `2C-separator'. This way lines that continue across both
363 columns remain untouched in the first buffer.
365 This function can be used with a prototype line, to set up things. You
366 write the first line of each column and then split that line. E.g.:
368 First column's text sSs Second column's text
369 \\___/\\
370 / \\
371 5 character Separator You type M-5 \\[2C-split] with the point here.
373 \(See \\[describe-mode] .)"
374 (interactive "*p")
375 (and (2C-other)
376 (if (y-or-n-p (concat "Overwrite associated buffer `"
377 (buffer-name (2C-other))
378 "'? "))
379 (with-current-buffer (2C-other)
380 (erase-buffer))
381 (signal 'quit nil)))
382 (let ((point (point))
383 ;; make next-line always come back to same column
384 (column (current-column))
385 ;; a counter for empty lines in other buffer
386 (n (1- (count-lines (point-min) (point))))
387 chars other)
388 (save-excursion
389 (backward-char arg)
390 (setq chars (buffer-substring (point) point))
391 (skip-chars-forward " \t" point)
392 (make-local-variable '2C-separator)
393 (setq 2C-separator (buffer-substring (point) point)
394 2C-window-width (+ (fringe-columns 'left)
395 (fringe-columns 'right)
396 (scroll-bar-columns 'left)
397 (scroll-bar-columns 'right)
398 (current-column))))
399 (2C-two-columns)
400 (setq other (2C-other))
401 ;; now we're ready to actually split
402 (save-excursion
403 (while (not (eobp))
404 (if (not (and (= (current-column) column)
405 (string= chars
406 (buffer-substring (point)
407 (save-excursion
408 (backward-char arg)
409 (point))))))
410 (setq n (1+ n))
411 (setq point (point))
412 (backward-char arg)
413 (skip-chars-backward " \t")
414 (delete-region point (point))
415 (setq point (point))
416 (insert-char ?\n n)
417 (append-to-buffer other point (progn (end-of-line)
418 (if (eobp)
419 (point)
420 (1+ (point)))))
421 (delete-region point (point))
422 (setq n 0))
423 (forward-line 1)
424 (move-to-column column)))))
427 (defun 2C-dissociate ()
428 "Turn off two-column minor mode in current and associated buffer.
429 If the associated buffer is unmodified and empty, it is killed."
430 (interactive)
431 (let ((buffer (current-buffer))
432 (other (2C-other)))
433 (if other
434 (with-current-buffer other
435 (when (or (not (2C-other)) (eq buffer (2C-other)))
436 (if (and (not (buffer-modified-p)) (zerop (buffer-size)))
437 (kill-buffer)
438 (kill-local-variable '2C-mode)
439 (kill-local-variable '2C-window-width)
440 (kill-local-variable '2C-separator)
441 (kill-local-variable 'mode-line-format)
442 (kill-local-variable 'fill-column))))))
443 (kill-local-variable '2C-mode)
444 (kill-local-variable '2C-window-width)
445 (kill-local-variable '2C-separator)
446 (kill-local-variable 'mode-line-format)
447 (kill-local-variable 'fill-column)
448 (force-mode-line-update))
451 ;; this doesn't use yank-rectangle, so that the first column can
452 ;; contain long lines
453 (defun 2C-merge ()
454 "Merges the associated buffer with the current buffer.
455 They get merged at the column, which is the value of `2C-window-width',
456 i.e. usually at the vertical window separator. This separator gets
457 replaced with white space. Beyond that the value of `2C-separator' gets
458 inserted on merged lines. The two columns are thus pasted side by side,
459 in a single text. If the other buffer is not displayed to the left of
460 this one, then this one becomes the left column.
462 If you want `2C-separator' on empty lines in the second column,
463 you should put just one space in them. In the final result, you can strip
464 off trailing spaces with \\[delete-trailing-whitespace]."
465 (interactive)
466 (and (> (car (window-edges)) 0) ; not touching left edge of screen
467 (eq (window-buffer (previous-window))
468 (2C-other t))
469 (other-window -1))
470 (save-excursion
471 (let ((b1 (current-buffer))
472 (b2 (2C-other t))
473 string)
474 (goto-char (point-min))
475 (set-buffer b2)
476 (goto-char (point-min))
477 (while (not (eobp))
478 (setq string (buffer-substring (point)
479 (progn (end-of-line) (point))))
480 (or (eobp)
481 (forward-char)) ; next line
482 (set-buffer b1)
483 (if (string= string "")
485 (end-of-line)
486 (indent-to-column 2C-window-width)
487 (insert 2C-separator string))
488 (forward-line 1) ; add one if necessary
489 (set-buffer b2))))
490 (unless (window-full-width-p)
491 (enlarge-window 99999 t)))
493 ;;;;; utility functions ;;;;;
495 (defun 2C-associated-buffer ()
496 "Switch to associated buffer."
497 (interactive)
498 (let ((line (+ (count-lines (point-min) (point))
499 (if (bolp) 1 0)))
500 (col (if (eolp) (if (bolp) 0) (current-column))))
501 (if (get-buffer-window (2C-other t))
502 (select-window (get-buffer-window (2C-other)))
503 (switch-to-buffer (2C-other)))
504 (goto-char (point-min))
505 (newline (forward-line (1- line)))
506 (if col
507 (move-to-column col)
508 (end-of-line 1))))
510 (defun 2C-newline (arg)
511 "Insert ARG newlines in both buffers."
512 (interactive "P")
513 (save-window-excursion
514 (2C-associated-buffer)
515 (newline arg))
516 (newline arg))
518 (defun 2C-toggle-autoscroll (arg)
519 "Toggle autoscrolling.
520 With prefix argument ARG, turn on autoscrolling if ARG is
521 positive, otherwise turn it off. When autoscrolling is turned
522 on, this also realigns the two buffers."
523 (interactive "P")
524 ;(sit-for 0)
525 (setq 2C-autoscroll-start (window-start))
526 (if (setq 2C-autoscroll (if arg
527 (>= (prefix-numeric-value arg) 0)
528 (not 2C-autoscroll)))
529 (select-window
530 (prog1 (selected-window)
531 (message "Autoscrolling is on.")
532 (setq arg (count-lines (point-min) (window-start)))
533 (if (get-buffer-window (2C-other t))
534 (progn
535 (select-window (get-buffer-window (2C-other)))
536 (setq arg (- arg (count-lines (point-min) (window-start))))
537 ;; make sure that other buffer has enough lines
538 (save-excursion
539 (insert-char ?\n
540 (- arg (count-lines (window-start)
541 (goto-char (point-max)))
542 -1)))
543 (scroll-up arg)))))
544 (message "Autoscrolling is off.")))
547 (defun 2C-autoscroll ()
548 (if 2C-autoscroll
549 ;; catch a mouse scroll on non-selected scrollbar
550 (select-window
551 (prog1 (selected-window)
552 (and (consp last-command-event)
553 (not (eq (selected-window)
554 (car (car (cdr last-command-event)))))
555 (select-window (car (car (cdr last-command-event)))))
556 ;; In some cases scrolling causes an error, but post-command-hook
557 ;; shouldn't, and should always stay in the original window
558 (ignore-errors
559 (and (or 2C-autoscroll-start (2C-toggle-autoscroll t) nil)
560 (/= (window-start) 2C-autoscroll-start)
561 (2C-other)
562 (get-buffer-window (2C-other))
563 (let ((lines (count-lines (window-start)
564 2C-autoscroll-start)))
565 (if (< (window-start) 2C-autoscroll-start)
566 (setq lines (- lines)))
567 (setq 2C-autoscroll-start (window-start))
568 (select-window (get-buffer-window (2C-other)))
569 ;; make sure that other buffer has enough lines
570 (save-excursion
571 (insert-char
572 ?\n (- lines (count-lines (window-start)
573 (goto-char (point-max)))
574 -1)))
575 (scroll-up lines)
576 (setq 2C-autoscroll-start (window-start)))))))))
579 (defun 2C-enlarge-window-horizontally (arg)
580 "Make current window ARG columns wider."
581 (interactive "p")
582 (enlarge-window arg t)
583 (and (2C-other)
584 (setq 2C-window-width (+ 2C-window-width arg))
585 (set-buffer (2C-other))
586 (setq 2C-window-width (- 2C-window-width arg))))
588 (defun 2C-shrink-window-horizontally (arg)
589 "Make current window ARG columns narrower."
590 (interactive "p")
591 (2C-enlarge-window-horizontally (- arg)))
594 (provide 'two-column)
596 ;;; two-column.el ends here