Improves documentation

The script updt.sh is revisited to generate better the meta data. The format of events is documented. Change-Id: I3bb7347f3ac0f660196a25a4c0c0432848fe4168 Signed-off-by: José Bollo <jose.bollo@iot.bzh>
author: José Bollo <jose.bollo@iot.bzh> 2016-06-10 13:49:34 +0200
committer: José Bollo <jose.bollo@iot.bzh> 2016-06-10 13:49:34 +0200
commit: 17b196f1326d6b6c249d44b8744d73d7bba12d7a (patch)
tree: 6592d70b095c010cf726ac27ad51fd6ca86cc61a /doc
parent: 6518887513840471ea9c5af7e534787717e6bd82 (diff)
13 files changed, 181 insertions, 61 deletions
diff --git a/doc/FAQ.md b/doc/FAQ.md
index 61105823..7dad1ab2 100644
--- a/doc/FAQ.md
+++ b/doc/FAQ.md
@@ -4,6 +4,5 @@ Frequently Asked Question about AFB-DAEMON
     Date:    27 mai 2016
     Author:  José Bollo
 
-TABLE-OF-CONTENT-HERE
 
 
diff --git a/doc/README.html b/doc/README.html
index a45c16e1..837505ae 100644
--- a/doc/README.html
+++ b/doc/README.html
@@ -4,7 +4,7 @@
   <meta charset="utf-8">
   <meta name="generator" content="pandoc">
   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
-  <title></title>
+  <title>### Inititial Build</title>
   <style type="text/css">code{white-space: pre;}</style>
   <!--[if lt IE 9]>
     <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
@@ -12,6 +12,9 @@
   <link rel="stylesheet" href="doc.css">
 </head>
 <body>
+<header>
+<h1 class="title">### Inititial Build</h1>
+</header>
 <nav id="TOC">
 <ul>
 <li><a href="#inititial-build">Inititial Build</a></li>
@@ -19,6 +22,7 @@
 <li><a href="#copy-nbprojet-at-project-base">Copy nbprojet at project base</a></li>
 </ul>
 </nav>
+<p>mkdir build cd build cmake .. ### Netbeans % Fulup Ar Foll % 14 décembre 2015</p>
 <h3 id="inititial-build">Inititial Build</h3>
 <p>mkdir build cd build cmake ..</p>
 <h3 id="netbeans">Netbeans</h3>
diff --git a/doc/afb-application-writing.html b/doc/afb-application-writing.html
index b394e6b9..1f1fcc1c 100644
--- a/doc/afb-application-writing.html
+++ b/doc/afb-application-writing.html
@@ -5,17 +5,38 @@
   <meta name="generator" content="pandoc">
   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
   <meta name="author" content="José Bollo">
+  <meta name="author" content="Fulup Ar Foll">
   <title>HOWTO WRITE an APPLICATION above AGL FRAMEWORK</title>
   <style type="text/css">code{white-space: pre;}</style>
   <!--[if lt IE 9]>
     <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
   <![endif]-->
+  <style type="text/css">
+table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
+  margin: 0; padding: 0; vertical-align: baseline; border: none; }
+table.sourceCode { width: 100%; line-height: 100%; }
+td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
+td.sourceCode { padding-left: 5px; }
+code > span.kw { color: #007020; font-weight: bold; }
+code > span.dt { color: #902000; }
+code > span.dv { color: #40a070; }
+code > span.bn { color: #40a070; }
+code > span.fl { color: #40a070; }
+code > span.ch { color: #4070a0; }
+code > span.st { color: #4070a0; }
+code > span.co { color: #60a0b0; font-style: italic; }
+code > span.ot { color: #007020; }
+code > span.al { color: #ff0000; font-weight: bold; }
+code > span.fu { color: #06287e; }
+code > span.er { color: #ff0000; font-weight: bold; }
+  </style>
   <link rel="stylesheet" href="doc.css">
 </head>
 <body>
 <header>
 <h1 class="title">HOWTO WRITE an APPLICATION above AGL FRAMEWORK</h1>
 <h2 class="author">José Bollo</h2>
+<h2 class="author">Fulup Ar Foll</h2>
 <h3 class="date">09 juin 2016</h3>
 </header>
 <nav id="TOC">
@@ -32,10 +53,16 @@
 <li><a href="#example-of-session-management">Example of session management</a></li>
 </ul></li>
 <li><a href="#format-of-replies">Format of replies</a><ul>
+<li><a href="#template">Template</a></li>
 <li><a href="#field-jtype">Field jtype</a></li>
 <li><a href="#field-request">Field request</a></li>
 <li><a href="#field-response">Field response</a></li>
-<li><a href="#template">Template</a></li>
+</ul></li>
+<li><a href="#format-of-events">Format of events</a><ul>
+<li><a href="#template-1">Template</a></li>
+<li><a href="#field-jtype-1">Field jtype</a></li>
+<li><a href="#field-event">Field event</a></li>
+<li><a href="#field-data">Field data</a></li>
 </ul></li>
 </ul></li>
 </ul>
@@ -130,6 +157,9 @@ Author:  José Bollo</code></pre>
   }
 }</code></pre>
 <h4 id="using-afb-client-demo">Using afb-client-demo</h4>
+<blockquote>
+<p>The program is packaged within AGL in the rpm <strong>libafbwsc-dev</strong></p>
+</blockquote>
 <p>Here is an example of exchange using <strong>afb-client-demo</strong>:</p>
 <pre><code>$ afb-client-demo ws://localhost:1234/api?token=123456
 auth connect
@@ -155,6 +185,19 @@ ON-REPLY 1:auth/check: {&quot;jtype&quot;:&quot;afb-reply&quot;,&quot;request&qu
 <h2 id="format-of-replies">Format of replies</h2>
 <p>Replies use javascript object returned as serialized JSON.</p>
 <p>This object contains at least 2 mandatory fields of name <strong>jtype</strong> and <strong>request</strong> and one optional field of name <strong>response</strong>.</p>
+<h3 id="template">Template</h3>
+<p>This is a template of replies:</p>
+<pre class="sourceCode json"><code class="sourceCode json"><span class="fu">{</span>
+   <span class="dt">&quot;jtype&quot;</span><span class="fu">:</span> <span class="st">&quot;afb-reply&quot;</span><span class="fu">,</span>
+   <span class="dt">&quot;request&quot;</span><span class="fu">:</span> <span class="fu">{</span>
+      <span class="dt">&quot;status&quot;</span><span class="fu">:</span> <span class="st">&quot;success&quot;</span><span class="fu">,</span>
+      <span class="dt">&quot;info&quot;</span><span class="fu">:</span> <span class="st">&quot;informationnal text&quot;</span><span class="fu">,</span>
+      <span class="dt">&quot;token&quot;</span><span class="fu">:</span> <span class="st">&quot;e83b36f8-d945-463d-b983-5d8ed73ba52&quot;</span><span class="fu">,</span>
+      <span class="dt">&quot;uuid&quot;</span><span class="fu">:</span> <span class="st">&quot;5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1&quot;</span><span class="fu">,</span>
+      <span class="dt">&quot;reqid&quot;</span><span class="fu">:</span> <span class="st">&quot;application-generated-id-23456&quot;</span>
+   <span class="fu">},</span>
+   <span class="dt">&quot;response&quot;</span><span class="fu">:</span> <span class="er">....any</span> <span class="er">response</span> <span class="er">object....</span>
+<span class="fu">}</span></code></pre>
 <h3 id="field-jtype">Field jtype</h3>
 <p>The field <strong>jtype</strong> must have a value of type string equal to <strong>&quot;afb-reply&quot;</strong>.</p>
 <h3 id="field-request">Field request</h3>
@@ -171,18 +214,22 @@ ON-REPLY 1:auth/check: {&quot;jtype&quot;:&quot;afb-reply&quot;,&quot;request&qu
 <p><strong>reqid</strong> is of type string. It is sent in response to HTTP requests that added a parameter of name <strong>reqid</strong> or <strong>x-afb-reqid</strong> at request time. Value returns in the reply has the exact same value as the one received in the request.</p>
 <h3 id="field-response">Field response</h3>
 <p>This field response optionally contains an object returned when request succeeded.</p>
-<h3 id="template">Template</h3>
-<p>This is a template of replies:</p>
-<pre><code>{
-  &quot;jtype&quot;: &quot;afb-reply&quot;,
-  &quot;request&quot;: {
-       &quot;status&quot;: &quot;success&quot;,
-       &quot;info&quot;: &quot;informationnal text&quot;,
-       &quot;token&quot;: &quot;e83b36f8-d945-463d-b983-5d8ed73ba52&quot;,
-       &quot;uuid&quot;: &quot;5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1&quot;,
-       &quot;reqid&quot;: &quot;application-generated-id-23456&quot;
-     },
-  &quot;response&quot;: ....any response object....
-}</code></pre>
+<h2 id="format-of-events">Format of events</h2>
+<p>Events are javascript object serialized as JSON.</p>
+<p>This object contains at least 2 mandatory fields of name <strong>jtype</strong> and <strong>event</strong> and one optional field of name <strong>data</strong>.</p>
+<h3 id="template-1">Template</h3>
+<p>Here is a template of event:</p>
+<pre class="sourceCode json"><code class="sourceCode json"><span class="fu">{</span>
+   <span class="dt">&quot;jtype&quot;</span><span class="fu">:</span> <span class="st">&quot;afb-event&quot;</span><span class="fu">,</span>
+   <span class="dt">&quot;event&quot;</span><span class="fu">:</span> <span class="st">&quot;sample_api_name/sample_event_name&quot;</span><span class="fu">,</span>
+   <span class="dt">&quot;data&quot;</span><span class="fu">:</span> <span class="er">...any</span> <span class="er">event</span> <span class="er">data...</span>
+<span class="fu">}</span></code></pre>
+<h3 id="field-jtype-1">Field jtype</h3>
+<p>The field <strong>jtype</strong> must have a value of type string equal to <strong>&quot;afb-event&quot;</strong>.</p>
+<h3 id="field-event">Field event</h3>
+<p>The field <strong>event</strong> carries the event's name.</p>
+<p>The name of the event is made of two parts separated by a slash: the name of the name of the API that generated the event and the name of event within the API.</p>
+<h3 id="field-data">Field data</h3>
+<p>This field data if present holds the data carried by the event.</p>
 </body>
 </html>
diff --git a/doc/afb-application-writing.md b/doc/afb-application-writing.md
index 1fd02e5f..772d9914 100644
--- a/doc/afb-application-writing.md
+++ b/doc/afb-application-writing.md
@@ -4,7 +4,7 @@ HOWTO WRITE an APPLICATION above AGL FRAMEWORK
     Date:    09 juin 2016
     Author:  José Bollo
 
-TABLE-OF-CONTENT-HERE
+
 
 Programmation Languages for Applications
 -----------------------------------------
@@ -166,6 +166,8 @@ Checking on closed session for uuid should be refused:
 
 #### Using afb-client-demo
 
+> The program is packaged within AGL in the rpm **libafbwsc-dev**
+
 Here is an example of exchange using **afb-client-demo**:
 
     $ afb-client-demo ws://localhost:1234/api?token=123456
@@ -202,6 +204,24 @@ Replies use javascript object returned as serialized JSON.
 This object contains at least 2 mandatory fields of name **jtype** and **request**
 and one optional field of name **response**.
 
+### Template
+
+This is a template of replies:
+
+```json
+{
+   "jtype": "afb-reply",
+   "request": {
+      "status": "success",
+      "info": "informationnal text",
+      "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
+      "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
+      "reqid": "application-generated-id-23456"
+   },
+   "response": ....any response object....
+}
+```
+
 ### Field jtype
 
 The field **jtype** must have a value of type string equal to **"afb-reply"**.
@@ -240,19 +260,39 @@ Value returns in the reply has the exact same value as the one received in the r
 
 This field response optionally contains an object returned when request succeeded.
 
+Format of events
+----------------
+
+Events are javascript object serialized as JSON.
+
+This object contains at least 2 mandatory fields of name **jtype** and **event**
+and one optional field of name **data**.
+
 ### Template
 
-This is a template of replies:
+Here is a template of event:
 
-    {
-      "jtype": "afb-reply",
-      "request": {
-           "status": "success",
-           "info": "informationnal text",
-           "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
-           "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
-           "reqid": "application-generated-id-23456"
-         },
-      "response": ....any response object....
-    }
+```json
+{
+   "jtype": "afb-event",
+   "event": "sample_api_name/sample_event_name",
+   "data": ...any event data...
+}
+```
+
+### Field jtype
+
+The field **jtype** must have a value of type string equal to **"afb-event"**.
+
+### Field event
+
+The field **event** carries the event's name.
+
+The name of the event is made of two parts separated by a slash:
+the name of the name of the API that generated the event
+and the name of event within the API.
+
+### Field data
+
+This field data if present holds the data carried by the event.
 
diff --git a/doc/afb-daemon-vocabulary.md b/doc/afb-daemon-vocabulary.md
index 8427b736..83472d51 100644
--- a/doc/afb-daemon-vocabulary.md
+++ b/doc/afb-daemon-vocabulary.md
@@ -4,7 +4,7 @@ Vocabulary for AFB-DAEMON
     Date:    27 mai 2016
     Author:  José Bollo
 
-TABLE-OF-CONTENT-HERE
+
 
 ## Event
 
diff --git a/doc/afb-overview.md b/doc/afb-overview.md
index 2ae8e066..1bd83240 100644
--- a/doc/afb-overview.md
+++ b/doc/afb-overview.md
@@ -4,7 +4,7 @@ Overview of AFB-DAEMON
     Date:    30 mai 2016
     Author:  José Bollo
 
-TABLE-OF-CONTENT-HERE
+
 
 Roles of afb-daemon
 -------------------
diff --git a/doc/afb-plugin-writing.html b/doc/afb-plugin-writing.html
index eaa7a370..6c866fb6 100644
--- a/doc/afb-plugin-writing.html
+++ b/doc/afb-plugin-writing.html
@@ -5,6 +5,7 @@
   <meta name="generator" content="pandoc">
   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
   <meta name="author" content="José Bollo">
+  <meta name="author" content="Fulup Ar Foll">
   <title>HOWTO WRITE a PLUGIN for AFB-DAEMON</title>
   <style type="text/css">code{white-space: pre;}</style>
   <!--[if lt IE 9]>
@@ -35,7 +36,8 @@ code > span.er { color: #ff0000; font-weight: bold; }
 <header>
 <h1 class="title">HOWTO WRITE a PLUGIN for AFB-DAEMON</h1>
 <h2 class="author">José Bollo</h2>
-<h3 class="date">30 mai 2016</h3>
+<h2 class="author">Fulup Ar Foll</h2>
+<h3 class="date">09 juin 2016</h3>
 </header>
 <nav id="TOC">
 <ul>
@@ -83,7 +85,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
 </nav>
 <h1 id="howto-write-a-plugin-for-afb-daemon">HOWTO WRITE a PLUGIN for AFB-DAEMON</h1>
 <pre><code>version: 1
-Date:    30 mai 2016
+Date:    09 juin 2016
 Author:  José Bollo</code></pre>
 <h2 id="summary">Summary</h2>
 <p>Afb-daemon binders serve files through HTTP protocol and offers to developers the capability to expose application API methods through HTTP or WebSocket protocol.</p>
diff --git a/doc/afb-plugin-writing.md b/doc/afb-plugin-writing.md
index bc43e4e4..9e13d0d5 100644
--- a/doc/afb-plugin-writing.md
+++ b/doc/afb-plugin-writing.md
@@ -1,10 +1,10 @@
 HOWTO WRITE a PLUGIN for AFB-DAEMON
 ===================================
     version: 1
-    Date:    30 mai 2016
+    Date:    09 juin 2016
     Author:  José Bollo
 
-TABLE-OF-CONTENT-HERE
+
 
 Summary
 -------
diff --git a/doc/afb-plugins-overview.html b/doc/afb-plugins-overview.html
index 6c1506ad..291b7f79 100644
--- a/doc/afb-plugins-overview.html
+++ b/doc/afb-plugins-overview.html
@@ -4,7 +4,9 @@
   <meta charset="utf-8">
   <meta name="generator" content="pandoc">
   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
-  <title></title>
+  <meta name="author" content="Manuel Bachmann">
+  <meta name="author" content="José Bollo">
+  <title>Overview of plugins shipped with AFB-Daemon</title>
   <style type="text/css">code{white-space: pre;}</style>
   <!--[if lt IE 9]>
     <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
@@ -12,6 +14,12 @@
   <link rel="stylesheet" href="doc.css">
 </head>
 <body>
+<header>
+<h1 class="title">Overview of plugins shipped with AFB-Daemon</h1>
+<h2 class="author">Manuel Bachmann</h2>
+<h2 class="author">José Bollo</h2>
+<h3 class="date">09 juin 2016</h3>
+</header>
 <nav id="TOC">
 <ul>
 <li><a href="#overview-of-plugins-shipped-with-afb-daemon">Overview of plugins shipped with AFB-Daemon</a><ul>
diff --git a/doc/afb-plugins-overview.md b/doc/afb-plugins-overview.md
index a6d59737..dfbe6010 100644
--- a/doc/afb-plugins-overview.md
+++ b/doc/afb-plugins-overview.md
@@ -1,10 +1,12 @@
-# Overview of plugins shipped with AFB-Daemon
+Overview of plugins shipped with AFB-Daemon
+===========================================
     Version: 1
     Date:    09 juin 2016
     Author:  Manuel Bachmann
 
 
-## List of plugins
+List of plugins
+---------------
 
 Here are the plugins shipped in the source tree:
 
@@ -18,7 +20,8 @@ Here are the plugins shipped in the source tree:
 All plugins may not be built, depending on the development libraries present on the system at build time.
 
 
-## Detail of plugins
+Detail of plugins
+-----------------
 
 ### Hello World
 
diff --git a/doc/afb-tests-overview.html b/doc/afb-tests-overview.html
index f663a75f..e9711c4e 100644
--- a/doc/afb-tests-overview.html
+++ b/doc/afb-tests-overview.html
@@ -5,6 +5,7 @@
   <meta name="generator" content="pandoc">
   <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
   <meta name="author" content="Manuel Bachmann">
+  <meta name="author" content="José Bollo">
   <title>Overview of tests shipped with AFB-Daemon</title>
   <style type="text/css">code{white-space: pre;}</style>
   <!--[if lt IE 9]>
@@ -16,7 +17,8 @@
 <header>
 <h1 class="title">Overview of tests shipped with AFB-Daemon</h1>
 <h2 class="author">Manuel Bachmann</h2>
-<h3 class="date">30 mai 2016</h3>
+<h2 class="author">José Bollo</h2>
+<h3 class="date">09 juin 2016</h3>
 </header>
 <nav id="TOC">
 <ul>
@@ -32,7 +34,7 @@
 </nav>
 <h1 id="overview-of-tests-shipped-with-afb-daemon">Overview of tests shipped with AFB-Daemon</h1>
 <pre><code>Version: 1
-Date:    30 mai 2016
+Date:    09 juin 2016
 Author:  Manuel Bachmann</code></pre>
 <h2 id="list-of-tests">List of tests</h2>
 <p>Here are the tests shipped in the source tree:</p>
diff --git a/doc/afb-tests-overview.md b/doc/afb-tests-overview.md
index 272d98af..6bb1b8a9 100644
--- a/doc/afb-tests-overview.md
+++ b/doc/afb-tests-overview.md
@@ -1,7 +1,7 @@
 Overview of tests shipped with AFB-Daemon
 =========================================
     Version: 1
-    Date:    30 mai 2016
+    Date:    09 juin 2016
     Author:  Manuel Bachmann
 
 
diff --git a/doc/updt.sh b/doc/updt.sh
index e6b721d6..5267ad5f 100755
--- a/doc/updt.sh
+++ b/doc/updt.sh
@@ -1,37 +1,52 @@
 #!/bin/bash
 
-meta() {
-	awk '
-		NR == 1 { t = $0; next }
-		NR == 2 && $1 ~ "======" { next }
-		NR == 2 { exit }
-		$1 == "Date:" { d = $2; for(i = 3 ; i <= NF ; i++) d = d " " $i; next }
-		$1 == "Author:" { a = $2; for(i = 3 ; i <= NF ; i++) a = a " " $i; next }
-		$1 == "version" || $1 == "Version" {next}
-		/^[ \t]*$/ { printf "%% %s\n%% %s\n%% %s\n", t, a, d; exit }
-	' "$1"
+title() {
+	sed '/^[ \t]*$/d' "$1" |
+	sed '/^===/Q' |
+	sed '/^---/Q' |
+	sed 's/^# //;T;Q' |
+	sed 's/^## //;T;Q' |
+	sed '/^---/Q'
 }
 
-# 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
+authors() {
+	git log --numstat --format='A %aN' -- "$1" |
+	awk '$1=="A"{sub(/^A /,"");a=$0; s[a]+=0; next}NF==3{s[a]+=($1+0)}END{for(a in s)print s[a]" : "a}' |
+	sort -nr |
+	sed 's/[^:]* : //' |
+	sed '1!s/^/; /' |
+	tr -d '\n'
+}
+
+dateof() {
+	local file="$1"
+	local t=$(git log -n 1 --format=%ct "$file")
+	[[ -n "$t" ]] || t=$(stat -c %Y "$file")
+	LANG= date -d @$t +"%d %B %Y"
 }
 
+meta() {
+	local file="$1"
+	local t=$(title "$file")
+	local a=$(authors "$file")
+	local d=$(dateof "$file")
+	echo "% $t"
+	echo "% $a"
+	echo "% $d"
+	cat "$file"
+}
+
+
 # make the html file for $1
 mkhtml() {
   local x=$1
   local h=${x%%.md}.html
-  { meta "$x"; sed 's/TABLE-OF-CONTENT-HERE//' "$x"; } |
+  meta "$x" |
   pandoc --css doc.css -f markdown -t html5 --toc > "$h"
 }
 
 # apply
 for x in *.md; do
-  updadate $x
   mkhtml $x
 done
author	José Bollo <jose.bollo@iot.bzh>	2016-06-10 13:49:34 +0200
committer	José Bollo <jose.bollo@iot.bzh>	2016-06-10 13:49:34 +0200
commit	17b196f1326d6b6c249d44b8744d73d7bba12d7a (patch)
tree	6592d70b095c010cf726ac27ad51fd6ca86cc61a /doc
parent	6518887513840471ea9c5af7e534787717e6bd82 (diff)