[
https://issues.apache.org/jira/browse/CASSANDRA-20195?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17916123#comment-17916123
]
Brad Schoening edited comment on CASSANDRA-20195 at 1/22/25 6:22 PM:
---------------------------------------------------------------------
I've chatted directly with [~mck] because I didn't understand all the moving
parts here with anatora, textile and asciidoc. Based upon that, I suggest the
following steps:
a) Review and merge this AsciiDoc syntax fixes (PR 3803) for
cql_singefille.adoc with it's 800+ line changes. This is a markup only change,
but its corrects really terrible miss-formatting on our website which is the
URL CQLSH brings up for help. It's a pre-requisite for fixing the content.
b) Creating a new Jira to sync content between cql_singlefile.adoc and
CQL.textile with the aim of switching to AsciiDoc (.adoc) going forward. This
addresses [~smiklosovic] notes that the content between the files is
inconsistent (3.4.8 vs 3.4.3 among others). I'll work on this next.
c) Fixing the doc build to generate HTML from AsciiDoc for inclusion in the
build and which is referenced locally by cqlsh with a tarball install. This is
part of CASSANDRA-17260. This will use asciidoctorj, which is the same tooling
as anatora.
Today we have 212 files in .adoc format and just one in Textile (CQL.textile)
on [github.com/apache/cassandra|http://github.com/apache/cassandra]. Also,
* AsciiDoc has been contributed to the Eclipse Foundation and now managed by
them.
* The Eclipse AsciiDoc Working Group is drafting a standard
[https://asciidoc-wg.eclipse.org/]
* IntelliJ has plugin support for AsciiDoc and renders it beautifully in the
IDE – which I used for my PR to verify correctness
* AsciiDoc has support for many source highlighters, with Highlights.js
working with asciidoctorj
Attached is the new cql_singlefile.html generated by:
{quote}asciidoctorj -a source-highlighter=highlight.js -a highlightjs-theme=vs
cassandra/pages/developing/cql/cql_singlefile.adoc
{quote}
[^cql_singlefile.html]
was (Author: bschoeni):
I've chatted directly with [~mck] because I didn't understand all the moving
parts here with anatora, textile and asciidoc. Based upon that, I suggest the
following steps:
a) Review and merge this AsciiDoc syntax fixes (PR 3803) for
cql_singefille.adoc with it's 800+ line changes. This is a markup only change,
but its corrects really terrible miss-formatting on our website which is the
URL CQLSH brings up for help. It's a pre-requisite for fixing the content.
b) Creating a new Jira to sync content between cql_singlefile.adoc and
CQL.textile with the aim of switching to AsciiDoc (.adoc) going forward. This
addresses [~smiklosovic] notes that the content between the files is
inconsistent (3.4.8 vs 3.4.3 among others). I'll work on this next.
c) Fixing the doc build to generate HTML from AsciiDoc for inclusion in the
build and which is referenced locally by cqlsh with a tarball install. This is
part of CASSANDRA-17260. This will use asciidoctorj, which is the same tooling
as anatora.
Today we have 212 files in .adoc format and just one in Textile (CQL.textile)
on [github.com/apache/cassandra|http://github.com/apache/cassandra]. Also,
* AsciiDoc has been contributed to the Eclipse Foundation and now managed by
them.
* The Eclipse AsciiDoc Working Group is drafting a standard
[https://asciidoc-wg.eclipse.org/]
* IntelliJ has plugin support for AsciiDoc and renders it beautifully in the
IDE – which I used for my PR to verify correctness
* AsciiDoc has support for many source highlighters, with Highlights.js
working with asciidoctorj
Attached is the new cql_singlefile.html generated by:
{quote}sciidoctorj -a source-highlighter=highlight.js -a highlightjs-theme=vs
cassandra/pages/developing/cql/cql_singlefile.adoc
{quote}
[^cql_singlefile.html]
> 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: cql_singlefile.html, 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]
