Hey, all,
I've been working on a greenfield Perl client for the CQL Binary
Protocol. Since this is a client-in-progress, and my question
is actually about the protocol, I guessed dev@ seemed like the better
list, but please let me know if I should relocate to client-dev@.
As always happens when working from a spec, I have ended up with a quick
clarification request, a more involved question, and would like to know
how best to contribute to the document.
* 4.1.2. CREDENTIALS
My quick clarification is from this bit of text:
The body is a list of key/value informations. It is a [short] n,
followed by n pair of [string]. These key/value pairs [...]
Is this just a string map, and the text just isn't using consistent
terminology?
* 4.2.5.2. Rows
My more involved question is about this text describing the column
contents:
- <rows_content> is composed of <row_1>...<row_m> where m is <rows_count>.
Each <row_i> is composed of <value_1>...<value_n> where n is
<columns_count> and where <value_j> is a [bytes] representing the value
returned for the jth column of the ith row. In other words, <rows_content>
is composed of (<rows_count> * <columns_count>) [bytes].
I read this and thought, "Oh, sure I'll need to figure out the width of
the java types for the different columns, tedious but easily doable",
and then noticed some of the options are things like Blob or Varchar,
both which I would assume to be variable width. So how should one
determine how many bytes to read for different types?
I'm guessing the actual information about how much space the different
values take up is located somewhere else. At the very least it seems
like that should be mentioned, though even more ideal, it seems to me
all that information should be called out in the spec itself.
* Updating the docs
Which kind of brings me to my final question: what would be the best way
to contribute cleanups, etc. for the document, and how far could I take
it?
At the very least, there are a lot of typos I'd be happy to fix. I also
think the text could be tightened up in various ways. And I think some
things could be moved around to make the spec more accessible to
implementors.
But most importantly, I think it needs to be in some format that can
produce a hyperlinked document, because right now having to scroll back
and forth through everything is tedious indeed. But it seems improbable
to me that this is the native format for the document---did someone
really do that TOC by hand? So is there a source doc where it would be
best to actually work on edits? And if not, could I contribute by
converting it to textile (which seems already in use in the tree) or
perhaps markdown?
Mike.
