2.1 Start editing

Just call latex-table-wizard when point is inside of table-like environment.

This commands actually activates the non-global minor mode latex-table-wizard-mode. If you intend to use this package’s commands without the transient interface brought up by latex-table-wizard, activate this minor mode to have the interactive functions loaded.

2.2 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.

With just one of these you can get anywhere you want in the table:

\begin{tabular}{lll}
  A0 & B0 & C0 \\\hline
  A1 & B1 & C1 \\
  A2 & B2 & C2
\end{tabular}

This is because these commands try to Do What You Mean if there is no suitable cell to move to:

• Point on C0, latex-table-wizard-right ⇒ point on A1
• Point on A0, latex-table-wizard-left ⇒ point on C2
• Point on C2, latex-table-wizard-down ⇒ point on A0
• Point on B0, latex-table-wizard-up ⇒ point on A2

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 latex-table-wizard with the key u (bound to 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 A2, both of the following expressions will return nil and won’t move point:

(latex-table-wizard-left 1 t)
(latex-table-wizard-down 1 t)

2.3 Absolute motion commands

2.4 Mark, kill and insert commands

latex-table-wizard-kill-cell-content and 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: latex-table-wizard-yank-cell-content will replace the content of the current cell with whatever that value is.

latex-table-wizard-delete-column and 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).

2.5 Swap adjacent fields

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:

\begin{tabular}{lll}
  A0 & B0    & C0 \\\hline
  A1 & B1 & C1 \\
  A2 & B2 & C2
\end{tabular}

This is because these commands try to Do What You Mean if there is no suitable cell to move to:

Point on C0, latex-table-wizard-swap-cell-right ⇒

\begin{tabular}{lll}
 C0 & B0    & A0 \\\hline
  A1 & B1 & C1 \\
  A2 & B2 & C2
\end{tabular}

Point on B0, latex-table-wizard-swap-row-up ⇒

\begin{tabular}{lll}
 A2 & B2 & C2 \\\hline
  A1 & B1 & C1 \\
 A0 & B0 & C0
\end{tabular}

Point on A1, latex-table-wizard-swap-column-right ⇒

\begin{tabular}{lll}
 B0 & A0 & C0 \\\hline
 B1 & A1 & C1 \\
 B2 & A2 & C2
\end{tabular}

2.6 Swap arbitrary fields

To swap arbitrary fields one must first select something and then move point somewhere else and perform the swap. Importantly, 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:

The first command, 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:

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).

2.7 Comment out cells

These two commands act on all the selected cells, if any is; otherwise, on the current cell point is on.

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.

2.8 Format the table

The only command to format the table is 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.

The following five tables illustrate the effect of calling latex-table-wizard-align repeatedly.

This is the original cell:

\begin{tabular}{lll}
 A2 longer cell & B2  & C2  \\\hline
  A1 & B1 & C1 \\ A0  & B0 \makecell{longer & nested cell}     & C0
\end{tabular}

left aligned:

\begin{tabular}{lll}
 A2 longer cell & B2                                 & C2 \\\hline
 A1             & B1                                 & C1 \\
 A0             & B0 \makecell{longer & nested cell} & C0
\end{tabular}

centered:

\begin{tabular}{lll}
 A2 longer cell &                 B2                 & C2 \\\hline
       A1       &                 B1                 & C1 \\
       A0       & B0 \makecell{longer & nested cell} & C0
\end{tabular}

right aligned:

\begin{tabular}{lll}
 A2 longer cell &                                 B2 & C2 \\\hline
             A1 &                                 B1 & C1 \\
             A0 & B0 \makecell{longer & nested cell} & C0
\end{tabular}

compressed:

\begin{tabular}{lll}
 A2 longer cell & B2 & C2 \\\hline
 A1 & B1 & C1 \\
 A0 & B0 \makecell{longer & nested cell} & C0
\end{tabular}

As you can see, 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 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:

• latex-table-wizard-align-left
• latex-table-wizard-align-right
• latex-table-wizard-center
• latex-table-wizard-compress

2.9 Extra commands in the transient prefix

The transient interfaces invoked by latex-table-wizard also exposes some other commands that are not defined by this package but are useful for its usage. These are:

3.1 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 \\ \\ 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 \\ \\ we will have \\ \blk{} \\.

4.1 Customize transient prefix

To change the default key bindings, you need to provide change the value of the alist latex-table-wizard-transient-keys. The easiest and most convenient way to do it is through 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 kbd takes as arguments).

For example, these three cons cells are members of the default value of latex-table-wizard-transient-keys:

(undo . "//")
(latex-table-wizard-swap-cell-right . "C-f")
(latex-table-wizard-insert-row . "i r")

4.2 Define rules for new environments

Remember the default values used for parsing table environments:

(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)

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 mytable, that uses !ROW and !COL instead of & and \\ as delimiters, and a macro \horizontal for horizontal lines. When you are in a 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 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 defcustom expression:

(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)

You can add the new syntax for the 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:

(add-to-list 'latex-table-wizard-new-environments-alist
             '("mytable" . (:col ("!COL") :row ("!ROW") :lines ("horizontal"))))

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 :lines list are 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 ‘\horizontal{1}’ will be interpreted as a hline macro if in a mytable environment.

4.3 Customizing faces

Calling 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 latex-table-wizard-no-focus to t.

If instead you want effect to be different than the default (which is applying a foreground of color gray40), change the value of the face 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 latex-table-wizard-no-highlight to 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 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 latex-table-wizard-customize.

4.4 Detached arguments

Optional or obligatory arguments can be separated from the macro or from each other in LaTeX. Suppose there is a macro \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 myenv whose \begin macro accepts an optional argument. Is ‘[abc]’ below the optional argument of the environment or content of the first cell?

By default, latex-table-wizard will consider ‘[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 latex-table-wizard-allow-detached-args to t.

If 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: 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, latex-table-wizard-allow-detached-args is nil as per default), you have the option to be warned when 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 latex-table-wizard-warn-about-detached-args to t.