Re: Review of debputy editor provided docs for packagers

Justin B Rye:
> Niels Thykier wrote:
>> I am asking for English review of some strings in `debputy` with the intend
>> to submit them for translation afterwards. I tried to send this email out in
>> the past, but it was silently dropped by the list. This time, I am no longer
>> including the texts themselves in my opening email to avoid being filtered
>> on size limits.
> 
> I'll reply to the followup with reviews, which means I get to use this
> reply to check that I've understood the basics.
> 

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.

> So the strings in question are basically chopped up
> reminders of stuff out of Debian Policy, and if I was a DD working on
> a new package in my favourite integrated development environment this
> would be a really handy new bell and/or whistle it could provide.
> 

Indeed that is the gist of it.

With more feature support on either side (editor and debputy), the user 
will get more features. The most basic of features are:

  * Hover docs
  * Completion support
  * Diagnostics (warnings)


> Fortunately, debputy's intended users are bound to be quicker to
> understand this context than I was, and non-developers reading the
> debputy package description get to see that it's in section: devel.
> Most people won't see "language server protocol" and immediately start
> thinking about C-3PO, the way I naturally do...

:)

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.

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.

Many editors support the LSP either directly or via extensions.

# Target audience of the strings

[...]
```

Best regards,
Niels