<?xml version="1.0" encoding="iso-8859-15"?>
<!-- $Id$ -->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
	<!ENTITY firstname "Pierre">
	<!ENTITY surname   "Pronchery">
	<!ENTITY email     "khorben@defora.org">
	<!ENTITY section   "1">
	<!ENTITY package   "DaPortal">
	<!ENTITY name      "daportal">
	<!ENTITY title     "DaPortal Administrator Manual">
	<!ENTITY purpose   "Invoke DaPortal requests from the command line">
]>
<refentry>
	<info>
		<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>2012</year>
			<year>2013</year>
			<year>2014</year>
			<year>2015</year>
			<year>2016</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>
	</info>
	<refmeta>
		<refentrytitle>&name;</refentrytitle>
		<manvolnum>1</manvolnum>
	</refmeta>
	<refnamediv>
		<refname>&name;</refname>
		<refpurpose>&purpose;</refpurpose>
	</refnamediv>
	<refsynopsisdiv>
		<cmdsynopsis>
			<command>&name;</command>
			<arg choice="opt"><option>-D</option></arg>
			<arg choice="opt"><option>-M</option> <replaceable>MIME type</replaceable></arg>
			<arg choice="opt"><option>-f</option></arg>
			<arg choice="opt"><option>-m</option> <replaceable>module</replaceable></arg>
			<arg choice="opt"><option>-a</option> <replaceable>action</replaceable></arg>
			<arg choice="opt"><option>-i</option> <replaceable>ID</replaceable></arg>
			<arg choice="opt"><option>-q</option></arg>
			<arg choice="opt"><option>-t</option> <replaceable>title</replaceable></arg>
			<arg choice="opt"><option>-v</option></arg>
			<arg choice="opt" rep="repeat"><option>-o</option> <replaceable>variable=value</replaceable></arg>
		</cmdsynopsis>
	</refsynopsisdiv>
	<refsect1 id="description">
		<title>Description</title>
		<para>The &name; command line utility can locate a local installation of the
			&package; Content Management System, and issue requests directly. A single
			request can be issued per invocation of the &name; command.</para>
		<para>By default, it ensures that requests do not affect the state of the
			local installation (idempotence). Updates can however be allowed with a
			special argument.</para>
	</refsect1>
	<refsect1 id="options">
		<title>Options</title>
		<para>The following options are available:</para>
		<variablelist>
			<varlistentry>
				<term><option>-D</option></term>
				<listitem>
					<para>Enables debugging mode.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-M</option></term>
				<listitem>
					<para>Sets a MIME type for the output format (default:
						<quote>text/plain</quote>).</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-f</option></term>
				<listitem>
					<para>Allows requests to not be idempotent.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-m</option></term>
				<listitem>
					<para>Sets the module to be invoked.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-a</option></term>
				<listitem>
					<para>Sets the action to be called.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-i</option></term>
				<listitem>
					<para>Sets the request's ID.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-t</option></term>
				<listitem>
					<para>Sets the request's title.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-o</option></term>
				<listitem>
					<para>Sets additional parameter values.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</refsect1>
	<refsect1 id="requests">
		<title>Requests</title>
		<para>&package; requests are messages sent to the processing engine selected,
			which in turn dispatches them to the right module. Requests are composed of:
			<itemizedlist>
				<listitem><para>a module name</para></listitem>
				<listitem><para>an action (optional)</para></listitem>
				<listitem><para>an ID (optional)</para></listitem>
				<listitem><para>a title (optional), which should usually match the ID's
						title in database</para></listitem>
				<listitem><para>an additional list of parameters
						(optional)</para></listitem>
			</itemizedlist>
			Unspecified parameters may be set automatically, depending on the engine
			running and the configuration.</para>
		<para>By default, requests are considered idempotent: the state of the
			database remains the same before and after the request, triggering equivalent
			results when the request is repeated. Other operations are considered
			privileged, and require a special flag to work.</para>
		<para>Requests are also sent and received internally by &package;; they are
			however denied from external tools like <command>&name;</command>.</para>
	</refsect1>
	<refsect1 id="files">
		<title>Files</title>
		<para>
			<variablelist>
				<varlistentry>
					<term><filename>@PREFIX@/etc/daportal.conf</filename></term>
					<listitem><para>Configuration file for the &name; script.</para></listitem>
				</varlistentry>
			</variablelist>
		</para>
	</refsect1>
	<refsect1 id="environment">
		<title>Environment</title>
		<para>The following environment variables affect the execution of
			<command>&name;</command>:</para>
		<variablelist>
			<varlistentry><term>DAPORTALCONF</term>
				<listitem><para>Path to an alternative configuration file.</para></listitem>
			</varlistentry>
			<varlistentry><term>DAPORTAL_USERNAME</term>
				<listitem><para>Username to login against (requires environment-based
						authentication, like provided by the EnvAuth authentication
						backend)</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/12/DaPortal"/>.</para>
		<para>Importantly, the &name; command (and therefore, this manual page)
			assumes the engine configured or selected by &package; to be
			<classname>CliEngine</classname>, or inheriting from
			<classname>CliEngine</classname>.
			&package; may however be configured or extended with additional engines,
			which may expect different arguments, function differently, have differing
			output (such as <classname>GtkEngine</classname>) or may not even work at all
			from the command line interface.</para>
	</refsect1>
	<refsect1 id="see_also">
		<title>See also</title>
		<para>
			<citerefentry>
				<refentrytitle>daportal.conf</refentrytitle>
				<manvolnum>5</manvolnum>
			</citerefentry>
		</para>
	</refsect1>
</refentry>
<!-- vim: set noet ts=1 sw=1 sts=1 tw=80: -->
