FREETABLE(1)

💖 FREETABLE 💖

okay bestie, sit down, hydrate, because we're about to talk about the freetable situation and honestly? it's giving life-changing. this is the manual page for freetable, section 1 of the manual, and no cap it's the tool that fixes the one thing HTML did dirty. 🫶

---

✨ NAME ✨

freetable — a tool for making HTML tables generation easier. yes literally that. the table trauma ends here. 💅

---

🌸 VERSION 🌸

this manpage describes version 2.3 of freetable.

it might be not 100% accurate if you use a different version. so like, vibe check your version first, bestie. 😭

---

🎀 SYNOPSIS 🎀

freetable [options] filename

or

freetable [options]

possible options are:

• -h, --help — print usage info and exit. the classic "help me" button. ✨
• -V, --version — print version information and exit.
• -c, --comment — insert comment before every cell to point its location. lowkey a map for your own table, iconic.
• -b, --no-nbsp — do not insert   to empty cells for lowered-3D apperance. (yes, "apperance" — that's the original spelling, i'm not touching it, i'm just reporting. 💀)
• -w, --warning — print a warning before each generated table that you should not change it. you should change its source. she's telling you to edit the source, not the output. listen to her. 👑
• -l, --location — substitute <row> and <col> flags inside table with correct cell's location.
• -m, --macro [program] — use macro procesor to proces cells content (default: m4).

---

⚠️ WARNING ⚠️

DO NOT USE MACRO PROCESSOR OVER UNSURE SOURCE M4 MAY BE USED TO COMPROMISE YOUR SECURITY FOR MORE INFORMATION ON THIS EXEC:

info m4 'UNIX commands' syscmd

no fr fr, this one is not a joke, this is the danger part. do not run the macro processor over source you don't trust. it can literally compromise your security. that's the whole deal. 🚨

---

🦋 DESCRIPTION 🦋

this is a free replacement of wwwtable. 💖

HTML is a great language, but have one horrible flaw: tables. (one? bestie, ONE? okay, the author said one, we're going with one. 🙈) i spent many hours looking at HTML source i just written and trying to guess which cell in source is which in browser.

if this also describes you, then read this manpage and your pain will stop. genuinely. the healing is real. ✨

program reads HTML source from either stdin or file. then it searches for line starting table:

<wwwtable [options]>

then it analyzes table, puts correct HTML table in this place and continues searching for the next table. like a little scavenger hunt but for tables. 🌈

---

🧚 TABLE SYNTAX 🧚

it is very easy:

wwwtable :
<wwwtable [wwwtable_options]>
[preamble]
[cell]
[cell]
...
</wwwtable>

wwwtable_options will be passed to <table> tags. there is no magic inside preamble. it can be any HTML text. it will be simply put in front of table.

cell is either normal_cell (<td> tag) or header_cell (<th> tag). at least it was this way in freetable 1.x. see the next section for alternative cell address syntax. 👀

normal_cell :
(row,col) cell_options
cell_content

header_cell :
((row,col)) cell_options
cell_content

cell_options will be passed to cell tag. there is magic inside — colspan and rowspan keys are parsed to make correct table. ✨

cell_content can be anything. it may contain text, tags, and even nested wwwtables. nesting! we love a recursive moment. 🪆

if you use -m (or --macro) option, it will be passed thru m4(1), with <row> and <col> set to adress of curent cell. (again: original spelling, not mine, don't come for me 😭)

row and col are either numbers locating cells, expressions relative to previous cell or regular expresions to match few of them. unlike wwwtable, freetable can use regular expresions for header cells. also * can be used, and it mean .* really.

relative expressions are:

• = or empty means: the same as previous
• + or +X means: one and X more than previous
• - or -X means: one and X less than previous

if many definisions adress the same cell all options and contents are concatenated in order of apperance. (yes, they stack. it's a whole thing. 💅)

if you want to use only regular expresions you must tell program about the last cell:

<wwwtable>
(*,1)
these are colums 1
(1,*)
these are rows 1
(4,4)
</wwwtable>

---

👑 ALTERNATIVE CELL ADDRESS SYNTAX 👑

it is inconvenient to specify cell address as regular expression. so in freetable 2.0 two new methods were introduced. both can be used to either normal or header cells. 🎀

full bakward compatibility is preserved. to preserve it, new syntax had to be introduced. unfortunatelly, you can't specify row address using one method, and column address using another. to come around this, both new methods are very liberal and allow you to use =, +, -, +X, -X and null string with the same meaning as they have in old addressing method. (she said liberal, she said flexible, she said slay. 🫶)

unlike regular expression method, new methods will find out the last cell automatically. no more manual "hey program, this is the last one" energy. 😌

🔥 EXPLICIT RANGES 🔥

(rowrange;colrange) cell_options
cell_content

syntax for both rowrange and colrange is like: 1-2,4-7,9,12. duplicates will be eliminated. for purpose of relative addresses last given number is used. so if you write

(1-100,32;1)
foo
(+,)
bar

cell (33,1) will contain foobar and all others only foo. see? math. beautiful math. 💖

🌈 ARBITRARY PERL CODE 🌈

({code for rows},{code for tables}) cell_options
cell_content

you can use arbitrary Perl one-liner as long as it matches our not very intelligent regular expressions and evaluates to list. unfortunatelly there isn't any regular expression for Perl code, but as long as it doesn't contain },{ and }) it should work. example:

<wwwtable>
({grep {$_%3 == 1} 1..100},{1..2,4})
foo
</wwwtable>

will evaluate to 100 rows x 4 columns table with foo in every 1st, 2nd and 4th column of every row with number equal 1 modulo 3. ok that's actually iconic. 👑

if you want to use "arbitrary code" in one part of address and explicit range in the other, change - into .. in defenition of range, and put in between { and }.

if you want to use "arbitrary code" in one part of address and regular expression in the other, you have to write {grep {/expression/} from..to}. unfortunatelly, in this case you have to specify size of the table explicitely. yes you have to. no shortcuts. 😤

---

💀 INCOMPATIBILITIES WITH WWWTABLE 💀

if you was formerly user of wwwtable and want to change your tool, you should read this. most of this is about regexps handling. notice also that wwwtable couldnt do location tags substitution nor macroprocesing. (glow-up behavior, honestly ✨)

option -w has completely oposite meaning. we dont print warnings by default, and -w or --warning is used to force warnings. yes. the flag flipped. read it twice. 🙈

table header fields can be specified by regexps ex:

((1,*))

it was impossible in wwwtable.

axis counters are 100% orthogonal. this mean that code:

(*,1) width=30
(*,2) width=35
(*,3) width=40
(=,=)
Foo

Foo will appear in 3rd column. if you wanted it to be in 1st you should write:

(*,1) width=30
(*,2) width=35
(*,3) width=40
(=,1)
Foo

or

(*,) width=30
(*,+) width=35
(*,+) width=40
(=,1)
Foo

in freetable 2.0 two new methods o specifying cell address were introduced. they are completely incompatible with wwwtable. (two new methods! big era! 🎉)

---

🍓 BUGS 🍓

"Arbitrary Perl Code" cell address will fail on very complex Perl code. so like, keep your Perl code normal-complex, bestie. 😭

---

🌟 SEE ALSO 🌟

• m4(1)

---

💜 AUTHOR 💜

Tomasz Wegrzanowski <taw@users.sourceforge.net>

---

okay that's the whole thing!! go forth and generate tables, you gorgeous genius. and remember: this page shipped with perl v5.34.0, dated 2022-05-25, and it's FREETABLE(1) in the manual — so when you cite it in your group chat, cite it right. periodt. 💅✨🎀