doc: Re-write proper manual page

doc/Makefile

@@ -18,7 +18,7 @@
 
 MANUAL_URL="https://wiki.debian.org/FreedomBox/Manual?action=show&mimetype=text%2Fdocbook"
 
-OUTPUTS=freedombox-manual.pdf freedombox-manual.html freedombox-manual.part.html
+OUTPUTS=freedombox-manual.pdf freedombox-manual.html freedombox-manual.part.html plinth.1
 
 
 all: $(OUTPUTS)
@@ -58,6 +58,10 @@ fetch:
 	xmlto html-nochunks $<
 
 
+%.1: %.xml
+	xmlto man $<
+
+
 .PHONY: clean
 clean:
 	rm -f $(OUTPUTS)

doc/plinth.xml

@@ -0,0 +1,201 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<!--
+#
+# This file is part of Plinth.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+-->
+<refentry>
+  <refmeta>
+    <refentrytitle><application>plinth</application></refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="manual">FreedomBox</refmiscinfo>
+    <refmiscinfo class="version"> </refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname><application>plinth</application></refname>
+    <refpurpose>
+      a web front end for administering FreedomBox
+    </refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>plinth</command>
+      <arg><option>-h, </option><option>--help</option></arg>
+      <arg><option>--server_dir</option><arg choice="req">SERVER_DIR</arg></arg>
+      <arg><option>--pidfile</option><arg choice="req">PIDFILE</arg></arg>
+      <arg><option>--debug</option></arg>
+      <arg><option>--no-daemon</option></arg>
+      <arg><option>--diagnose</option></arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      FreedomBox is a community project to develop, design and promote
+      personal servers running free software for private, personal
+      communications.  It is a networking appliance designed to allow
+      interfacing with the rest of the Internet under conditions of
+      protected privacy and data security.  It hosts applications such
+      as blog, wiki, website, social network, email, web proxy and a
+      Tor relay on a device that can replace a wireless router so that
+      data stays with the users.
+    </para>
+    <para>
+      Plinth is a web interface to administer the functions of the
+      FreedomBox.  It is extensible and is made of modules.  Each
+      module provides a simplified user interface to control the
+      underlying functionality of a specific application of
+      FreedomBox.  As FreedomBox can act as a wireless router, it is
+      possible to configure networking from Plinth.  Plinth allows
+      configuration of basic system parameters such as time zone,
+      hostname and automatic upgrade settings.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+    <variablelist>
+      <varlistentry>
+	<term><option>--pidfile PIDFILE</option></term>
+	<listitem>
+	  <para>
+            Write the process ID of the daemon into the provided
+            PIDFILE.  By default the value from
+            <filename>plinth.config</filename> is used.  Plinth is
+            shipped with a value of
+            <filename>/var/run/plinth.pid</filename> in
+            <filename>/etc/plinth/plinth.config</filename>.  When
+            <filename>/etc/plinth/plinth.config</filename> is not
+            available, <filename>plinth.config</filename> from current
+            directory is used.  In source directory, this has the
+            default value of
+            <filename>./data/var/run/plinth.pid</filename>.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--server_dir SERVER_DIR</option></term>
+	<listitem>
+	  <para>
+            This the URL fragment under which Plinth will provide its
+            services.  By default the value from
+            <filename>plinth.config</filename> is used.  Plinth is
+            shipped with a value of <filename>/plinth</filename> in
+            <filename>/etc/plinth/plinth.config</filename>.  This
+            means that Plinth will be available as
+            http://localhost:8000/plinth by default.  When
+            <filename>/etc/plinth/plinth.config</filename> is not
+            available, <filename>plinth.config</filename> from current
+            directory is used.  In source directory, this has the
+            default value of <filename>/</filename>.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--debug</option></term>
+	<listitem>
+	  <para>
+	    Enable debug mode.  Turn off Django security features.
+	    Print extra debug messages.  Monitor source files for
+	    changes and restart Plinth on modifications.  Turn on
+	    Django debug mode to show details on error pages.  Die if
+	    there is an error during module initialization.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--no-daemon</option></term>
+	<listitem>
+	  <para>
+	    Normally Plinth goes into daemon mode as soon as it
+	    finishes initialization.  This is useful when performing
+	    development and debugging on the command line.  Further,
+	    this is useful when running as systemd service as systemd
+	    takes care of sending the process into background.
+	  </para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term><option>--diagnose</option></term>
+	<listitem>
+	  <para>
+            If provided, Plinth loads modules, performs initialization
+            but does start the web server.  Instead it runs diagnostic
+            tests on each module and exits.
+	  </para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration</title>
+    <para>
+      Plinth reads various configuraiton options from the file
+      <filename>/etc/plinth/plinth.config</filename>.  If this file is
+      not present, then it reads configuration file
+      <filename>./plinth.config</filename> from the current directory.
+      This is mainly meant to make Plinth work with configuration from
+      source code directory for debugging purposes.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Start Plinth as daemon with default options</title>
+      <synopsis>$ plinth</synopsis>
+      <para>
+        Become a daemon after initialization and write a PIDFILE as
+        specified in the configuration.
+      </para>
+    </example>
+
+    <example>
+      <title>Run Plinth for debugging</title>
+      <synopsis>$ plinth --server_dir=/plinth --debug --no-daemon</synopsis>
+      <para>
+        Enable debug mode and don't become a daemon.  Also override
+        the configuration file value for the URL fragment to start
+        Plinth under and set it to /plinth.
+      </para>
+    </example>
+</refsect1>
+
+  <refsect1>
+    <title>Bugs</title>
+    <para>
+      See <ulink
+      url="https://github.com/freedombox/Plinth/issues">Plinth issue
+      tracker</ulink> for a full list of known issues and TODO items.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Author</title>
+    <para>
+      <author>
+	<firstname>Plinth Developers</firstname>
+	<contrib>Original author</contrib>
+      </author>
+    </para>
+  </refsect1>
+</refentry>