[elpa] externals/latex-table-wizard 230bb852fa 43/70: Add .texi file

[ELPA Syncer]

branch: externals/latex-table-wizard
commit 230bb852fad8be9ff5e29f8bf85dc5c6f348647d
Author: Enrico Flor <nericoflor@gmail.com>
Commit: Enrico Flor <nericoflor@gmail.com>

    Add .texi file
---
 latex-table-wizard.texi | 658 ++++++++++++++++++++++++++++++++++++++++++++++++
 wizard-01.gif           | Bin 309942 -> 0 bytes
 2 files changed, 658 insertions(+)

diff --git a/latex-table-wizard.texi b/latex-table-wizard.texi
new file mode 100644
index 0000000000..ebeafbf2c4
--- /dev/null
+++ b/latex-table-wizard.texi
@@ -0,0 +1,658 @@
+\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.0.0
+@author Enrico Flor (@email{enrico@@eflor.net})
+@end titlepage
+
+@contents
+
+@ifnottex
+@node Top
+@top @LaTeX{} table wizard - Magic editing of @LaTeX{} tables
+
+Copyright (C) 2022 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::
+
+@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::
+* 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::
+
+@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::
+* 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}).
+
+@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 {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaa} 
{aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
+@headitem Command
+@tab Default key
+@tab
+@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-kill-column}
+@tab @code{k c}
+@tab add content of current column to kill ring
+@item @code{latex-table-wizard-kill-row}
+@tab @code{k r}
+@tab add content of current row to kill ring
+@item @code{exchange-point-and-mark}
+@tab @code{x}
+@tab
+@end multitable
+
+@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 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.
+
+@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::
+@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}.
+
+@bye
diff --git a/wizard-01.gif b/wizard-01.gif
deleted file mode 100644
index a69e48f5e1..0000000000
Binary files a/wizard-01.gif and /dev/null differ