[tor-commits] [ooni-probe/master] Update report documentation with better markup and better descriptions

[art at torproject.org]

commit 4648dd50aa44066eec9de1526f08a2e517ea14fb
Author: Arturo Filastò <art at fuffa.org>
Date:   Thu Dec 6 15:13:54 2012 +0100

    Update report documentation with better markup and better descriptions
---
 docs/source/reports.rst |   34 ++++++++++++++++++++++++----------
 1 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/docs/source/reports.rst b/docs/source/reports.rst
index cf5e008..7a49dcb 100644
--- a/docs/source/reports.rst
+++ b/docs/source/reports.rst
@@ -2,32 +2,46 @@ Reports
 =======
 
 The reports collected by ooniprobe are stored on
-https://ooni.torproject.org/reports/`reportFormatVersion`/`CC`/
+https://ooni.torproject.org/reports/ ``reportFormatVersion`` / ``CC`` /
 
-Where `CC` is the two letter country code as specified by
-http://en.wikipedia.org/wiki/ISO_3166-2.
+Where ``CC`` is the two letter country code as specified by `ISO 31666-2
+<http://en.wikipedia.org/wiki/ISO_3166-2>`_.
 
-For example the reports for Italy (`CC` is `it`) of the `reportVersion` 0.1 may
+For example the reports for Italy (``CC`` is ``it``) of the ``reportVersion`` 0.1 may
 be found in:
 
-::
-  https://ooni.torproject.org/reports/0.1/IT/
+https://ooni.torproject.org/reports/0.1/IT/
 
 
 This directory shall contain the various reports for the test using the
 following convention:
 
-`ISO8601`-AS`probeASNumber`.yamloo
+``dateInISO8601Format`` _ ``probeASNumber`` .yamloo
+
+The date is expressed using `ISO 8601 <http://en.wikipedia.org/wiki/ISO_8601`_
+including seconds and with no ``:`` to delimit hours, minutes, days.
+
+Like so
+
+  ``YEAR`` - ``MONTH`` - ``DAY`` T ``HOURS`` ``MINUTES`` ``SECONDS`` Z
+
+The time is **always** expressed in UTC.
 
 If a collision is detected then an int (starting with 1) will get appended to
 the test.
 
-For example a report that was created on the first of January 2012 at Noon (UTC
-time) sharp from MIT (AS3) will be stored here:
+For example if two report that are created on the first of January 2012 at Noon
+(UTC time) sharp from MIT (AS3) will be stored here:
 
 ::
 
-  https://ooni.torproject.org/reports/0.1/US/2012-01-01T120000Z-AS3.yamloo
+  https://ooni.torproject.org/reports/0.1/US/2012-01-01T120000Z_AS3.yamloo
+  https://ooni.torproject.org/reports/0.1/US/2012-01-01T120000Z_AS3.1.yamloo
+
+
+Note: it is highly unlikely that reports get created with the same exact
+timestamp from the same exact ASN. If this does happen it could be index of
+some malicious report poisoning attack in progress.
 
 
 Report format version changelog