TXTABLE.TXT                          1                         Aug 25, 1999

WIN95 AND WINNT NOTICE:  As with most  DOS-based  utilities,  this  program
doesn't  understand  the  weird  subdirectories,  long  filenames,  invalid
characters that  are  possible  under  Windows  95  and  Windows/NT.   Both
operating systems alias long filenames into names like MYFILE~1.TXT and you
will need to specify the aliased versions of file names to process them. If
you're not sure what the pseudo-name is, use the "DIR /X" command in DOS to
check.  Under some file structure systems in NT, the program may  not  work
at all.

This program creates tables from an  ASCII  text  input  file.   Easier  to
maintain than  most  word  processing  tables,  the  program  automatically
handles alignment and such.  Features:

  * Creates tables which can be (at this point) up to 10 columns wide.
  * Automatically sets table column widths but you can override this.
  * Allows flexibility in terms of alignment,  borders,  titles,  and  page
    lengths.
  * You can either use a straight ASCII  text  input  file  (typically  one
    record per cell) or else a pseudo-HTML input file
  * If you use the optional embedded HTML stuff, you can have more than one
    table per input file.
  * Pressing escape stops the program early.


The TXTABLE.EXE input file:

TXTABLE.EXE works off an ASCII text input file  which  basically  tells  it
what goes in each cell.  This file can be created and maintained by hand.

(A sample file, TXTABLE2.SAM, should have been included in  the  ZIP  file.
It's used as the basis of the example shown below.  Feel free to try it out
using "TXTABLE TXTABLE2.SAM".)

Tables can be indicated in this file in one of two ways.  The  first  is  a
method which doesn't use HTML commands and basically expects  one  cell  of
data per line on input.  The second method is based on a limited version of
the HTML coding for tables.

You will notice that the sample file actually mixes the two  techniques  in
the same file.  If this is done, the HTML-based table(s) must appear  after
the one-line/one-cell model.



TXTABLE.TXT                          2                         Aug 25, 1999

Using format one (non-HTML):

Each record in the input file is the contents of a single cell.  Long lines
are automatically wrapped on output by the program.  For  example,  if  you
have a table that looks like this:

ͻ
 Character    Actor/Actress     Viewpoint                              
͹
 Fox Mulder   David Duchovny    Searching for the truth about his      
                                sister.  Conspiracy under every rock.  
Ķ
 Dana Scully  Gillian Anderson  Science is god.  However, strong       
                                religious beliefs provide second       
                                foundation.                            
ͼ

(This table was generated by running TXTABLE on the TXTABLE2.SAM file using
the syntax: "TXTABLE TXTABLE2.SAM /WIDTH=75".)

The input file would consist of the nine cells shown above,  in  the  order
they are shown.  In this case, the input file was the following:

  Character
  Actor/Actress
  Viewpoint
  Fox Mulder
  David Duchovny
  Searching for the truth about his sister.  Conspiracy under every rock.
  Dana Scully
  Gillian Anderson
  Science  is  god.   However,  strong  religious  beliefs  provide  second
foundation.

Leading spaces are removed by the program for data lines.

You can embed comment lines within the input file.  Comments are any  lines
that begin with a colon (":"),  semicolon  (";"),  or  slash-asterisk  pair
("/*").  These special characters have to begin in column 1.   The  typical
use for comments would be to indicate where  table  lines  begin  and  what
parameters are suggested for this table.  For example,  a  commented  input
file for this example might be the following:

  /* TXTABLE2.SAM
  Character
  Actor/Actress
  Viewpoint
  /*
  Fox Mulder
  David Duchovny
  Searching for the truth about his sister.  Conspiracy under every rock.
  /*
  Dana Scully
  Gillian Anderson
  Science  is  god.   However,  strong  religious  beliefs  provide  second
foundation.


TXTABLE.TXT                          3                         Aug 25, 1999

One advantage of this approach is that it makes it very easy to  move  rows
around, something which I could never figure out how to do in WordPerfect.

A blank line means an empty cell.

The cell contents can include  embedded  decimal  and  hexadecimal  strings
(including space representations) if desired (see BRUCEHEX.TXT  file).   If
you want to force a new line within a cell (for example, "Actor/" and  then
have "Actress" on the next line), include the representation of a  carriage
return/linefeed within the line.  For example:  Actor/\013\010Actress.

If you have a very long cell, you can split the line  in  your  input  file
into multiple lines.  To do this, end the line(s) to be continued with  the
continuation indicator, which initially defaults to "__".  For example,

        This cell consists of a number of words__
          so it's been split into multiple lines to make it easier__
          to read in the input file.

Leading spaces are ignored by the program (except for  comments)  and  it's
much easier to read the lines if you indent the continued lines.

Line continuations in the input file has no bearing on where the cells will
be wrapped in the final table.  That's based exclusively on cell widths and
the \013\010 indicators.

Note that the program automatically adds one space when it joins the  lines
unless a space is already there.  So the above example will have  the  cell
shown based on "words so" and "easier to".


Parts of a table and their alignment:

Each table consists of a header section (the first line  of  cells)  and  a
stub (the left-most column of cells).  The contents  of  the  cells  within
each of these sections can be positioned independently from the body of the
table.  By default, the contents of the  headers  are  centered,  then  the
stubs are flush left, and then body of the table is also flush  left.   The
uppermost left cell is considered to be part of the header, not the stub.

Numeric values are positioned totally independent of everything  else.   By
default, they are positioned flush  right.   At  this  point,  the  program
doesn't support decimal alignment so just  make  sure  you  have  the  same
number of decimal places for every cell in the column.

In addition, you can have an optional title in your table.  The  title  can
be as long as you want it; it will be automatically  wrapped  and  centered
based on your page width.  Note that the only way to have  a  title  is  to
embed it in your input file.  This is explained shortly in the  "Specifying
parameters" section.



TXTABLE.TXT                          4                         Aug 25, 1999

Using format two (HTML based):

The second format for the input file is based on the HTML standard.  Having
said this, it does *not* the HTML standard; just a subset of it.

HTML uses indicators enclosed in "<..>" characters to  indicate  what's  to
happen.  Unlike the HTMSTRIP command (also released  by  freeware  by  this
author), TXTABLE only supports certain HTML codes:

        <BR>                     Line is to be split at this point
        <CAPTION>...</CAPTION>   Title of table
                                 (<TITLE>...</TITLE> works too)
        <TABLE>...</TABLE>       Table definition
        <TD>...</TD>             Table cell data contents
        <TH>...</TH>             Table header data contents
        <HR>                     Horizontal rule is to appear here
        <TITLE>...</TITLE>       Title of table
                                 (<CAPTION>...</CAPTION> works too)
        <TR>...</TR>             Table row
        <VERBATIM>...</VERBATIM> Block which follows appears outside of a
                                 table block and is to be printed verbatim.

A typical table looks like the following:

        <TABLE>
        <CAPTION>Main exports by country</CAPTION>
        <TR><TH>Table stub</TH><TH>Col 1</TH><TH>Col 2</TH></TR>
        <TR><TD>China</TD>
            <TD>Textiles</TD>
            <TD>Apparel</TD></TR>
        <TR><TD>Japan</TD>
            <TD>Automobiles</TD>
            <TD>Electronics</TD></TR>
        </TABLE>

This input file would result in the following output:

                          Main exports by country

                ͻ
                 Table stub  Col 1        Col 2       
                ͹
                 China       Textiles     Apparel     
                Ķ
                 Japan       Automobiles  Electronics 
                ͼ

Under the HTML coding conventions, the only forced  line  breaks  are  done
using the <BR> option or some other HTML command which  forces  a  new  row
(for example, <TH> or <TITLE>).


TXTABLE.TXT                          5                         Aug 25, 1999

The <TD ...> and <TH ...> statements can include alignment statements which
override the default alignment for that column.   These  appear  like  "<TD
ALIGN=RIGHT>".  Valid ALIGN= values are RIGHT, LEFT, CENTER, or JUSTIFY.

You can also embed ROWSPAN=n and COLSPAN=n statements in your <TD> and <TR>
specifications.  These tell the program that the value of the cell  extends
to the right or down for a certain number of rows or columns.  For example:

        <table>
        <tr><td colspan=2>1(1)<td>1(2)<td>1(3)
        <tr><td rowspan=2>2(1)<td>2(2)<td>2(3)<td>2(4)
        <tr><td>3(1)<td>3(2)<td>3(3)
        </table>

Generates this table:

                       ͻ
                        1(1)        1(2)  1(3) 
                       ͹
                        2(1)  2(2)  2(3)  2(4) 
                       Ķ
                              3(1)  3(2)  3(3) 
                       ͼ

Unexpected HTML commands are ignored by TXTABLE.   Unlike  with  real  HTML
commands, TXTABLE expects your HTML commands to begin and end on  the  same
line.


TXTABLE.TXT                          6                         Aug 25, 1999

Column widths:

Column widths are set automatically by the program.  You can  override  any
of the width settings that you'd like.

By default, the program processes your input twice.   The  first  time,  it
scans for maximum column widths.  As far as the program is  concerned,  the
width of the column includes all of the following:

  * The character(s) after the delimiter that starts the cell  (the  number
    of characters being set by /BUFF=n but it defaults to just 1),
  * The actual text to be stuffed into that cell,
  * The character(s) before  the  delimiter  that  ends  the  cell  (again,
    /BUFF=n),
  * The cell delimiter itself (always one character), and
  * For the first cell only, the very first cell delimiter character.

In the example shown above, /BUFF=1  was  left  by  default.   The  longest
string in the first column of cells (the stub) is the string "Dana  Scully"
which is 11 characters.  So the maximum required width for the first column
is 1+11+1+1+1 or 15.

The second column's longest string is "Gillian Anderson"  (must  have  been
when she was pregnant) which is 16 characters in length.   So  the  maximum
required width for the secon column is 1+16+1+1+0 or 19.

The third column is some big number like 80.

The program looks at your specified width for the table, divides it by  the
number of columns in the table, and figures the average column  width.   If
the maximum width for the column is less than or equal to the average,  the
program sets the column width to be this maximum.

In our example, the default table width of 80 is in effect  and  there  are
three columns so the average column width is 27 (80 divided by  3)  or  so.
Since they're smaller than the average,  the  program  sets  the  width  of
column 1 and column 2 to be 15 and 19 respectively.

The program looks to see if there are any remaining columns.  If yes, their
width is set to be the remaining width divided by  the  number  of  columns
affected.  In our case, there are 80-15-19 or 46 characters  left  and  one
column so the width of the third column is set to be 46 characters and some
of the lines of text have to be wrapped accordingly.


TXTABLE.TXT                          7                         Aug 25, 1999

If the automatic width detection discovers that the specified  table  width
is too big, the program will typically adjust the maximum table width.  For
example, if you have 3 columns and they're  all  like  10  characters,  the
table width will be shrunk appropriately.  The page  width,  however,  will
stay as it was so the table will appear  centered  within  the  given  page
width.

You can adjust any of the widths if you'd like.  This  is  done  using  the
"/{+n}{-n}{@n}..." parameter.  For each column in sequence, you can specify
one of the following:

   "+n" says to add "n" characters to the initial width.
   "-n" says to subtract "n" characters from the initial width.
   "@n" says to make that column exactly "n" characters in width.

In our example, the column widths ended up being /@15@19@46.  If you wanted
to, you could expand the last column and shrink the  first  one  by  saying
"/-2+0+2" or by using some combination of "@n"  specifications  to  do  the
same thing.

If your adjustments cause the  table  width  to  expand  or  contract,  the
/WIDTH=n  (and  /PAGEW=n   if   necessary)   specifications   will   change
appropriately.

Except in rather bizarre cases, the default system column  settings  should
be more than adequate.



TXTABLE.TXT                          8                         Aug 25, 1999

Specifying parameters:

Parameters for this program can be set in the  following  ways.   The  last
setting encountered always wins:
  - Read from an *.INI file (see BRUCEINI.TXT file),
  - Through the use of an environmental variable (SET TXTABLE=whatever),
    or
  - From the command line (see "Syntax" below)

In addition, the TXTABLE.EXE program allows you embed commands  within  the
input file itself.  This makes it easier to keep table-specific  parameters
with the input file.

The embedded commands have to begin with "/=" in column one  of  the  input
file.  Any statement which begins with "/"  is  processed  like  a  regular
parameter.  For example:

        /*TACSCHED.TST
        /=/7 /border=d /@10@10@10@10@10@10@10
        Time

(The line which begins with "/*" is just a comment line.)

You can have as many "/=" lines as you'd like and they  can  have  multiple
options on them.  As always, the last parameter encountered wins.

In addition to embedding regular commands, you can  also  specify  a  table
title by putting it on a "/=" line.  Any "/=" line that doesn't start  with
a "/" parameter is, in fact, presumed to be a title.  Titles  can  continue
to multiple lines if desired (you don't need the line  continuation  string
to do this) but each line must begin with "/=".  For example:

        /=Return on interest rates based on some stupid formula that
        /=my boss wants but it must be one that no one seriously
        /=uses any more.

If you'd like to force  wrapping,  you  can  embed  \013\010  sequences  as
desired.  You can also include The title can include other embedded decimal
and hexadecimal strings (including space representations) if  desired  (see
BRUCEHEX.TXT file).

Titles that appear on page two or afterward  will  automatically  end  with
"(cont)" so you'll know it's a continued table.


TXTABLE.TXT                          9                         Aug 25, 1999

Syntax:

    TXTABLE [ infile ] [ outfile ] [ /n ] [ /EXT=.xxx ] [ /BORDER=c ]
      [ /ALIGN=c ] [ /ALIGNH=c ] [ /ALIGNN=c ] [ /ALIGNS=c ] [ /RULE=s ]
      [ /WIDTH=n ] [ /PAGE=n ] [ /PAGEW=n ] [ /FORCE ] [ /EJECT ]
      [ /BUFF=n ] [ /CONT=s ] [ /{+n}{-n}{@n}... ] [ /DEBUG ]
      [ /T=temp_dir ] [ /initfile | /-I ] [ /-ENV ] [ /? ] [ /?HEX ]

where:

"infile" is the name of the input file to process.  See example above.  The
program will prompt for an infile name if none is provided.

"outfile" is the name of the output file to create.  Is overwritten  if  it
exists already.  If no output file name is provided, the routine  will  use
the infile and provide an extension of *.TAB.  (The default .TAB  extension
can be overridden using the /EXT=.xxx parameter.)

"/n" tells the program how many cells across the table consists  of.   This
is a required parameter if you're not using pseudo-HTML input files.

"/EXT=.xxx" allows you to specify a different default  file  extension  for
the output file.  This parameter only matters  if  you  do  not  explicitly
specify an output file name.  The default value is "/EXT=.TAB".

"/BORDER=c" specifies the type of border to use.  The possible choices  for
"c" are:

  D  -- double line
  S  -- single line
  T  -- text character line
  B  -- blanks (spaces)
  N  -- none
  DV -- double line is used for vertical borders, lines are skipped in
        horizontal rows within the table itself
  SV -- same as DV except single line
  TV -- same as DV except text lines

Examples of the various border types:

          <D>ouble       <S>ingle        <T>ext         <B>lank
        ͻ  Ŀ  +---+---+---+
         1  2  3    1  2  3   | 1 | 2 | 3 |    1   2   3
        ͹  Ĵ  +---+---+---+
         4  5  6    4  5  6   | 4 | 5 | 6 |    4   5   6
        Ķ  Ĵ  +---+---+---+
         7  8  9    7  8  9   | 7 | 8 | 9 |    7   8   9
        ͼ    +---+---+---+

           <N>one          <DV>           <SV>           <TV>
                       ͻ  Ŀ  +---+---+---+
          1   2   3     1  2  3    1  2  3   | 1 | 2 | 3 |
          4   5   6    ͹  Ĵ  +---+---+---+
          7   8   9     4  5  6    4  5  6   | 4 | 5 | 6 |
                        7  8  9    7  8  9   | 7 | 8 | 9 |
                       ͼ    +---+---+---+


TXTABLE.TXT                          10                        Aug 25, 1999

"/ALIGN=c" specifies how to align the contents of the cells  that  are  not
either header or stub cells.  In the <T>ext example above,  /ALIGN=c  would
affect cells 5, 6, 8, and 9.  Possible values for "c" are R (flush  right),
L (flush left), J (justify), and C (center).  The default is /ALIGN=L.  The
positioning of any numeric cells is overridden by the /ALIGNN=c parameter.

"/ALIGNH=c" specifies how to align the contents of the cells that are  part
of the first row of cells, called the header.  In the <T>ext example above,
/ALIGNH=c would affect cells 1 to 3.  Possible values for "c" are R  (flush
right), L (flush left), J  (justify),  and  C  (center).   The  default  is
/ALIGN=C.  The positioning of  any  numeric  cells  is  overridden  by  the
/ALIGNN=c parameter.

"/ALIGNN=c" specifies how to align the contents of cells that are  entirely
numeric.  This specification overrides any other alignment  specifications.
Possible values for "c"  are  R  (flush  right),  L  (flush  left),  and  C
(center).  The default in /ALIGNN=R.

"/ALIGNS=c" specifies how to align the contents of the cells that are  part
of the leftmost column of cells, called the  stub.   The  very  first  cell
(cell 1 above), is part of the header, not the stub.  In the <T>ext example
above, /ALIGNS=c would affect cells 4 and 7.  Possible values for "c" are R
(flush right), L (flush left), J (justify), and C (center).  The default is
/ALIGN=L.  The positioning of  any  numeric  cells  is  overridden  by  the
/ALIGNN=c parameter.

"/RULE=s" specifies that a string is to be repeated the width of the  line.
This is used to separate sections.  The string can be  a  single  character
(like "/RULE=-"), multiple characters (like "/RULE="- ""), it  can  contain
decimal  and   hexadecimal   characters   (like   "/RULE=\066\097\116"--see
BRUCEHEX.TXT), it can be "/RULE=NULL" (which typically results in  a  blank
line), or just simply "/RULE" (which is the  same  thing  as  "/RULE=-"  if
/BORDER=T and "RULE=\196" if /BORDER=S or /BORDER=D).  Personally, if  your
printer supports IBM graphics characters, I find  "/RULE=\196"  to  be  the
most pleasing of the rule lines.

"/WIDTH=n" specifies the desired table  width.   This  determines  wrapping
long lines and such.  Can be reset automatically by  the  program  if  your
data warrants it.  Initially defaults to /WIDTH=80.

"/PAGE=n" specifies how long each page is.  This will cause the program  to
judge whether the contents of the current line of cells  will  fit  on  the
current page.  If not, the program will do all of the following steps:

    * print a blank line,
    * print an optional page eject (if /EJECT in effect),
    * reprint any table titles (see "Specifying parameters" above),
    * repeat the headers over again, and
    * then produce the next cells.

No page is required and in fact the default  for  this  option  is  /PAGE=0
which turns off any page length adjusting.  Doing the adjusting forces  the
program to store cells in memory and may cause errors if your table exceeds
the array bounds that were set for this.  The current maximum is  10  lines
for the header and 50 lines for any single non-header row.  If you  do  get
errors, just use /PAGE=0 and redo it.


TXTABLE.TXT                          11                        Aug 25, 1999

"/PAGEW=n" specifies  what  the  page  width  is.   If  no  page  width  is
specified, the program will use the /WIDTH=n  parameter  instead.   If  the
page is wider than the table, the program will center the table within  the
page.

"/FORCE" says that the specified  width  must  be  adhered  to.   The  only
exception to this is that tables may force a width expansion if  the  cells
simply can't fit on the page otherwise.  Using /FORCE means that some words
in tables may get split up if the entire word can't  fit  in  the  computed
cell width.  The latter is especially a problem if there are lots  of  cell
columns in a table; there isn't much room for  the  actual  data  when  the
cells themselves take up so much space.  Initially defaults to "/-FORCE".

"/-FORCE" says that the desired widths can be ignored if table cells  would
look more natural without it.  This is initially the default.

"/EJECT" says to put a page eject character (decimal 12) between  pages  in
the table.  This is initially the default.  You can  specify  "/-EJECT"  if
you want to turn them off.  See also "/PAGE=n" parameter.

"/-EJECT" says to put nothing (including  the  standard  decimal  12  eject
characters) between pages in the table.  Initially defaults to "/EJECT".

"/BUFF=n" specifies how many spaces to  position  on  either  side  of  the
vertical bars in the tables.  Defaults to /BUFF=1.

"/CONT=s" specifies that the contents of lines that end with the  specified
string indicate that the contents of the cell continues on the  next  line.
This allows you to put fairly long cells in your table without killing your
text editor.  Note that this does not indicate joined cells  in  the  final
table; just that the text of a single cell is huge.  A  space  is  presumed
before the continuation string whether it's present or not.   For  ease  of
reading, you might want to begin the  continued  lines  with  one  or  more
spaces.  Defaults to /CONT=__

"/{+n}{-n}{@n}..." allows you to adjust the widths of the columns.  See the
"Column widths" description above.

"/DEBUG" is mainly used for  testing  purposes.   It  shows  the  first  80
characters of the table to you on the screen in addition to writing  it  to
your outfile.  This allows you to see results of each parameter more easily
and make adjustments as necessary.

"/T=temp_dir" specifies where to write the temporary files that the routine
needs.  Examples are "/T=C:"  and  "/T=C:\TEMP".   If  not  specified,  the
routine writes to the following in sequence:

  - the value of any TEMP, then TMP, environmental variable
  - C:\TEMP
  - C:\

"/Iinitfile" says to  read  an  initialization  file  with  the  file  name
"initfile".  The file specification *must* contain a period.  Initfiles are
described in the BRUCEINI.TXT file.  Initially defaults to "/ITXTABLE.INI".

"/-I" (or "/INULL") says to skip loading the initialization file.


TXTABLE.TXT                          12                        Aug 25, 1999

"/ENV" says to look for %var% occurrences in the command line  and  try  to
resolve any apparent environmental variable references.   See  BRUCEINI.TXT
for more information.  This is initially the default.

"/-ENV" says to skip resolving apparent %var% occurrences  in  the  command
line.  Initially defaults to "/ENV".

"/?" or "/HELP" or "HELP" shows you the syntax for the command.

"/?HEX" gives you a hexadecimal and decimal conversion table.


Return codes:

TXTABLE returns the following ERRORLEVEL codes:

        0 = no problems
      253 = escape pressed
      254 = input file not found
      255 = syntax problems, or /? requested


Author:

This program was written by Bruce Guthrie of Wayne Software.   It  is  free
for use and redistribution provided relevant documentation is kept with the
program, no changes are made to the program or documentation, and it is not
bundled with commercial programs or charged  for  separately.   People  who
need to bundle it in for-sale packages must pay a $50 registration  fee  to
"Bruce Guthrie" at the following address.

Additional information about this and other Wayne Software programs can  be
found in the file BRUCE.TXT which should be included in  the  original  ZIP
file.  The recent change  history  for  this  and  the  other  programs  is
provided in the HISTORY.ymm file which should be in the same ZIP file where
"y" is replaced by the last digit of the year and "mm"  is  the  two  digit
month of the release; HISTORY.611 came out in  November  1996.   This  same
naming convention is used in naming the ZIP file (TXTABymm.ZIP)  that  this
program was included in.

Comments and suggestions can also be sent to:

                Bruce Guthrie
                Wayne Software
                113 Sheffield St.
                Silver Spring, MD 20910

                e-mail: WayneSof@erols.com   fax: (301) 588-8986
                http://www.geocities.com/SiliconValley/Lakes/2414
             or find through http://www.erols.com/waynesof

Please provide an Internet e-mail address on all correspondence.


