search

microsoft / vscode-docs

Public documentation for Visual Studio Code
http://code.visualstudio.com/docs
Other
5.69k stars 4.63k forks source link

Reviewing embedded language server documentation #3519

Closed aeschli closed 4 years ago

aeschli commented 4 years ago

Testing https://github.com/microsoft/vscode/issues/93809

Following up the discussion from https://github.com/microsoft/vscode-docs/pull/3508#issuecomment-605211179

I thought "needing a parser for the primary language" is self-evident, just as in the language server guide we don't even mention "you need a parser".

Agree, it's not about the parser. I wanted to state that there's always a primary language that defines the syntax of the document. It's an issue that comes up all the time: See https://github.com/microsoft/vscode/issues/92349. Looks like HTML, but is PHP. People just think this can be handled by a HTML language server, but no, it's an embedded scenario, with HTML as an embedded language.

I think that's a minor detail that can be explained later in the doc. What issue would you encounter if you don't consider character encoding?

What I find important to understand is that extracting the embedded content involves a transformation of the input to the embeddeded language and a transformation of the result back to the host language. What has been suggested several times, why doesn't the HTML language server just gives back ranges of where JavaScript is and let TypeScript server directly work on it. Again in HTML for <script> and <style> this is very subtle and can even be ignored (in fact our code ignores escaping aspects), but it's important to realize. An example to illustrate that is JavaScript embedded in style attributes:

 <INPUT name="num" value="0" onchange="if (compare(this.value, &quot;help&quot;)) {gethelp()}">

The transformation of LS result (e.g. completions) back to the host language not only involves positions and ranges, but can also mean that you need to adjust the competion item insertText

For example in <script> and <style> you can not have a </ in your content. So when done correctly, the completion items would have to be adjusted as described here: https://www.w3.org/TR/html401/appendix/notes.html#h-B.3.2

We should add some examples of different languages.

The techniques how to use services or other LS can come after that.

For the various approaches, a process diagram would help.

octref commented 4 years ago

I addressed the second point but not the first. Feel free to add another section to ## Potential issues.

primary language that defines the syntax of the document

I don't think we want to drift the focus to syntax highlighting. The linked issue is talking about syntax highlighting.

If people are expecting HTML support to work for PHP, we can either point them to this doc or ask them to try files.associations and see how it doesn't work for PHP because PHP is not HTML.

I'm not sure what point exactly does "each document has a primary language" convey, as it's something people should already know from reading the previous Language Server guide and also clear from the API TextDocument.languageId.