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

Patrick Bannister edited comment on CASSANDRA-13047 at 4/7/18 3:10 AM:
-----------------------------------------------------------------------

Originally I asked a complicated question about how to handle the new docs, but 
I've found some more information that probably makes all my questions 
irrelevant. I'll continue studying the issue.

Reading doc/README.md, I see we're building our docs at 
[http://cassandra.apache.org/doc/latest/cql/index.html] with the gen-doc target 
in build.xml.

 

-Does this ticket have a hidden subtask to add the online CQL docs at 
[http://cassandra.apache.org/doc/latest/cql/index.html] to the cassandra build?-

-Currently, cqlsh tries to point to help at the following locations:-
 # -$CASSANDRA_DIR/doc/cql3/CQL.html-
 # -/usr/share/doc/cassandra/CQL.html-
 # -A URL, depending on the branch:-
 -3.0 goes to- 
 -[https://cassandra.apache.org/doc/cql3/CQL-3.0.html,] which seems to be the 
same as $CASSANDRA_DIR/doc/cql3/CQL.html-
 -3.11 and trunk go to [https://cassandra.apache.org/doc/cql3/CQL-3.2.html] 
(which currently serves a nice 404 Error)-

-CQL.html at $CASSANDRA_DIR/doc/cql3/CQL.html appears to be built by the ant 
build.xml target generate-cql-html.-

-Nothing uses what seems to be our latest and greatest online CQL docs at 
[http://cassandra.apache.org/doc/latest/cql/index.html,] and it doesn't look 
like that content is part of the current build.-

-As it stands, I can do the following:-
 * -Change 3.11 and trunk to use 
[https://cassandra.apache.org/doc/cql3/CQL-3.0.html] as their fallback URL 
instead of their current broken links-
 * -Double dip by continuing to prefer the filesystem CQL.html files if they're 
present, but falling back to the new online help at 
[http://cassandra.apache.org/doc/latest/cql/index.html], which would also mean 
a rewrite of pylib/cqlshlib/helptopics.py since the structure of the newer 
online help is different-
 * -Add the online CQL docs to our build, remove the old CQL.html, and 
completely favor the new content. This probably merits some more input if this 
is the chosen path, since I think I've seen some discussion on the lists about 
how to host and maintain our docs.-

 


was (Author: ptbannister):
Does this ticket have a hidden subtask to add the online CQL docs at 
[http://cassandra.apache.org/doc/latest/cql/index.html] to the cassandra build?

Currently, cqlsh tries to point to help at the following locations:
 # $CASSANDRA_DIR/doc/cql3/CQL.html
 # /usr/share/doc/cassandra/CQL.html
 # A URL, depending on the branch:
3.0 goes to 
[https://cassandra.apache.org/doc/cql3/CQL-3.0.html,] which seems to be the 
same as $CASSANDRA_DIR/doc/cql3/CQL.html
3.11 and trunk go to [https://cassandra.apache.org/doc/cql3/CQL-3.2.html] 
(which currently serves a nice 404 Error)

CQL.html at $CASSANDRA_DIR/doc/cql3/CQL.html appears to be built by the ant 
build.xml target generate-cql-html.

Nothing uses what seems to be our latest and greatest online CQL docs at 
[http://cassandra.apache.org/doc/latest/cql/index.html,] and it doesn't look 
like that content is part of the current build.

As it stands, I can do the following:
 * Change 3.11 and trunk to use 
https://cassandra.apache.org/doc/cql3/CQL-3.0.html as their fallback URL 
instead of their current broken links
 * Double dip by continuing to prefer the filesystem CQL.html files if they're 
present, but falling back to the new online help at 
[http://cassandra.apache.org/doc/latest/cql/index.html], which would also mean 
a rewrite of pylib/cqlshlib/helptopics.py since the structure of the newer 
online help is different
 * Add the online CQL docs to our build, remove the old CQL.html, and 
completely favor the new content. This probably merits some more input if this 
is the chosen path, since I think I've seen some discussion on the lists about 
how to host and maintain our docs.

 

> Point cqlsh help to the new doc
> -------------------------------
>
>                 Key: CASSANDRA-13047
>                 URL: https://issues.apache.org/jira/browse/CASSANDRA-13047
>             Project: Cassandra
>          Issue Type: Bug
>          Components: CQL
>            Reporter: Sylvain Lebresne
>            Assignee: Patrick Bannister
>            Priority: Major
>             Fix For: 4.0
>
>
> Cqlsh still points to the "old" textile CQL doc, but that's not really 
> maintain anymore now that we have the new doc (which include everything the 
> old doc had and more). We should update cqlsh to point to the new doc so we 
> can remove the old one completely.
> Any takers?



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org

Reply via email to