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

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

Gallopapace,youfiery-footedsteeds,
TowardsPhoebus'lodging;suchawaggoner
AsPhaethonwouldwhipyoutothewest,
Andbringincloudynightimmediately.

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

Gallopapace,youfiery-footedsteeds,
TowardsPhoebus'lodging;suchawaggoner
AsPhaethonwouldwhipyoutothewest,
Andbringincloudynightimmediately.

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-footedsteeds,
TowardsPhoebus'lodging;such a waggoner
As Phaethonwould whip you to thewest,
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

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, youto the west, and bring inThat 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 aslove 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,
TowardsPhoebus'a waggoner
As Phaethonyou to the west,
And bring in cloudy night immediately.

'Copying, selecting the first two lines and appending'

Gallop apace, you fiery-footedsteeds,you fiery-footed
TowardsPhoebus'lodging;such a waggoner lodging; such
As Phaethonwould whip you to the west,
And bring in cloudy night immediately.

'Copying, selecting the second column and inserting'

Gallop you fiery-footedapace, you fiery-footedsteeds,
Towardslodging;such Phoebus'lodging;such a waggoner
As would whip Phaethonwould whip you to thewest,
And bring in cloudy night immediately.

'Twiddling'

Gallop apace, fiery-footedyou steeds,
TowardsPhoebus'such lodging;a waggoner
As Phaethonwhip would you to thewest,
And bring in cloudy night immediately.

'Sorting Columns'

Gallop apace, lodging;such steeds,
TowardsPhoebus'would whip a waggoner
As Phaethonyou fiery-footedyou to thewest,
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 Phaethonwould whip you to thewest,
And bring in cloudy night immediately.

'Selecting all four lines and inserting rows numbers'

1Gallop apace, you fiery-footedsteeds,
2TowardsPhoebus'lodging;such a waggoner
3As Phaethonwould whip you to thewest,
4And 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 ato append columns
ctrl-c bto show info about bindings
ctrl-c cto copy columns
ctrl-c dto delete columns
ctrl-c eto equalize columns (left justified)
ctrl-c fto insert rows numbers from a certain value
ctrl-c ito insert columns
ctrl-c jto justify text (not columns)
ctrl-c kto kolorize kolumns
ctrl-c mto center columns (m for middle)
ctrl-c nto insert rows numbers
ctrl-c oto sort each row in increasing order
ctrl-c pto complete rows
ctrl-c rto right justify columns
ctrl-c sto change the columns separator
ctrl-c tto transpose columns and rows
ctrl-c uto unequalize columns
ctrl-c vto set the margin values for columnizing
ctrl-c wto twiddle columns
ctrl-c xto cut columns (extract them and copy in system scrap)
ctrl-c zto uncolumnize

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

ctrl-c hto convert a table to html code
ctrl-c lto 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 :

Version History

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:

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.