improves documentation formatting

Change-Id: I819dfdc98dab5fc75c8858b2afb1484e8d6b3b5a
Signed-off-by: José Bollo <jose.bollo@iot.bzh>

14 files changed, 260 insertions, 66 deletions

diff --git a/doc/afm-system-daemon.html b/doc/afm-system-daemon.html
index dac4315..00cf81a 100644
--- a/doc/afm-system-daemon.html
+++ b/doc/afm-system-daemon.html
@@ -8,10 +8,31 @@
 <h1>The afm-system-daemon</h1>
 
 <pre><code>version: 1
-Date:    15 March 2016
+Date:    29 mai 2016
 Author:  José Bollo
 </code></pre>
 
+<p><ul>
+ <li><a href="#The.afm-system-daemon">The afm-system-daemon</a>
+ <ul>
+  <li><a href="#Foreword">Foreword</a></li>
+  <li><a href="#Introduction">Introduction</a></li>
+  <li><a href="#Starting..strong.afm-system-daemon..strong.">Starting <strong>afm-system-daemon</strong></a></li>
+  <li><a href="#The.D-Bus.interface">The D-Bus interface</a>
+  <ul>
+   <li><a href="#Overview.of.the.dbus.interface">Overview of the dbus interface</a></li>
+   <li><a href="#The.protocol.over.D-Bus">The protocol over D-Bus</a>
+   <ul>
+    <li><a href="#Method.org.AGL.afm.system.install">Method org.AGL.afm.system.install</a></li>
+    <li><a href="#Method.org.AGL.afm.system.uninstall">Method org.AGL.afm.system.uninstall</a></li>
+   </ul>
+   </li>
+  </ul>
+  </li>
+ </ul>
+ </li>
+</ul></p>
+
 <a name="Foreword"></a>
 <h2>Foreword</h2>
 
@@ -76,30 +97,30 @@ located at /lib/systemd/system/afm-system-daemon.service.</p>
 <pre><code>-r
 --root directory
 
-     Set the root application directory.
+ Set the root application directory.
 
-     Note that the default root directory is defined
-     to be /usr/share/afm/applications (may change).
+ Note that the default root directory is defined
+ to be /usr/share/afm/applications (may change).
 
 -d
 --daemon
 
-     Daemonizes the process. It is not needed by sytemd.
+ Daemonizes the process. It is not needed by sytemd.
 
 -q
 --quiet
 
-     Reduces the verbosity (can be repeated).
+ Reduces the verbosity (can be repeated).
 
 -v
 --verbose
 
-     Increases the verbosity (can be repeated).
+ Increases the verbosity (can be repeated).
 
 -h
 --help
 
-     Prints a short help.
+ Prints a short help.
 </code></pre>
 
 <a name="The.D-Bus.interface"></a>
@@ -143,9 +164,9 @@ returns a dbus error that is a string.</p>
 installed applications.</p>
 
 <pre><code>dbus-send --session --print-reply \
-    --dest=org.AGL.afm.system \
-    /org/AGL/afm/system \
-    org.AGL.afm.system.install 'string:"/tmp/appli.wgt"'
+--dest=org.AGL.afm.system \
+/org/AGL/afm/system \
+org.AGL.afm.system.install 'string:"/tmp/appli.wgt"'
 </code></pre>
 
 <a name="The.protocol.over.D-Bus"></a>
diff --git a/doc/afm-system-daemon.md b/doc/afm-system-daemon.md
index 9a22add..7589574 100644
--- a/doc/afm-system-daemon.md
+++ b/doc/afm-system-daemon.md
@@ -3,9 +3,10 @@ The afm-system-daemon
 =====================
 
     version: 1
-    Date:    15 March 2016
+    Date:    29 mai 2016
     Author:  José Bollo
 
+TABLE-OF-CONTENT-HERE
 
 
 Foreword
diff --git a/doc/afm-user-daemon.html b/doc/afm-user-daemon.html
index 29001bb..77af347 100644
--- a/doc/afm-user-daemon.html
+++ b/doc/afm-user-daemon.html
@@ -8,10 +8,55 @@
 <h1>The afm-user-daemon</h1>
 
 <pre><code>version: 1
-Date:    15 March 2016
+Date:    29 mai 2016
 Author:  José Bollo
 </code></pre>
 
+<p><ul>
+ <li><a href="#The.afm-user-daemon">The afm-user-daemon</a>
+ <ul>
+  <li><a href="#Foreword">Foreword</a></li>
+  <li><a href="#Introduction">Introduction</a></li>
+  <li><a href="#Tasks.of..strong.afm-user-daemon..strong.">Tasks of <strong>afm-user-daemon</strong></a>
+  <ul>
+   <li><a href="#Maintaining.list.of.applications">Maintaining list of applications</a></li>
+   <li><a href="#Launching.applications">Launching applications</a></li>
+   <li><a href="#Managing.instances.of.running.applications">Managing instances of running applications</a></li>
+   <li><a href="#Installing.and.uninstalling.applications">Installing and uninstalling applications</a></li>
+  </ul>
+  </li>
+  <li><a href="#Starting..strong.afm-user-daemon..strong.">Starting <strong>afm-user-daemon</strong></a></li>
+  <li><a href="#Configuration.of.the.launcher">Configuration of the launcher</a>
+  <ul>
+   <li><a href="#mode.local">mode local</a></li>
+   <li><a href="#mode.remote">mode remote</a></li>
+   <li><a href="#L.substitutions">%substitutions</a></li>
+  </ul>
+  </li>
+  <li><a href="#The.D-Bus.interface">The D-Bus interface</a>
+  <ul>
+   <li><a href="#Overview.of.the.dbus.interface">Overview of the dbus interface</a></li>
+   <li><a href="#Using..strong..em.afm-util..em...strong.">Using <strong><em>afm-util</em></strong></a></li>
+   <li><a href="#The.protocol.over.D-Bus">The protocol over D-Bus</a>
+   <ul>
+    <li><a href="#Method.org.AGL.afm.user.detail">Method org.AGL.afm.user.detail</a></li>
+    <li><a href="#Method.org.AGL.afm.user.runnables">Method org.AGL.afm.user.runnables</a></li>
+    <li><a href="#Method.org.AGL.afm.user.install">Method org.AGL.afm.user.install</a></li>
+    <li><a href="#Method.org.AGL.afm.user.uninstall">Method org.AGL.afm.user.uninstall</a></li>
+    <li><a href="#Method.org.AGL.afm.user.start">Method org.AGL.afm.user.start</a></li>
+    <li><a href="#Method.org.AGL.afm.user.terminate">Method org.AGL.afm.user.terminate</a></li>
+    <li><a href="#Method.org.AGL.afm.user.stop">Method org.AGL.afm.user.stop</a></li>
+    <li><a href="#Method.org.AGL.afm.user.continue">Method org.AGL.afm.user.continue</a></li>
+    <li><a href="#Method.org.AGL.afm.user.state">Method org.AGL.afm.user.state</a></li>
+    <li><a href="#Method.org.AGL.afm.user.runners">Method org.AGL.afm.user.runners</a></li>
+   </ul>
+   </li>
+  </ul>
+  </li>
+ </ul>
+ </li>
+</ul></p>
+
 <a name="Foreword"></a>
 <h2>Foreword</h2>
 
@@ -149,48 +194,48 @@ located at /usr/lib/systemd/user/afm-user-daemon.service.</p>
 <pre><code>-a
 --application directory
 
-     Includes the given application directory to
-     the database base of applications.
+ Includes the given application directory to
+ the database base of applications.
 
-     Can be repeated.
+ Can be repeated.
 
 -r
 --root directory
 
-     Includes the root application directory to
-     the database base of applications.
+ Includes the root application directory to
+ the database base of applications.
 
-     Note that the default root directory for
-     applications is always added. It is defined
-     to be /usr/share/afm/applications (may change).
+ Note that the default root directory for
+ applications is always added. It is defined
+ to be /usr/share/afm/applications (may change).
 
-     Can be repeated.
+ Can be repeated.
 
 -m
 --mode (local|remote)
 
-     Set the default launch mode.
-     The default value is 'local'
+ Set the default launch mode.
+ The default value is 'local'
 
 -d
 --daemon
 
-     Daemonizes the process. It is not needed by sytemd.
+ Daemonizes the process. It is not needed by sytemd.
 
 -q
 --quiet
 
-     Reduces the verbosity (can be repeated).
+ Reduces the verbosity (can be repeated).
 
 -v
 --verbose
 
-     Increases the verbosity (can be repeated).
+ Increases the verbosity (can be repeated).
 
 -h
 --help
 
-     Prints a short help.
+ Prints a short help.
 </code></pre>
 
 <a name="Configuration.of.the.launcher"></a>
@@ -257,11 +302,11 @@ to launch an application declared of types <em>application/x-executable</em>,
 
 application/x-executable
 text/x-shellscript
-    %r/%c
+%r/%c
 
 text/html
-    /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon
-    /usr/bin/web-runtime http://localhost:%P/%c?token=%S
+/usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon
+/usr/bin/web-runtime http://localhost:%P/%c?token=%S
 </code></pre>
 
 <p>This shows that:</p>
@@ -443,9 +488,9 @@ returns a dbus error that is a string.</p>
 installed applications.</p>
 
 <pre><code>dbus-send --session --print-reply \
-    --dest=org.AGL.afm.user \
-    /org/AGL/afm/user \
-    org.AGL.afm.user.runnables string:true
+--dest=org.AGL.afm.user \
+/org/AGL/afm/user \
+org.AGL.afm.user.runnables string:true
 </code></pre>
 
 <a name="Using..strong..em.afm-util..em...strong."></a>
diff --git a/doc/afm-user-daemon.md b/doc/afm-user-daemon.md
index b7b6636..590b511 100644
--- a/doc/afm-user-daemon.md
+++ b/doc/afm-user-daemon.md
@@ -3,9 +3,10 @@ The afm-user-daemon
 ===================
 
     version: 1
-    Date:    15 March 2016
+    Date:    29 mai 2016
     Author:  José Bollo
 
+TABLE-OF-CONTENT-HERE
 
 Foreword
 --------
diff --git a/doc/application-framework.html b/doc/application-framework.html
index 3b62cb7..d2e19c5 100644
--- a/doc/application-framework.html
+++ b/doc/application-framework.html
@@ -8,10 +8,36 @@
 <h1>Application framework</h1>
 
 <pre><code>version: 1
-Date:    15 March 2016
+Date:    29 mai 2016
 Author:  José Bollo
 </code></pre>
 
+<p><ul>
+ <li><a href="#Application.framework">Application framework</a>
+ <ul>
+  <li><a href="#Foreword">Foreword</a></li>
+  <li><a href="#Overview">Overview</a></li>
+  <li><a href="#Comparison.to.other.frameworks">Comparison to other frameworks</a>
+  <ul>
+   <li><a href="#Tizen.framework">Tizen framework</a></li>
+   <li><a href="#xdg-app">xdg-app</a></li>
+   <li><a href="#ostro">ostro</a>
+</li>
+  </ul>
+  </li>
+ </ul>
+ </li>
+ <li><a href="#Organisation.of.directory.of.applications">Organisation of directory of applications</a>
+ <ul>
+  <li><a href="#Identity.of.installed.files">Identity of installed files</a></li>
+  <li><a href="#Labelling.the.directories.of.applications">Labelling the directories of applications</a></li>
+ </ul>
+ </li>
+ <li><a href="#Organisation.of.data">Organisation of data</a></li>
+ <li><a href="#Setting.Smack.rules.for.the.application">Setting Smack rules for the application</a></li>
+ <li><a href="#What.user.can.run.an.application.">What user can run an application?</a></li>
+</ul></p>
+
 <a name="Foreword"></a>
 <h2>Foreword</h2>
 
diff --git a/doc/application-framework.md b/doc/application-framework.md
index ac6d40d..278df60 100644
--- a/doc/application-framework.md
+++ b/doc/application-framework.md
@@ -3,9 +3,11 @@ Application framework
 =====================
 
     version: 1
-    Date:    15 March 2016
+    Date:    29 mai 2016
     Author:  José Bollo
 
+TABLE-OF-CONTENT-HERE
+
 Foreword
 --------
 
diff --git a/doc/doc.css b/doc/doc.css
index 19699bf..27be9dc 100644
--- a/doc/doc.css
+++ b/doc/doc.css
@@ -1,9 +1,39 @@
 body {
-    background: #fff url(triskel_iot_bzh.svg) no-repeat fixed right top;
-    font-family: "Verdana";
-    color: #000;
+	background: #fff url(triskel_iot_bzh.svg) no-repeat fixed right top;
+	font-family: "Verdana";
+	color: #000;
 }
 
-h1, h2, h3 { color: #306; }
+h1, h2, h3, h4 {
+	color: #306;
+	text-decoration: underline;
+}
+
+pre {
+	border: medium dashed #306;
+	border-width: 0.1em;
+	background-color: #eee;
+	margin-left: 2em;
+	margin-right: 2em;
+	padding: 1em;
+	outline: #555;
+}
 
+pre:first-of-type { width: 20em; }
 
+blockquote {
+	border-left: solid thick black;
+	background-color: #ff8;
+	font: bolder;
+	padding: 0.7em 1.5em;
+}
+
+table  {
+	margin-left: 2em;
+	background-color: #dff;
+	outline: 0.25em solid #a6f;
+/*	padding: 0.25em;*/
+}
+thead {background-color: #a6f;}
+tr:nth-child(even) {background-color: #aee;}
+td { padding: 0.1em 0.5em; }
diff --git a/doc/overview.html b/doc/overview.html
index 0c67b63..999b247 100644
--- a/doc/overview.html
+++ b/doc/overview.html
@@ -8,10 +8,23 @@
 <h1>AGL framework, overview of the proposal of IoT.bzh</h1>
 
 <pre><code>version: 1
-Date:    15 March 2016
+Date:    29 mai 2016
 Author:  José Bollo
 </code></pre>
 
+<p><ul>
+ <li><a href="#AGL.framework..overview.of.the.proposal.of.IoT.bzh">AGL framework, overview of the proposal of IoT.bzh</a>
+ <ul>
+  <li><a href="#Foreword">Foreword</a></li>
+  <li><a href="#Introduction">Introduction</a></li>
+  <li><a href="#Overview">Overview</a></li>
+  <li><a href="#Links.between.the..Security.framework..and.the..Application.framework.">Links between the "Security framework" and the "Application framework"</a></li>
+  <li><a href="#The.security.framework">The security framework</a></li>
+  <li><a href="#The.application.framework">The application framework</a></li>
+ </ul>
+ </li>
+</ul></p>
+
 <a name="Foreword"></a>
 <h2>Foreword</h2>
 
@@ -71,14 +84,14 @@ The 3 layers are providing components for:</p>
 
 <p>The figure below shows the history of these layers.</p>
 
-<pre><code>                  2014         2015
+<pre><code>              2014         2015
 Tizen OBS ----------+---------------------------&gt;
-                     \
-                      \
-     Tizen Yocto       +---------+--------------&gt;
-                                  \
-                                   \
-       meta-intel-iot-security      +-----------&gt;
+                 \
+                  \
+ Tizen Yocto       +---------+--------------&gt;
+                              \
+                               \
+   meta-intel-iot-security      +-----------&gt;
 </code></pre>
 
 <p>We took the decision to use these security layers that provides the
diff --git a/doc/overview.md b/doc/overview.md
index 22d8d81..6dc65bb 100644
--- a/doc/overview.md
+++ b/doc/overview.md
@@ -3,9 +3,11 @@ AGL framework, overview of the proposal of IoT.bzh
 ==================================================
 
     version: 1
-    Date:    15 March 2016
+    Date:    29 mai 2016
     Author:  José Bollo
 
+TABLE-OF-CONTENT-HERE
+
 Foreword
 --------
 
diff --git a/doc/security-framework.html b/doc/security-framework.html
index 98598f0..38fb2f9 100644
--- a/doc/security-framework.html
+++ b/doc/security-framework.html
@@ -8,10 +8,16 @@
 <h1>The security framework</h1>
 
 <pre><code>version: 1
-Date:    15 March 2016
+Date:    29 mai 2016
 Author:  José Bollo
 </code></pre>
 
+<p><ul>
+ <li><a href="#The.security.framework">The security framework</a></li>
+ <li><a href="#Setting.Smack.rules.for.the.application">Setting Smack rules for the application</a></li>
+ <li><a href="#What.user.can.run.an.application.">What user can run an application?</a></li>
+</ul></p>
+
 <a name="Setting.Smack.rules.for.the.application"></a>
 <h1>Setting Smack rules for the application</h1>
 
diff --git a/doc/security-framework.md b/doc/security-framework.md
index 7407c17..ad20742 100644
--- a/doc/security-framework.md
+++ b/doc/security-framework.md
@@ -3,10 +3,12 @@ The security framework
 ======================
 
     version: 1
-    Date:    15 March 2016
+    Date:    29 mai 2016
     Author:  José Bollo
 
 
+TABLE-OF-CONTENT-HERE
+
 Setting Smack rules for the application
 =======================================
 
diff --git a/doc/updt.sh b/doc/updt.sh
index a6292c8..1c9d023 100755
--- a/doc/updt.sh
+++ b/doc/updt.sh
@@ -1,25 +1,47 @@
-#!/bin/sh
+#!/bin/bash
 
-fmd() {
-cat << EOC
-<html>
+# the HTML template
+main='<html>
 <head>
   <link rel="stylesheet" type="text/css" href="doc.css">
   <meta charset="UTF-8">
 </head>
 <body>
-$(cat)
+GENERATED-MARKDOWN-HERE
 </body>
-</html>
-EOC
+</html>'
+
+# substitute the pattern $1 by the content of the file $2
+subst() {
+  awk -v pat="$1" -v rep="$(sed 's:\\:\\\\:g' $2)" '{gsub(pat,rep);gsub(pat,"\\&");print}'
+}
+
+# update the date field of file $1
+updadate() {
+  local x=$1
+  local t=$(git log -n 1 --format=%ct $x)
+  [[ -n "$t" ]] || t=$(stat -c %Y $x)
+  local d=$(LANG= date -d @$t +"%d %B %Y")
+  sed -i "s/^\(    Date: *\).*/\1$d/" $x
 }
 
+# make the html file for $1
+mkhtml() {
+  local x=$1
+  local h=${x%%.md}.html
+  expand -i $x | sed 's:^        :    :' > $h.pre
+  markdown -f toc,autolink $h.pre > $h.toc.no
+  markdown -Tf toc,autolink $h.pre > $h.toc.yes
+  head --bytes=-$(stat -c %s $h.toc.no) $h.toc.yes > $h.toc
+  echo "$main" |
+  subst GENERATED-MARKDOWN-HERE $h.toc.no |
+  subst TABLE-OF-CONTENT-HERE $h.toc > $h
+  rm $h.*
+}
 
+# apply
 for x in *.md; do
-  t=$(stat -c %Y $x)
-  t=$(git log -n 1 --format=%ct $x)
-  d=$(LANG= date -d @$t +"%d %B %Y")
-  sed -i "s/^\(    Date: *\).*/\1$d/" $x
-  markdown -f toc,autolink $x | fmd > ${x%%.md}.html
+  updadate $x
+  mkhtml $x
 done
 
diff --git a/doc/widgets.html b/doc/widgets.html
index 77bf236..e0f68f9 100644
--- a/doc/widgets.html
+++ b/doc/widgets.html
@@ -8,10 +8,31 @@
 <h1>The widgets</h1>
 
 <pre><code>version: 1
-Date:    15 March 2016
+Date:    29 mai 2016
 Author:  José Bollo
 </code></pre>
 
+<p><ul>
+ <li><a href="#The.widgets">The widgets</a>
+ <ul>
+  <li><a href="#The.widgets">The widgets</a>
+  <ul>
+   <li><a href="#signature.of.the">signature of the</a></li>
+   <li><a href="#directory.where.are.stored.applications">directory where are stored applications</a>
+</li>
+  </ul>
+  </li>
+ </ul>
+ </li>
+ <li><a href="#Organisation.of.directory.of.applications">Organisation of directory of applications</a>
+ <ul>
+  <li><a href="#Identity.of.installed.files">Identity of installed files</a></li>
+  <li><a href="#Labelling.the.directories.of.applications">Labelling the directories of applications</a></li>
+ </ul>
+ </li>
+ <li><a href="#Organisation.of.data">Organisation of data</a></li>
+</ul></p>
+
 <a name="The.widgets"></a>
 <h2>The widgets</h2>
 
diff --git a/doc/widgets.md b/doc/widgets.md
index 6016a0d..1b2df87 100644
--- a/doc/widgets.md
+++ b/doc/widgets.md
@@ -3,9 +3,11 @@ The widgets
 ===========
 
     version: 1
-    Date:    15 March 2016
+    Date:    29 mai 2016
     Author:  José Bollo
 
+TABLE-OF-CONTENT-HERE
+
 The widgets
 -----------