Improve doc: back-tick fix, packet/payload, etc #1
Conversation
-- only did non-bulk text updates through Section 3.2 ... more to come
-- bulk update converting double back-tick pairs to <tt>...</tt>
-- detailed language fix was on the imprecise use of the term "packet"
when we meant the "payload". I think everybody gets the idea that
the payload follows the headers; so TCP or UDP, we can address the
payload
-- bulk convert apostrophe (') character to "'". This is not
required for for proper rendering by the xml2rfc program; it is
done to help some editors avoid incorrect syntax highlighting
between apostrophes
-- detailed language fix proposal on the client/server vs peer-to-peer
use case. No fix here, yet. Question for the group.
Signed-off-by: Mark Deric <[email protected]>
Make the fix and remove the editor's note. Signed-off-by: Mark Deric <[email protected]>
|
The apostrophe conversion was to |
| </t> | ||
| </section> | ||
| <section title="Basic OpenVPN packet format"> | ||
|
|
||
| <section title="OpenVPN payload format"> |
There was a problem hiding this comment.
I would avoid using "payload" here since we use the same term later for the VPN playload inside the OpenVPN packets.
There was a problem hiding this comment.
@flichtenheld I see what you mean. As in the example of layout:
-opcode- || -session_id- || -packet_id- || auth_tag || * payload *
and in the chart heading in the "Overview of OPCODEs" section.
My suggestion here is that the use of "payload" in both of those examples is unconventional. My usage follows the convention that the payload is what comes after the headers. And the body of the section you identify in the comment only addresses the payload, not the full packet. To reconcile that with the unconventional usage, I would suggest calling the additional data that follows opcodes and other stuff at the front of the payload "more data", "control data", "optional data", "extra data", or "vpn traffic" depending on the specific context. I would be happy to add those changes to the PR.
There was a problem hiding this comment.
A couple references for conventional vs unconventional use of payload:
https://en.wikipedia.org/wiki/Network_packet
https://networkengineering.stackexchange.com/questions/35016/whats-the-difference-between-frame-packet-and-payload
and there are more by googling packet payload.
|
I don't really like the ' to ' change. This sounds like a workaround to a broken editor and makes the source code less readable. I thought you used emacs as well and my emacs has no problems with the ' in the xml source code. |
|
I believe apostrophe is a "special character" in XML, so it should be avoided in plain and be encoded instead. Some quick (and various) references:
This seems to be quite standard. |
I do use emacs and the xml syntax highlighting changed the text color between two unrelated apostrophes as shown If you have a better setting that avoids this, please share. |
|
@schwabe the above is for you |
-- Only did non-bulk text updates through Section 3.2
-- Detailed language fix was on the imprecise use of the term "packet"
when we meant the "payload". I think everybody gets the idea that
the payload follows the headers; so TCP or UDP, we can address the
payload
-- Revise "The OpenVPN Wire Protocol" section start
-- Bulk update converting double back-tick pairs to ...
-- Bulk convert apostrophe (') character to "'". This is not
required for for proper rendering by the xml2rfc program; it is
done to help some editors avoid incorrect syntax highlighting
between apostrophes