[Standards] Syntax Highlighting in XEPs

Florian Schmaus flo at geekplace.eu
Sat Jan 28 17:12:47 UTC 2017


On 28.01.2017 17:00, Tobias M wrote:
> 
>> On 28 Jan 2017, at 16:50, Sam Whited <sam at samwhited.com
>> <mailto:sam at samwhited.com>> wrote:
>>
>> Currently there are several XEPs that contain examples of a round trip
>> between the client and the server that delineate client sent packets
>> and server sent packets with some text similar to this:
>>
>> ```
>> Client:
>> <iq/>
>>
>> Server:
>> <iq type='result'/>
>> ```
>>
>> This leads to strange results in the syntax highlighting of the example.
>> My initial thought was to replace them with comments (possibly noting
>> that the comments were for example only and not valid in an XMPP
>> stream if it wasn't obvious from the context):
>>
>> ```
>> <!-- Client -->
>> <iq/>
>>
>> <!-- Server -->
>> <iq type='result'/>
>> ```
>>
>> but someone else told me they weren't a fan of that approach. Does
>> anyone have opinions on why we should or should not use comments? Any
>> alternative ideas?
> 
> Instead of :
>>       <example caption='Focus updates payload information for a channel'>
>>         <![CDATA[
>> SEND: <iq to='garden.montague.lit' from='romeo at montague.lit
>> <mailto:from='romeo at montague.lit>/orchard' 
>>           type='set' id='74s'>
>>>>       </iq>
>> ]]></example>
> 
> You could have:
>>  <protocol-example caption='Focus updates payload information for a
>> channel’>
>> <send-example>
>>         <![CDATA[
>> <iq to='garden.montague.lit' from='romeo at montague.lit
>> <mailto:from='romeo at montague.lit>/orchard' 
>>           type='set' id='74s'>
>>>>       </iq>]]>
>> </send-example>
>> </protocol-example>
> 
> The same thing for the receiving part, so you could have multiple
> send-example/recv-example in a protocol-example element. I think the
> changes to our XSL for HTML/PDF generation should be minimal to support
> that.

I don't think that "Send" and "Receive" is a good idea, as you still
need to mention involved party. It gets even more complicated if more
than two parties are involved.

- Florian

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 603 bytes
Desc: OpenPGP digital signature
URL: <http://mail.jabber.org/pipermail/standards/attachments/20170128/bcb89e69/attachment.sig>


More information about the Standards mailing list