> This is "ManipCols Help", help file for the columns manipulation package in Alpha. This file should be located in the Help subfolder of Alpha's folder to show up automatically in the Help menu when Alpha is loaded.

- Introduction
- Installation
  - Automatic installation
  - Manual installation
  - Activating the manipCols feature
  - After installing
- Basics
  - Columns selection
  - Columns separator
  - Caveat
  - Text columnizing
  - More examples
- Menu Items
  - Main columns menu
  - Columns formatting submenu
  - Columns sorting submenu
  - Columns utilities submenu
- Key Bindings
- Preferences
- Version History
- More Cols Package
- Known problems
  - Troubleshooting
  - Bugs report
- License terms

## Introduction

The 'manipCols' package is a feature which allows to do various manipulations with the columns of any tabulated material i-e a series of lines in which items are separated by a tabulation or by any other specific character (like & or a tabulation or a colon, a comma, an endash etc. or even the space character). Once it is installed and activated, it adds a submenu called Columns to the Text menu in Alpha. The items of this submenu are explained below. Basic manipulations are copying, inserting, appending, twiddling, deleting, sorting, numbering and (un/)equalizing columns, formating text in columns.

## Installation

### Automatic installation

Open the "OPEN TO INSTALL" file. Opening this file indicates to Alpha that a new package has to be installed : the procedure is automatic. Alpha knows where to store the different elements of your manipCols package.

### Manual installation

1. put the "manipCols.tcl" file in the "Packages" subfolder of the "Tcl" folder which is located at the same level as your Alpha application
2. put the "ManipCols Help" file in the "Help" folder located at the same level as your Alpha application. Next time you launch Alpha, you will have a "ManipCols Help" item in the Help menu.
3. launch Alpha. You have to rebuild the package indices and the Tcl indices. Rebuild Package Indices is in the Config-Packages menu, and Rebuild Tcl Indices is in the Tcl menu.
4. quit Alpha and relaunch it : that's all there is to it.

### Activating the manipCols feature

Go to "Config--Preferences--Menus and Features" and select 'Manip Cols' in the features list by checking the corresponding checkbox.

### After installing

Have a look at the Manip Cols preferences in the Packages submenu of the Config menu. More explanations below.

## Basics

### Columns selection

to select one or several columns, put the cursor anywhere in the text of the top left item (or "cell") you want to select, press the mouse button and, without releasing the button, go to the text of the bottom right item you want to select. This will hilite a region which is much more than what you want but the package will consider only the columns located between the top and bottom positions. Here is an example (from Romeo and Juliet). We suppose here that each word is separated by a tabulation (any single character can be chosen as a separator, even the space character; see below) :

Gallop | apace, | you | fiery-footed | steeds,
Towards | Phoebus' | lodging; | such | a | waggoner
As | Phaethon | would | whip | you | to | the | west,
And | bring | in | cloudy | night | immediately.

Put the cursor in the word 'you' (first row, third word), press the mouse button and, without releasing it, go to the word 'whip' in the third row, then release : you have selected the following region you fiery-footed lodging; such would whip

even though all the words from 'you' to 'whip' are hilited. We have thus selected columns 3-4 and rows 1-3. It is sometimes difficult to be sure what has been selected because columns are not aligned vertically so you can check this using the Colorize Columns menu item : only the selected columns will be colorized like so

Gallop | apace, | you | fiery-footed | steeds,
Towards | Phoebus' | lodging; | such | a | waggoner
As | Phaethon | would | whip | you | to | the | west,
And | bring | in | cloudy | night | immediately.

So dragging the mouse from position (a,b) in a table to position (c,d) selects columns 'a' to 'c' and rows 'b' to 'd'.

If you want to have a better vertical alignment of your columns you can use the Equalize Columns menu item. Select the region as above and select Equalize Columns in the Columns menu. The result will be :

Gallop | apace, | you | fiery-footed | steeds,
Towards | Phoebus' | lodging; | such | a | waggoner
As | Phaethon | would | whip | you | to | the | west,
And | bring | in | cloudy | night | immediately.

By the way, equalizing makes it very easy to use rectangular hiliting : select a region with the mouse holding the option key down.

### Columns separator

It must NECESSARILY be a SINGLE character. Default is the tabulation character \t. With Latex you might want to choose '&' as a separator for \array or \table environments:

         \begin{tabular}{|c|c|c|}
     	\hline
         you & fiery-footed \\
         lodging; & such \\
         would & whip \\
     	\hline
         \end{tabular}

You can even use the 'space' character as a separator. See also the Columns to Latex item below.

### Caveat

- the cursor can be positioned anywhere in a "cell" : the entire column will always be selected.
- you do not have necessarily to colorize the selected region. This is just handy for visualisation. BEWARE that this procedure removes all other colors in your document (this proc might be improved later).
- columns are numbered from 1 to n (see the messages in the status bar).
- hiliting must still be there if you want to apply a manipulation like copying, inserting, appending, twiddling, deleting columns.
- note that (since version 0.5b) you DO NOT have anymore to escape (i-e put a backslash before) the special characters like 'backslash' \ or 'dollar' $ or 'circumflex' ^ or 'endash' - etc. The package takes care of this internally. The tabulation character though is represented by '\t'.
- all the actions are undoable (with cmd-Z).

### Text columnizing

There are tools to format text in vertical justified columns (single or multiple). This will be very handy to prepare nice looking documentations, help files, etc. All the paragraphs in the present file have been justified with this tool. Everything is parametrizable: number of columns, left margin, text width. Here an example of multicolumnizing :

Gallop apace, you | to the west, and bring in | That runaways' eyes may
fiery-footed steeds, | cloudy night immediately. | wink, and Romeo leap to
towards Phoebus' lodging; | Spread thy close curtain, | these arms, untalk'd-of,
such a waggoner as | love performing night! | and unseen !
Phaethon would whip you

### More examples

You can now select a region and experiment : here are some examples applied to the previous selection.

'Deleting'

Gallop | apace, | steeds,
Towards | Phoebus' | a | waggoner
As | Phaethon | you | to | the | west,
And | bring | in | cloudy | night | immediately.

'Copying, selecting the first two lines and appending'

Gallop | apace, | you | fiery-footed | steeds, | you | fiery-footed
Towards | Phoebus' | lodging; | such | a | waggoner | lodging; | such
As | Phaethon | would | whip | you | to | the | west,
And | bring | in | cloudy | night | immediately.

'Copying, selecting the second column and inserting'

Gallop | you | fiery-footed | apace, | you | fiery-footed | steeds,
Towards | lodging; | such | Phoebus' | lodging; | such | a | waggoner
As | would | whip | Phaethon | would | whip | you | to | the | west,
And | bring | in | cloudy | night | immediately.

'Twiddling'

Gallop | apace, | fiery-footed | you | steeds,
Towards | Phoebus' | such | lodging; | a | waggoner
As | Phaethon | whip | would | you | to | the | west,
And | bring | in | cloudy | night | immediately.

'Sorting Columns'

Gallop | apace, | lodging; | such | steeds,
Towards | Phoebus' | would | whip | a | waggoner
As | Phaethon | you | fiery-footed | you | to | the | west,
And | bring | in | cloudy | night | immediately.

'Selecting the first two lines and reverse sorting rows'

you | steeds, | apace, | Gallop | fiery-footed
waggoner | Towards | such | Phoebus' | lodging; | a
As | Phaethon | would | whip | you | to | the | west,
And | bring | in | cloudy | night | immediately.

'Selecting all four lines and inserting rows numbers'

1 | Gallop | apace, | you | fiery-footed | steeds,
2 | Towards | Phoebus' | lodging; | such | a | waggoner
3 | As | Phaethon | would | whip | you | to | the | west,
4 | And | bring | in | cloudy | night | immediately.

etc. etc.

## Menu Items

Almost all of these items suppose you have selected columns : see above how to select columns.

### Main columns menu

Copy Columns

Copy the selected columns in the MacOS system scrap. Note that if no region has been selected or hilited, the entire line containing the cursor will be copied.

Insert Columns

Insert columns from the system scrap BEFORE the first selected column.

Append Columns

Append columns contained in the system scrap to the right of the selected lines. The procedure will append as much as it can : if you have selected a region with less rows than the material contained in the system scrap, it will ignore the remaining lines.

Cut Columns

Delete the selected columns and send a copy to the system scrap so that they may be pasted, inserted, appended elsewhere. All the columns to the right of the selection will be shifted left.

Delete Columns

Delete the selected columns.

Twiddle Columns

Exchange the leftmost and right most columns of your selection. Note that there must be enough elements on each row to allow twiddling : if not the procedure will fail and send an alert. This can easily been solved by using the Complete Rows item.

Transpose Columns

Transpose columns and rows. All rows must have the same number of cells. The entire row is transposed even if you select only a portion.

Colorize Columns

Colorize the selected items. This is useful to visualize a selected region and control that it contains what you want. Please note that you will lose any colorization you did previously in your file. This point should be improved later. So use with care.

### Columns formatting submenu

Equalize Columns

This proc calculates the maximum length of each of the selected columns and appends the necessary amount of blank space so that each column has a unique width. This allows a perfect vertical alignment to make selections easier. Equalizing columns makes it very easy to use rectangular hiliting : select a region with the mouse holding the option key down.

Unequalize Columns

This is the opposite of the previous items : any blank space at the right of a "cell" will be trimed.

Complete Rows

In case all the rows do not have the same "length" (i-e number of items), this procedure will add empty cells to the incomplete rows.

Right Justify

To right justify the selected columns.

Center

To center the selected columns.

Left Justify

To left justify the selected columns.

Insert Rows Numbers

Insert the number of the row at the beginning of the selected lines. Numbers are separated by the current separator and constitute a separate column.

Insert Numbers From...

The same as the previous except that you are prompted to choose the starting number. The last number reached in a previous numbering is proposed as a default choice.

Columnize Text

To justify the selected text : it is left and right justified vertically in a rectangle. The values for the left margin and for the total text width can be set with the Set Margins item. Default values in Text mode are 5 and 75.

Multi Columnize Text

To put text in multiple columns like in a newspaper. You are prompted in the status bar to choose the number of columns (default value is 2).

Uncolumnize Text

To undo the previous command : all the columns of a table will be put one over the other in a single column.

### Columns sorting submenu

Sort Columns

Reverse Sort Columns

Num Sort Columns

Reverse Num Sort Columns

This allows different kinds of sorting of columns in the selected region. Sorting can be done in increasing or decreasing order, in litteral (1 before 11 before 2) or numerical order (1 before 2 before 11). Sorting is case insensitive. If several columns are included in the selected region, sorting applies to the left one.

Sort Rows

Reverse Sort Rows

Num Sort Rows

Reverse Num Sort Rows

This allows different kinds of sorting of each entire row in the selected region. Sorting can be done in increasing or decreasing order, in litteral (1 before 11 before 2) or numerical order (1 before 2 before 11). Sorting is case insensitive.

### Columns utilities submenu

Set Margins

You will be prompted in the status bar to set the values for the left margin and the total text width.

Columns Separator

Change here the character considered as columns separator. Remember that you must choose a SINGLE character :if not, some procs might not work properly. It can be of course the tabulation character represented by \t. This menu item allows to do temporary changes (as long as you do not quit Alpha). To change the Columns Separator permanently go to the manipCols Preferences.

Columns Bindings

Brings a window with information about the key bindings available when the manipCols package is active. See below.

Columns Tutorial

Brings a window with a tutorial file.

## Key Bindings

All the key bindings will use 'ctrl-c' (c for columns !). Hit 'ctrl-c', release, then hit one of the following letters :

ctrl-c a | to append columns
ctrl-c b | to show info about bindings
ctrl-c c | to copy columns
ctrl-c d | to delete columns
ctrl-c e | to equalize columns (left justified)
ctrl-c f | to insert rows numbers from a certain value
ctrl-c i | to insert columns
ctrl-c j | to justify text (not columns)
ctrl-c k | to kolorize kolumns
ctrl-c m | to center columns (m for middle)
ctrl-c n | to insert rows numbers
ctrl-c o | to sort each row in increasing order
ctrl-c p | to complete rows
ctrl-c r | to right justify columns
ctrl-c s | to change the columns separator
ctrl-c t | to transpose columns and rows
ctrl-c u | to unequalize columns
ctrl-c v | to set the margin values for columnizing
ctrl-c w | to twiddle columns
ctrl-c x | to cut columns (extract them and copy in system scrap)
ctrl-c z | to uncolumnize

If you use the 'More Cols' package (see below), you four more key bindings :

ctrl-c h | to convert a table to html code
ctrl-c l | to convert a table to a latex tabular environment

## Preferences

The Manip Cols Prefs... item in the Packages submenu of the Config menu allows you to make a few choices :

- the Columns Color variable allows you to choose the color in which to colorize the selected columns.
- the Columns Separator variable allows you to choose the default character used to separate columns : this is the separator which will be used each time you launch Alpha and as long as you do not override this choice with the Columns Separator menu item.
- the Min Columns Width variable allows you to set the minimum width allowed for columns when using the Text Columnizing tool.

## Version History

- 0.1b -- 05/27/00 -- First writing of this package.
- 0.2b -- 05/29/00 -- Changed 'ctrl-k' to 'ctrl-c' for keybindings. Rearranged the menu items.
- 0.3b -- 05/31/00 -- Added a Cut Columns item. Added tools for text columnizing. Added new key bindings.
- 0.4b -- 06/02/00 -- Corrected a bug in backward search. Made changes for Alphatk compatibility.
- 0.5b -- 06/03/00 -- Made the problem of special characters to escape invisible for the user : it is done internally.
- 0.6b -- 06/03/00 -- Changed the routine to split a region in paragraphs.
- 0.7b -- 07/01/00 -- Added items to convert a table to HTML code or to a LaTeX tabular environment. Items to do the reverse. Html nested tables are handled.
- 0.8b -- 08/17/00 -- The conversion of tables to Html or Latex formats are now an independant feature coming as a complement to manipCols.
- 0.9b -- 09/20/00 -- Added a "Colums Tutorial" item to link to the Example file.
- 1.0 -- 10/06/00 -- Added procs to justify some columns (left, right, center). The columns equalization now work on the selected columns and not on the entire table.
- 1.0.1 -- 07/10/00 -- Change a proc name (help::openExample instead of file::hyperExampleOpen)
- 1.0.2 -- 16/02/01 -- Corrected a bug (misplaced switch item in three procs) which had no effect in Alpha 7 but crashes Alpha 8.
- 1.1 -- 17/02/01 -- Changed the code to store all global variables in an array. Changed the package's type from extension to feature so that it now removes itself properly. Changed all buttonAlert instructions for PreAlpha8 compatibility. Changed license to BSD.
- 1.1.1 -- 13/04/01 -- Corrected a binding (broken after rearrangement).
- 1.1.2 -- 23/06/01 -- Updated colorizing to new text::color proc.
- 1.2 -- 09/08/02 -- Added transposition of rows and columns.

## More Cols Package

The 'More Cols' Package (moreCols.tcl) adds a few more capacities to the 'Manip Cols' Package. It allows conversion of text tables to and from Html or Latex formats. When it is activated, a new submenu called Tables Conversion is added at the bottom of the Columns menu. It contains the following items :

Columns to Html

Converts an ordinary text table to HTML code to export to an Html document.

Columns to Latex

Converts an ordinary text table to a LaTeX 'tabular' environment.

Columns to Html

or

Latex to Columns

They convert an HTML table or a Latex 'tabular' (or 'array') environment to a simple text tabulated with the current 'columns separator'. Nested HTML tables are handled.

## Known problems

### Troubleshooting

If sometimes a proc does not do what you expect it to do, it is very often because you have changed the columns separator and still think it is another one. For instance if you change the separator from '\t' to a blank space ' ', any word will be considered in a different column whereas two words separated by a tab will be considered in the same column. And vice versa.

### Bugs report

Please e-mail any problem or bug you encounter : bdesgraupes@easyconnect.fr

Visit my Web page for updates and other Alpha utilities :

http://webperso.easyconnect.fr/bdesgraupes/alpha.html

## License terms

This software is free software distributed under the terms of the new BSD license : Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of Bernard Desgraupes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the regents or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.