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
Reply to: