Clarified tutorial w.r.t reading/writing buffers.

Bug: 30736848

Signed-off-by: Wouter van Oortmerssen <wvo@google.com>

docs/source/Tutorial.md

@@ -1231,6 +1231,11 @@ like so:
 ~~~
 </div>
 
+Now you can write the bytes to a file, send them over the network..
+**Make sure your file mode (or tranfer protocol) is set to BINARY, not text.**
+If you transfer a FlatBuffer in text mode, the buffer will be corrupted,
+which will lead to hard to find problems when you read the buffer.
+
 #### Reading Orc FlatBuffers
 
 Now that we have successfully created an `Orc` FlatBuffer, the monster data can
@@ -1326,92 +1331,82 @@ before:
 ~~~
 </div>
 
-Then, assuming you have a variable containing to the bytes of data from disk,
+Then, assuming you have a buffer of bytes received from disk,
-network, etc., you can create a monster from this data:
+network, etc., you can create start accessing the buffer like so:
+
+**Again, make sure you read the bytes in BINARY mode, otherwise the code below
+won't work**
 
 <div class="language-cpp">
 ~~~{.cpp}
-  // We can access the buffer we just made directly. Pretend this came over a
+  uint8_t *buffer_pointer = /* the data you just read */;
-  // network, was read off of disk, etc.
-  auto buffer_pointer = builder.GetBufferPointer();
 
-  // Deserialize the data from the buffer.
+  // Get a pointer to the root object inside the buffer.
   auto monster = GetMonster(buffer_pointer);
 
-  // `monster` is of type`Monster *`, and points to somewhere inside the buffer.
+  // `monster` is of type `Monster *`.
-
   // Note: root object pointers are NOT the same as `buffer_pointer`.
 ~~~
 </div>
 <div class="language-java">
 ~~~{.java}
-  // We can access the buffer we just made directly. Pretend this came over a
+  byte[] bytes = /* the data you just read */
-  // network, was read off of disk, etc.
+  java.nio.ByteBuffer buf = java.nio.ByteBuffer.wrap(bytes);
-  java.nio.ByteBuffer buf = builder.dataBuffer();
 
-  // Deserialize the data from the buffer.
+  // Get an accessor to the root object inside the buffer.
   Monster monster = Monster.getRootAsMonster(buf);
 ~~~
 </div>
 <div class="language-csharp">
 ~~~{.cs}
-  // We can access the buffer we just made directly. Pretend this came over a
+  byte[] bytes = /* the data you just read */
-  // network, was read off of disk, etc.
+  var buf = new ByteBuffer(bytes);
-  var buf = builder.DataBuffer;
 
-  // Deserialize the data from the buffer.
+  // Get an accessor to the root object inside the buffer.
   var monster = Monster.GetRootAsMonster(buf);
 ~~~
 </div>
 <div class="language-go">
 ~~~{.go}
-  // We can access the buffer we just made directly. Pretend this came over a
+  var buf []byte = /* the data you just read */
-  // network, was read off of disk, etc.
-  buf := builder.FinishedBytes()
 
-  // Deserialize the data from the buffer.
+  // Get an accessor to the root object inside the buffer.
   monster := sample.GetRootAsMonster(buf, 0)
 
-  // Note: We use `0` for the offset here, since we got the data using the
+  // Note: We use `0` for the offset here, which is typical for most buffers
-  // `builder.FinishedBytes()` method. This simulates the data you would
+  // you would read. If you wanted to read from `builder.Bytes` directly, you
-  // store/receive in your FlatBuffer. If you wanted to read from the
+  // would need to pass in the offset of `builder.Head()`, as the builder
-  // `builder.Bytes` directly, you would need to pass in the offset of
+  // constructs the buffer backwards, so may not start at offset 0.
-  // `builder.Head()`, as the builder actually constructs the buffer backwards.
 ~~~
 </div>
 <div class="language-python">
 ~~~{.py}
-  # We can access the buffer we just made directly. Pretend this came over a
+  buf = /* the data you just read, in an object of type "bytearray" */
-  # network, was read off of disk, etc.
-  buf = builder.Output()
 
-  # Deserialize the data from the buffer.
+  // Get an accessor to the root object inside the buffer.
   monster = MyGame.Sample.Monster.Monster.GetRootAsMonster(buf, 0)
 
-  # Note: We use `0` for the offset here, since we got the data using the
+  # Note: We use `0` for the offset here, which is typical for most buffers
-  # `builder.Output()` method. This simulates the data you would store/receive
+  # you would read.  If you wanted to read from the `builder.Bytes` directly,
-  # in your FlatBuffer. If you wanted to read from the `builder.Bytes` directly,
   # you would need to pass in the offset of `builder.Head()`, as the builder
-  # actually constructs the buffer backwards.
+  # constructs the buffer backwards, so may not start at offset 0.
 ~~~
 </div>
 <div class="language-javascript">
 ~~~{.js}
-  // We can access the buffer we just made directly. Pretend this came over a
+  var bytes = /* the data you just read, in an object of type "Uint8Array" */
-  // network, was read off of disk, etc.
+  var buf = new flatbuffers.ByteBuffer(bytes);
-  var buf = builder.dataBuffer();
 
-  // Deserialize the data from the buffer.
+  // Get an accessor to the root object inside the buffer.
   var monster = MyGame.Sample.Monster.getRootAsMonster(buf);
 ~~~
 </div>
 <div class="language-php">
 ~~~{.php}
-  // We can access the buffer we just made directly. Pretend this came over a
+  $bytes = /* the data you just read, in a string */
-  // network, was read off of disk, etc.
+  $buf = Google\FlatBuffers\ByteBuffer::wrap($bytes);
-  $buf = $builder->dataBuffer();
 
-  // Deserialize the data from the buffer.
+  // Get an accessor to the root object inside the buffer.
   $monster = \MyGame\Sample\Monster::GetRootAsMonster($buf);
 ~~~
 </div>