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

jld01 · jld01 · commit f4a08f256bf8 · 2024-12-14T16:38:10.000Z
diff --git a/bundles/org.eclipse.cdt.lsp.doc/build.properties b/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
diff --git a/bundles/org.eclipse.cdt.lsp.doc/help.css b/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}
diff --git a/bundles/org.eclipse.cdt.lsp.doc/images/lsp_editor_properties.png b/bundles/org.eclipse.cdt.lsp.doc/images/lsp_editor_properties.png
diff --git a/bundles/org.eclipse.cdt.lsp.doc/plugin.xml b/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>
diff --git a/bundles/org.eclipse.cdt.lsp.doc/src/asciidoc/lsp_cpp_editor.adoc b/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 {cpp} language features than the legacy C/{cpp} editor.
+The Language Server based editor is invoked automatically when you edit 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 the _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.
diff --git a/bundles/org.eclipse.cdt.lsp.doc/src/asciidoc/lsp_cpp_editor_prefs.adoc b/bundles/org.eclipse.cdt.lsp.doc/src/asciidoc/lsp_cpp_editor_prefs.adoc
@@ -0,0 +1,21 @@
+////
+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
diff --git a/bundles/org.eclipse.cdt.lsp.doc/toc_editor.xml b/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>
diff --git a/bundles/org.eclipse.cdt.lsp.doc/toc_prefs.xml b/bundles/org.eclipse.cdt.lsp.doc/toc_prefs.xml
@@ -0,0 +1,17 @@
+<?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"/>
+</toc>
