package Pod::Table;
use Pod::Parser;


=pod

=head1 NAME

Pod::Table - a pod extension to add support for tables

=head1 DESCRIPTION

People complain all the time that pod does not natively deal with tables.
This extension aims to propose a remedy by becoming a Pod Formatter.

So when translating pod to your desired output format,
if a I<=begin table> is encountered,
a table should be generated.

Currently only html is supported.

Each translator should follow this example 
and make =begin table work just like here.

All text based formats , like:

    pod2text
    pod2html
    pod2xml
    pod2docbook
    pod2latex
    pod2man

ought to be easy to do (and Pod::Table will likely handle them all).
The real problem is pod2pdf and other exotics out there,
cause I don't if its even possible.

=head1 SYNOPSIS

    =begin table
    
    =over table
    
    =item table
    
    This is a TD people, a table cell
    
    =item table
    
    This is table cell number 333
    
    =over table
    
    =item table row 3, td 1
    
    =item table row 3, td 2
    
    =back table
    
    =end table

becomes

    <table border=1>
    <tr>
    
    <td>
    
    This is a TD people, a table cell
    
    </td>
    <td>
    
    This is table cell number 333
    </tr>
    <tr>
    
    <td> row 3, td 1</td>
    
    <td> row 3, td 2</td>
    
    </tr>
    
    </table>

or more precisely (=begin html follows)

=begin html

<table border=1>
<tr>

<td>

This is a TD people, a table cell

</td>
<td>

This is table cell number 333
</tr>
<tr>

<td> row 3, td 1</td>

<td> row 3, td 2</td>

</tr>

</table>

=end html

=head1 The Rules

=head2 =begin/=end table

Obvious, the outermost always required.

 A =end implies a =over when there is no other =begin's left (think stack).

=head2 =over/=back  table

  A =over is equivalent to a <tr>
  A =back is equivalent to a </tr>
  A =over implies a =back (equivalent to a </tr><tr>)

=head2 =item  table

A I<=item table> paragraph implies a C<<td>paragraph</td>>
A I<=item table> is closed by the next I<=item table> or I<=back table>


=head1 NESTED TABLES (an example)

    =begin table
    
    =over table
    
    =item table
    
    This is a TD people, a table cell
    
    =item table
    
    This is table cell number 333
    
    =over table
    
    =item table row 3, td 1
    
    =begin table
    
    =over table
    
    =item table Yes, a Lone Table Cell
    
    =back table
    
    =end table
    
    =item table The previous end implied a =back (or should have, maybe)
    
    =back table
    
    =end table


is

=begin html
<table border=1>

<tr>

<Td>

This is a TD people, a table cell

</td><td>

This is table cell number 333

</tr><tr>

<td> row 3, td 1

<table border=2>

<tr>

<td> Yes, a Lone Table Cell

</td></tr>

</table>

</td><td> The previous end implied a =back (or should have, maybe)

</td></tr>

</table>

=end html


=cut