From c63f988d5c8aeb49513618060c79937a1d3dfb8c Mon Sep 17 00:00:00 2001
From: John Dallaway <john@dallaway.org.uk>
Date: Thu, 17 Jul 2025 16:39:12 +0100
Subject: [PATCH] Convert 'Before you begin' help page to AsciiDoc

---
 doc/org.eclipse.cdt.doc.user/.gitignore       |   3 +
 .../concepts/cdt_c_before_you_begin.htm       |  88 ------------
 .../src/concepts/cdt_c_before_you_begin.adoc  | 129 ++++++++++++++++++
 .../src/concepts/docinfo-footer.htm           |   2 +
 .../src/concepts/docinfo-header.htm           |   1 +
 5 files changed, 135 insertions(+), 88 deletions(-)
 delete mode 100644 doc/org.eclipse.cdt.doc.user/concepts/cdt_c_before_you_begin.htm
 create mode 100644 doc/org.eclipse.cdt.doc.user/src/concepts/cdt_c_before_you_begin.adoc
 create mode 100644 doc/org.eclipse.cdt.doc.user/src/concepts/docinfo-footer.htm
 create mode 100644 doc/org.eclipse.cdt.doc.user/src/concepts/docinfo-header.htm
diff --git a/doc/org.eclipse.cdt.doc.user/.gitignore b/doc/org.eclipse.cdt.doc.user/.gitignore
index 2fddf3a13e9..d7a67220bea 100644
--- a/doc/org.eclipse.cdt.doc.user/.gitignore
+++ b/doc/org.eclipse.cdt.doc.user/.gitignore
@@ -1,2 +1,5 @@
+/concepts/cdt_c_before_you_begin.htm
+/concepts/docinfo-footer.htm
+/concepts/docinfo-header.htm
 /getting_started/
 /example/
diff --git a/doc/org.eclipse.cdt.doc.user/concepts/cdt_c_before_you_begin.htm b/doc/org.eclipse.cdt.doc.user/concepts/cdt_c_before_you_begin.htm
deleted file mode 100644
index c354bf699f2..00000000000
--- a/doc/org.eclipse.cdt.doc.user/concepts/cdt_c_before_you_begin.htm
+++ /dev/null
@@ -1,88 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-
-<html lang="en">
-<head>
-	<meta http-equiv="Content-Language" content="en-us">
-	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-	<title>Before you begin</title>
-	<link rel="stylesheet" type="text/css" href="../help.css">
-</head>
-<body>
-<div role="main">
-<h1>Before you begin</h1>
-
-<p>Depending on how you obtained the CDT, you might have also received
-a toolchain with a built-in CDT integration.
-However, if you downloaded the CDT from the Eclipse web site, then you will require a toolchain before
-you can build and debug any projects.</p>
-
-<p>The standard CDT supports integration with the GNU toolchain.
-This includes GNU's make, gcc compiler, and gdb debugger utilities.
-If you require a toolchain to build software for your development host, this
-is the best choice to get started.
-
-<p>Each platform that runs the CDT requires different steps to acquire this toolchain.</p>
-
-<h2>Windows</h2>
-<p>For windows, MinGW and Cygwin are the two main platform choices for acquiring the GNU toolchain.
-It is important to understand the difference between them.
-Cygwin produces executables that use the Cygwin POSIX runtime. Note that this runtime is GPL licensed.
-MinGW produces native Windows executables that do not require a separate runtime.</p>
-
-<ul>
-<li><p>For <strong>MinGW</strong>, it is recommended to use the MSYS2 software distribution.
-The CDT will automatically detect tools that are installed using the MSYS2 package manager.
-Download and run the latest MSYS2 installer by following instructions on the <a href="https://www.msys2.org/">MSYS2 Getting Started</a> page.
-When you reach the UCRT64 environment prompt, use the following commands to install individual tools:</p>
-<p />
-<p><table style="border: 1px solid grey; border-collapse: collapse;">
-<tr><th style="border: 1px solid grey; padding: 5px;">Tool</th>   <th style="border: 1px solid grey; padding: 5px;">Installation command</th>                                       <th style="border: 1px solid grey; padding: 5px;">Notes</th><tr>
-<tr><td style="border: 1px solid grey; padding: 5px;">clang</td>  <td style="border: 1px solid grey; padding: 5px;"><tt>pacman -S mingw-w64-ucrt-x86_64-clang</tt></td>             <td style="border: 1px solid grey; padding: 5px;">Provides the <i>LLVM with Clang</i> toolchain</td></tr>
-<tr><td style="border: 1px solid grey; padding: 5px;">clangd</td> <td style="border: 1px solid grey; padding: 5px;"><tt>pacman -S mingw-w64-ucrt-x86_64-clang-tools-extra</tt></td> <td style="border: 1px solid grey; padding: 5px;">Required by the <i>C/C++ Editor (LSP)</i></td></tr>
-<tr><td style="border: 1px solid grey; padding: 5px;">cmake</td>  <td style="border: 1px solid grey; padding: 5px;"><tt>pacman -S mingw-w64-ucrt-x86_64-cmake</tt></td>             <td style="border: 1px solid grey; padding: 5px;">Required for building <i>CMake</i> projects</td></tr>
-<tr><td style="border: 1px solid grey; padding: 5px;">gcc</td>    <td style="border: 1px solid grey; padding: 5px;"><tt>pacman -S mingw-w64-ucrt-x86_64-gcc</tt></td>               <td style="border: 1px solid grey; padding: 5px;">Provides the <i>MinGW GCC</i> toolchain</td></tr>
-<tr><td style="border: 1px solid grey; padding: 5px;">gdb</td>    <td style="border: 1px solid grey; padding: 5px;"><tt>pacman -S mingw-w64-ucrt-x86_64-gdb</tt></td>               <td style="border: 1px solid grey; padding: 5px;">Required for debugging</td></tr>
-<tr><td style="border: 1px solid grey; padding: 5px;">make</td>   <td style="border: 1px solid grey; padding: 5px;"><tt>pacman -S make</tt></td>                                    <td style="border: 1px solid grey; padding: 5px;">Required for building <i>Managed Build</i> projects</td></tr>
-<tr><td style="border: 1px solid grey; padding: 5px;">ninja</td>  <td style="border: 1px solid grey; padding: 5px;"><tt>pacman -S mingw-w64-ucrt-x86_64-ninja</tt></td></td>        <td style="border: 1px solid grey; padding: 5px;">Required for building <i>CMake</i> projects</td></tr>
-</table></p>
-</li>
-
-<li><p><strong>Cygwin</strong> can be installed from the Cygwin site at
-<a href="https://www.cygwin.com">https://www.cygwin.com</a>. You need to manually select
-the gcc, gdb, and make packages to install the toolchain.
-Note that there is a <a href="https://github.com/eclipse-cdt/cdt/issues/228">known issue</a>
-with running recent versions of Cygwin gdb under the CDT.</p>
-</li>
-
-<li><p>The <strong>Windows SDK</strong> provides the Visual C++ compiler and header files and libraries required
-to create Windows applications. The CDT Visual C++ build integration will find these files based on where you installed
-the SDK. No other setup is required.</p>
-<p><i>Note:</i> For this release, the integration should be considered beta quality. It is not recommended for
-production use.</p>
-</li>
-</ul>
-
-<h2>Linux</h2>
-<p>All Linux distributions include the GNU toolchain. They may not, however, be installed by default.
-For instructions about installing the GNU toolchain for Linux, see the instructions for your particular distribution.</p>
-
-<h2>Mac OS X</h2>
-The CDT supports the Apple GNU toolchain that is included in with the Xcode IDE. It can be downloaded
-from the Apple's developer site, <a href="https://developer.apple.com/">https://developer.apple.com</a>
-
-<h2>Other Platforms</h2>
-<p>The GNU toolchain is supported on all platforms that the CDT supports. For instructions about installing the GNU toolchain
-on your platform, see your platform vendor.</p>
-
-<p> <img src="../images/ngref.gif" ALT="Related reference" width="143" height="21">  <br>
-  <a href="../concepts/cdt_o_home.htm">CDT Home</a><br>
-  
-<p> <img src="../images/ngtasks.gif" ALT="Related tasks"> <br>
-  <a href="../tasks/cdt_t_manualbuild.htm">Building Manually</a>
-</p>
-<p><img src="../images/ng00_04a.gif" ALT="QNX Copyright Statement" > 
-</p>
-</div>
-</body>
-
-</html>
\ No newline at end of file
diff --git a/doc/org.eclipse.cdt.doc.user/src/concepts/cdt_c_before_you_begin.adoc b/doc/org.eclipse.cdt.doc.user/src/concepts/cdt_c_before_you_begin.adoc
new file mode 100644
index 00000000000..1e7fd91ae51
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/src/concepts/cdt_c_before_you_begin.adoc
@@ -0,0 +1,129 @@
+////
+Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
+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
+////
+
+// pull in shared headers, footers, etc
+:docinfo: shared
+
+// support image rendering and table of contents within GitHub
+ifdef::env-github[]
+:imagesdir: ../../images
+:toc:
+:toc-placement!:
+endif::[]
+
+// enable support for button, menu and keyboard macros
+:experimental:
+
+// Until ENDOFHEADER the content must match adoc-headers.txt for consistency,
+// this is checked by the build in do_generate_asciidoc.sh, which also ensures
+// that the checked in html is up to date.
+// do_generate_asciidoc.sh can also be used to apply this header to all the
+// adoc files.
+// ENDOFHEADER
+
+== Before you begin
+
+Depending on how you obtained the CDT, you might have also received a
+toolchain with a built-in CDT integration. However, if you downloaded
+the CDT from the Eclipse web site, then you will require a toolchain
+before you can build and debug any projects.
+
+The standard CDT supports integration with the GNU toolchain. This
+includes GNU's make, gcc compiler, and gdb debugger utilities. If you
+require a toolchain to build software for your development host, this is
+the best choice to get started.
+
+Each platform that runs the CDT requires different steps to acquire this
+toolchain.
+
+=== Windows
+
+For windows, MinGW and Cygwin are the two main platform choices for
+acquiring the GNU toolchain. It is important to understand the
+difference between them. Cygwin produces executables that use the Cygwin
+POSIX runtime. Note that this runtime is GPL licensed. MinGW produces
+native Windows executables that do not require a separate runtime.
+
+* For *MinGW*, it is recommended to use the MSYS2 software distribution.
+The CDT will automatically detect tools that are installed using the
+MSYS2 package manager. Download and run the latest MSYS2 installer by
+following instructions on the https://www.msys2.org/[MSYS2 Getting
+Started] page. When you reach the UCRT64 environment prompt, use the
+following commands to install individual tools:
++
+[cols="1,5,3"]
+|===
+|Tool|Installation command|Notes
+
+|clang
+|`pacman -S mingw-w64-ucrt-x86_64-clang`
+|Provides the _LLVM with Clang_ toolchain
+
+|clangd
+|`pacman -S mingw-w64-ucrt-x86_64-clang-tools-extra`
+|Required by the _C/{cpp} Editor (LSP)_
+
+|cmake
+|`pacman -S mingw-w64-ucrt-x86_64-cmake`
+|Required for building _CMake_ projects
+
+|gcc
+|`pacman -S mingw-w64-ucrt-x86_64-gcc`
+|Provides the _MinGW GCC_ toolchain
+
+|gdb
+|`pacman -S mingw-w64-ucrt-x86_64-gdb`
+|Required for debugging
+
+|make
+|`pacman -S make`
+|Required for building _Managed Build_ projects
+
+|ninja
+|`pacman -S mingw-w64-ucrt-x86_64-ninja`
+|Required for building _CMake_ projects
+|===
+
+* *Cygwin* can be installed from the Cygwin site at
+https://www.cygwin.com. You need to manually select the gcc, gdb, and
+make packages to install the toolchain. Note that there is a
+https://github.com/eclipse-cdt/cdt/issues/228[known issue] with running
+recent versions of Cygwin gdb under the CDT.
+* The *Windows SDK* provides the Visual {cpp} compiler and header files
+and libraries required to create Windows applications. The CDT Visual
+{cpp} build integration will find these files based on where you installed
+the SDK. No other setup is required. +
+_Note:_ For this release, the integration should be considered beta
+quality. It is not recommended for production use.
+
+=== Linux
+
+All Linux distributions include the GNU toolchain. They may not,
+however, be installed by default. For instructions about installing the
+GNU toolchain for Linux, see the instructions for your particular
+distribution.
+
+=== Mac OS X
+
+The CDT supports the Apple GNU toolchain that is included in with the
+Xcode IDE. It can be downloaded from the Apple's developer site,
+https://developer.apple.com/[https://developer.apple.com]
+
+=== Other Platforms
+
+The GNU toolchain is supported on all platforms that the CDT supports.
+For instructions about installing the GNU toolchain on your platform,
+see your platform vendor.
+
+image:ngref.gif[Related reference,width=143,height=21] +
+* link:../concepts/cdt_o_home.htm[CDT Home] +
+
+image:ngtasks.gif[Related tasks] +
+* link:../tasks/cdt_t_manualbuild.htm[Building Manually]
diff --git a/doc/org.eclipse.cdt.doc.user/src/concepts/docinfo-footer.htm b/doc/org.eclipse.cdt.doc.user/src/concepts/docinfo-footer.htm
new file mode 100644
index 00000000000..004b62dd2dc
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/src/concepts/docinfo-footer.htm
@@ -0,0 +1,2 @@
+<hr>
+<p><small>Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation</small></p>
diff --git a/doc/org.eclipse.cdt.doc.user/src/concepts/docinfo-header.htm b/doc/org.eclipse.cdt.doc.user/src/concepts/docinfo-header.htm
new file mode 100644
index 00000000000..97fef13afc5
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/src/concepts/docinfo-header.htm
@@ -0,0 +1 @@
+<script type="text/javascript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>

Tool	Installation command	Notes
clang	`pacman -S mingw-w64-ucrt-x86_64-clang`	Provides the LLVM with Clang toolchain
clangd	`pacman -S mingw-w64-ucrt-x86_64-clang-tools-extra`	Required by the C/C++ Editor (LSP)
cmake	`pacman -S mingw-w64-ucrt-x86_64-cmake`	Required for building CMake projects
gcc	`pacman -S mingw-w64-ucrt-x86_64-gcc`	Provides the MinGW GCC toolchain
gdb	`pacman -S mingw-w64-ucrt-x86_64-gdb`	Required for debugging
make	`pacman -S make`	Required for building Managed Build projects
ninja	`pacman -S mingw-w64-ucrt-x86_64-ninja`	Required for building CMake projects