diff --git a/README.md b/README.md
index 6d953cc..f5d320b 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,482 @@
-# example-files
+# XDF example files
-Minimal example files to test XDF readers
+Example files to test XDF readers.
+
+* [minimal.xdf](#minimalxdf)
+* [clock\_resets.xdf](#clock_resetsxdf)
+* [empty\_streams.xdf](#empty_streamsxdf)
+
+## minimal.xdf
+
+Minimal example file with two streams.
+
+### Stream 0
+
+3 `int16` channels, 9 samples
+
+#### Header
+
+``` xml
+
+ SendDataC
+ EEG
+ 3
+ 10
+ int16
+ 50942.723319709003
+
+ xdfwriter_11_int
+
+```
+
+#### Footer
+
+``` xml
+
+ LabRecorder xdfwriter
+ 5.1
+ 5.9
+ 9
+
+
+
+ -.01
+
+
+
+ -.02
+
+
+
+```
+
+#### Time-series data
+
+Data:
+
+```
+[192, 255, 238],
+[ 12, 22, 32],
+[ 13, 23, 33],
+[ 14, 24, 34],
+[ 15, 25, 35],
+[ 12, 22, 32],
+[ 13, 23, 33],
+[ 14, 24, 34],
+[ 15, 25, 35]
+```
+
+Timestamps: 5.1 to 5.9 in .1 steps
+
+These time-stamps precede the first clock offset measurement, but for
+synchronization they will be handled with respect to the first (and
+only in this case) detected clock segment.
+
+#### Clock offsets
+
+Clock offset times do not match the footer. This should not happen
+with LabRecorder but as this file is code-generated it's just a
+quirk. The footer values are not used for synchronization so they can
+be safely ignored here.
+
+| time | value |
+|--------|---------|
+| 6.1 | -0.1 |
+| 7.1 | -0.1 |
+
+### Stream 0x02C0FFEE / 46202862
+
+1 string channel, 9 samples
+
+#### Header
+
+``` xml
+
+ SendDataString
+ StringMarker
+ 1
+ 10
+ string
+ 50942.723319709003
+
+ xdfwriter_11_str
+
+```
+
+#### Footer
+
+Identical to stream 0.
+
+#### Time-series data
+
+Data: `[ (the XML footer), 'Hello', 'World', 'from', 'LSL', 'Hello', 'World', 'from', 'LSL']`
+
+Timestamps: as above
+
+#### Clock offsets
+
+No clock offsets, so synchronization will have no effect.
+
+
+## clock\_resets.xdf
+### Stream 1
+#### Header
+
+``` xml
+
+ MyMarkerStream
+ Markers
+ 1
+ 0
+ string
+ myuidw43536
+ 1.1000000000000001
+ 564076.02850699995
+ 1efcb4a6-8894-4014-b404-4b6f6b2205f2
+ default
+ BP-LP-022
+
+ 16572
+ 16572
+
+ 16572
+ 16572
+
+
+```
+
+#### Footer
+
+``` xml
+
+ 653153.2121885
+ 259.6538279
+ 174
+
+
+
+ -652340.2838639501
+
+
+
+
+ 1121.165595
+
+
+
+```
+
+### Stream 2
+#### Header
+
+``` xml
+
+ BioSemi
+ EEG
+ 8
+ 100
+ float32
+ myuid34234
+ 1.1000000000000001
+ 653103.26692229998
+ fa3e14ab-b621-480e-a9d5-c740f0e47140
+ default
+ BP-LP-022
+
+ 16573
+ 16573
+
+ 16573
+ 16573
+
+
+```
+
+#### Footer
+``` xml
+
+ 653150.379117
+ 261.9267033
+ 27814
+
+
+
+ -652340.28383985
+
+
+
+
+ 1121.1656319
+
+
+
+```
+
+## empty\_streams.xdf
+
+Example containing empty and non-empty data and marker streams.
+
+### Stream 1
+
+1 `string` channel, 1 sample
+
+#### Header
+
+``` xml
+
+ ctrl
+ control
+ 1
+ string
+ kassia
+ 0.000000000000000
+ 1.100000000000000
+ 91684.87631725401
+ 4740b9ba-d45d-4e2b-9a4b-ee966d9b56df
+ default
+ kassia
+
+ 16572
+ 16572
+
+ 0
+ 0
+
+ pylsltools
+
+
+```
+
+#### Footer
+
+``` xml
+
+ 91725.014004246
+ 91725.014004246
+ 1
+
+
+
+ -1.889200211735442e-05
+
+
+
+
+ -3.837950498564169e-05
+
+
+
+```
+
+#### Time-series data
+
+| time_stamp | 0 |
+|------------|--------------|
+| 91725 | {"state": 2} |
+
+#### Clock offsets
+
+| time | value |
+|---------|-------|
+| 91716.7 | ≅0 |
+| 91721.7 | ≅0 |
+| 91726.7 | ≅0 |
+| 91731.7 | ≅0 |
+| 91736.7 | ≅0 |
+| 91741.7 | ≅0 |
+| 91746.7 | ≅0 |
+
+### Stream 2
+
+Empty stream.
+
+#### Header
+
+``` xml
+
+ Empty marker stream: test stream 0 counter
+ data
+ 1
+ string
+ test_stream.py:191748:0
+ 0.000000000000000
+ 1.100000000000000
+ 91696.18816467900
+ 6f7e0288-10b8-4f48-89f8-0381ce20922f
+ default
+ kassia
+
+ 16574
+ 16574
+
+ 0
+ 0
+
+ pylsltools
+
+
+```
+
+#### Footer
+
+``` xml
+
+ 0
+ 0
+ 0
+
+
+
+ -2.540599962230772e-05
+
+
+
+
+ -2.026499714702368e-05
+
+
+
+```
+
+#### Clock offsets
+
+As above.
+
+### Stream 3
+
+Empty stream.
+
+#### Header
+
+``` xml
+
+ Empty data stream: test stream 0 counter
+ data
+ 1
+ float32
+ test_stream.py:191790:0
+ 1.000000000000000
+ 1.100000000000000
+ 91699.83395166400
+ ff430a18-9954-43f5-bb5f-f5589e3aa6a2
+ default
+ kassia
+
+ 16575
+ 16575
+
+ 0
+ 0
+
+ pylsltools
+
+
+
+ misc
+
+
+
+
+```
+
+#### Footer
+
+``` xml
+
+ 0
+ 0
+ 0
+
+
+
+ -2.211050014011562e-05
+
+
+
+
+ -1.128000440075994e-05
+
+
+
+```
+
+#### Clock offsets
+
+As above.
+
+### Stream 4
+
+1 `int32` channel, 10 samples
+
+#### Header
+
+``` xml
+
+ Data stream: test stream 0 counter
+ data
+ 1
+ int32
+ test_stream.py:191695:0
+ 1.000000000000000
+ 1.100000000000000
+ 91690.55328314200
+ bc60b7bb-e632-407c-b3db-e42f9cad4179
+ default
+ kassia
+
+ 16573
+ 16573
+
+ 0
+ 0
+
+ pylsltools
+
+
+
+ misc
+
+
+
+
+```
+
+#### Footer
+
+``` xml
+
+ 91725.21394789348
+ 91735.21394789348
+ 10
+
+
+
+ -1.94335007108748e-05
+
+
+
+
+ -3.694550105137751e-05
+
+
+
+```
+
+#### Time-series data
+
+| time_stamp | ch:00 |
+|------------|-------|
+| 91725.2 | 0 |
+| 91726.2 | 1 |
+| 91727.2 | 2 |
+| 91728.2 | 3 |
+| 91729.2 | 4 |
+| 91730.2 | 5 |
+| 91731.2 | 6 |
+| 91732.2 | 7 |
+| 91733.2 | 8 |
+| 91734.2 | 9 |
+
+#### Clock offsets
+
+As above.
diff --git a/data_with_clock_resets.xdf b/clock_resets.xdf
similarity index 99%
rename from data_with_clock_resets.xdf
rename to clock_resets.xdf
index 27a68a8..a59d925 100644
Binary files a/data_with_clock_resets.xdf and b/clock_resets.xdf differ
diff --git a/empty_streams.xdf b/empty_streams.xdf
new file mode 100644
index 0000000..e7417cf
Binary files /dev/null and b/empty_streams.xdf differ
diff --git a/minimal.md b/minimal.md
deleted file mode 100644
index e817324..0000000
--- a/minimal.md
+++ /dev/null
@@ -1,78 +0,0 @@
-This is a minimal example file with two streams.
-
-# Stream 0
-
-3 int16 channels, 9 samples
-
-Data:
-
-```
-[192, 255, 238],
-[ 12, 22, 32],
-[ 13, 23, 33],
-[ 14, 24, 34],
-[ 15, 25, 35],
-[ 12, 22, 32],
-[ 13, 23, 33],
-[ 14, 24, 34],
-[ 15, 25, 35]
-```
-
-Timestamps: 5.1 to 5.9 in .1 steps
-
-The stream's XML header:
-```
-
- SendDataC
- EEG
- 3
- 10
- int16
- 50942.723319709003
-
- xdfwriter_11_int
-
-```
-its footer:
-```
-
- LabRecorder xdfwriter
- 5.1
- 5.9
- 9
-
-
-
- -.01
-
-
-
- -.02
-
-
-
-```
-
-
-# Stream 0x02C0FFEE / 46202862
-
-1 string channel, 9 samples
-
-Data: `[ (the XML footer), 'Hello', 'World', 'from', 'LSL', 'Hello', 'World', 'from', 'LSL']`
-
-Timestamps: as above
-
-The stream's XML header:
-```
-
- SendDataString
- StringMarker
- 1
- 10
- string
- 50942.723319709003
-
- xdfwriter_11_str
-
-```
-This stream's footer is identical to the previous one.
\ No newline at end of file