[jira] [Commented] (CASSANDRA-4879) CQL help in trunk/doc/cql3/CQL.textile outdated

["Sylvain Lebresne (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/CASSANDRA-4879?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13487818#comment-13487818 ] 

Sylvain Lebresne commented on CASSANDRA-4879:
---------------------------------------------

That's on my todo list and I'll make sure that's ready for 1.2 release. However:

bq. BNR-like formatting needs to be replaced, right?

I'm not sure about that. The fact that we use '<' and '>' for collection types is not a big deal in the sense that we can quote those characters in the grammar (much like we do when we have other signs like '=', ':', etc...). Since that's a reference documentation, I'd rather have the grammar be as precise as can be (nested [..] do matter) and not rely on things like italics (that don't translate if you say copy-paste the grammar into a text file). Yes, it might be slightly less readable, but that's what the examples are for. Of course the datastax documentation should feel free to use a syntax that is easier on the eye.
                
> CQL help in trunk/doc/cql3/CQL.textile outdated
> -----------------------------------------------
>
>                 Key: CASSANDRA-4879
>                 URL: https://issues.apache.org/jira/browse/CASSANDRA-4879
>             Project: Cassandra
>          Issue Type: Bug
>    Affects Versions: 1.2.0 beta 1
>            Reporter: Kristine Hahn
>            Assignee: Sylvain Lebresne
>              Labels: documentation
>
> https://github.com/apache/cassandra/blob/trunk/doc/cql3/CQL.textile doesn't include the new create keyspace syntax or the collections. Last time, I updated the CQL.textile for Paul Cannon to review. Want me to do it again? 
> BNR-like formatting needs to be replaced, right?, because the brackets now have literal meaning. I test-applied this custom formatting to commands and it seems ok: Uppercase means literal (lowercase nonliteral), italics mean optional, the | symbol means OR, ... means repeatable. The ... in italics doesn't strictly explain things like nested [...] does, but it's easier on the eyes and loosely understandable. Any doubt could be erased by examples, I think. 

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira