-
Notifications
You must be signed in to change notification settings - Fork 1
/
latex-table-wizard.texi
806 lines (662 loc) · 26.4 KB
/
latex-table-wizard.texi
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
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename latex-table-wizard.info
@settitle @LaTeX{} table wizard - Magic editing of @LaTeX{} tables
@documentencoding UTF-8
@documentlanguage en
@c %**end of header
@finalout
@titlepage
@title @LaTeX{} table wizard - Magic editing of @LaTeX{} tables
@subtitle for version 1.4.0
@author Enrico Flor (@email{enrico@@eflor.net})
@end titlepage
@contents
@ifnottex
@node Top
@top @LaTeX{} table wizard - Magic editing of @LaTeX{} tables
@uref{https://melpa.org/#/latex-table-wizard, file:https://melpa.org/packages/latex-table-wizard-badge.svg}
Copyright (C) 2022, 2023 Enrico Flor.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover Texts
being “A GNU Manual,” and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
“GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
modify this GNU manual.”
@end ifnottex
@menu
* Introduction::
* Available commands::
* Known issues::
* Customization::
* Example setup without Transient interface (Emacs 28 and later)::
@detailmenu
--- The Detailed Node Listing ---
Available commands
* Start editing::
* Relative motion commands::
* Absolute motion commands::
* Mark, kill and insert commands: Mark kill and insert commands.
* Swap adjacent fields::
* Swap arbitrary fields::
* Comment out cells::
* Format the table::
* Extra commands in the transient prefix::
Known issues
* Empty cells in single-column tables::
Customization
* Customize transient prefix::
* Define rules for new environments::
* Customizing faces::
* Detached arguments::
@end detailmenu
@end menu
@node Introduction
@chapter Introduction
One of org-mode's magic features is its table editing capabilities.
The goal of this package is to replicate that magic for @LaTeX{}
table(-like) environments.
The way this is done is through a series of interactive commands that
are exposed as @strong{transient suffixes} through the transient interface
invoked by the command @code{latex-table-wizard}. What this means is that
by calling @code{latex-table-wizard} when point is in a table-like
environment, you will be presented with a choice of keys that are
bound to all the commands provided by this package.
All these commands can of course be called through
@code{execute-extended-command}, and you can bind any key you want to them.
See @ref{Customize transient prefix} for how to change the default bindings
offered by the transient prefix.
An important feature of @LaTeX{}-table-wizard is that it @strong{tries to be
smart}: for instance, it should not be fooled if the current
table-like environments contains @strong{embedded tables} (that is, other
tabular environments inside of its cells). The table is parsed so
that these big cells are treated like any other cell.
For example, if you call @code{latex-table-wizard} when point is outside of
the embedded @code{tabular} environment, @LaTeX{}-table-wizard will behave as if
it was in any other 3x3 table, and the embedded table will be treated
just as any other cell content.
@example
\begin@{tabular@}@{lll@}
\begin@{tabular@}@{ll@}
a & b \\
c & d
\end@{tabular@}
& █B2 & C2 \\\hline
A1 & B1 & C1 \\
A0 & B0 \makecell@{longer & nested cell@} & C0
\end@{tabular@}
@end example
Of course you can call @code{latex-table-wizard} with point inside of the
embedded table, in which case any command you use will operate only on
the embedded table.
For most of this document we will assume the table-like environment
has the standard @LaTeX{}2e syntax, but you can define your own types of
table-like environments (more on this @ref{Define rules for new environments, , below}).
@node Available commands
@chapter Available commands
For now, we will assume a standard @LaTeX{} syntax for tabular
environments, where @code{&} delimits columns and @code{\\} rows (see @ref{Define rules for new environments, , below} for
info as to how to specify additional environments).
Whenever we say ``current'' we mean ``at point''.
@menu
* Start editing::
* Relative motion commands::
* Absolute motion commands::
* Mark, kill and insert commands: Mark kill and insert commands.
* Swap adjacent fields::
* Swap arbitrary fields::
* Comment out cells::
* Format the table::
* Extra commands in the transient prefix::
@end menu
@node Start editing
@section Start editing
Just call @code{latex-table-wizard} when point is inside of table-like
environment.
This commands actually activates the non-global minor mode
@code{latex-table-wizard-mode}. If you intend to use this package's commands
without the transient interface brought up by @code{latex-table-wizard},
activate this minor mode to have the interactive functions loaded.
@node Relative motion commands
@section Relative motion commands
These commands move point N cells to the right, left, down, and up. N
is passed as a prefix argument, and if it's not passed, it defaults
to 1.
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaa}
@headitem Command
@tab Default key
@item @code{latex-table-wizard-right}
@tab @code{f}
@item @code{latex-table-wizard-left}
@tab @code{b}
@item @code{latex-table-wizard-down}
@tab @code{n}
@item @code{latex-table-wizard-up}
@tab @code{p}
@end multitable
With just one of these you can get anywhere you want in the table:
@example
\begin@{tabular@}@{lll@}
A0 & B0 & C0 \\\hline
A1 & B1 & C1 \\
A2 & B2 & C2
\end@{tabular@}
@end example
This is because these commands try to Do What You Mean if there is no
suitable cell to move to:
@itemize
@item
Point on @code{C0}, @code{latex-table-wizard-right} ⇒ point on @code{A1}
@item
Point on @code{A0}, @code{latex-table-wizard-left} ⇒ point on @code{C2}
@item
Point on @code{C2}, @code{latex-table-wizard-down} ⇒ point on @code{A0}
@item
Point on @code{B0}, @code{latex-table-wizard-up} ⇒ point on @code{A2}
@end itemize
and so on.
These four commands accept a positive integer passed as a prefix
argument that determines how many steps (i.e. how many cells) the
movement will consist of. By default, you can pass this argument
from the transient interface of @code{latex-table-wizard} with the key @code{u}
(bound to @code{universal-argument}).
These four commands also accept a second optional argument which, if
non-nil, prevents the Do What You Mean behavior. This is useful if
you want to use these functions to write your own functions to edit
tables. Given the table above, if point is on @code{A2}, both of the
following expressions will return nil and won't move point:
@lisp
(latex-table-wizard-left 1 t)
(latex-table-wizard-down 1 t)
@end lisp
@node Absolute motion commands
@section Absolute motion commands
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Command
@tab Default key
@tab Move to@dots{}
@item @code{latex-table-wizard-beginning-of-cell}
@tab @code{a}
@tab end of current cell
@item @code{latex-table-wizard-end-of-cell}
@tab @code{e}
@tab beginning of current cell
@item @code{latex-table-wizard-beginning-of-row}
@tab @code{B}
@tab leftmost cell in current row
@item @code{latex-table-wizard-end-of-row}
@tab @code{F}
@tab rightmost cell in current row
@item @code{latex-table-wizard-bottom}
@tab @code{N}
@tab bottom cell in current column
@item @code{latex-table-wizard-top}
@tab @code{P}
@tab top cell in current column
@end multitable
@node Mark kill and insert commands
@section Mark, kill and insert commands
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Command
@tab Default key
@tab
@item @code{latex-table-wizard-edit-cell}
@tab @code{.}
@tab edit current cell
@item @code{latex-table-wizard-mark-cell}
@tab @code{m c}
@tab mark current cell
@item @code{latex-table-wizard-insert-column}
@tab @code{i c}
@tab insert empty column to the right
@item @code{latex-table-wizard-insert-row}
@tab @code{i r}
@tab insert row below
@item @code{latex-table-wizard-copy-cell-content}
@tab @code{w}
@tab copy content of current cell
@item @code{latex-table-wizard-yank-cell-content}
@tab @code{y}
@tab replace and yank into current cell
@item @code{latex-table-wizard-kill-cell-content}
@tab @code{k k}
@tab kill content of current cell
@item @code{latex-table-wizard-kill-column-content}
@tab @code{k c}
@tab kill content of current column
@item @code{latex-table-wizard-kill-row-content}
@tab @code{k r}
@tab kill content of current row
@item @code{latex-table-wizard-delete-column}
@tab @code{D c}
@tab delete current column
@item @code{latex-table-wizard-delete-row}
@tab @code{D r}
@tab delete current row
@item @code{exchange-point-and-mark}
@tab @code{x}
@tab
@end multitable
@code{latex-table-wizard-kill-cell-content} and
@code{latex-table-wizard-copy-cell-content} add the content of current cell
both to the kill ring (like the default kill and copy commands) and to
the value of a special variable: @code{latex-table-wizard-yank-cell-content}
will replace the content of the current cell with whatever that value
is.
@code{latex-table-wizard-delete-column} and @code{latex-table-wizard-delete-row}
modify the structure of the table (they actually remove the
column/table, not just the content of the cells in them).
@node Swap adjacent fields
@section Swap adjacent fields
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@headitem Command
@tab Default key
@tab Swap current@dots{}
@item @code{latex-table-wizard-swap-cell-right}
@tab @code{C-f}
@tab cell with the one to the right
@item @code{latex-table-wizard-swap-cell-left}
@tab @code{C-b}
@tab cell with the one to the left
@item @code{latex-table-wizard-swap-cell-down}
@tab @code{C-n}
@tab cell with the one below
@item @code{latex-table-wizard-swap-cell-up}
@tab @code{C-p}
@tab cell with the one above
@item @code{latex-table-wizard-swap-column-right}
@tab @code{M-f}
@tab column with the one to the right
@item @code{latex-table-wizard-swap-column-left}
@tab @code{M-b}
@tab column with the one to the left
@item @code{latex-table-wizard-swap-row-down}
@tab @code{M-n}
@tab row with the one below
@item @code{latex-table-wizard-swap-row-up}
@tab @code{M-p}
@tab row with the one above
@end multitable
For these commands, think of the cells and columns as circular: if
there is no item in the direction given, the target is the one on the
opposite end of the current cell. So for example:
@example
\begin@{tabular@}@{lll@}
A0 & B0 & C0 \\\hline
A1 & B1 & C1 \\
A2 & B2 & C2
\end@{tabular@}
@end example
This is because these commands try to Do What You Mean if there is no
suitable cell to move to:
Point on @code{C0}, @code{latex-table-wizard-swap-cell-right}
⇒
@example
\begin@{tabular@}@{lll@}
C0 & B0 & A0 \\\hline
A1 & B1 & C1 \\
A2 & B2 & C2
\end@{tabular@}
@end example
Point on @code{B0}, @code{latex-table-wizard-swap-row-up}
⇒
@example
\begin@{tabular@}@{lll@}
A2 & B2 & C2 \\\hline
A1 & B1 & C1 \\
A0 & B0 & C0
\end@{tabular@}
@end example
Point on @code{A1}, @code{latex-table-wizard-swap-column-right}
⇒
@example
\begin@{tabular@}@{lll@}
B0 & A0 & C0 \\\hline
B1 & A1 & C1 \\
B2 & A2 & C2
\end@{tabular@}
@end example
@node Swap arbitrary fields
@section Swap arbitrary fields
To swap arbitrary fields one must first @strong{select} something and then move
point somewhere else and perform the swap. Importantly, @strong{selecting
does not mean marking}: the mark is not even moved when selecting
(however, by default the selected cell will receive the same kind of
highlighting the loaded theme defines for the active region, but this
is a purely graphical equivalence). ``Selecting'', for the purposes of
@LaTeX{}-table-wizard only means storing a cell, a line or a row to be
swapped with another.
The simplest case is one in which the current cell, column or row are
selected:
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaa}
@headitem Command
@tab Default key
@tab Select current@dots{}
@item @code{latex-table-wizard-select-deselect-cell}
@tab @code{SPC}
@tab select/deselect cell
@item @code{latex-table-wizard-select-column}
@tab @code{c}
@tab select column
@item @code{latex-table-wizard-select-row}
@tab @code{r}
@tab deselect row
@item @code{latex-table-wizard-deselect-all}
@tab @code{d}
@tab deselect all
@end multitable
The first command, @code{latex-table-wizard-select-deselect-cell} toggles the
status of the current cell as being selected or not.
Once things are selected, you move point somewhere else in the table
(with the above mentioned motion commands), and then:
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaa} {aaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item @code{latex-table-wizard-swap}
@tab @code{s}
@tab swap selection and current thing
@end multitable
What is swapped depends on what is selected: if the selection was only
a cell, then that cell and the current one are swapped. If it was (a
potentially discontinuous segment of) a column or a row, then that
selection is swapped with the current column or row or the
corresponding portion thereof. If you selected multiple cell that are
not part of the same column or row, the swap won't happen
(@LaTeX{}-table-wizard doesn't know what you want it to do in that case).
@node Comment out cells
@section Comment out cells
These two commands act on all the selected cells, if any is;
otherwise, on the current cell point is on.
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaa}
@headitem Command
@tab Default key
@tab Select current@dots{}
@item @code{latex-table-wizard-comment-out-content}
@tab @code{; c}
@tab comment out content
@item @code{latex-table-wizard-comment-out}
@tab @code{; ;}
@tab comment out
@end multitable
The difference between the two is that one only comments out the
content, preserving both delimiters around the cell; the other one
actually modifies the structure of the table because for any cell that
is commented out, one delimiter around it is commented out too.
@node Format the table
@section Format the table
The only command to format the table is @code{latex-table-wizard-align}. The
behavior of this command is cyclic, in the sense that calling it
repeatedly causes the table to cycle through four types of formatting:
left aligned, centered, right aligned and compressed. The latter
state is actually not one of alignment (that is, the column separators
are not vertically aligned): it just means that all the extra space at
the beginning and end of each cell is collapsed into one.
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaa}
@headitem Command
@tab Default key
@item @code{latex-table-wizard-align}
@tab @code{TAB}
@end multitable
The following five tables illustrate the effect of calling
@code{latex-table-wizard-align} repeatedly.
This is the original cell:
@example
\begin@{tabular@}@{lll@}
A2 longer cell & B2 & C2 \\\hline
A1 & B1 & C1 \\ A0 & B0 \makecell@{longer & nested cell@} & C0
\end@{tabular@}
@end example
left aligned:
@example
\begin@{tabular@}@{lll@}
A2 longer cell & B2 & C2 \\\hline
A1 & B1 & C1 \\
A0 & B0 \makecell@{longer & nested cell@} & C0
\end@{tabular@}
@end example
centered:
@example
\begin@{tabular@}@{lll@}
A2 longer cell & B2 & C2 \\\hline
A1 & B1 & C1 \\
A0 & B0 \makecell@{longer & nested cell@} & C0
\end@{tabular@}
@end example
right aligned:
@example
\begin@{tabular@}@{lll@}
A2 longer cell & B2 & C2 \\\hline
A1 & B1 & C1 \\
A0 & B0 \makecell@{longer & nested cell@} & C0
\end@{tabular@}
@end example
compressed:
@example
\begin@{tabular@}@{lll@}
A2 longer cell & B2 & C2 \\\hline
A1 & B1 & C1 \\
A0 & B0 \makecell@{longer & nested cell@} & C0
\end@{tabular@}
@end example
As you can see, @code{latex-table-wizard-align} also forces every row of the
table to start on its own line.
As always, this alignment command tries to be smart and not be fooled
by column or row delimiters embedded in a cell.
Beside @code{latex-table-wizard-align} with its cycling behavior, four
commands are defined (but not exposed by the transient interface),
each of which just performs one of these transformations. These are:
@itemize
@item
@code{latex-table-wizard-align-left}
@item
@code{latex-table-wizard-align-right}
@item
@code{latex-table-wizard-center}
@item
@code{latex-table-wizard-compress}
@end itemize
@node Extra commands in the transient prefix
@section Extra commands in the transient prefix
The transient interfaces invoked by @code{latex-table-wizard} also exposes
some other commands that are not defined by this package but are
useful for its usage. These are:
@multitable {aaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaa}
@headitem Command
@tab Default key
@item @code{toggle-truncate-lines}
@tab @code{t}
@item @code{undo}
@tab @code{/}
@item @code{exchange-point-and-mark}
@tab @code{x}
@item @code{universal-argument}
@tab @code{u}
@item @code{transient-quit-one}
@tab @code{RET}
@end multitable
@node Known issues
@chapter Known issues
@menu
* Empty cells in single-column tables::
@end menu
@node Empty cells in single-column tables
@section Empty cells in single-column tables
This package handles empty cells (that is, cells without any text in
them except perhaps comments) well. The only exception is in tables
with a single column. The problem is that a buffer substring like
@code{\\ \\} is not parsed as a cell. This is normally not a problem, but if
the table has only one column then that substring could be meant to be
an empty or blank cell.
A way to avoid this problem may be defining a @LaTeX{} macro that does
nothing, and use it in the cell you intend to be empty so that the
parser sees some text.
So instead of @code{\\ \\} we will have @code{\\ \blk@{@} \\}.
@node Customization
@chapter Customization
To quickly access all customizations pertinent to @LaTeX{}-table-wizard
through the Customize interface, call @code{latex-table-wizard-customize}.
@menu
* Customize transient prefix::
* Define rules for new environments::
* Customizing faces::
* Detached arguments::
@end menu
@node Customize transient prefix
@section Customize transient prefix
To change the default key bindings, you need to provide change the
value of the alist @code{latex-table-wizard-transient-keys}. The easiest and
most convenient way to do it is through @code{latex-table-wizard-customize}.
Each cons cell in this alist maps a command to a key description
string (the kind of strings that the macro @code{kbd} takes as arguments).
For example, these three cons cells are members of the default value of
@code{latex-table-wizard-transient-keys}:
@lisp
(undo . "//")
(latex-table-wizard-swap-cell-right . "C-f")
(latex-table-wizard-insert-row . "i r")
@end lisp
@node Define rules for new environments
@section Define rules for new environments
Remember the default values used for parsing table environments:
@lisp
(defcustom latex-table-wizard-column-delimiters '("&")
"List of strings that are column delimiters if unescaped."
:type '(repeat string)
:group 'latex-table-wizard)
(defcustom latex-table-wizard-row-delimiters '("\\\\")
"List of strings that are row delimiters if unescaped."
:type '(repeat string)
:group 'latex-table-wizard)
(defcustom latex-table-wizard-hline-macros '("cline"
"vline"
"midrule"
"hline"
"toprule"
"bottomrule")
"Name of macros that draw horizontal lines.
Each member of this list is a string that would be between the
\"\\\" and the arguments."
:type '(repeat string)
:group 'latex-table-wizard)
@end lisp
@LaTeX{}-table-wizard will always presume the table you want operate on
has a syntax specified like this. But suppose you use different
environments with non-standard syntax: suppose you define a
table-like environment of your choice, let's call it @code{mytable}, that
uses @code{!ROW} and @code{!COL} instead of @code{&} and @code{\\} as delimiters, and a macro
@code{\horizontal} for horizontal lines. When you are in a @code{mytable}
environments, you want @LaTeX{}-table-wizard to adapt to this new
syntax.
All you need to do add an appropriate cons cell to the
@code{latex-table-wizard-new-environments-alist} association list, mapping
the name of the environment, as a string, to a property list
specifying the values. Here is this variable's @code{defcustom} expression:
@lisp
(defcustom latex-table-wizard-new-environments-alist nil
"Alist mapping environment names to property lists.
The environment name is a string, for example \"foo\" for an
environment like
\\begin@{foo@}
...
\\end@{foo@}
The cdr of each mapping is a property list with three keys:
:col
:row
:lines
The values for :col and :row are two lists of strings.
The value for :lines is a list of strings just like is the case
for `latex-table-wizard-hline-macros', each of which is the name
of a macro that inserts some horizontal line. For a macro
\"\\foo@{@}\", use string \"foo\"."
:type '(alist :key-type (string :tag "Name of the environment:")
:value-type (plist :key-type symbol
:options (:col :row :lines)
:value-type (repeat string)))
:group 'latex-table-wizard)
@end lisp
You can add the new syntax for the @code{mytable} environment through the
Customize interface, which will present you with the correct values to
set, or you can just add a cons cell of your writing to the alist:
@lisp
(add-to-list 'latex-table-wizard-new-environments-alist
'("mytable" . (:col ("!COL") :row ("!ROW") :lines ("horizontal"))))
@end lisp
Each of the values in the plist is a list of strings: this way you can
define environments that can use more than one type of column
separator. Importantly, the strings in the @code{:lines} list are @strong{names of
@LaTeX{}} macros, which means that they should not start with the
backslash and you should not add any argument to them. In the example
above a buffer substring like @samp{\horizontal@{1@}} will be interpreted as a
hline macro if in a @code{mytable} environment.
@node Customizing faces
@section Customizing faces
Calling @code{latex-table-wizard} by default causes the portions of the
buffer before and after the table at point to be ``grayed out'', so
that you can clearly focus on the table. If you don't want this to
happen, set the value of the variable @code{latex-table-wizard-no-focus} to
@code{t}.
If instead you want effect to be different than the default (which is
applying a foreground of color @code{gray40}), change the value of the face
@code{latex-table-wizard-background}.
By default, when you move around the table and select objects from it
the relevant portions of the table are highlighted. If you don't
want this to happen, set the value of the variable
@code{latex-table-wizard-no-highlight} to @code{t}.
If instead you want the highlighting to be done differently than the
default (which is applying a background of the same color as the
loaded theme defines for the active region), change the value of the
face @code{latex-table-wizard-highlight}.
The easiest and most convenient way to set these variables,
especially the two faces, is through the Customize interface, which
you can access quickly by calling @code{latex-table-wizard-customize}.
@node Detached arguments
@section Detached arguments
Optional or obligatory arguments can be separated from the macro or
from each other in @LaTeX{}. Suppose there is a macro @code{\macro} that takes
one optional and one obligatory argument. Now, @LaTeX{} can deal with
all of the following forms:
This fact matters for this package for several reasons but the most
important is that, in parsing the table, we need to know where the
table content starts. Suppose you defined a tabular like environment
@code{myenv} whose @code{\begin} macro accepts an optional argument. Is @samp{[abc]} below
the optional argument of the environment or content of the first cell?
By default, @code{latex-table-wizard} will consider @samp{[abc]} part of the first
cell in the example above, because it does not recognize the
possibility for the arguments of @LaTeX{} macros to be detached. If you
want to change this default, set the value of
@code{latex-table-wizard-allow-detached-args} to t.
If @code{latex-table-wizard-allow-detached-args} is set to t (that is, if
detached arguments are allowed), you should not have in your table
strings between braces or brackets after a macro without them be
separated by a blank line, unless these strings between braces or
brackets are in fact the arguments of the macro. This is not a
problem for @LaTeX{}, because it knows what is a valid macro and what
isn't, and how many arguments a macro accepts: @code{latex-table-wizard}
however does not know it and it could get confused while parsing, and
thus get the start of the first cell wrong.
Good practice is to never separate arguments from each other or from
the @LaTeX{} macro: if you respect this good practice, you will never
need to be concerned with this customization.
If detached arguments are ``disallowed'' (that is,
@code{latex-table-wizard-allow-detached-args} is nil as per default), you
have the option to be warned when @code{latex-table-wizard} finds cases of
suspect detached arguments. The warning is just a message in the echo
area right after the table is parsed. If you want this, set the value
of @code{latex-table-wizard-warn-about-detached-args} to t.
@node Example setup without Transient interface (Emacs 28 and later)
@chapter Example setup without Transient interface (Emacs 28 and later)
Since the interactive commands work independently from the
functionalities provided by transient.el, you can build your own
alternative interfaces easily if you prefer so. For example, the code
below uses @code{repeat-mode} (built-in with Emacs 28 and later):
@lisp
(require 'repeat)
(define-prefix-command 'latex-table-wizard-map)
(define-key global-map (kbd "C-c C-|") 'latex-table-wizard-map)
(dolist (c latex-table-wizard-transient-keys)
(define-key latex-table-wizard-map (kbd (cdr c)) (car c)))
(dolist (cmd (mapcar #'car latex-table-wizard-transient-keys))
(put cmd 'repeat-map 'latex-table-wizard-map))
@end lisp
@bye