DOCS(dev): Convert network protocol rst to md #6715
Conversation
The cross-document reference apparently worked on readthedocs (our previous docs), but does not work on GitHub. The cross-document figure reference is replaced with a file reference.
The figure follows below the paragraph.
This is done as a separate commit to retain Git change file history association. (Git does not store renames. It assumes renames according to content similarity.)
Two tables are not converted because they are not flat tables but contain "complex" content/structure.
|
I initially tried converting with pandoc, but that did not result in complete, correct, clean Markdown. So I did these conversions manually, step-by-step. |
There was a problem hiding this comment.
I would vote for linking to the actual Protobuf file for checking the exact structure for messages. Duplicating their structure here only adds potential for making them become out of sync.
Also, I do realize that my review comments have nothing to do with the conversion to Markdown itself. So I'd be fine if we address them in another follow-up PR (though for me it'd also be fine to do it here).
| | `os_version` | `string` | | ||
|
|
||
| The version field is a combination of major, minor and patch version numbers (e.g. 1.2.0) | ||
| so that major number takes two bytes and minor and patch numbers take one byte each. |
There was a problem hiding this comment.
Iirc this is now the legacy version format. We now use two bytes for every part.
I would tend to just mention the new format but would be fine with mentioning both.
| features such as encryption are implemented by the transport layer. Integers | ||
| above 8-bits are encoded using the *Variable length integer encoding*. | ||
|
|
||
| ## Packet format |
There was a problem hiding this comment.
Imo we should just describe the new Protobuf based format.
There was a problem hiding this comment.
I am not familiar with a change of old and new formats.
I see MumbleUDP.proto. So this doc reported an older voice channel protocol?
Do current clients support legacy and new, and servers default to proto if available on the client?
|
I'll address them as follow-ups to keep this MR/changeset narrow/specific scope. |
|
I'm currently drafting a first changeset to update references, improve text, and add notes about outdated. I'm considering doing a more thorough fixup/cleanup/removal afterwards. |
Convert our network protocol docs from rst (ReStructuredText) to md (Markdown) format.
This changeset is a followup to PR #6623. In that PR, which first integrated these docs into this repository, the comments indicated consensus that the docs should be in Markdown format to match our other docs.
This changeset is based on PR #6714, which does some baseline corrections, and which should be merged first.
Two tables are not converted to Markdown tables because they are not flat tables, which is hard, if not impossible, to represent in Markdown. Preformatted code blocks are being used for them instead.
Otherwise, the conversion seems straightforward.
The changeset includes individual commits by change type, so each kind of change can be traced. The first commit is purely a rename to ensure Git follows the content history across the file conversion. Unless there is interest in the individual changes, a review of the target state or full diff makes the most sense/is enough.
Checks