Creates an html representation of tabular data, either from a tabarray or 
    an externa file (`including ``.hsv``, ``.csv``, ``.tsv``).  If no data is 
    directly provided by passing a tabarray to `X`, then a tabarray is 
    constructed using :func:`tabular.tabarray.tabarray.__new__`.

    **Parameters**

            **fname** :  string

                    Path to the "main" HTML file to be created.  This file path
                    must end in ``.html``.

                    Note that this function will create additional files (e.g. 
                    a ``.css`` file and multiple linked ``.html`` files for 
                    large datasets) linked to this HTML file, inside of the 
                    directory containing `fname`.

            **X** :  tabarray

                    If `X` is `None`, then one of `fin`, `array`, `records`,
                    `columns`, `SV`, `HSV`, or `HSVlist` must not be `None`.

            **fin** :  string

                    File path to to a source of tabular dat, which will be
                    loaded using the tabarray constructor.  The load method
                    will be inferred from the file extension and whether or not
                    there is a headerkey in the first line of the file.

            **title** :  string

                    Description to be used in the <title> tag of the created
                    html file.

            **printheader** : boolean

                    If `printheader = True`, will print out a "header" and 
                    "footer" (both in the body of the HTML documents) on every 
                    page.  The header contains information about the name of 
                    the input file and the number of rows, as well what the 
                    current page number is (if split between multiple 
                    documents) and links to any other pages.  The footer 
                    contains the same page number and links.

            **split** : boolean

                    If `split = False`, will not split to multiple HTML pages, 
                    regardless of value of `ROWS_PER_PAGE`.

            **usecss** : False or None or string

                    If usecss is False, no link to a cssfile is included in the 
                    page header, and no cssfile is written out.  If is a 
                    string, that string is assumed to be a path and is linked 
                    to as the CSS file.  If it is None, then consideration of 
                    the `writecss` variable is made.

            **writecss** : boolean

                    If `usecss` is not `None`, then if `writecss` is not 
                    `False`:  the default css sheet is generated and written to 
                    a file whose name is either generated by default (if 
                    writecss is None) else given by writecss itself, and linked 
                    to in the file header

            **SERVERNAME** :  string

                    Server name.  For example, this could be the ServerName
                    of a VirtualHost on your local machine, assuming that
                    `fname` describes a path on the server.

            **SERVER_FROM_CURDIR** :  string

                    Root path of server relative to the current directory.
                    Assumed to be '../'.

            **ROWS_PER_PAGE** :  positive integer or 'all'

                    This sets the number of records displayed per .html page
                    (if the tabular file has more than ROWS_PER_PAGE rows,
                    it will be split into multiple sections on several .html
                    pages (default = 1000).

                    If the value is 'all' then the page is not split (e.g. it 
                    is as if split = False)

            **See also:**  the kwargs arguments must be valid keyword arguments 
            for :func:`tabular.tabarray.tabarray.__new__`, the tabarray 
            constructor, see documentation for descriptions.

def tabular2html(fname=None, X=None, fin=None, title=None, printheader=False, 
                 split=True, usecss=None, writecss=None, SERVERNAME=None, 
                 SERVER_FROM_CURDIR='../', ROWS_PER_PAGE=1000, 
                 returnstring = False, **kwargs):
    """
    Creates an html representation of tabular data, either from a tabarray or 
    an externa file (`including ``.hsv``, ``.csv``, ``.tsv``).  If no data is 
    directly provided by passing a tabarray to `X`, then a tabarray is 
    constructed using :func:`tabular.tabarray.tabarray.__new__`.

    **Parameters**

            **fname** :  string

                    Path to the "main" HTML file to be created.  This file path
                    must end in ``.html``.

                    Note that this function will create additional files (e.g. 
                    a ``.css`` file and multiple linked ``.html`` files for 
                    large datasets) linked to this HTML file, inside of the 
                    directory containing `fname`.

            **X** :  tabarray

                    If `X` is `None`, then one of `fin`, `array`, `records`,
                    `columns`, `SV`, `HSV`, or `HSVlist` must not be `None`.

            **fin** :  string

                    File path to to a source of tabular dat, which will be
                    loaded using the tabarray constructor.  The load method
                    will be inferred from the file extension and whether or not
                    there is a headerkey in the first line of the file.

            **title** :  string

                    Description to be used in the <title> tag of the created
                    html file.

            **printheader** : boolean

                    If `printheader = True`, will print out a "header" and 
                    "footer" (both in the body of the HTML documents) on every 
                    page.  The header contains information about the name of 
                    the input file and the number of rows, as well what the 
                    current page number is (if split between multiple 
                    documents) and links to any other pages.  The footer 
                    contains the same page number and links.

            **split** : boolean

                    If `split = False`, will not split to multiple HTML pages, 
                    regardless of value of `ROWS_PER_PAGE`.

            **usecss** : False or None or string

                    If usecss is False, no link to a cssfile is included in the 
                    page header, and no cssfile is written out.  If is a 
                    string, that string is assumed to be a path and is linked 
                    to as the CSS file.  If it is None, then consideration of 
                    the `writecss` variable is made.

            **writecss** : boolean

                    If `usecss` is not `None`, then if `writecss` is not 
                    `False`:  the default css sheet is generated and written to 
                    a file whose name is either generated by default (if 
                    writecss is None) else given by writecss itself, and linked 
                    to in the file header

            **SERVERNAME** :  string

                    Server name.  For example, this could be the ServerName
                    of a VirtualHost on your local machine, assuming that
                    `fname` describes a path on the server.

            **SERVER_FROM_CURDIR** :  string

                    Root path of server relative to the current directory.
                    Assumed to be '../'.

            **ROWS_PER_PAGE** :  positive integer or 'all'

                    This sets the number of records displayed per .html page
                    (if the tabular file has more than ROWS_PER_PAGE rows,
                    it will be split into multiple sections on several .html
                    pages (default = 1000).

                    If the value is 'all' then the page is not split (e.g. it 
                    is as if split = False)

            **See also:**  the kwargs arguments must be valid keyword arguments 
            for :func:`tabular.tabarray.tabarray.__new__`, the tabarray 
            constructor, see documentation for descriptions.

    """

    # Must write to an HTML file.

    assert returnstring or fname.endswith( '.html' ), 'fname must end in ".html".'
      
    if X is None:
        if fin is not None:
            if fin.lstrip('/').endswith('.hsv'):
                kwargs['HSVfile'] = fin
            elif fin.endswith('.tsv') or fin.endswith('.csv'):
                kwargs['SVfile'] = fin
            elif fin.endswith(('.npy','.npz')):
                kwargs['binary'] = fin
            else:
                assert False, ('This algorithm is being forced to determine '
                              'the proper file type for web representation '
                              'from file\'s path (e.g. by looking at '
                              'extension) since the type is not given ' 
                              'explicitly by use of a keyword argument, but '
                              'is having problems deducing the intended file ' 
                              'type from the path (e.g., because the '
                              'extension is not one of those this algorithm ' 
                              'recognizes).')
        else:
            assert any([l in kwargs.keys() and kwargs[l] != None 
                        for l in ['SVfile','binary','HSVfile']]), \
                   ('Either a tabarray is given, or file path "fin" is '
                    'given, or one of "HSV", "binary", or "SV" keyword '
                    'arguments are given.')

        X = tb.tabarray(**kwargs)

    names = X.dtype.names
    try:
        RowColors = X['__color__']
    except:
        if '__color__' in names:
            cspot = names.index('__color__')
            RowColors = [r[cspot] for r in X]
        else:
            RowColors = [''] * len(X)
    try:
        coloring = X.coloring
    except:
        coloring = {}

    Num_Records = len(X)
    Num_Cols = len(names)
    ColorStyles = CSSColoring(names, coloring)
    HdrNts = HeaderNotations(names, coloring)

    # If I specify usecss and it is not false, it must be a string and I want 
    # to put that file name in the link and not write anything out.
    # If I specify writecss I want it to write out file to that name and use it 
    # in the link.
    # If usecss = false, writecss is false and nothing is put in the link.
    # If usecss is not specified, then ...

    if usecss != None:
        if isinstance(usecss, str):
            cssfile = usecss
            CSSLINK = ('<link rel="stylesheet" type="text/css" href="' + '/' + 
                       cssfile[len(SERVER_FROM_CURDIR):] + '"</link>')
        else:
            assert usecss == False
            CSSLINK = ''
    else:
        if writecss == False or returnstring:
            CSSLINK = ''
        else:
            if not isinstance(writecss,str):
                cssfile = fname[:-5] + '.css'
            else:
                cssfile = writecss
            WriteOutCSS(ColorStyles[1],cssfile)
            CSSLINK = ('<link rel="stylesheet" type="text/css" href="' + '/'  + 
                       cssfile[len(SERVER_FROM_CURDIR):] + '"</link>')

    if returnstring:
        split = False
    
    if not split or ROWS_PER_PAGE == 'all':
        ROWS_PER_PAGE = Num_Records + 1

    numSections = int(Num_Records / ROWS_PER_PAGE) + 1   
    
    # section2file(i) returns the name of the .html file corresponding to 
    # section number i.
    section2file = (lambda sectionNum: fname if sectionNum == 0 
                else splitext(fname)[0] + str(sectionNum) + splitext(fname)[1])
    
    if title is None:
        if not fin is None:
            title = fin
        else:
            title = 'Title Not Given'
    for section in range(numSections):
        sectionfname = section2file(section)
        fromRow = section * ROWS_PER_PAGE  # Start record # for this section.
        toRow = min( fromRow + ROWS_PER_PAGE, Num_Records)  # End record #.

        if printheader and not returnstring:
            prefix = '/' + DirName(fname[len(SERVER_FROM_CURDIR):]) + '/'
        else:
            prefix = ''

        # Open the output file for the section to fileobject 'f'.
        if not returnstring:
            f = open(sectionfname,'w')
        else:
            f = tempfile.TemporaryFile('w+b')
                     
        # Write out file header.
        if not returnstring:
            f.write('<html><META HTTP-EQUIV="Content-Type" '
                'CONTENT="text/html; charset=utf-8" /><head><title>' + 
                title + '</title>' + CSSLINK + '</head><body>\n' )
        if printheader:
            f.write('<p>Tabular File (page ' + str(section + 1) + ' of ' + 
                    str(numSections) + ', rows ' + str(fromRow + 1) + 
                    ' - ' + str(toRow) + '): ' + title + '</p>\n')
            f.write('<p>page ')
            if section > 0:
                f.write(' <a href="' + prefix + 
                       basename(section2file(section - 1)) + '">prev</a> ')
            if section < numSections - 1:
                f.write(' <a href="' + prefix + 
                       basename(section2file(section + 1)) + '">next</a> ')
            for page in range(numSections):
                f.write((' <a href="' + prefix + 
                      basename(section2file(page)) + '">' + str(page + 1) + 
                      '</a>') if page != section else ' ' + str(page + 1))
            f.write( '</p>' )

        # Write out table with number of cols.
        f.write('<table border="1" cellspacing="0" cellpadding="4">\n')
        f.write('<col span="' + str(Num_Cols) + '" align="center">\n')

        # Write out table header line.
        f.write('<thead>')
        if len(HdrNts) > 0:
            for h in HdrNts:
                f.write(h + '\n')
        f.write('<tr align="center">')
        for name in names:
            f.write('<th class="' + ColorStyles[0][name] + '">' + 
                    cgi.escape(name) + '</th>')
        f.write('</tr>')
        f.write('</thead>\n')

        # Write out each record in the section.
        f.write( '<tbody>\n' )
        if (len(names) > 1) or (fin != None and fin.endswith('.csv')):
            for row in range( fromRow, toRow ):
                colorst = (' style="background-color:' + RowColors[row] + 
                           '" ' if  RowColors[row] != '' else '')
                f.write('<tr align="center">')
                for (i, val) in enumerate(X[ row ]):
                    #f.write('<td>' + cgi.escape(str(val)) + '</td>')
                    f.write('<td ' + colorst + ' class="' + 
                            ColorStyles[0][names[i]] + '">' + str(val).replace('\n','<br/>') + 
                            '</td>')
                f.write('</tr>\n')
        else:
            for row in range(fromRow, toRow):
                f.write('<tr align="center">')
                #f.write('<td>' + cgi.escape(str(X[row])) + '</td>')
                f.write('<td>' + str(X[row]).replace('\n','<br/>') + '</td>')
                f.write('</tr>\n')
        f.write('</tbody>\n')

        f.write( '</table>' )

        # Write out hyperlinks to other sections.
        if printheader:
            f.write('<p>page ')
            if section > 0:
                f.write(' <a href="' + prefix + 
                       basename(section2file(section - 1)) + '">prev</a> ')
            if section < numSections - 1:
                f.write(' <a href="' + prefix + 
                       basename(section2file(section + 1)) + '">next</a> ')
            for page in range(numSections):
                f.write((' <a href="' + prefix + 
                         basename(section2file(page)) + '">' + 
                         str(page + 1) + '</a>') if page != section 
                                                 else ' ' + str(page + 1))

            f.write('</p>')

        # End file.
        if not returnstring:
            f.write('</body></html>\n')
    
        if returnstring:
            f.seek(0)
            s = f.read()
            f.close()
            return s
        else:
            f.close()