Import a manual page for database(1)

This commit is contained in:
Pierre Pronchery 2019-09-01 04:46:10 +02:00
parent 055ec36c46
commit cd90cdcace
7 changed files with 590 additions and 3 deletions

7
doc/database.css.xml Normal file
View File

@ -0,0 +1,7 @@
<?xml version="1.0"?>
<!-- $Id$ -->
<!DOCTYPE style [
<!ENTITY manual "manual.css.xml">
]>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="&manual;"/>
<!-- vim: set noet ts=1 sw=1 sts=1 tw=80: -->

109
doc/database.xml.in Normal file
View File

@ -0,0 +1,109 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Id$ -->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY firstname "Pierre">
<!ENTITY surname "Pronchery">
<!ENTITY username "khorben">
<!ENTITY email "khorben@defora.org">
<!ENTITY section "1">
<!ENTITY title "libDatabase User Manual">
<!ENTITY package "DeforaOS libDatabase">
<!ENTITY name "database">
<!ENTITY purpose "Generic tool to perform operations on databases">
]>
<refentry>
<refentryinfo>
<title>&title;</title>
<date>@DATE@</date>
<productname>&package;</productname>
<authorgroup>
<author>
<firstname>&firstname;</firstname>
<surname>&surname;</surname>
<contrib>Code and documentation.</contrib>
<address>
<email>&email;</email>
</address>
</author>
</authorgroup>
<copyright>
<year>2019</year>
<holder>&firstname; &surname; &lt;&email;&gt;</holder>
</copyright>
<legalnotice>
<para>This manual page was written for the DeforaOS project (and may be
used by others).</para>
<para>Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU General Public License,
Version 3 as published by the Free Software Foundation.</para>
</legalnotice>
</refentryinfo>
<refmeta>
<refentrytitle>&name;</refentrytitle>
<manvolnum>&section;</manvolnum>
</refmeta>
<refnamediv>
<refname>&name;</refname>
<refpurpose>&purpose;</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>&name;</command>
<arg choice="plain"><option>-d</option>
<replaceable>engine</replaceable></arg>
<arg choice="opt"><option>-C</option>
<replaceable>configuration</replaceable>
<arg choice="opt"><option>-S</option>
<replaceable>section</replaceable></arg></arg>
<arg choice="opt">query</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="description">
<title>Description</title>
<para><command>&name;</command> is a generic tool to perform operations on
databases.</para>
</refsect1>
<refsect1 id="options">
<title>Options</title>
<para><command>&name;</command> expects the name of a database engine to be
specified on the command line, optionally followed by the path to a
connection file and the name of a section within that file.
The following options are available:</para>
<variablelist>
<varlistentry>
<term><option>-d</option></term>
<listitem>
<para>Name of the database engine.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-C</option></term>
<listitem>
<para>Connection file describing how to access the database.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-S</option></term>
<listitem>
<para>Name of a section to use in the connection file.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="bugs">
<title>Bugs</title>
<para>Issues can be listed and reported at <ulink
url="http://www.defora.org/os/project/bug_list/4317/libDatabase"/>.</para>
</refsect1>
<refsect1 id="see_also">
<title>See also</title>
<para>
<citerefentry>
<refentrytitle>configctl</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>
<!-- vim: set noet ts=1 sw=1 sts=1 tw=80: -->

213
doc/docbook.sh Executable file
View File

@ -0,0 +1,213 @@
#!/bin/sh
#$Id$
#Copyright (c) 2012-2017 Pierre Pronchery <khorben@defora.org>
#
#Redistribution and use in source and binary forms, with or without
#modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice, this
# list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
#THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
#AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
#IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
#DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
#FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
#DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
#SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
#CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
#OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
#OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#variables
PREFIX="/usr/local"
[ -f "../config.sh" ] && . "../config.sh"
PROGNAME="docbook.sh"
#executables
DEBUG="_debug"
FOP="fop"
INSTALL="install -m 0644"
MKDIR="mkdir -m 0755 -p"
RM="rm -f"
XMLLINT="xmllint"
XSLTPROC="xsltproc --nonet --xinclude"
#functions
#debug
_debug()
{
echo "$@" 1>&3
"$@"
}
#docbook
_docbook()
{
target="$1"
source="${target%.*}.xml"
[ -f "$source" ] || source="${source#$OBJDIR}"
ext="${target##*.}"
ext="${ext##.}"
case "$ext" in
html)
XSL="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"
[ -f "${source%.*}.xsl" ] && XSL="${source%.*}.xsl"
[ -f "${target%.*}.xsl" ] && XSL="${target%.*}.xsl"
if [ -f "${target%.*}.css.xml" ]; then
XSLTPROC="$XSLTPROC --param custom.css.source \"${target%.*}.css.xml\" --param generate.css.header 1"
elif [ -f "${source%.*}.css.xml" ]; then
XSLTPROC="$XSLTPROC --param custom.css.source \"${source%.*}.css.xml\" --param generate.css.header 1"
fi
$DEBUG $XSLTPROC -o "$target" "$XSL" "$source"
;;
pdf)
XSL="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"
[ -f "${source%.*}.xsl" ] && XSL="${source%.*}.xsl"
[ -f "${target%.*}.xsl" ] && XSL="${target%.*}.xsl"
$DEBUG $XSLTPROC -o "${target%.*}.fo" "$XSL" "$source" &&
$DEBUG $FOP -fo "${target%.*}.fo" -pdf "$target"
$RM -- "${target%.*}.fo"
;;
1|2|3|4|5|6|7|8|9)
XSL="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"
$DEBUG $XSLTPROC -o "$target" "$XSL" "$source"
;;
*)
_error "$target: Unknown type"
return 2
;;
esac
if [ $? -ne 0 ]; then
_error "$target: Could not create page"
$RM -- "$target"
return 2
fi
}
#error
_error()
{
echo "$PROGNAME: $@" 1>&2
return 2
}
#usage
_usage()
{
echo "Usage: $PROGNAME [-c|-i|-u][-P prefix] target..." 1>&2
return 1
}
#main
clean=0
install=0
uninstall=0
while getopts "ciO:uP:" name; do
case "$name" in
c)
clean=1
;;
i)
uninstall=0
install=1
;;
O)
export "${OPTARG%%=*}"="${OPTARG#*=}"
;;
u)
install=0
uninstall=1
;;
P)
PREFIX="$OPTARG"
;;
?)
_usage
exit $?
;;
esac
done
shift $((OPTIND - 1))
if [ $# -lt 1 ]; then
_usage
exit $?
fi
#check the variables
if [ -z "$PACKAGE" ]; then
_error "The PACKAGE variable needs to be set"
exit $?
fi
[ -z "$DATADIR" ] && DATADIR="$PREFIX/share"
[ -z "$MANDIR" ] && MANDIR="$DATADIR/man"
exec 3>&1
while [ $# -gt 0 ]; do
target="$1"
shift
#determine the type
ext="${target##*.}"
ext="${ext##.}"
case "$ext" in
html)
instdir="$DATADIR/doc/$ext/$PACKAGE"
source="${target#$OBJDIR}"
source="${source%.*}.xml"
xpath="string(/refentry/refmeta/manvolnum)"
section=$($XMLLINT --xpath "$xpath" "$source")
if [ $? -eq 0 -a -n "$section" ]; then
instdir="$MANDIR/html$section"
fi
;;
pdf)
instdir="$DATADIR/doc/$ext/$PACKAGE"
;;
1|2|3|4|5|6|7|8|9)
instdir="$MANDIR/man$ext"
;;
*)
_error "$target: Unknown type"
exit 2
;;
esac
#clean
[ "$clean" -ne 0 ] && continue
#uninstall
if [ "$uninstall" -eq 1 ]; then
target="${target#$OBJDIR}"
$DEBUG $RM -- "$instdir/$target" || exit 2
continue
fi
#install
if [ "$install" -eq 1 ]; then
source="${target#$OBJDIR}"
dirname=
if [ "${source%/*}" != "$source" ]; then
dirname="/${source%/*}"
fi
$DEBUG $MKDIR -- "$instdir$dirname" || exit 2
$DEBUG $INSTALL "$target" "$instdir/$source" || exit 2
continue
fi
#create
#XXX ignore errors
_docbook "$target" || break
done

33
doc/manual.css.xml Normal file
View File

@ -0,0 +1,33 @@
<?xml version="1.0"?>
<style><![CDATA[/* $Id$ */
div.refentry {
font-family: monospace;
margin-left: 5ex;
min-width: 102ex;
width: 102ex;
}
div.refentry h1, div.refentry h2, div.refentry h3 {
font-size: inherit;
margin-bottom: 0;
}
div.refentry h1, div.refentry h2 {
margin-left: -4ex;
text-transform: uppercase;
}
div.refentry h3 {
margin-left: -2ex;
}
div.refentry p {
margin-top: 0;
padding-top: 0;
}
div.refentry blockquote, div.refentry pre {
margin-left: 5ex;
}
]]></style>

View File

@ -1,6 +1,24 @@
subdirs=gtkdoc
targets=gtkdoc/libDatabase.types,gtkdoc/tmpl.stamp,gtkdoc/sgml.stamp,gtkdoc/html.stamp
dist=Makefile,gtkdoc.sh
targets=database.1,database.html,database.xml,gtkdoc/libDatabase.types,gtkdoc/tmpl.stamp,gtkdoc/sgml.stamp,gtkdoc/html.stamp
dist=Makefile,database.css.xml,database.xml.in,gtkdoc.sh,manual.css.xml
#targets
[database.1]
type=script
script=./docbook.sh
depends=$(OBJDIR)database.xml
install=
[database.html]
type=script
script=./docbook.sh
depends=database.css.xml,$(OBJDIR)database.xml,manual.css.xml
install=
[database.xml]
type=script
script=../tools/subst.sh
depends=../tools/subst.sh,database.xml.in
[gtkdoc/libDatabase.types]
type=script

View File

@ -4,7 +4,7 @@ cflags_force=`pkg-config --cflags libSystem`
cflags=-W -Wall -g -O2 -pedantic -fPIE -D_FORTIFY_SOURCE=2 -fstack-protector-all
ldflags_force=`pkg-config --libs libSystem` -L$(OBJDIR)../src -Wl,-rpath,../src -lDatabase
ldflags=-pie -Wl,-z,relro -Wl,-z,now
dist=Makefile
dist=Makefile,subst.sh
#targets
[database]

207
tools/subst.sh Executable file
View File

@ -0,0 +1,207 @@
#!/bin/sh
#$Id$
#Copyright (c) 2012-2019 Pierre Pronchery <khorben@defora.org>
#
#Redistribution and use in source and binary forms, with or without
#modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice, this
# list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
#THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
#AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
#IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
#DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
#FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
#DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
#SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
#CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
#OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
#OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#variables
CONFIGSH="${0%/subst.sh}/../config.sh"
PREFIX="/usr/local"
BINDIR=
DATADIR=
INCLUDEDIR=
LDSO=
LIBDIR=
LIBEXECDIR=
MANDIR=
PROGNAME="subst.sh"
SYSCONFDIR=
#executables
CHMOD="chmod"
DATE="date"
DEBUG="_debug"
DEVNULL="/dev/null"
INSTALL="install"
MKDIR="mkdir -m 0755 -p"
RM="rm -f"
SED="sed"
[ -f "$CONFIGSH" ] && . "$CONFIGSH"
#functions
#subst
_subst()
{
#check the variables
if [ -z "$PACKAGE" ]; then
_error "The PACKAGE variable needs to be set"
return $?
fi
if [ -z "$VERSION" ]; then
_error "The VERSION variable needs to be set"
return $?
fi
[ -z "$BINDIR" ] && BINDIR="$PREFIX/bin"
[ -z "$DATADIR" ] && DATADIR="$PREFIX/share"
[ -z "$INCLUDEDIR" ] && INCLUDEDIR="$PREFIX/include"
if [ -z "$LDSO" ]; then
case "$(uname -s)" in
FreeBSD)
LDSO="/libexec/ld-elf.so.1"
;;
Linux)
LDSO="/lib/ld-linux-$(uname -m | tr _ -).so.2"
;;
*)
LDSO="/libexec/ld.elf_so"
;;
esac
fi
[ -z "$LIBDIR" ] && LIBDIR="$PREFIX/lib"
[ -z "$LIBEXECDIR" ] && LIBEXECDIR="$PREFIX/libexec"
[ -z "$MANDIR" ] && MANDIR="$DATADIR/man"
if [ -z "$SYSCONFDIR" ]; then
SYSCONFDIR="$PREFIX/etc"
[ "$PREFIX" = "/usr" ] && SYSCONFDIR="/etc"
fi
while [ $# -gt 0 ]; do
target="$1"
shift
#clean
[ "$clean" -ne 0 ] && continue
#uninstall
if [ "$uninstall" -eq 1 ]; then
$DEBUG $RM -- "$PREFIX/$target" || return 2
continue
fi
#install
if [ "$install" -eq 1 ]; then
source="${target#$OBJDIR}"
$DEBUG $MKDIR -- "$PREFIX" || return 2
mode="-m 0644"
[ -x "${source}.in" ] && mode="-m 0755"
$DEBUG $INSTALL $mode "$target" "$PREFIX/$source" \
|| return 2
continue
fi
#create
source="${target#$OBJDIR}"
source="${source}.in"
([ -z "$OBJDIR" ] || $DEBUG $MKDIR -- "${target%/*}") \
|| return 2
$DEBUG $SED -e "s;@PACKAGE@;$PACKAGE;g" \
-e "s;@VERSION@;$VERSION;g" \
-e "s;@PREFIX@;$PREFIX;g" \
-e "s;@BINDIR@;$BINDIR;g" \
-e "s;@DATADIR@;$DATADIR;g" \
-e "s;@DATE@;$DATE;g" \
-e "s;@INCLUDEDIR@;$INCLUDEDIR;g" \
-e "s;@LDSO@;$LDSO;g" \
-e "s;@LIBDIR@;$LIBDIR;g" \
-e "s;@LIBEXECDIR@;$LIBEXECDIR;g" \
-e "s;@MANDIR@;$MANDIR;g" \
-e "s;@PWD@;$PWD;g" \
-e "s;@SYSCONFDIR@;$SYSCONFDIR;g" \
-- "$source" > "$target"
if [ $? -ne 0 ]; then
$RM -- "$target" 2> "$DEVNULL"
return 2
elif [ -x "$source" ]; then
$DEBUG $CHMOD -- 0755 "$target"
fi
done
return 0
}
#debug
_debug()
{
echo "$@" 1>&3
"$@"
}
#error
_error()
{
echo "$PROGNAME: $@" 1>&2
return 2
}
#usage
_usage()
{
echo "Usage: $PROGNAME [-c|-i|-u][-P prefix] target..." 1>&2
return 1
}
#main
clean=0
install=0
uninstall=0
while getopts "ciuO:P:" name; do
case $name in
c)
clean=1
;;
i)
uninstall=0
install=1
;;
u)
install=0
uninstall=1
;;
O)
export "${OPTARG%%=*}"="${OPTARG#*=}"
;;
P)
PREFIX="$OPTARG"
;;
?)
_usage
exit $?
;;
esac
done
shift $(($OPTIND - 1))
if [ $# -lt 1 ]; then
_usage
exit $?
fi
if [ -n "$SOURCE_DATE_EPOCH" ]; then
DATE="$($DATE -d "@$SOURCE_DATE_EPOCH" '+%B %d, %Y')"
else
DATE="$($DATE '+%B %d, %Y')"
fi
exec 3>&1
_subst "$@"