design: sparsestreams: section breakdown, markup, readability and grammar fixes

diff --git a/markdown/design/sparsestreams.md b/markdown/design/sparsestreams.md
index 708a99ad382b0822b9a2fd5aa8f41983746bd0dd..07e1a6d77c03d89e9fcb874f3a5cfd01bdaa4d51 100644 (file)
--- a/markdown/design/sparsestreams.md
+++ b/markdown/design/sparsestreams.md
@@ -2,19 +2,21 @@
 
 ## Introduction
 
-In 0.8, there was some support for Sparse Streams through the use of
-FILLER events. These were used to mark gaps between buffers so that
+In 0.8, there was some support for sparse streams through the use of
+`FILLER` events. These were used to mark gaps between buffers so that
 downstream elements could know not to expect any more data for that gap.
 
-In 0.10, segment information conveyed through SEGMENT events can be used
+In 0.10, segment information conveyed through `SEGMENT` events can be used
 for the same purpose.
 
-In 1.0, there is a GAP event that works in a similar fashion as the
-FILLER event in 0.8.
+In 1.0, there is a `GAP` event that works in a similar fashion as the
+`FILLER` event in 0.8.
 
 ## Use cases
 
-1) Sub-title streams Sub-title information from muxed formats such as
+### Sub-title streams
+
+Sub-title information from muxed formats such as
 Matroska or MPEG consist of irregular buffers spaced far apart compared
 to the other streams (audio and video). Since these usually only appear
 when someone speaks or some other action in the video/audio needs
@@ -23,16 +25,19 @@ apart. Downstream elements that want to mix sub-titles and video (and muxers)
 have no way of knowing whether to process a video packet or wait a moment
 for a corresponding sub-title to be delivered on another pad.
 
-2) Still frame/menu support In DVDs (and other formats), there are
-still-frame regions where the current video frame should be retained and
-no audio played for a period. In DVD, these are described either as a
-fixed duration, or infinite duration still frame.
+### Still frame/DVD menues
+
+In DVDs and other formats, there are still-frame regions where the current
+video frame should be retained and no audio played for a period. In DVD,
+these are described either as a fixed duration, or infinite duration still
+frame.
+
+### Avoiding processing silence from audio generators
 
-3) Avoiding processing silence from audio generators Imagine a source
-that from time to time produces empty buffers (silence or blank images).
-If the pipeline has many elements next, it is better to optimise the
-obsolete data processing in this case. Examples for such sources are
-sound-generators (simsyn in gst-buzztard) or a source in a voip
+Imagine a source that, from time to time, produces empty buffers (silence or
+blank images). If the pipeline has many elements next, it is better to
+optimise the absolute data processing in this case. Examples for such sources
+are sound-generators (simsyn in gst-buzztard) or a source in a voip
 application that uses noise-gating (to save bandwith).
 
 ## Details
@@ -60,10 +65,9 @@ a clock time, a SEGMENT update can be sent in its place.
 
 ### Still frame/menu support
 
-Still frames in DVD menus are not the same,
-in that they do not introduce a gap in the timestamps of the data.
-Instead, they represent a pause in the presentation of a stream.
-Correctly performing the wait requires some synchronisation with
+Still frames in DVD menus are different because they do not introduce a gap
+in the data timestamps. Instead, they represent a pause in the presentation
+of a stream. Correctly performing the wait requires some synchronisation with
 downstream elements.
 
 In this scenario, an upstream element that wants to execute a still frame
@@ -71,24 +75,24 @@ performs the following steps:
 
   - Send all data before the still frame wait
 
-  - Send a DRAIN event to ensure that all data has been played
+  - Send a `DRAIN` event to ensure that all data has been played
     downstream.
 
   - wait on the clock for the required duration, possibly interrupting
     if necessary due to an intervening activity (such as a user
     navigation)
 
-  - FLUSH the pipeline using a normal flush sequence (FLUSH\_START,
-    chain-lock, FLUSH\_STOP)
+  - FLUSH the pipeline using a normal flush sequence (`FLUSH_START`,
+    chain-lock, `FLUSH_STOP`)
 
   - Send a SEGMENT to restart playback with the next timestamp in the
     stream.
 
-The upstream element performing the wait must only do so when in the PLAYING
-state. During PAUSED, the clock will not be running, and may not even have
+The upstream element performing the wait must only do so when in the `PLAYING`
+state. During `PAUSED`, the clock will not be running, and may not even have
 been distributed to the element yet.
 
-DRAIN is a new event that will block on a src pad until all data downstream
+`DRAIN` is a new event that will block on a src pad until all data downstream
 has been played out.
 
 Flushing after completing the still wait is to ensure that data after the wait
@@ -103,7 +107,7 @@ data that needs to be presented, and this can be done by sending a
 SEGMENT update that moves the start time of the segment to the next
 timestamp when data will be sent.
 
-For video, however it is slightly different. Video frames are typically
+For video, however, it is slightly different. Video frames are typically
 treated at the moment as continuing to be displayed after their indicated
 duration if no new frame arrives. Here, it is desired to display a blank
 frame instead, in which case at least one blank frame should be sent before