Add "C/C++ editor (LSP)" documentation content

bundles/org.eclipse.cdt.lsp.doc/build.properties

@@ -15,7 +15,9 @@ bin.includes = META-INF/,\
                OSGI-INF/,\
                .,\
                html/,\
+               images/,\
                help.css,\
                toc_editor.xml,\
+               toc_prefs.xml,\
                plugin.xml
 src.includes = about.html

bundles/org.eclipse.cdt.lsp.doc/help.css

@@ -82,3 +82,15 @@ 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 }
 div.listingblock pre { padding: 0.7em }
+.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
+.admonitionblock>table td.icon{text-align:center;width:80px}
+.admonitionblock>table td.icon img{max-width:initial}
+.admonitionblock>table td.icon .title{font-weight:bold;text-transform:uppercase}
+.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8}
+.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
+.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
+.admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c}
+.admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
+.admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900}
+.admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400}
+.admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000}

bundles/org.eclipse.cdt.lsp.doc/plugin.xml

@@ -15,5 +15,6 @@ Contributors:
 <plugin>
 	<extension point="org.eclipse.help.toc">
 		<toc file="toc_editor.xml" />
+		<toc file="toc_prefs.xml" />
 	</extension>
 </plugin>

bundles/org.eclipse.cdt.lsp.doc/src/asciidoc/lsp_clangd_prefs.adoc

@@ -0,0 +1,44 @@
+////
+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 (#963)
+////
+
+// support image rendering and table of contents within GitHub
+ifdef::env-github[]
+:imagesdir: ../../images
+:toc:
+:toc-placement!:
+endif::[]
+
+= clangd
+
+Use the image:command_link.png[] link:javascript:executeCommand('org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.cdt.lsp.clangd.editor.preferencePage)')[clangd] preference page to configure the behaviour of the `clangd` language server:
+
+image:lsp_clangd_prefs.png[width=550]
+
+.clangd Preference Options
+:!table-caption:
+[%autowidth]
+[options="header"]
+|===
+|Option                        |Description
+|Path                          |The absolute path of the `clangd` command-line tool.
+|Enable clang-tidy diagnostics |Enables the link:https://clang.llvm.org/extra/clang-tidy[_ClangTidy_] {cpp} linter tool.
+|Index project code in the background and persist index on disk |Enables building of files in the background to generate a project index.
+|Completion                    |The granularity of code completion suggestions.
+|Pretty-print JSON output      |Enables the pretty-printing of JSON output.
+|Drivers                       |A comma-separated list of globs for the extraction of system includes.
+|Additional                    |Miscellaneous `clangd` command-line arguments.
+|===
+
+Related concepts:
+
+* link:lsp_cpp_editor.html[C/C++ editor (LSP)]

bundles/org.eclipse.cdt.lsp.doc/src/asciidoc/lsp_cpp_editor.adoc

@@ -18,4 +18,25 @@ ifdef::env-github[]
 :toc-placement!:
 endif::[]
 
-= LSP C/C++ editor
+// enable support for button, menu and keyboard macros
+:experimental:
+
+= C/{cpp} editor (LSP)
+
+The CDT provides a Language Server based editor that gives you specific support for editing C/{cpp} code.
+This editor uses _Language Server Protocol_ (LSP) to provide better support for modern C/{cpp} language features than the legacy C/{cpp} editor.
+The Language Server based editor is invoked automatically when you open a C/{cpp} source file within new projects.
+Projects created using an older version of CDT may be configured to use this editor from the menu:Project[Preferences > C/{cpp} General > Editor (LSP)] properties page:
+
+image:lsp_editor_properties.png[width=526]
+
+The C/{cpp} editor (LSP) includes the following features:
+
+- Syntax highlighting
+- Content/code assist
+- Code folding
+- Integrated debugging features
+
+You can customize formatting behaviour of the editor by modifying style options in the _link:https://clang.llvm.org/docs/ClangFormatStyleOptions.html[ClangFormat]_ configuration file from the menu:Project[Preferences > C/{cpp} General > Editor (LSP) > Formatter] properties page.
+
+IMPORTANT: The C/{cpp} editor (LSP) requires an installation of the `link:https://clangd.llvm.org[clangd]` command-line tool. Refer to link:lsp_cpp_editor_prefs.html[Editor (LSP) preferences] for setup details.

bundles/org.eclipse.cdt.lsp.doc/src/asciidoc/lsp_cpp_editor_prefs.adoc

@@ -0,0 +1,38 @@
+////
+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 (#963)
+////
+
+// support image rendering and table of contents within GitHub
+ifdef::env-github[]
+:imagesdir: ../../images
+:toc:
+:toc-placement!:
+endif::[]
+
+= C/{cpp} editor (LSP) preferences
+
+Use the image:command_link.png[] link:javascript:executeCommand('org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.cdt.lsp.editor.preferencePage)')[Editor (LSP)] preference page to configure general behaviour of the C/{cpp} editor (LSP):
+
+image:lsp_editor_prefs.png[width=550]
+
+.C/{cpp} Editor (LSP) Preference Options
+:!table-caption:
+[%autowidth]
+[options="header"]
+|===
+|Option              |Description
+|Set C/{cpp} Editor (LSP) as default |When opening a C/{cpp} source file, the C/C++ editor (LSP) will be used by default.
+|===
+
+Related concepts:
+
+* link:lsp_cpp_editor.html[C/C++ editor (LSP)]

bundles/org.eclipse.cdt.lsp.doc/src/asciidoc/lsp_save_prefs.adoc

@@ -0,0 +1,38 @@
+////
+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 (#963)
+////
+
+// support image rendering and table of contents within GitHub
+ifdef::env-github[]
+:imagesdir: ../../images
+:toc:
+:toc-placement!:
+endif::[]
+
+= Save actions
+
+Use the image:command_link.png[] link:javascript:executeCommand('org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.cdt.lsp.editor.SaveActionsPreferencePage)')[Save Actions] preference page to configure actions performed by the C/{cpp} editor (LSP) while saving a file:
+
+image:lsp_save_prefs.png[width=550]
+
+.Save Actions Preference Options
+:!table-caption:
+[%autowidth]
+[options="header"]
+|===
+|Option              |Description
+|Format source code  |While saving a file, the editor will format all lines or edited lines only.
+|===
+
+Related concepts:
+
+* link:lsp_cpp_editor.html[C/C++ editor (LSP)]

bundles/org.eclipse.cdt.lsp.doc/toc_editor.xml

@@ -12,6 +12,6 @@ SPDX-License-Identifier: EPL-2.0
 Contributors:
   John Dallaway - initial implementation (#963)
 -->
-<toc link_to="../org.eclipse.cdt.doc.user/topics_Concepts.xml#cdt_EditingCpp_Anchor" label="LSP C/C++ editor">
-	<topic label="LSP C/C++ editor" href="html/lsp_cpp_editor.html"/>
+<toc link_to="../org.eclipse.cdt.doc.user/topics_Concepts.xml#cdt_EditingCpp_Anchor" label="C/C++ editor (LSP)">
+	<topic label="C/C++ editor (LSP)" href="html/lsp_cpp_editor.html" />
 </toc>

bundles/org.eclipse.cdt.lsp.doc/toc_prefs.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<?NLS TYPE="org.eclipse.help.toc"?>
+<!--
+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 implementation (#963)
+-->
+<toc link_to="../org.eclipse.cdt.doc.user/topics_Reference.xml#cdt_Preferences_Anchor" label="Editor (LSP) preferences">
+	<topic label="Editor (LSP) preferences" href="html/lsp_cpp_editor_prefs.html">
+		<topic label="clangd" href="html/lsp_clangd_prefs.html" />
+		<topic label="Save Actions" href="html/lsp_save_prefs.html" />
+	</topic>
+</toc>