Generate more of the documentation with asciidoc and automate more

- Migrate all getting_started from html to adoc
- Document (in README.md) notes on migrating html to adoc
- Reorganize generation of adoc slightly so that
  - all directories can be generates at once
  - output suffix changed to htm so that migrated files
    exist at the same URL on help.eclipse.org
- Add generation to the cleanliness checks to ensure that the
  html matches adoc
- Manage the adoc headers with a script as that is a large section
  of copy-pasted code on each adoc file (see README + adoc-headers.txt)
- Move maven version info to pluginManagement (consistency with other
  maven plug-ins)
- New profile "asciidoc-auto-refresh" which will auto build the
  files as edited.

Prerequisite of #992

.github/workflows/build-test.yml

@@ -21,6 +21,8 @@ jobs:
             - 'dsf/**'
             - 'debug/**'
             - 'jtag/**'
+          docs:
+            - 'doc/org.eclipse.cdt.doc.user/**'
     - name: Set up JDK 21
       uses: actions/setup-java@v4
       with:
@@ -64,3 +66,17 @@ jobs:
         path: |
           */*/target/surefire-reports/*.xml
           terminal/plugins/org.eclipse.tm.terminal.test/target/surefire-reports/*.xml
+    - name: Prepare Docs for upload
+      if: (success() || failure()) && steps.filter.outputs.docs
+      run: |
+        mkdir -p docs/user
+        cd docs/user
+        unzip ../../releng/org.eclipse.cdt.repo/target/repository/plugins/org.eclipse.cdt.doc.user_*.jar
+    - name: Upload Docs
+      uses: actions/upload-artifact@v4
+      if: (success() || failure()) && steps.filter.outputs.docs
+      with:
+        name: docs
+        include-hidden-files: true
+        path: |
+          docs/**

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

@@ -1,2 +1,2 @@
-/html/
-/workspace/
+/getting_started/
+/example/

doc/org.eclipse.cdt.doc.user/README.md

@@ -10,4 +10,50 @@ During content development, HTML files may be generated by invoking Maven locall
 
 ```
 mvn --define jgit.dirtyWorkingTree-cdtDefault=ignore --projects org.eclipse.cdt:org.eclipse.cdt.doc.user generate-resources
+# or to turn on auto-refresh
+mvn --define jgit.dirtyWorkingTree-cdtDefault=ignore --projects org.eclipse.cdt:org.eclipse.cdt.doc.user generate-resources -P asciidoc-auto-refresh
 ```
+
+Adding `-DuseSimrelRepo`, and after first run `-o` can speed up target platform resolution speed significantly.
+
+## Embedding commands in help
+
+Embedding commands in help needs to modify syntax slightly.
+Links in adoc are always surrounded by double-quotes, therefore single-quotes (`'`) or escaped double-quote (`"`) need to be used in the command, as appropriate, this is opposite to the quoting that is shown in the Eclipse help [documentation](https://help.eclipse.org/latest/topic/org.eclipse.platform.doc.isv/guide/ua_help_content_command_authoring.htm).
+See the [Eclipse help for general information](https://help.eclipse.org/latest/topic/org.eclipse.platform.doc.isv/guide/ua_help_content_command.htm).
+
+e.g. opening a preference page can be done like this:
+
+`
+image:command_link.png[] link:javascript:executeCommand('org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Editors)')[General > Editors]
+`
+
+Notes:
+
+- The `livehelp.js` is included automatically with `docinfo-header.htm`
+- `PLUGINS_ROOT` cannot be used within the adoc files, so use `image:command_link.png[]` instead
+
+## Converting html CDT help to adoc
+
+Use pandoc, e.g.:
+
+```
+pandoc getting_started/cdt_w_basic.htm -o src/getting_started/cdt_w_basic.adoc
+# or a whole group of files
+for i in getting_started/*; do pandoc -o src/${i%.*}.adoc $i; done
+```
+
+Apply these changes after:
+
+- Replace `image:../images/` -> `image:` because we use images in different locations depending on whether we are in GitHub or in online help
+- Replace `link:([^[]+).htm\[` -> `xref:$1.adoc[` so that links are always to `adoc` files. Asciidoctor will change that to `htm` on generation so if target has not been converted yet that is ok. This allows links to work when asciidoctor generates for other formats
+- Fix anchors `\[#([^\]]+)\]####` -> `[[$1]]`
+- Fix unneeded ` ` with `\u00A0` -> nothing (some of these were used to indent makefiles, but that meant they couldn't be copied and pasted anyway, so another solution is needed)
+- Remove doubled-up line continuation characters `^\+\n \+` -> `+`
+- Remove extra `+` around horizontal rulers (lines with `'''''`) `'''[\n\s]+\+` -> `'''` and ` *\+[\n\s]+'''` -> `'''`
+- Removed unneeded line breaks `(.) \+$` -> `$1` (lines that have just `+` are [list continuation](https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#list-continuation))
+- Since `C++` uses a double `+` it can confuse asciidoc, replace `C\+\+` -> `{cpp}` (the C++ attribute). See [Character Replacement Attributes Reference](https://docs.asciidoctor.org/asciidoc/latest/attributes/character-replacement-ref/) for all built-in attributes.
+- Remove copyright statements from bottom of files (the `docinfo-footer.htm` has copyright)
+- Fix the related concepts/tasks in the footer (convert to lists?)
+- Add the headers to the adoc file to enable all the features and ensure consistent copyrights. See adoc-headers.txt
+- Remove the original htm file from source control and add it to .gitignore (add whole folder if possible, or individual files if not whole folder is converted)

doc/org.eclipse.cdt.doc.user/adoc-headers.txt

@@ -0,0 +1,29 @@
+////
+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

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

@@ -23,6 +23,8 @@ bin.includes = about.html,\
                contexts_CDT_make.xml,\
                getting_started/,\
                help.css,\
+               helpadoc.css,\
+               font-awesome/,\
                images/,\
                plugin.properties,\
                plugin.xml,\
@@ -38,8 +40,7 @@ bin.includes = about.html,\
                intro/,\
                notices.html,\
                book.css,\
-               index*/,\
-               html/
+               index*/
 
 bin.excludes = build.properties,\
 			   customBuildCallbacks.xml