sqlite2html.1

.\"	$Id$
.\"
.\" Copyright (c) 2016 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: June 30 2016 $
.Dt SQLITE2HTML 1
.Os
.Sh NAME
.Nm sqlite2html
.Nd convert sqlite3 schema to an HTML5 fragment
.\" .Sh LIBRARY
.\" For sections 2, 3, and 9 only.
.\" Not used in OpenBSD.
.Sh SYNOPSIS
.Nm sqlite2html
.Op Fl v
.Op Fl p Ar prefix
.Op Ar schema
.Sh DESCRIPTION
The
.Nm
utility converts an
.Xr sqlite3 1
schema file to an HTML5 fragment.
Its options are as follows:
.Bl -tag -width Ds
.It Fl v
Causes the parser to emit informational messages on stderr.
.It Fl p Ar prefix
Prefix to use for creating HTML ID tags.
.It Ar schema
An SQLite schema file.
.Pp
The outputted HTML5 fragment consists of a
.Li <dl class="tabs">
list consisting of tables; and then for each table, a
.Li <dl class="cols">
list of columns.
The
.Li <dt>
for each list entry consists of the name of the table or column and has
its ID attribute set to the transformed name.
The
.Li <dd>
for each list begins with a
.Li <div class="comment">
if the table or column is preceeded by comments
For columns with a foreign key reference, this will be preceeded by
.Li <div class="foreign">
containing an anchor to the key having a text node of the endpoint.
.Pp
The
.Li @
character within a comment is special: the following table name and
optional column name will be transformed into an HTML link to the
identifier.
Thus,
.Li @foo.bar
will point to the
.Dq bar
column in table
.Dq foo .
If this identifier is not followed by white-space, you may quote the
identifier to prevent subsequent characters from being pulled into the
identifier, e.g.,
.Li @"foo.bar" .
If you wish to print a standalone
.Li @ ,
you may escape it with a backslash
.Pq Dq \e .
.Pp
The
.Li [
character is similar, as it encloses general-purpose links in a manner
similar to Markdown.
Links are formatted as follows:
.Bl -item
.It
.Li [link text](http://link)
.It
.Li [http://link]
.El
.Pp
You can escape the
.Li [
character as well, to prevent this behaviour.
.Pp
The following sequences are also special:
.Bl -tag -width Ds
.It Li --
Print an formatted n-dash.
.It Li ---
Print an formatted m-dash.
.It Li ``
Print formatted left-double quotes.
.It Li ''
Print formatted right-double quotes.
.El
.Pp
Any of these may be escaped with the backslash to have it print as-is.
If you wish to print a backslash, you must escape it, for example,
.Li the \e\e-character---and an \e@-sign .
.Pp
Lastly, a blank (without any white-space but the newline!) one-line
comment line is considered to be a paragraph break, for example:
.Bd -literal
-- Hello, world.
--
-- And after the break...
.Ed
.Pp
In multi-line comment, this can be affected with a blank line in the
comment stream:
.Bd -literal
/* 
 * Hello, world.
 *
 * That was another line break.
 */
.Ed
.Sh SEE ALSO
.Xr sqlite2dot 1 ,
.Xr sqlite3 1
.\" .Sh STANDARDS
.\" .Sh HISTORY
.\" .Sh AUTHORS
.Sh CAVEATS
The schema language accepted by
.Nm
is currently limited to the table declaration with a subset of the
column specification.
.\" .Sh BUGS
.\" .Sh SECURITY CONSIDERATIONS
.\" Not used in OpenBSD.