.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Parse::Dia::SQL::Output::HTML 3pm"
.TH Parse::Dia::SQL::Output::HTML 3pm "2022-11-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Parse::Dia::SQL::Output::HTML \- Create HTML documentation.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    use Parse::Dia::SQL;
\&    my $dia = Parse::Dia::SQL\->new(
\&      file => \*(Aqfoo.dia\*(Aq,
\&      db   => \*(Aqhtml\*(Aq [ , htmlformat => {formatfile} ]
\&    );
\&    print $dia\->get_sql();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This sub-class creates \s-1HTML\s0 formatted database documentation.
.PP
\&\s-1HTML\s0 formatting is controlled by templates selected with the optional
\&\fIhtmlformat\fR parameter which supplies a format file. See \*(L"\s-1HTML\s0
formats\*(R" for more.
.PP
The generated \s-1HTML\s0 is intended to be useful rather than beautiful.
.PP
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.
.SS "new"
.IX Subsection "new"
The constructor.
.PP
Object names in \s-1HTML\s0 have no inherent limit. 64 has been arbitrarily chosen.
.SS "get_sql"
.IX Subsection "get_sql"
Return all sql documentation.
.PP
First build the data structures:
.PP
.Vb 5
\&  schema create
\&  view create
\&  permissions create
\&  inserts
\&  associations create  (indices first, then foreign keys)
.Ve
.PP
Then generate the output:
.PP
.Vb 6
\&  html start
\&  html comments
\&  body start
\&  generate main html
\&  body end
\&  html end
.Ve
.SS "_get_preamble"
.IX Subsection "_get_preamble"
\&\s-1HTML\s0 Header
.SS "_get_comment"
.IX Subsection "_get_comment"
Comment for \s-1HTML\s0 Header
.SS "get_smallpackage_pre_sql"
.IX Subsection "get_smallpackage_pre_sql"
\&\s-1HTML\s0 Body start
.SS "get_smallpackage_post_sql"
.IX Subsection "get_smallpackage_post_sql"
\&\s-1HTML\s0 Body close
.SS "_get_postscript"
.IX Subsection "_get_postscript"
\&\s-1HTML\s0 close
.SS "_get_create_table_sql"
.IX Subsection "_get_create_table_sql"
Extracts the documentation details for a single table.
.SS "get_schema_drop"
.IX Subsection "get_schema_drop"
Do nothing
.SS "get_view_drop"
.IX Subsection "get_view_drop"
Do nothing
.SS "_get_fk_drop"
.IX Subsection "_get_fk_drop"
Do nothing
.SS "_get_drop_index_sql"
.IX Subsection "_get_drop_index_sql"
Do nothing
.SS "get_permissions_create"
.IX Subsection "get_permissions_create"
Permissions are formatted as \f(CW\*(C`{type} {name} to {list of roles}\*(C'\fR where:
.PP
\&\f(CW\*(C`type\*(C'\fR is the operation \f(CW\*(C`GRANT\*(C'\fR, \f(CW\*(C`REVOKE\*(C'\fR etc
.PP
\&\f(CW\*(C`name\*(C'\fR is the permission name \f(CW\*(C`SELECT\*(C'\fR, \f(CW\*(C`INSERT\*(C'\fR etc
.PP
\&\f(CW\*(C`list of roles\*(C'\fR is the set of datbase roles affected.
.PP
\fIWarning\fR
.IX Subsection "Warning"
.PP
Permissions are at best lightly tested (ie potentially buggy)
.SS "get_permissions_drop"
.IX Subsection "get_permissions_drop"
Do nothing
.SS "_get_create_association_sql"
.IX Subsection "_get_create_association_sql"
Extracts the documentation for table relationships.
.SS "_get_create_index_sql"
.IX Subsection "_get_create_index_sql"
Extracts the documentation for table indices.
.SS "generate_html"
.IX Subsection "generate_html"
Do the output
.SS "set_html_template"
.IX Subsection "set_html_template"
Set up the formatting template
.PP
Template elements use \f(CW\*(C`{placeholders}\*(C'\fR to identify how the document should be built.
.SH "HTML Formats"
.IX Header "HTML Formats"
The default format may be all you need.
If you want to create different \s-1HTML\s0 formats for different uses, create a format file
with template elements defined between \f(CW\*(C`{def:element}\*(C'\fR and \f(CW\*(C`{/def:element}\*(C'\fR markers.
You only need to define those elements that you want to be \fIdifferent\fR from the defaults.
.PP
Any text outside the \f(CW\*(C`{def:element}\*(C'\fR and \f(CW\*(C`{/def:element}\*(C'\fR is ignored, so you can add comments without affecting the output.
.PP
Any \f(CW\*(C`\en\*(C'\fR literals in the format file are replaced with newlines; although newlines in the generated \s-1HTML\s0 typically have
no effect on the layout, they can make the output easier for humans to read.
.SS "Template elements"
.IX Subsection "Template elements"
\fIhtmlpreamble\fR
.IX Subsection "htmlpreamble"
.PP
The start of the html document.
.PP
\&\fIPlaceholders\fR: filename
.PP
\&\fIDefault\fR: <html><head>\en<title>Database documentation: {filename}</title>
.PP
\fIhtmlcomment\fR
.IX Subsection "htmlcomment"
.PP
A generated comment at the start of the html document. This is the standard comment at the start of the \s-1SQL\s0 script.
.PP
\&\fIPlaceholders\fR: htmlcomment
.PP
\&\fIDefault\fR: \en<!\-\- {htmlcomment} \-\->\en
.PP
\fIhtmlstartbody\fR
.IX Subsection "htmlstartbody"
.PP
The start body html tag.
.PP
\&\fIDefault\fR: </head><body>
.PP
\fIhtmlendbody\fR
.IX Subsection "htmlendbody"
.PP
The end body html tag.
.PP
\&\fIPlaceholders\fR: gentime
.PP
\&\fIDefault\fR: <p style=\*(L"font\-size:75%\*(R">Generated at {gentime}.</p>
.PP
\fIhtmlend\fR
.IX Subsection "htmlend"
.PP
The end html tag.
.PP
\&\fIDefault\fR: </html>
.PP
\fItablelist\fR
.IX Subsection "tablelist"
.PP
The bit at the top of the page which lists all the tables.
Each is formatted with \*(L"tablelistitem\*(R", separated by \*(L"tablelistsep\*(R".
.PP
\&\fIPlaceholders\fR: tablelist (the assembled list of table), filename
.PP
\&\fIDefault\fR:
.PP
.Vb 4
\& <h1>Data Dictionary for {filename}</h1>
\& <h2\e>List of Tables</h2>
\& {tablelist}
\& <hr width=\*(Aq80%\*(Aq/>
.Ve
.PP
\fItablelistitem\fR
.IX Subsection "tablelistitem"
.PP
An individual element (table) in the table list
.PP
\&\fIPlaceholders\fR: tablename, tablecomment
.PP
\&\fIDefault\fR: <a href='#{tablename}'>{tablename}</a>
.PP
\fItablelistsep\fR
.IX Subsection "tablelistsep"
.PP
Separator between individual elements in the table list.
.PP
\&\fIDefault\fR: \f(CW\*(C`, \*(C'\fR
.PP
\fItablestart\fR
.IX Subsection "tablestart"
.PP
Introduction to the table details
.PP
\&\fIDefault\fR: <h2>Table details</h2>
.PP
\fItable\fR
.IX Subsection "table"
.PP
Details of one table.
.PP
\&\fIPlaceholders\fR: tablename, comment, refto, refby, tablerowdata, autoupdate, indices, permissions.
.PP
\&\fIDefault\fR:
.PP
.Vb 12
\& <h3>Table: {tablename}<a name=\*(Aq{tablename}\*(Aq/></h3>
\& {comment}
\& {refto}
\& {refby}
\& <table border=\*(Aq1\*(Aq cellspacing=\*(Aq0\*(Aq cellpadding=\*(Aq1\*(Aq>
\& <tr><td>Field</td><td>Type</td><td>Default</td><td>Description</td></tr>
\& {tablerowdata}
\& </table>
\& {autoupdate}
\& {indices}
\& {permissions}
\& <hr width=\*(Aq80%\*(Aq/>
.Ve
.PP
\fItablekeyrow, tablerow\fR
.IX Subsection "tablekeyrow, tablerow"
.PP
Details of an individual field (column) from the (table) in the table detail.
.PP
tablekeyrow is used for primary key fields, tablerow for other fields.
.PP
\&\fIPlaceholders\fR: name, type, default, comment.
.PP
\&\fIDefault\fR \fBtablekeyrow\fR: <tr><td><b>{name}</b></td><td>{type}</td><td>{default}</td><td>{comment}</td></tr>
.PP
\&\fIDefault\fR \fBtablerow\fR: <tr><td>{name}</td><td>{type}</td><td>{default}</td><td>{comment}</td></tr>
.PP
\fItablecomment\fR
.IX Subsection "tablecomment"
.PP
Table comments/description.
.PP
\&\fIPlaceholders\fR: comment
.PP
\&\fIDefault\fR: <p>{comment}</p>
.PP
\fItablecommentlist\fR
.IX Subsection "tablecommentlist"
.PP
Table comments/description in a list context
.PP
\&\fIPlaceholders\fR: comment
.PP
\&\fIDefault\fR: {comment}
.PP
\fIautoupdate\fR
.IX Subsection "autoupdate"
.PP
Auto update code, if used.
.PP
\&\fIPlaceholders\fR: autoupdate
.PP
\&\fIDefault\fR: <p>Automatically set:{autoupdate}</p>
.PP
\fIrefby, refto\fR
.IX Subsection "refby, refto"
.PP
References by \- a list of tables that refer to this one via foreign keys.
.PP
References to \- a list of tables to which this table refers via foreign keys.
.PP
The whole section is omitted if there are no references (including any static text).
.PP
\&\fIPlaceholders\fR: refbylist, reftolist respectively.
.PP
\&\fIDefault\fR: \fBrefby\fR <p>Referenced by: {refbylist}</p>
.PP
\&\fIDefault\fR: \fBrefto\fR <p>References: {reftolist}</p>
.PP
\fIrefbyitem, reftoitem\fR
.IX Subsection "refbyitem, reftoitem"
.PP
A single item in the reference by list
.PP
\&\fIPlaceholders\fR: tablename, key, fk, action, refname
.PP
Here \fItablename\fR is the other table, \fIkey\fR is the field in this table, \fIfk\fR is the field in the other table,
\&\fIaction\fR in the action on update/delete (such as cascade or update) and \fIrefname\fR is the name of the constraint.
.PP
\&\fIDefault\fR: <a href='#{tablename}'>{tablename}</a>
.PP
\fIrefbysep, reftosep\fR
.IX Subsection "refbysep, reftosep"
.PP
Separator between references.
.PP
\&\fIDefault\fR: \f(CW\*(C`, \*(C'\fR
.PP
\fIindices\fR
.IX Subsection "indices"
.PP
List of indices on this tables.
.PP
The whole section is omitted if there are no indices (including any static text).
.PP
\&\fIPlaceholders\fR: indexlist
.PP
\&\fIDefault\fR: <h4>Indices</h4><p>{indexlist}</p>
.PP
\fIindexitem\fR
.IX Subsection "indexitem"
.PP
A single item in the index list
.PP
\&\fIPlaceholders\fR: tablename, columns, comment, type, indexname
.PP
Here \fItablename\fR is the indexed (ie current) table, \fIcolumns\fR is the set of columns in the index, \fIcomment\fR is the index comment if any,
\&\fItype\fR is 'unique' (or blank) and \fIindexname\fR is the name of the index.
.PP
\&\fIDefault\fR: {indexname}: {type} on {columns} {comment}
.PP
\fIindexsep\fR
.IX Subsection "indexsep"
.PP
Separator between indices.
.PP
\&\fIDefault\fR: \f(CW\*(C`<br\e\*(C'\fR>
.PP
\fIpermission\fR
.IX Subsection "permission"
.PP
A list of permissions granted on this table.
.PP
\&\fIPlaceholders\fR: permissionlist
.PP
\&\fIDefault\fR: <h4>Permissions</h4><p>{permissionlist}</p>
.PP
\fIpermissionitem\fR
.IX Subsection "permissionitem"
.PP
A single permission in the list
.PP
\&\fIPlaceholders\fR: permission
.PP
\&\fIDefault\fR: {permission}
.PP
\fIpermissionsep\fR
.IX Subsection "permissionsep"
.PP
Separator between permissions.
.PP
\&\fIDefault\fR: <br/>
.PP
\fIfieldblank\fR
.IX Subsection "fieldblank"
.PP
Replacement character(s) for blank values. Default value is empty.
.SS "Sample format file"
.IX Subsection "Sample format file"
This format file generates vertical lists of tables and references rather than single paragraph, comma separated
lists (which is the default).
.PP
.Vb 6
\& {def:tablelist}
\& <h1>List of Tables</h1>
\& <table border=\*(Aq1\*(Aq cellspacing=\*(Aq0\*(Aq cellpadding=\*(Aq2\*(Aq>
\& <tr><td><b>Name</b></td><td><b>Description</b></td></tr>
\& {tablelist}
\& </table>
\&
\& <hr width=\*(Aq80%\*(Aq/>
\& {/def:tablelist}
\&
\& {def:tablelistitem}<tr><td><a href=\*(Aq#{tablename}\*(Aq>{tablename}</a></td><td>{tablecomment}</td></tr> {/def:tablelistitem}
\& {def:tablelistsep}\en{/def:tablelistsep}
\&
\& {def:refby}<p><b>Referenced by:</b> <br/>{refbylist}</p>{/def:refby}
\& {def:refbyitem}{fk}=<a href=\*(Aq#{tablename}\*(Aq>{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=\*(Aq#{tablename}\*(Aq>{tablename}</a>.{key} {action}{/def:reftoitem}
\& {def:reftosep}<br/>{/def:reftosep}
\&
\& # Comments don\*(Aqt matter
\& {def:permission}<h4>Permissions</h4><p>{permissionlist}</p>{/def:permission}
\& {def:permissionitem}{permission}{/def:permissionitem}
\& {def:permissionsep}<br/>{/def:permissionsep}
.Ve
.PP
Note that comments or other text outside the {def:}
The other template elements are the same as the default.
.SH "TODO"
.IX Header "TODO"
Things that might get added in future versions:
.PP
Views are not currently documented.
.PP
Bugs etc