Re: Review of debputy editor provided docs for packagers
Niels Thykier wrote:
> Hi Justin
>
> Thanks for looking into this.
>
> Apologies for not being around to respond until now. I have gotten through
> all your replies and processed the textual reviews.
>
>> It took me quite a lot of reading webpages about LSP and so on to work
>> out what any of this was talking about. I gather it's basically for
>> generating C#-specific popup hints and the like in Visual Studio, or
>> (therefore) Debian-control-file-specific hints in Emacs (or just
>> conceivably vi)?
>
> It is about generating language specific features in any editor that support
> the protocol. It is aimed at programming languages with Java and C# probably
> being strongly represented.
>
> As for editor support, the website for LSP has a long list of editors that
> support it. Both emacs and vim support LSP or can do so via a plugin.
Indeed, there are even some IDEs that I *haven't* published webrants
against on that list!
> But there might be a point here that the README-translators.md should
> probably explain what LSP means earlier. Most translators will probably be
> using as that as entry point. I am contemplating having
> README-translators.md start with:
>
> ```
> # Translatable strings for `debputy`'s LSP module
>
> Thanks for contributing to the `debputy` Language Server Protocol (LSP)
> module. :)
>
> This document is here to help you with some context of what you are working
> with.
>
> # What is the LSP
>
> The Language Server Protocol is a protocol between editors and language
> servers. The language servers will provide a set of features for a given
> language like resolving documentation, providing completion suggestions,
> or emit diagnostics (warnings and errors). The `debputy` tool provides a
> language server that delivers features for Debian packaging files.
If you're talking to translators, I'd suggest establishing a
programming context early on. The easiest way is to throw in the word
"IDE" ("between ⁁IDE editors..."); then as an optional extra, maybe
"for a given language ⁁or data format⁁" would make it obvious that
we're talking about things with IEEE specs rather than ISO-639 codes.
Oh, and grammar fix: "or emit⁁ting⁁ diagnostics".
> The Language Server Protocol describes how the editors and language
> servers communicate and thereby enable all LSP supporting editors to
> leverage `debputy` to provide the language features.
The protocol (singular) "enable⁁s" editors to do this.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: