Improve readme (#263)

README.md

@@ -1,6 +1,6 @@
 # Eclipse CDT LSP - LSP based C/C++ Editor
 
-**Target audience** are Eclipse plugin developers who want to use/develop a LSP based C/C++ Editor.
+**Target audience** CDT users who want to use a language server based C/C++ Editor which supports newer C/C++ standards and Eclipse plugin developers who want to use/develop a LSP based C/C++ Editor. The editor in this Eclipse feature is backed by the [LLVM clangd C/C++ language server](https://clangd.llvm.org/).
 
 This plugin is based on the [LSP4E](https://github.com/eclipse/lsp4e) and [TM4E](https://github.com/eclipse/tm4e) Eclipse projects. The editor is based on the [`ExtensionBasedTextEditor`](https://github.com/eclipse-platform/eclipse.platform.ui/blob/master/bundles/org.eclipse.ui.genericeditor/src/org/eclipse/ui/internal/genericeditor/ExtensionBasedTextEditor.java#L55-L56) in Eclipse.
 
@@ -52,7 +52,7 @@ int main() {
 -->
 
 The Editors features depends on the support on client ([LSP4E](https://github.com/eclipse/lsp4e)) and server ([clangd](https://clangd.llvm.org/)) side.
-Currently these feature are supported (clangd 15 and 16) and current LSP4E:
+Currently these feature are supported (clangd 17) and current LSP4E:
 
 - Auto completion
 - Hovering
@@ -70,8 +70,11 @@ Not supported (yet):
 
 ### Activating LSP based C/C++ Editor
 
-The `org.eclipse.cdt.lsp.clangd` plugin provides an activation UI for the LSP based C/C++ Editor on project and workspace level. 
-The clangd language server path and the arguments can be changed in the workspace preferences as well:
+The `org.eclipse.cdt.lsp` plugin provides an activation UI for the LSP based C/C++ Editor on project and workspace level.
+
+![image](images/editor.png "editor.png")
+
+The clangd path and the arguments can be changed in the workspace preferences as well:
 
 ![image](images/preferences.png "preferences.png")
 
@@ -108,7 +111,17 @@ The following tools are needed on the `PATH` to operate the demo.
 
 ### Import an existing project
 
-You can import an existing project that contains a `compile_commands.json` file, or follow these instructions to create a simple starting project.
+You can import an existing project that contains a `compile_commands.json` file, or follow these instructions to create a simple starting project. 
+The language server (clangd) searches for a `compile_commands.json` file in the source file folder and its parents. Users can define a `.clangd` file in the project root to configure clangd (e.g. add include paths).
+A [.clangd](https://clangd.llvm.org/config#files) is a text file with YAML syntax. A `compile_commands.json` file can be generated by CMake.
+
+[!TIP] 
+This configuration entry in the `.clangd` file would tell clangd to use the `compile_commands.json` file in the build/default folder:
+
+```yaml
+CompileFlags:
+  CompilationDatabase: build/default
+```
 
 ### Create an example CMake project
 
@@ -128,9 +141,11 @@ This file may be hidden by default, therefore to see the file uncheck the *.\* r
 By default C/C++ will be opened with the standard CEditor.
 The default can be changed per project or per workspace with the *C/C++ General* -> *Editor (LSP)* -> *Set C/C++ Editor (LSP) as default* checkbox in the project properties or workspace preference page.
 
-- Note: The workspace setting will be used for projects that have not checked the *Enable project specific settings* checkbox in the project properties -> *C/C++ General* -> *Editor (LSP)* page.
+[!TIP]
+The workspace setting will be used for projects that have not checked the *Enable project specific settings* checkbox in the project properties -> *C/C++ General* -> *Editor (LSP)* page.
 
-**Note:** Opening a C/C++ file using *Open With* in the context menu of a file won't work for the LSP based editor, because the language server won't be started if *Set C/C++ Editor (LSP) as default* is not enabled!
+[!NOTE]
+Opening a C/C++ file using *Open With* in the context menu of a file won't work for the LSP based editor, because the language server won't be started if *Set C/C++ Editor (LSP) as default* is not enabled!
 
 With the *C/C++ Editor (LSP)* open, the presentation of the C++ file will follow the LSP4E conventions augmented by the information returned from clangd.