Convert LLVM managed build help pages to AsciiDoc

doc/org.eclipse.cdt.doc.user/.gitignore

@@ -2,4 +2,5 @@
 /concepts/docinfo-footer.htm
 /concepts/docinfo-header.htm
 /getting_started/
+/llvm/
 /example/

doc/org.eclipse.cdt.doc.user/build.properties

@@ -26,11 +26,13 @@ bin.includes = about.html,\
                helpadoc.css,\
                font-awesome/,\
                images/,\
+               llvm/,\
                plugin.properties,\
                plugin.xml,\
                reference/,\
                tasks/,\
                toc.xml,\
+               toc_LLVM.xml,\
                topics_Concepts.xml,\
                topics_Getting_Started.xml,\
                topics_Reference.xml,\

doc/org.eclipse.cdt.doc.user/plugin.xml

@@ -14,6 +14,10 @@
             file="toc.xml"
             primary="true">
       </toc>
+      <toc
+            file="toc_LLVM.xml"
+            primary="true">
+      </toc>
       <index path="index"/>
    </extension>
 

doc/org.eclipse.cdt.doc.user/src/.gitignore

@@ -0,0 +1 @@
+.asciidoctorconfig.adoc

doc/org.eclipse.cdt.doc.user/src/llvm/general.adoc

@@ -0,0 +1,44 @@
+////
+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
+
+== General information
+
+LLVM with Clang/GCC for Eclipse CDT plug-in provides LLVM toolchain with
+Clang or llvm-gcc compiler to compile C/(cpp} programs.
+
+http://www.llvm.org[LLVM] is a rather modern toolchain that supports the
+compilation of C/(cpp} code (among others) to LLVM virtual machine's
+_bitcode_, which in turn can be compiled to each platform's native
+binary.
+
+The plug-in includes the following tools from the LLVM toolchain:
+Clang/Clang{plus}{plus}/llvm-gcc/llvm-g{plus}{plus} (C/(cpp} compilers), llvm-ld (linker),
+llvm-ar (archiver), llvm-as (assembler), llc (static compiler) and lli
+(JIT/Interpreter).

doc/org.eclipse.cdt.doc.user/src/llvm/initial_configuration.adoc

@@ -0,0 +1,53 @@
+////
+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
+
+== Initial configuration
+
+When you launch an Eclipse workspace with LLVM plug-in for the first
+time, you may need to set paths to LLVM binaries, headers and libraries.
+This is done in Eclipse by navigating to Window -> Preferences -> LLVM.
+Set LLVM installation folder to point where your LLVM binaries are,
+include directory to point where your Clang includes are and library
+path to the directory where your LLVM libraries reside.
+
+If your paths in Preferences and LLVM are correctly set and the plug-in
+is able to find your LLVM binaries, you should have the option to use
+"LLVM with Clang (Linux/MacOSX/Windows)" toolchain and "LLVM with GCC
+(Linux/MacOSX/Windows) toolchain". The toolchains are available in
+project types of 'executable', 'static library' and 'dynamic library' in
+both C and {cpp}.
+
+An alternative way is to set the LLVM binary path to PATH system
+environment variable.
+
+You may also have to include the path to
+Standard {cpp} Library in order to compile {cpp} programs by adding the
+path in LLVM Preferences or appending it to LD_LIBRARY_PATH system
+environment variable.

doc/org.eclipse.cdt.doc.user/src/llvm/llvm_specific.adoc

@@ -0,0 +1,64 @@
+////
+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
+
+== LLVM Specific Information
+
+=== Project types
+
+==== [#executables]#Executables#
+
+At the moment the executables built with the default settings of a LLVM
+with Clang project are native binaries and can be run and debugged as
+such. However LLVM does also support compiling programs to LLVM bitcode,
+which in turn can be run with lli, which is the LLVM toolchain's
+interpreter/JIT compiler. Unfortunately programs run with lli can not be
+efficiently debugged, since the only (usable) debugging information that
+you can get from them is the backtrace. You can, however, compile the
+bitcode versions of your programs, if you will (TODO: even though
+running them from Eclipse doesn't work at the moment).
+
+===== Compiling to LLVM bitcode instead of native binary
+
+You can compile your programs to LLVM bitcode instead of native binaries
+by unchecking the "Create native binary (-native)" checkbox in your
+project's properties in Properties → C/{cpp} Build → Settings → LLVM
+Linker → General LLVM options. After this Eclipse will not give the
+-native flag to llvm-ld, so the product of linking is just linked
+bitcode files (.bc) and a Bash script file with the name of the wanted
+executable. The Bash script will simply run the compiled LLVM bitcode
+file with lli.
+
+==== [#libraries]#Shared and static libraries#
+
+The shared and static libraries generated with LLVM plugin are (TODO:
+for now) only LLVM bitcode files linked into one file and therefore
+cannot be used with gcc unless compiled to object code first. These
+libraries can naturally be used when working with the LLVM toolchain and
+on the other hand llvm-ld can use libraries that are object code.

doc/org.eclipse.cdt.doc.user/src/llvm/user_manual.adoc

@@ -0,0 +1,39 @@
+////
+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
+
+== LLVM with Clang/GCC for Eclipse CDT
+
+This guide is intended for the users of the LLVM with Clang/GCC for
+Eclipse CDT plugin. It describes the initial configuration, general
+information and some special cases about the plugin.
+
+* xref:general.adoc[General information]
+* xref:initial_configuration.adoc[Initial configuration]
+* xref:llvm_specific.adoc[LLVM specific information and options]

doc/org.eclipse.cdt.doc.user/toc_LLVM.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<toc label="LLVM plug-in for Eclipse CDT">
+	<topic label="User manual" href="llvm/user_manual.htm">
+		<topic label="General information about the plugin" href="llvm/general.htm"/>
+		<topic label="Initial configuration" href="llvm/initial_configuration.htm"/>
+		<topic label="LLVM specific information and options" href="llvm/llvm_specific.htm">
+		</topic>
+	</topic>
+</toc>

llvm/org.eclipse.cdt.managedbuilder.llvm.ui/build.properties

@@ -8,8 +8,6 @@ bin.includes = plugin.xml,\
                about.ini,\
                about.mappings,\
                about.properties,\
-               cdt_logo_icon32.png,\
+               cdt_logo_icon32.png
-               help/
 src.includes = patches/,\
-               help/,\
                about.html

llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/general.html

@@ -1,13 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<title>General information</title>
-</head>
-<body>
-<h2>General information</h2>
-<p>LLVM with Clang/GCC for Eclipse CDT plug-in provides LLVM toolchain with Clang or llvm-gcc compiler to compile C/C++ programs.</p>
-<p><a href="http://www.llvm.org">LLVM</a> is a rather modern toolchain that supports the compilation of C/C++ code (among others) to LLVM virtual machine's <i>bitcode</i>, which in turn can be compiled to each platform's native binary.</p>
-<p>The plug-in includes the following tools from the LLVM toolchain: Clang/Clang++/llvm-gcc/llvm-g++ (C/C++ compilers), llvm-ld (linker), llvm-ar (archiver), llvm-as (assembler), llc (static compiler) and lli (JIT/Interpreter).
-</body>
-</html>

llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/initial_configuration.html

@@ -1,14 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<title>Initial configuration</title>
-</head>
-<body>
-<h2>Initial configuration</h2>
-<p>When you launch an Eclipse workspace with LLVM plug-in for the first time, you may need to set paths to LLVM binaries, headers and libraries. This is done in Eclipse by navigating to Window -> Preferences -> LLVM. Set LLVM installation folder to point where your LLVM binaries are, include directory to point where your Clang includes are and library path to the directory where your LLVM libraries reside.</p>
-<p>If your paths in Preferences and LLVM are correctly set and the plug-in is able to find your LLVM binaries, you should have the option to use "LLVM with Clang (Linux/MacOSX/Windows)" toolchain and "LLVM with GCC (Linux/MacOSX/Windows) toolchain". The toolchains are available in project types of 'executable', 'static library' and 'dynamic library' in both C and C++.</p>
-<p>An alternative way is to set the LLVM binary path to PATH system environment variable.</p>
-<p>You may also have to <a href="../help/adding_c++_standard_library.html">include the path to Standard C++ Library</a> in order to compile C++ programs by adding the path in LLVM Preferences or appending it to LD_LIBRARY_PATH system environment variable.</p>
-</body>
-</html>

llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/llvm_specific.html

@@ -1,17 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<title>LLVM Specific Information</title>
-</head>
-<body>
-<h1>LLVM Specific Information</h1>
-<h2>Project types</h2>
-<h3><a name="executables">Executables</a></h3>
-<p>At the moment the executables built with the default settings of a LLVM with Clang project are native binaries and can be run and debugged as such. However LLVM does also support compiling programs to LLVM bitcode, which in turn can be run with lli, which is the LLVM toolchain's interpreter/JIT compiler. Unfortunately programs run with lli can not be efficiently debugged, since the only (usable) debugging information that you can get from them is the backtrace. You can, however, compile the bitcode versions of your programs, if you will (TODO: even though running them from Eclipse doesn't work at the moment).</p>
-<h4>Compiling to LLVM bitcode instead of native binary</h4>
-<p>You can compile your programs to LLVM bitcode instead of native binaries by unchecking the "Create native binary (-native)" checkbox in your project's properties in Properties &rarr; C/C++ Build &rarr; Settings &rarr; LLVM Linker &rarr; General LLVM options. After this Eclipse will not give the -native flag to llvm-ld, so the product of linking is just linked bitcode files (.bc) and a Bash script file with the name of the wanted executable. The Bash script will simply run the compiled LLVM bitcode file with lli.</p>
-<h3><a name="libraries">Shared and static libraries</a></h3>
-<p>The shared and static libraries generated with LLVM plugin are (TODO: for now) only LLVM bitcode files linked into one file and therefore cannot be used with gcc unless compiled to object code first. These libraries can naturally be used when working with the LLVM toolchain and on the other hand llvm-ld can use libraries that are object code.</p>
-</body>
-</html>

llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/toc.xml

@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<toc label="LLVM plug-in for Eclipse CDT">
-	<topic label="User manual" href="help/user_manual.html">
-		<topic label="General information about the plugin" href="help/general.html"/>
-		<topic label="Initial configuration" href="help/initial_configuration.html"/>
-		<topic label="LLVM specific information and options" href="help/llvm_specific.html">
-		</topic>
-	</topic>
-</toc>

llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/user_manual.html

@@ -1,17 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<title>User manual - LLVM with Clang/GCC for Eclipse CDT</title>
-</head>
-<body>
-<h1>LLVM with Clang/GCC for Eclipse CDT</h1>
-<p>This guide is intended for the users of the LLVM with Clang/GCC for Eclipse CDT plugin. It describes the initial configuration, general information and some special cases about the plugin.</p> 
-<ul>
-  <li><a href="general.html">General information</a></li>
-  <li><a href="initial_configuration.html">Initial configuration</a></li>
-  <li><a href="llvm_specific.html">LLVM specific information and options</a></li>
-    <li><a href="adding_c++_standard_library.html">Adding C++ Standard Library</a></li>
-</ul>
-</body>
-</html>

llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml

@@ -5483,13 +5483,6 @@ Contributors:
          </toolChain>
       </template>
    </extension>
-   <extension
-         point="org.eclipse.help.toc">
-      <toc
-            file="help/toc.xml"
-            primary="true">
-      </toc>
-   </extension>
    <extension
          id="llvmNature"
          name="%extension.name.2"