Details

    • Type: Sub-task Sub-task
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Fix Version/s: 1.1.2
    • Component/s: API
    • Labels:

      Description

      The language doc (doc/cql/CQL.textile) needs to be forked for CQLv3 and updated accordingly.

        Activity

        Hide
        Sylvain Lebresne added a comment -

        I've forked and update the doc at https://github.com/pcmanus/cassandra/commits/3779.

        Note that this is a pretty extensive rewrite, but I wanted to make sure it reflected the code and typically rewriting the grammar parts was simpler than checking all the diffs. The doc is also reorganized (and imho improved by it). I've also played with the CSS, but if others don't like it, I'll just keep that CSS for my own use

        Going through that also make made remark a few inconsistency here and there in the code. I've noted those down and will open tickets for those, but I've sometimes redacted the doc as if those were fixed. If one of those small fixes/change don't make it, I'll update the doc accordingly. Besides, CQL3 is beta so so is the doc so far.

        Please don't hesitate to voice criticism and other complains.

        Show
        Sylvain Lebresne added a comment - I've forked and update the doc at https://github.com/pcmanus/cassandra/commits/3779 . Note that this is a pretty extensive rewrite, but I wanted to make sure it reflected the code and typically rewriting the grammar parts was simpler than checking all the diffs. The doc is also reorganized (and imho improved by it). I've also played with the CSS, but if others don't like it, I'll just keep that CSS for my own use Going through that also make made remark a few inconsistency here and there in the code. I've noted those down and will open tickets for those, but I've sometimes redacted the doc as if those were fixed. If one of those small fixes/change don't make it, I'll update the doc accordingly. Besides, CQL3 is beta so so is the doc so far. Please don't hesitate to voice criticism and other complains.
        Hide
        Sylvain Lebresne added a comment - - edited

        Forgot to say: The doc is trying to stick to a vocabulary that I think make sense for CQL3. In particular, it does not respect the current Cassandra vocabulary. For instance, the notion of column and row in the document are the ones of SQL, not the one of our internal representation. I also use the term table instead of column family systematically. While I understand this may be confusing for current users of Cassandra, I think this happens to be a very good fit to CQL3 and imho trying to do otherwise would make it very hard to explain CQL3. Besides, I doubt Cassandra users have already forgotten the notion of columns and rows in SQL, so the confusion should be minimal as long as we make the context clear.

        But this means I'll probably add a small warning at the beginning of the doc.

        Show
        Sylvain Lebresne added a comment - - edited Forgot to say: The doc is trying to stick to a vocabulary that I think make sense for CQL3. In particular, it does not respect the current Cassandra vocabulary. For instance, the notion of column and row in the document are the ones of SQL, not the one of our internal representation. I also use the term table instead of column family systematically. While I understand this may be confusing for current users of Cassandra, I think this happens to be a very good fit to CQL3 and imho trying to do otherwise would make it very hard to explain CQL3. Besides, I doubt Cassandra users have already forgotten the notion of columns and rows in SQL, so the confusion should be minimal as long as we make the context clear. But this means I'll probably add a small warning at the beginning of the doc.
        Hide
        Sylvain Lebresne added a comment -

        I pushed another commit on https://github.com/pcmanus/cassandra/commits/3779-v2 (I messed up my original branch so pushed a new one with both the old and new commit) to:

        • update the doc with the last cql3 changes
        • add 2 sentences at the beginning to explain that rows and columns are used in the sense of SQL
        • add a small banner at the beginning to remind people that CQL3 is beta currently.
        Show
        Sylvain Lebresne added a comment - I pushed another commit on https://github.com/pcmanus/cassandra/commits/3779-v2 (I messed up my original branch so pushed a new one with both the old and new commit) to: update the doc with the last cql3 changes add 2 sentences at the beginning to explain that rows and columns are used in the sense of SQL add a small banner at the beginning to remind people that CQL3 is beta currently.
        Hide
        Sylvain Lebresne added a comment -

        Any news on the review of this? I think it would be nice to get the doc out quickly (even if it's not perfect).

        Show
        Sylvain Lebresne added a comment - Any news on the review of this? I think it would be nice to get the doc out quickly (even if it's not perfect).
        Hide
        Eric Evans added a comment - - edited

        Sorry. I plan to have a look over the next few days, but if you get tired of waiting, I see no reason not to post them (any docs are better than no docs).

        Show
        Eric Evans added a comment - - edited Sorry. I plan to have a look over the next few days, but if you get tired of waiting, I see no reason not to post them (any docs are better than no docs).
        Hide
        Sylvain Lebresne added a comment -

        So I did commit that (with a few minor change to account for the last evolutions of CQL3). I'll wait a few days in case somewhat wants to do some proof-reading, but then I'll put it accessible from http://cassandra.apache.org/download/ (like the one for CQL2).

        Show
        Sylvain Lebresne added a comment - So I did commit that (with a few minor change to account for the last evolutions of CQL3). I'll wait a few days in case somewhat wants to do some proof-reading, but then I'll put it accessible from http://cassandra.apache.org/download/ (like the one for CQL2).

          People

          • Assignee:
            Sylvain Lebresne
            Reporter:
            Eric Evans
            Reviewer:
            Eric Evans
          • Votes:
            1 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development