Re: Review of debputy editor provided docs for packagers
Inline commentary *and* attached patch for the README.
> # Translatable strings for `debputy`'s LSP module
>
> Thanks for contributing to the `debputy` LSP module. :)
>
> This document is here to help you with some context of what you are working with.
Wait, these lines aren't in the version I fetched by hand...
> # Target audience of the strings
>
> The target audience of these strings are people, who work on Debian packages, of any experience
is people who
Singular audience, so "is" (though you'd get away with it in en_GB).
Then you want to define a subset of "people", not give a description
of what people (in general) are like, so no comma there.
> level. All strings are very technical by nature but at the same time should also be understandable
> for someone very new to the packaging concepts.
All ⁁the strings
> This is a difficult balance to strike both for the project to provide the initial strings, but
> it may also provide difficult for you as a translator.
The best I can do with this is
Producing the initial strings involves striking a difficult balance, which may also be difficult
for you as a translator.
> If it ever comes to prioritization between
> a newcomer and a seasoned packager, the text and its translation should prioritize the newcomer
> first.
This implies you're prioritising the seasoned packager last, which is
an odd way of prioritising something. You could say:
If it comes to balancing the interests of newcomers and seasoned
packagers, the text and its translation should prioritize newcomers.
> The project written and maintained by seasoned packagers, which is a likely weak point in the
⁁is
> strings that the project provides on average.
Avoiding the image of weak points in strings. Maybe:
The project is written and maintained by seasoned packagers, which may be a general weak
point in the documentation that the project provides.
> # Scope of the strings and how they are used
>
> The strings in this GNU gettext domain cover known fields and, where possible, known values of those fields.
What grounds do we have for suspecting the existence of unknown
ones?
> The strings covers `debian/control`, `debian/copyright` (DEP-5) format and `debian/tests/control` at this
> time.
s/covers/cover/. Oh, and all these sentences start the same way; so
here's a purely cosmetic reshuffle:
At this time the strings cover `debian/control`, `debian/copyright` (DEP-5) format and
`debian/tests/control`.
> The strings are handed over to an editor for exact rendering. As a consequence, they are subject to
> the "do not make assumptions about exact presentation and rendering" rule that debconf templates are
> subject too. Every editor can render these slightly different.
I know developers think Emacs is an editor, but it would be nice if
you'd mention IDEs somewhere around here, so that readers like me
don't assume you mean a real text editor like nano. Maybe something
like
The strings are designed to be used in an IDE editor, which will take care of rendering markup. As a
consequence, they are subject to the same rule against making assumptions about exact presentation
and rendering that applies to debconf templates. Each front-end may render them slightly differently.
> There are two major types of strings:
>
> * [Synopsis](#synopsis)
> * [Hover Doc (`long-description`)](#hover-docs-long-description)
>
> When and how they are used will be covered in their respective subsections.
>
> ## Synopsis
>
> The `synopsis` is used with "completion" actions. That is, if
> the editor is showing the user "here are the options for what you
> can insert here". The following screenshot provides an example:
The middle sentence isn't a sentence. Easiest fix: turn it into
The `synopsis` is used with "completion" actions; that is, when
> 
> The `synopsis` is a one-line plain-text string. It will be rendered
> in association with the value / field name it relates to. In this
> and many other ways, it works a lot like the Synopsis of a Debian
> package (like having to squeeze the most out of very limited text).
Instead of talking about squeezing things out I'd suggest
(and needs to squeeze a lot into a very limited space).
> The protocol used has support for marking completions as obsolete,
> where the editor has a way of showing this to the user (
> strike-through is a common pattern). Therefore, this should never
> be specified in the text itself as there is a code level flag for
> that *if* there is anything better to say in the synopsis.
> That said, there are a couple of cases where we do not know what
> the field did. An "anti-example" being `XS-Ruby-Versions` which has
This looks to me like a plain old pro-example.
Take for example `XS-Ruby-Versions`, which has
> `Obsolete (unknown usage)` as the synopsis in the lack of something
for the lack of anything
> better. Here, using "Obsolete" in the synopsis was an acceptable
> trade-off compared to hunting down what the obsolete field did.
>
> A few case still use `**Advanced field**` (etc.) in their synopsis
cases
> to steer newcomers away from those or warn them about it being
away from them or warn that they are
> potential time-sinks. The plan is to extract those into a general
these
> marker that is included in the synopsis as a prefix. This has
> already been done with "rare (but not obsolete)" fields/values.
>
> Known TODO:
> * Some "prefixes" should be turned into markers.
> * The markers themselves are currently not translatable.
I don't know about other Markdown-viewers, but /usr/bin/markdown
doesn't recognise these TODO-lists as lists. Oh, it wants a leading
blank line... and it's either plural items ("Known TODOs") or a
generic list ("TODO") - I'd go for the latter, since after all you'd
hardly be listing the unknown ones.
>
> ## Hover docs (`long-description`)
>
> The Hover docs (called `long-description` in the source file) are
> used with the LSP `Hover` requests. These are used when the user
XXX
> requests more information from the editor about what they see.
> The request is named `Hover` request, because usually this is
The name "Hover" is used because this is usually
> done by hovering the cursor over the subject of interest. The
> following screenshot provides an example:
>
> 
>
> The strings here are markdown formatted strings that can span
M
> multiple lines. The `debputy` side also auto-generates a header
> with field name and, for values, the value. This header is
> therefore omitted from the strings themselves. The header concrete
Header concrete?? Is "concrete" just some sort of random stray
cut'n'pasted word, or is it jargon so technical that the search
engines have never heard of it? I won't touch it.
> is one of:
>
> * For field names
>
> ```markdown
> # `{FIELD_NAME}`
> ```
>
> * For field values:
>
> ```markdown
> # `{VALUE}` (Field: `{FIELD_NAME}`)
> ```
>
> The editor is expected to provide some way of scrolling the text if
> it is too long. Though, it may provide a fixed size preview first,
However,
> where the user has to explicitly request the full description to
> get the scrolling. Often by clicking on the preview, though exceptions
> to this occur (In `emacs`, the user would run `M-X eldoc-doc-buffer`)
Assuming the Emacs is an example of an exception,
get the scrolling. This often means clicking on the preview, but there
are exceptions; in `emacs`, the user would run `M-X eldoc-doc-buffer`.
> The editor does not inform the `debputy` program whether a fixed
> size preview or the full text is rendered. It is the same request
> (and the same string) for both cases and often done in a single
> request. Nevertheless, it does mean that it can be worth squeezing
> the most juice out of the first few lines as it can sometimes
> enable the user to move on faster.
Nevertheless, it does mean that it can be worth squeezing as
much juice as possible out of the first few lines, as it can sometimes
> There is no rule for how large such a fixed preview is or how many
> lines it spans. It depends on the editor, the font and window
> size the editor is subject to at the time, etc. Therefore, there
> is no hard limit on what is considered "the first few lines".
>
> Note that `debputy` does not provide its own Markdown-to-text
> module. If the editor does not support Markdown, the raw Markdown
> is returned as the hover doc tagged as "plaintext" documentation.
Any hope of making this "plain(-)text"? Plaintext means
"unencrypted", not "unformatted". But if debputy hard-codes the wrong
label I'd better leave it for now.
(You could fudge the issue by referring to it as PlainText...)
> This means the raw markdown must be able to stand alone without
> being confusing to the reader.
>
> Known TODO:
> * The headers themselves are currently not translatable.
>
>
> # Testing / Validating the strings
>
> Currently, the best way to test the strings is to use the `debputy`
> LSP module in your editor and try out how it works in practice.
>
> This is a bit involved and requires that your have a text editor that supports LSP
you code editor
Supporting LSP sounds like a fairly reliable diagnostic for "not what
I'd call a text editor"...
> (see <https://microsoft.github.io/language-server-protocol/implementors/tools/>
> for a list of editors that is known to support this). The guide below
are
There's a guide below?
> assumes you are working in a git checkout of the `debputy` source code.
>
> If you are interested in this, please run:
>
> ./debputy.sh lsp features
>
> Which will tell you if you are missing any packages for the LSP
> module to run. On success, you should see `minimum requirements: enabled`
> under a `General features:` header.
>
> From there, you need to add the relevant editor configuration glue using
> `./debputy.sh lsp server` or `/path/to/debputy.sh lsp server` and use your
> editor on a relevant file from there. The use of `debputy.sh` is to ensure
> you are using
Using...?
>
> # Improving the generated POT file itself
>
> If you find yourself wanting to improve the POT itself, then please
> review the [update_lsp_data_pots.py](../../devutils/update_lsp_data_pots.py)
> script.
Fortunately I didn't read that before I reviewed the .pot file.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- README-translators.md.orig 2024-09-15 09:00:47.578746813 +0100
+++ README-translators.md 2024-09-18 13:08:57.555479069 +0100
@@ -6,27 +6,25 @@
# Target audience of the strings
-The target audience of these strings are people, who work on Debian packages, of any experience
-level. All strings are very technical by nature but at the same time should also be understandable
+The target audience of these strings is people who work on Debian packages, of any experience
+level. All the strings are very technical by nature but at the same time should also be understandable
for someone very new to the packaging concepts.
-This is a difficult balance to strike both for the project to provide the initial strings, but
-it may also provide difficult for you as a translator. If it ever comes to prioritization between
-a newcomer and a seasoned packager, the text and its translation should prioritize the newcomer
-first.
+Producing the initial strings involves striking a difficult balance, which may also be difficult
+for you as a translator. If it comes to balancing the interests of newcomers and seasoned
+packagers, the text and its translation should prioritize newcomers.
-The project written and maintained by seasoned packagers, which is a likely weak point in the
-strings that the project provides on average.
+The project is written and maintained by seasoned packagers, which in may be a general weak point in the
+documentation that the project provides in.
# Scope of the strings and how they are used
The strings in this GNU gettext domain cover known fields and, where possible, known values of those fields.
-The strings covers `debian/control`, `debian/copyright` (DEP-5) format and `debian/tests/control` at this
-time.
+At this time the strings cover `debian/control`, `debian/copyright` (DEP-5) format and `debian/tests/control`.
-The strings are handed over to an editor for exact rendering. As a consequence, they are subject to
-the "do not make assumptions about exact presentation and rendering" rule that debconf templates are
-subject too. Every editor can render these slightly different.
+The strings are designed to be used in an IDE editor, which will take care of rendering markup. As a
+consequence, they are subject to the same rule against making assumptions about exact presentation
+and rendering that applies to debconf templates. Each front-end may render them slightly differently.
There are two major types of strings:
@@ -37,7 +35,7 @@
## Synopsis
-The `synopsis` is used with "completion" actions. That is, if
+The `synopsis` is used with "completion" actions; that is, when
the editor is showing the user "here are the options for what you
can insert here". The following screenshot provides an example:
@@ -46,41 +44,42 @@
The `synopsis` is a one-line plain-text string. It will be rendered
in association with the value / field name it relates to. In this
and many other ways, it works a lot like the Synopsis of a Debian
-package (like having to squeeze the most out of very limited text).
+package (and needs to squeeze a lot into a very limited space).
The protocol used has support for marking completions as obsolete,
-where the editor has a way of showing this to the user (
-strike-through is a common pattern). Therefore, this should never
+where the editor has a way of showing this to the user (strike-through
+is a common pattern). Therefore, this should never
be specified in the text itself as there is a code level flag for
that *if* there is anything better to say in the synopsis.
That said, there are a couple of cases where we do not know what
-the field did. An "anti-example" being `XS-Ruby-Versions` which has
-`Obsolete (unknown usage)` as the synopsis in the lack of something
+the field did. ake for example `XS-Ruby-Versions`, which has
+`Obsolete (unknown usage)` as the synopsis for the lack of anything
better. Here, using "Obsolete" in the synopsis was an acceptable
trade-off compared to hunting down what the obsolete field did.
-A few case still use `**Advanced field**` (etc.) in their synopsis
-to steer newcomers away from those or warn them about it being
-potential time-sinks. The plan is to extract those into a general
-marker that is included in the synopsis as a prefix. This has
+A few cases still use `**Advanced field**` (etc.) in their synopsis
+to steer newcomers away from them or warn that they are
+potential time-sinks. The plan is to extract these into a general
+marker that is included in the synopsis as a prefix. This has
already been done with "rare (but not obsolete)" fields/values.
-Known TODO:
+TODO:
+
* Some "prefixes" should be turned into markers.
* The markers themselves are currently not translatable.
## Hover docs (`long-description`)
The Hover docs (called `long-description` in the source file) are
-used with the LSP `Hover` requests. These are used when the user
+used with LSP `Hover` requests. These are used when the user
requests more information from the editor about what they see.
-The request is named `Hover` request, because usually this is
+The name "Hover" is used because this is usuallly
done by hovering the cursor over the subject of interest. The
following screenshot provides an example:
-The strings here are markdown formatted strings that can span
+The strings here are Markdown formatted strings that can span
multiple lines. The `debputy` side also auto-generates a header
with field name and, for values, the value. This header is
therefore omitted from the strings themselves. The header concrete
@@ -99,16 +98,16 @@
```
The editor is expected to provide some way of scrolling the text if
-it is too long. Though, it may provide a fixed size preview first,
+it is too long. However, it may provide a fixed size preview first,
where the user has to explicitly request the full description to
-get the scrolling. Often by clicking on the preview, though exceptions
-to this occur (In `emacs`, the user would run `M-X eldoc-doc-buffer`)
+get the scrolling. This often means clicking on the preview, but there
+are exceptions; in `emacs`, the user would run `M-X eldoc-doc-buffer`.
The editor does not inform the `debputy` program whether a fixed
size preview or the full text is rendered. It is the same request
(and the same string) for both cases and often done in a single
-request. Nevertheless, it does mean that it can be worth squeezing
-the most juice out of the first few lines as it can sometimes
+request. Nevertheless, it does mean that it can be worth squeezing as
+much juice as possible out of the first few lines, as it can sometimes
enable the user to move on faster.
There is no rule for how large such a fixed preview is or how many
@@ -122,7 +121,8 @@
This means the raw markdown must be able to stand alone without
being confusing to the reader.
-Known TODO:
+TODO:
+
* The headers themselves are currently not translatable.
@@ -131,9 +131,9 @@
Currently, the best way to test the strings is to use the `debputy`
LSP module in your editor and try out how it works in practice.
-This is a bit involved and requires that your have a text editor that supports LSP
+This is a bit involved and requires that you have a code editor that supports LSP
(see <https://microsoft.github.io/language-server-protocol/implementors/tools/>
-for a list of editors that is known to support this). The guide below
+for a list of editors that are known to support this). The guide below
assumes you are working in a git checkout of the `debputy` source code.
If you are interested in this, please run:
Reply to: