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

markdown/design/seqnums.md

@@ -6,11 +6,11 @@ identify a group of events and messages as being part of the same
 
 Whenever a new event or message is created, a seqnum is set into them.
 This seqnum is created from an ever increasing source (starting from 0
-and it might wrap around), so each new event and message gets a new and
+but it might wrap around), so each new event and message gets a new and
 hopefully unique seqnum.
 
 Suppose an element receives an event A and, as part of the logic of
-handling the event A, creates a new event B. B should have its seqnum to
+handling the event A, creates a new event B. B should have its seqnum be
 the same as A, because they are part of the same operation. The same
 logic applies if this element had to create multiple events or messages,
 all of those should have the seqnum set to the value on the received
@@ -28,51 +28,53 @@ application.
 Seqnums are also useful for elements to discard duplicated events,
 avoiding handling them again.
 
+## Scenarios
+
 Below are some scenarios as examples of how to handle seqnums when
 receving events:
 
-# Forcing EOS on the pipeline
+### Forcing EOS on the pipeline
 
 The application has a pipeline running and does a
-`gst_element_send_event` to the pipeline with an EOS event. All the
+`gst_element_send_event()` to the pipeline with an EOS event. All the
 sources in the pipeline will have their `send_event` handlers called and
 will receive the event from the application.
 
 When handling this event, the sources will push either the same EOS
 downstream or create their own EOS event and push. In the later case,
 the source should copy the seqnum from the original EOS to the newly
-created. This same logic applies to all elements that receive the EOS
+created one. This same logic applies to all elements that receive the EOS
 downstream, either push the same event or, if creating a new one, copy
 the seqnum.
 
 When the EOS reaches the sink, it will create an EOS message, copy the
 seqnum to the message and post to the bus. The application receives the
-message and can compare the seqnum of the message with the one from the
+message and can compare its seqnum with the one from the
 original event sent to the pipeline. If they match, it knows that this
 EOS message was caused by the event it pushed and not from other reason
 (input finished or configured segment was over).
 
-# Seeking
+### Seeking
 
-A seek event sent to the pipeline is forwarded to all sinks in it. Those
-sinks, then, push the seek event upstream until they reach an element
+A seek event sent to the pipeline is forwarded to all sinks in it. These
+sinks, then, push the `SEEK` event upstream until they reach an element
 that is capable of handling it. If the element handling the seek has
 multiple source pads (tipically a demuxer is handling the seek) it might
 receive the same seek event on all pads. To prevent handling the same
 seek event multiple times, the seqnum can be used to identify those
-events as being the same and only handle the first received.
+events as being the same and only handle the one received first.
 
-Also, when handling the seek, the element might push flush-start,
-flush-stop and a segment event. All those events should have the same
-seqnum of the seek event received. When this segment is over and an
-EOS/Segment-done event is going to be pushed, it also should have the
-same seqnum of the seek that originated the segment to be played.
+Also, when handling the seek, the element might push `FLUSH_START`,
+`FLUSH_STOP` and a segment event. All these events should have the
+seqnum of the received seek event. When this segment is over and an
+`EOS/SEGMENT_DONE` event is going to be pushed, it should also have the
+seqnum of the seek that originated the segment to be played.
 
-Having the same seqnum as the seek on the segment-done or EOS events is
+Having the same seqnum as the seek on the `SEGMENT_DONE` or EOS events is
 important for the application to identify that the segment requested by
 its seek has finished playing.
 
-# Questions
+## Questions
 
 What happens if the application has sent a seek to the pipeline and,
 while the segment relative to this seek is playing, it sends an EOS