Provided by: libparse-dia-sql-perl_0.31-2_all bug

NAME

       Parse::Dia::SQL::Output::HTML - Create HTML documentation.

SYNOPSIS

           use Parse::Dia::SQL;
           my $dia = Parse::Dia::SQL->new(
             file => 'foo.dia',
             db   => 'html' [ , htmlformat => {formatfile} ]
           );
           print $dia->get_sql();

DESCRIPTION

       This sub-class creates HTML formatted database documentation.

       HTML formatting is controlled by templates selected with the optional htmlformat parameter
       which supplies a format file. See "HTML formats" for more.

       The generated HTML is intended to be useful rather than beautiful.

       This sub-class follows the same structure as the rdbms output sub-classes with the intent
       of maintaining consistency, even though this give less than optimum efficiency.

   new
       The constructor.

       Object names in HTML have no inherent limit. 64 has been arbitrarily chosen.

   get_sql
       Return all sql documentation.

       First build the data structures:

         schema create
         view create
         permissions create
         inserts
         associations create  (indices first, then foreign keys)

       Then generate the output:

         html start
         html comments
         body start
         generate main html
         body end
         html end

   _get_preamble
       HTML Header

   _get_comment
       Comment for HTML Header

   get_smallpackage_pre_sql
       HTML Body start

   get_smallpackage_post_sql
       HTML Body close

   _get_postscript
       HTML close

   _get_create_table_sql
       Extracts the documentation details for a single table.

   get_schema_drop
       Do nothing

   get_view_drop
       Do nothing

   _get_fk_drop
       Do nothing

   _get_drop_index_sql
       Do nothing

   get_permissions_create
       Permissions are formatted as "{type} {name} to {list of roles}" where:

       "type" is the operation "GRANT", "REVOKE" etc

       "name" is the permission name "SELECT", "INSERT" etc

       "list of roles" is the set of datbase roles affected.

       Warning

       Permissions are at best lightly tested (ie potentially buggy)

   get_permissions_drop
       Do nothing

   _get_create_association_sql
       Extracts the documentation for table relationships.

   _get_create_index_sql
       Extracts the documentation for table indices.

   generate_html
       Do the output

   set_html_template
       Set up the formatting template

       Template elements use "{placeholders}" to identify how the document should be built.

HTML Formats

       The default format may be all you need.  If you want to create different HTML formats for
       different uses, create a format file with template elements defined between
       "{def:element}" and "{/def:element}" markers.  You only need to define those elements that
       you want to be different from the defaults.

       Any text outside the "{def:element}" and "{/def:element}" is ignored, so you can add
       comments without affecting the output.

       Any "\n" literals in the format file are replaced with newlines; although newlines in the
       generated HTML typically have no effect on the layout, they can make the output easier for
       humans to read.

   Template elements
       htmlpreamble

       The start of the html document.

       Placeholders: filename

       Default: <html><head>\n<title>Database documentation: {filename}</title>

       htmlcomment

       A generated comment at the start of the html document. This is the standard comment at the
       start of the SQL script.

       Placeholders: htmlcomment

       Default: \n<!-- {htmlcomment} -->\n

       htmlstartbody

       The start body html tag.

       Default: </head><body>

       htmlendbody

       The end body html tag.

       Placeholders: gentime

       Default: <p style="font-size:75%">Generated at {gentime}.</p>

       htmlend

       The end html tag.

       Default: </html>

       tablelist

       The bit at the top of the page which lists all the tables.  Each is formatted with
       "tablelistitem", separated by "tablelistsep".

       Placeholders: tablelist (the assembled list of table), filename

       Default:

        <h1>Data Dictionary for {filename}</h1>
        <h2\>List of Tables</h2>
        {tablelist}
        <hr width='80%'/>

       tablelistitem

       An individual element (table) in the table list

       Placeholders: tablename, tablecomment

       Default: <a href='#{tablename}'>{tablename}</a>

       tablelistsep

       Separator between individual elements in the table list.

       Default: ", "

       tablestart

       Introduction to the table details

       Default: <h2>Table details</h2>

       table

       Details of one table.

       Placeholders: tablename, comment, refto, refby, tablerowdata, autoupdate, indices,
       permissions.

       Default:

        <h3>Table: {tablename}<a name='{tablename}'/></h3>
        {comment}
        {refto}
        {refby}
        <table border='1' cellspacing='0' cellpadding='1'>
        <tr><td>Field</td><td>Type</td><td>Default</td><td>Description</td></tr>
        {tablerowdata}
        </table>
        {autoupdate}
        {indices}
        {permissions}
        <hr width='80%'/>

       tablekeyrow, tablerow

       Details of an individual field (column) from the (table) in the table detail.

       tablekeyrow is used for primary key fields, tablerow for other fields.

       Placeholders: name, type, default, comment.

       Default tablekeyrow:
       <tr><td><b>{name}</b></td><td>{type}</td><td>{default}</td><td>{comment}</td></tr>

       Default tablerow:
       <tr><td>{name}</td><td>{type}</td><td>{default}</td><td>{comment}</td></tr>

       tablecomment

       Table comments/description.

       Placeholders: comment

       Default: <p>{comment}</p>

       tablecommentlist

       Table comments/description in a list context

       Placeholders: comment

       Default: {comment}

       autoupdate

       Auto update code, if used.

       Placeholders: autoupdate

       Default: <p>Automatically set:{autoupdate}</p>

       refby, refto

       References by - a list of tables that refer to this one via foreign keys.

       References to - a list of tables to which this table refers via foreign keys.

       The whole section is omitted if there are no references (including any static text).

       Placeholders: refbylist, reftolist respectively.

       Default: refby <p>Referenced by: {refbylist}</p>

       Default: refto <p>References: {reftolist}</p>

       refbyitem, reftoitem

       A single item in the reference by list

       Placeholders: tablename, key, fk, action, refname

       Here tablename is the other table, key is the field in this table, fk is the field in the
       other table, action in the action on update/delete (such as cascade or update) and refname
       is the name of the constraint.

       Default: <a href='#{tablename}'>{tablename}</a>

       refbysep, reftosep

       Separator between references.

       Default: ", "

       indices

       List of indices on this tables.

       The whole section is omitted if there are no indices (including any static text).

       Placeholders: indexlist

       Default: <h4>Indices</h4><p>{indexlist}</p>

       indexitem

       A single item in the index list

       Placeholders: tablename, columns, comment, type, indexname

       Here tablename is the indexed (ie current) table, columns is the set of columns in the
       index, comment is the index comment if any, type is 'unique' (or blank) and indexname is
       the name of the index.

       Default: {indexname}: {type} on {columns} {comment}

       indexsep

       Separator between indices.

       Default: "<br\">

       permission

       A list of permissions granted on this table.

       Placeholders: permissionlist

       Default: <h4>Permissions</h4><p>{permissionlist}</p>

       permissionitem

       A single permission in the list

       Placeholders: permission

       Default: {permission}

       permissionsep

       Separator between permissions.

       Default: <br/>

       fieldblank

       Replacement character(s) for blank values. Default value is empty.

   Sample format file
       This format file generates vertical lists of tables and references rather than single
       paragraph, comma separated lists (which is the default).

        {def:tablelist}
        <h1>List of Tables</h1>
        <table border='1' cellspacing='0' cellpadding='2'>
        <tr><td><b>Name</b></td><td><b>Description</b></td></tr>
        {tablelist}
        </table>

        <hr width='80%'/>
        {/def:tablelist}

        {def:tablelistitem}<tr><td><a href='#{tablename}'>{tablename}</a></td><td>{tablecomment}</td></tr> {/def:tablelistitem}
        {def:tablelistsep}\n{/def:tablelistsep}

        {def:refby}<p><b>Referenced by:</b> <br/>{refbylist}</p>{/def:refby}
        {def:refbyitem}{fk}=<a href='#{tablename}'>{tablename}</a>.{key} {action}{/def:refbyitem}
        {def:refbysep} <br/>{/def:refbysep}

        {def:refto}<p><b>References:</b> <br/>{reftolist}</p>{/def:refto}
        {def:reftoitem} {fk}=<a href='#{tablename}'>{tablename}</a>.{key} {action}{/def:reftoitem}
        {def:reftosep}<br/>{/def:reftosep}

        # Comments don't matter
        {def:permission}<h4>Permissions</h4><p>{permissionlist}</p>{/def:permission}
        {def:permissionitem}{permission}{/def:permissionitem}
        {def:permissionsep}<br/>{/def:permissionsep}

       Note that comments or other text outside the {def:} The other template elements are the
       same as the default.

TODO

       Things that might get added in future versions:

       Views are not currently documented.

       Bugs etc