Add doc/

Add the directory for all the future documentation. The file owlps.t2t
is aimed at being the entry point of all the other documentation pages.
Included are a Makefile to generate man pages and a couple of scripts to
improve the rendering.

doc/Makefile

@@ -0,0 +1,10 @@
+all: owlps.7
+
+%.7: %.man
+	mv $< $@
+
+%.man: %.t2t
+	./preproc-man.sh $< | txt2tags --infile=- --outfile=$@ -t man
+
+clean:
+	rm -f *~ *.html *.man *.7

doc/owlps.t2t

@@ -0,0 +1,132 @@
+Introduction to the Owl Positioning System
+OwlPS {{OWLPS_VERSION}}
+8 November 2012
+
+
+%%%
+% Man title & section:
+%!postproc(man): "^(\.TH.*) 1 "  ".TH owlps 7 "
+% Fix .TH, add NAME section and TABLE OF CONTENTS title:
+%!postproc(man): "^(\.TH.*)$"  "\1 OwlPS's\ User\ Manual\n.SH NAME\nowlps - Introduction to the Owl Positioning System\n\n.SH TABLE OF CONTENTS"
+% Add the table of contents:
+%!options(man): --toc
+% Man "links":
+%!preproc(man): "(owlps-architecture)\.t2t" "**\1**(7)"
+%!preproc(man): "(owlps-deployment)\.t2t" "**\1**(7)"
+%!preproc(man): "(owlps-deployment)\.t2t" "**\1**(7)"
+%!preproc(man): "(owlps-[^ ]*)\.t2t" "**\1**(1)"
+%!preproc(man): "(owlps-[^ ]*\.h)" "**\1**(3)"
+%%%
+
+
+
+
++ What is OwlPS? +
+
+**OwlPS** (//Owl Positioning System//) is a positioning (localization)
+system based on the IEEE 802.11 radio network (Wi-Fi), released by the
+University of Franche-Comte (Université de Franche-Comté, France) under
+the terms of the CeCILL free software license (GNU GPL-compatible).
+
+OwlPS uses an infrastructure-centred architecture, which means the
+infrastructure does the measurements and computes the mobile terminals'
+positions, rather than the terminals computing their own positions (as
+it is the case for instance with the GPS). The infrastructure is
+composed by several capture points that run //OwlPS Listener//, an
+aggregation server running //OwlPS Aggregator//, and a computation
+server running //OwlPS Positioner//. The role of each of these modules
+is detailed in the documentation's part dedicated to the system's
+architecture.
+
+OwlPS implements various positioning techniques and algorithms based on
+the radio signal strength (trilateration, signal strength
+fingerprinting, and hybrid techniques). //OwlPS Listener// uses the
+Radiotap header of the network packets to extract the RSS value. It
+would be possible to extend the system to work with the TOF (Time of
+Flight, i.e.  the signal propagation time), but that is out of scope for
+now (unless someone is willing to contribute).
+
+OwlPS features a self-calibration (or autocalibration) mechanism for
+signal strength fingerprinting-based algorithms, that avoids the
+time-consuming manual fingerprinting phase and allows considering
+dynamic changes of the environment (human, climatic, etc.) when
+computing the location of mobile terminals.
+
+
+
+
+
++ Releases +
+
+
+++ Timeline ++
+
+There is no precise timeline for OwlPS, but the file TODO.t2t lists a
+bunch of things that should be addressed at some point. A development
+point release is made after some work has been done, usually mainly on a
+particular topic. Usually such a release represents between 30 and 50
+commits.
+
+A stable release is made when a major goal has been reached and the
+interfaces stabilised. For research purposes, it is probably better to
+use the last development point release or even the last source version
+from the Git repository, especially if you are willing to contribute by
+integrating your changes in the main repository.
+
+
+++ Version numbers ++
+
+Releases are numbered according to the format //M.m.r//, where //M// is
+the major version number, //m// is the minor one, and //r// is the
+revision number.
+
+Development point release are numbered with an odd minor version number
+and a mandatory revision number starting at 0, for example:
+- v0.9.0
+- v1.1.0
+- v1.3.2
+
+
+A stable release is numbered with an even minor version number; the
+revision number is not mandatory, but it is allowed. For example:
+- v0.8
+- v1.0
+- v1.2
+- v1.2.1 (this one does not exist for real!)
+
+
+
+
++ Documentation summary +
+
+++ Architecture and other considerations ++
+
+- owlps-architecture.t2t
+- owlps-deployment.t2t
+
+
+++ Commands' user manuals ++
+
+- owlps-client.t2t
+- owlps-listenerd.t2t
+- owlps-aggregatord.t2t
+- owlps-positionerd.t2t
+
+
+++ Developping with OwlPS libraries ++
+
+% FIXME: these man pages could be generated from Doxygen comments
+- owlps.h
+- owlps-client.h
+- owlps-resultreader.h
+
+
+
+
++ Online ressources +
+
+- Official OwlPS' web page:
+  http://owlps.pu-pm.univ-fcomte.fr/
+
+- Project manager (source code, bug reports, documentation):
+  http://code.lm7.fr/p/owlps/

doc/preproc-man.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+#
+# This script is for preprocessing the files when man pages are
+# targetted. The main preproc.sh script is called automatically.
+#
+# Modifications done:
+# - Turns uppercase the first-level titles.
+
+sed -r 's/^([+=])([^+=].*)/\1\U\2/' $@ | ./preproc.sh

doc/preproc.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+#
+# This script is for preprocessing the files before to call txt2tags.
+#
+# Modifications done:
+# - Replaces all the occurrences of {{OWLPS_VERSION}} by the current Git
+#   version (as provided by git describe).
+
+# OwlPS source version
+OWLPS_VERSION=$(git describe 2>/dev/null || echo 'UNKNOWN_VERSION')
+
+sed "s/{{OWLPS_VERSION}}/${OWLPS_VERSION}/g" $@