EDU-1469: Re-writes idempotent publishing section to improve clarity

content/pub-sub/advanced.textile

@@ -935,54 +935,174 @@ h3(#idempotency). Idempotent publishing
 
 Idempotency ensures that multiple publishes of the same message cannot result in duplicate messages.
 
-It is possible that a client publishing a message using the REST interface may not receive acknowledgement of receipt from Ably, due to issues such as network failure outside of Ably's control. Clients will internally attempt to re-publish messages in these instances.
-
 When idempotent publishing is enabled, the Ably SDK will internally assign a unique ID to each message which ensures that subsequent retry attempts cannot result in duplicate messages. Idempotent publishing is enabled by default in all latest Ably SDKs. It can be disabled by setting the @idempotentRestPublishing@ "@ClientOptions@":/docs/api/rest-sdk#client-options to @false@.
 
-Note that Ably can only detect duplicate messages within a 2-minute window after the original message, with the same ID, is published. If a message with the same ID is published after this 2-minute window, it will be treated as a new message.
+In some cases you may wish to set the unique message ID yourself to achieve idempotency, such as:
 
-You can also specify message IDs externally. The following is an example of how you might do this:
+* To ensure idempotency when a publisher instance might be restarted, and continuous activity cannot be guaranteed.
+* To integrate with an upstream system that uses message IDs, to ensure idempotency across an entire message processing pipeline.
 
-```[rest_javascript]
-const rest = new Ably.Rest('{{API_KEY}}');
-const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
-await channel.publish([{data: 'payload', id: 'unique123'}]);
+If setting your own message IDs be aware of the "restrictions":https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically on its format when publishing messages atomically.
+
+<aside data-type='note'>
+<p>Ably can only detect duplicate messages within a 2-minute window after the original message, with the same ID, is published. If a message with the same ID is published after this 2-minute window, it will be treated as a new message.</p>
+</aside>
+
+The following is an example of specifying message IDs yourself when publishing:
+
+```[realtime_javascript]
+const realtime = new Ably.Realtime = '{{API_KEY}}';
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+const message = [{ data: 'payload', id: 'unique123' }];
 ```
 
-```[rest_go]
-rest, err := ably.NewREST(
+```[realtime_nodejs]
+const realtime = new Ably.Realtime = '{{API_KEY}}';
+const channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+const message = [{ data: 'payload', id: 'unique123' }];
+```
+
+```[realtime_ruby]
+realtime = Ably::Realtime.new(key: '{{API_KEY}}')
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+channel.publish(name: 'example', data: 'payload', id: 'unique123')
+```
+
+```[realtime_python]
+realtime = AblyRealtime('{{API_KEY}}')
+channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}')
+await channel.publish([{data: 'payload', id: 'unique123'}])
+```
+
+```[realtime_java]
+ClientOptions options = new ClientOptions('{{API_KEY}}');
+AblyRealtime ably = new AblyRealtime(options);
+Channel channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
+
+Message message = new Message();
+message.data = "payload";
+message.id = "unique123";
+```
+
+```[realtime_csharp]
+ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"{{API_KEY}}"];
+ARTRealtimeChannel *channel = [realtime.channels get:@"{{RANDOM_CHANNEL_NAME}}"];
+channel publish:@"example" data:@"payload" id:@"unique123" callback:^(ARTErrorInfo *error)
+```
+
+```[realtime_swift]
+let realtime = ARTRealtime(key: "{{API_KEY}}")
+let channel = realtime.channels.get("{{RANDOM_CHANNEL_NAME}}")
+channel.publish("example", data: "message data", id: "unique123")
+```
+
+```[realtime_objc]
+ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:("{{API_KEY}}"));
+ARTRealtimeChannel *channel = [realtime.channels get:("{{RANDOM_CHANNEL_NAME}}");
+[channel.publish("example", data: "message data", id: "unique123")];
+```
+
+```[realtime_flutter]
+final clientOptions = ably.ClientOptions(key: '{{API_KEY}}');
+final realtime = ably.Realtime(options: clientOptions);
+final channel = realtime.channels.get('{{RANDOM_CHANNEL_NAME}}');
+await message = ably.Message(data: 'payload', id: 'unique123');
+```
+
+```[realtime_go]
+realtime, err := ably.NewRealtime(
   ably.WithKey("{{API_KEY}}"))
 if err != nil {
   log.Fatalf("Error creating Ably client: %v", err)
 }
 
-channel := rest.Channels.Get("{{RANDOM_CHANNEL_NAME}}")
+channel := realtime.Channels.Get("{{RANDOM_CHANNEL_NAME}}")
 
 message := &ably.Message{
   Data: "payload",
   ID:   "unique123",
 }
+```
 
-// Publish the message to the channel
-err = channel.Publish(context.Background(), "eventName", message)
-if err != nil {
-  log.Fatalf("Error publishing message: %v", err)
-}
+```[rest_javascript]
+  const rest = new Ably.Rest = '{{API_KEY}}';
+  const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
+  const message = [{ data: 'payload', id: 'unique123' }];
+```
+
+```[rest_nodejs]
+  const rest = new Ably.Rest = '{{API_KEY}}';
+  const channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
+  const message = [{ data: 'payload', id: 'unique123' }];
+```
+
+```[rest_ruby]
+rest = Ably::Rest.new(key: '{{API_KEY}}')
+channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}')
+channel.publish(name: 'example', data: 'payload', id: 'unique123')
+```
+
+```[rest_python]
+rest = AblyRest('{{API_KEY}}')
+channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}')
+await channel.publish([{data: 'payload', id: 'unique123'}])
+```
+
+```[rest_php]
+$rest = new Ably\AblyRest('{{API_KEY}}');
+$channel = $rest->channels->get('{{RANDOM_CHANNEL_NAME}}')
+$channel->publish([{data: 'payload', id: 'unique123'}]);
 ```
 
 ```[rest_java]
-ClientOptions options = new ClientOptions("{{API_KEY}}");
-AblyRealtime ably = new AblyRealtime(options);
-Channel channel = ably.channels.get("{{RANDOM_CHANNEL_NAME}}");
+ClientOptions options = new ClientOptions('{{API_KEY}}');
+AblyRest ably = new AblyRest(options);
+Channel channel = ably.channels.get('{{RANDOM_CHANNEL_NAME}}');
 
 Message message = new Message();
 message.data = "payload";
 message.id = "unique123";
+```
 
-channel.publish(new Message[]{message});
+```[rest_csharp]
+ARTRealtime *rest = [[ARTRealtime alloc] initWithKey:@"{{API_KEY}}"];
+ARTRealtimeChannel *channel = [rest.channels get:@"{{RANDOM_CHANNEL_NAME}}"];
+channel publish:@"example" data:@"payload" id:@"unique123" callback:^(ARTErrorInfo *error)
 ```
 
-If manually specifying message IDs, it is important to be aware of how messages are published when calling the "publish()":/docs/api/rest-sdk/channels#publish method with an array of messages. See this "FAQ":https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically for further information.
+```[rest_swift]
+let rest = ARTRest(key: "{{API_KEY}}")
+var channel = rest.channels.get("{{RANDOM_CHANNEL_NAME}}")
+channel.publish("example", data: "message data", id: "unique123")
+```
+
+```[rest_objc]
+ARTRest *rest = [[ARTRest alloc] initWithKey:("{{API_KEY}}"));
+ARTRestChannel *channel = [rest.channels get:("{{RANDOM_CHANNEL_NAME}}");
+[channel.publish("example", data: "message data", id: "unique123")];
+```
+
+```[rest_flutter]
+final clientOptions = ably.ClientOptions(key: '{{API_KEY}}');
+final rest = ably.Rest(options: clientOptions);
+final channel = rest.channels.get('{{RANDOM_CHANNEL_NAME}}');
+await message = ably.Message(data: 'payload', id: 'unique123');
+```
+
+```[rest_go]
+rest, err := ably.NewREST(
+  ably.WithKey("{{API_KEY}}"))
+if err != nil {
+  log.Fatalf("Error creating Ably client: %v", err)
+}
+
+channel := rest.Channels.Get("{{RANDOM_CHANNEL_NAME}}")
+
+message := &ably.Message{
+  Data: "payload",
+  ID:   "unique123",
+}
+```
 
 h3(#publish-on-behalf). Publishing on behalf of a realtime connection