[
https://issues.apache.org/jira/browse/CASSANDRA-20195?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17914770#comment-17914770
]
Michael Semb Wever edited comment on CASSANDRA-20195 at 1/20/25 6:53 PM:
-------------------------------------------------------------------------
bq. but why are the docs in modules in AsciiDoc while CQL.textile uses textile
for the same content
The original is CQL.textile. This has always been generated as part of the
in-tree build and bundled into artefacts/releases.
After the antora build was introduced (using asciidoc files), from
cassandra-website that builds our website, we duplicated the file to
cql_singlefile.adoc so it was also on the website.
We didn't spent the time back then to figure out how to just use the
CQL.textile source. (And we don't yet have in place any way to build the whole
antora in-tree module into html that can be bundled into releases, but we
eventually want that too, ref: CASSANDRA-17260 )
was (Author: michaelsembwever):
bq. but why are the docs in modules in AsciiDoc while CQL.textile uses textile
for the same content
The original is CQL.textile. This has always been generated as part of the
in-tree build and bundled into artefacts/releases.
After the antora build was introduced (using asciidoc files), from
cassandra-website that builds our website, we duplicated the file to
cql_singlefile.adoc so it was also on the website.
We didn't spent the time back then to figure out how to just use the
CQL.textile source. (And we don't have in place a way to build the whole
antora in-tree module into html that can be bundled into releases, but we
eventually want that too, ref: CASSANDRA-17260 )
> CQL single file doc page has obsolete and invalid markup
> --------------------------------------------------------
>
> Key: CASSANDRA-20195
> URL: https://issues.apache.org/jira/browse/CASSANDRA-20195
> Project: Apache Cassandra
> Issue Type: Bug
> Components: Documentation/Website
> Reporter: Brad Schoening
> Assignee: Brad Schoening
> Priority: Normal
> Attachments: image-2025-01-08-13-25-42-002.png,
> image-2025-01-08-13-26-48-829.png, screenshot-1.png, screenshot-2.png
>
> Time Spent: 20m
> Remaining Estimate: 0h
>
> The
> [cql_singlefile.html|https://cassandra.apache.org/doc/latest/cassandra/developing/cql/cql_singlefile.html]
> has invalid markup. The legacy markup in the file resembles Wiki Markup.
> Old markup requiring conversion:
> * bc(syntax) to [source, bnf]
> * bc(sample) to [source, sql]
> * p. indicates end of code block, to four dashes (----)
> * code in AsciiDoc doesn't require escaping curly bracket
> * back quotes in code changed to regular single quotes
> 'sql', 'bnf' and 'text' are source language names supported in AsciiDocs
> Pygments highlighter.
> For example, invalid formatting in
> [cql_singlefile.html|https://cassandra.apache.org/doc/latest/cassandra/developing/cql/cql_singlefile.html]:
> !image-2025-01-08-13-26-48-829.png!
> Correct formatting of same content on DDL
> ([ddl.html|https://cassandra.apache.org/doc/latest/cassandra/developing/cql/ddl.html])
> page:
> !image-2025-01-08-13-25-42-002.png!
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
