Re: Review of debputy editor provided docs for packagers

To: debian-l10n-english@lists.debian.org
Cc: Niels Thykier <niels@thykier.net>
Subject: Re: Review of debputy editor provided docs for packagers
From: Justin B Rye <justin.byam.rye@gmail.com>
Date: Sun, 15 Sep 2024 21:18:29 +0100
Message-id: <[🔎] ZudBFUhW9XJSinSB@jbr.me.uk>
Mail-followup-to: debian-l10n-english@lists.debian.org, Niels Thykier <niels@thykier.net>
In-reply-to: <[🔎] 1f183285-7395-4a3d-af3b-398a1a0a0058@thykier.net>
References: <[🔎] 2bcddaa3-fb69-46c6-902e-1aa3f57e2df9@thykier.net> <[🔎] 1f183285-7395-4a3d-af3b-398a1a0a0058@thykier.net>
I'm starting with the actual .pot file and hoping to come back to the
README afterwards, but it's going to be a long haul!  I'm starting
with inline comments for as much of it as I've got through so far;
I'll hope to come up with a diff at a later date.

> # SOME DESCRIPTIVE TITLE.
> # This file is put in the public domain.
> # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
> #
> #, fuzzy
> msgid ""
> msgstr ""
> "Project-Id-Version: debputy 0.1.50-1-gbf15774\n"
> "Report-Msgid-Bugs-To: https://salsa.debian.org/debian/debputy/-/issues/\n";
> "POT-Creation-Date: 2024-09-15 05:53+0000\n"
> "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
> "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
> "Language-Team: LANGUAGE <LL@li.org>\n"
> "Language: \n"
> "MIME-Version: 1.0\n"
> "Content-Type: text/plain; charset=utf-8\n"
> "Content-Transfer-Encoding: 8bit\n"
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Source"
> msgid "Name of source package"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Source"
> msgid ""
> "Declares the name of the source package.\n"
> "\n"
> "Note this must match the name in the first entry of `debian/changelog` file.\n"
> msgstr ""

Strictly speaking this ought to be "Note that" or "Note:" or
something, but given that this is already a note of notable
information you don't need to say so.  And if this isn't being
abbreviated to the point of dropping the article in "the first entry"
then you also need a definite article in "the `debian/changelog` file".

  "This must match the name in the first entry of `debian/changelog` file.\n"

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Standards-Version"
> msgid "Debian Policy version this package complies with"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Standards-Version"
> msgid ""
> "Declares the last semantic version of the Debian Policy this package as last checked against.\n"

I'm assuming "w⁁as last checked against". But wait, why two "last"s?
Come to that, why one?  It's not as if you might go backwards and
start checking a package against policy version 1.0, or recording the
version it was first checked against.  Oh well, just make it:

  "Declares the last semantic version of Debian Policy this package has been checked against.\n"

(Debian Policy is the name of a collection of rules; talking about
"the" policy makes it sound as if you're talking about one particular
rule.)

> "\n"
> "**Example**:\n"
> "```\n"
> "Standards-Version: 4.7.0\n"
> "```\n"
> "\n"
> "Note that the last version part of the full Policy version (the **.X** in 4.7.0**.X**) is\n"
> "typically omitted as it is used solely for editorial changes to the policy (e.g. typo fixes).\n"
> msgstr ""

(Does Markdown markup count towards line lengths?)

Saying "to the policy" sounds even more as if you're talking about a
single rule; frankly I'd just drop it and say:

  "The last version part of the full Policy version (the **.X** in 4.7.0.**X**) is\n"
  "typically omitted, as it is used solely for editorial changes (e.g. typo-fixes).\n"
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Section"
> msgid "Default section for Package stanzas without an explicit Section field"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Section"
> msgid ""
> "Define the default section for packages in this source package.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Section: devel\n"
> "```\n"
> "\n"
> "Please see <https://packages.debian.org/unstable> for more details about the sections.\n"
> msgstr ""

That URL just gives a search for packages with "unstable" in their
names.  You want... um... oh, here it is:

  "See <https://packages.debian.org/sid/> for more details about the sections.\n"

(I wouldn't use "please" here, since we're not saying we'd be
grateful if they did this, we're just being helpful.)
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Priority"
> msgid ""
> "Default priority for Package stanzas without an explicit Priority field"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Priority"
> msgid ""
> "Define the default priority for packages in this source package.\n"
> "\n"
> "The priority field describes how important the package is for the functionality of the system.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Priority: optional\n"
> "```\n"
> "\n"
> "Unless you know you need a different value, you should choose **optional** for your packages.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "required" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Priority"
> msgid ""
> "Package is de facto Essential or an Essential package needs it (and is not a"
> " library)"
> msgstr ""

Strictly speaking that last parenthetical clause is saying "and if the
*Essential* package isn't a library", which I don't think is what you
mean.

Wait, is this meant to be a definition for "Priority: required"?  If
so, it's using "de facto" very oddly.  Should it be something like
"Essential or pseudo-Essential"?  Hang on, the current definitions at
https://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities
don't work in terms of Essentialness at all.  They define it as
"necessary for the proper functioning of the system".

So I'm just going to give up thinking about that and suggest:

  "Package is Essential, or is a non-library needed by an Essential package"

> #. [Hover Doc] Extended description for the value "required" [Markdown]. Shown
> #. in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Priority"
> msgid ""
> "The package is necessary for the proper functioning of the system (read: dpkg needs it).\n"
> "\n"
> "Applicable if dpkg *needs* this package to function and it is not a library.\n"
> "\n"
> "No two packages that both have a priority of *standard* or higher may conflict with\n"
> "each other.\n"
> msgstr ""

This is a completely different definition.  It has the advantage of
more closely resembling the manual, while making it explicable that my
bootloader and kernel are "Priority: optional".  I still don't see how
e2fsprogs gets to be "Priority: required", but never mind, at least
there's nothing to nitpick in the grammar!
 
> #. [Synopsis] One-line description for the value "important" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Priority"
> msgid "Bare minimum of commonly-expected and necessary tools"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "important" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Priority"
> msgid ""
> "The *important* packages are a bare minimum of commonly-expected and necessary tools.\n"
> "\n"
> "Applicable if 99% of all users in the distribution needs this package and it is not a library.\n"
> "\n"
> "No two packages that both have a priority of *standard* or higher may conflict with\n"
> "each other.\n"
> msgstr ""

"99% of users" is plural, and users are "of" the distribution, not
"in" it.

  "Applicable if 99% of all users of the distribution need this package and it is not a library.\n"

I'm unconvinced that 99% of users need vim-tiny, but I'm scared of
opening these cans now.
 
> #. [Synopsis] One-line description for the value "standard" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Priority"
> msgid ""
> "The distribution installer should install this by default (not for "
> "libraries)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "standard" [Markdown]. Shown
> #. in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Priority"
> msgid ""
> "These packages provide a reasonable small but not too limited character-mode system.  This is\n"
> "what will be installed by default (by the debian-installer) if the user does not select anything\n"
> "else.  This does not include many large applications.\n"
> "\n"
> "Applicable if your distribution installer will install this package by default on a new system\n"
> "and it is not a library.\n"
> "\n"
> "No two packages that both have a priority of *standard* or higher may conflict with\n"
> "each other.\n"
> msgstr ""

Is that "reasonable, small, but not too limited" or "reasonably small,
but not too limited"?

It's either "by the Debian installer" (describing the piece of
software) or "by debian-installer" (its name).

Does "This does not include many" mean "this includes few" or "this
omits/leaves out many"?

In each case I'm going for option B.  And I'm not sure what "your" is
doing in that middle paragraph, but I won't touch it.

  "These packages provide a reasonably small, but not too limited character-mode system.  This is\n"
  "what will be installed by default (by debian-installer) if the user does not select anything\n"
  "else.  This leaves out many large applications.\n"

> #. [Synopsis] One-line description for the value "optional" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Priority"
> msgid "The default priority"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "optional" [Markdown]. Shown
> #. in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Priority"
> msgid ""
> "This is the default priority and used by the majority of all packages in the Debian archive.\n"
> "\n"
> "It is used for most packages and means that the debian-installer should not directly install it\n"
> "by default on a system (it may still be pulled in as a dependency when relevant).\n"
> "\n"
> "All native shared libraries should have `optional` as their priority with a handful of exceptions\n"
> "like the libc library.\n"
> msgstr ""

The first sentence there has a couple of unidiomatic features; I'd say
  "This is the default priority, used by the majority of packages in the Debian archive.\n"

(If we're not leaving this unbranded for the convenience of Debuan or
Ubuntu or whoever, why does it keep saying "the distribution" instead
of "Debian" elsewhere?)

What's a *native* library?  The only answer I can think of is "one not
used for cross-building", and why would that make a difference to
whether they're Priority: optional?

The backticks round "`optional`" seem inconsistent.  Weren't you using
single-asterisks?

> 
> #. [Synopsis] One-line description for the value "extra" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Priority"
> msgid "Obsolete alias of optional"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "extra" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Priority"
> msgid ""
> "This priority was historically different from `optional`. However, the distinction in semantics\n"
> "between `extra` and `optional` turned out to be unnecessary bookkeeping and the two values were\n"
> "merged into `optional`.\n"
> "\n"
> "Any use of `extra` should unconditionally be replaced by `optional`.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Maintainer"
> msgid "Name and email of the maintainer or the maintenance team"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Maintainer"
> msgid ""
> "The maintainer of the package.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Maintainer: Jane Contributor <jane@janes.email-provider.org>\n"
> "```\n"
> "\n"
> "Note: If a person is listed in the Maintainer field, they should *not* be listed in Uploaders field.\n"
> msgstr ""

"A person" sounds as if this is struggling to be neutral; I'd just say

  "Anyone who is listed in the Maintainer field should *not* be listed in the Uploaders field.\n"

This also avoids annoying people who are allergic to "singular they",
which seems a pity, but never mind.

> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Build-Depends"
> msgid "Dependencies requires for clean and full build actions"
> msgstr ""

Plain typo, I suspect:
  msgid "Dependencies required for clean and full build actions"
                             ^
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Build-Depends"
> msgid ""
> "All minimum build-dependencies for this source package. Needed for any standard build target\n"
> "and the `clean` target.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Build-Depends-Arch"
> msgid ""
> "Dependencies requires for arch:any build actions (build-arch/binary-arch)"
> msgstr ""

Another copy of the same typo:
  "Dependencies required for arch:any build actions (build-arch/binary-arch)"

> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Build-Depends-Arch"
> msgid ""
> "Build-dependencies required for building the architecture dependent binary packages of this source\n"
> "package.\n"
> "\n"
> "These build-dependencies must be satisfied when executing the `build-arch` and `binary-arch`\n"
> "targets either directly or indirectly in addition to those listed in `Build-Depends`.\n"
> "\n"
> "Note that these dependencies are *not* available during `clean`. Use `Build-Depends` for things\n"
> "that must be installed during `clean`.\n"
> msgstr ""

All good; I won't even object to the "Note".  It could survive some
added hyphens, but I don't think it needs them.

> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Build-Depends-Indep"
> msgid ""
> "Dependencies requires for arch:all build actions (build-indep/binary-indep)"
> msgstr ""

Return of the typo:
  "Dependencies required for arch:all build actions (build-indep/binary-indep)"

> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Build-Depends-Indep"
> msgid ""
> "Build-dependencies required for building the architecture independent binary packages of this source\n"
> "package.\n"
> "\n"
> "These build-dependencies must be satisfied when executing the `build-indep` and `binary-indep`\n"
> "targets either directly or indirectly in addition to those listed in `Build-Depends`.\n"
> "\n"
> "Note that these dependencies are *not* available during `clean`. Use `Build-Depends` for things\n"
> "that must be installed during `clean`.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Build-Conflicts"
> msgid ""
> "Package versions that will break the build or the clean target (use "
> "sparingly)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Build-Conflicts"
> msgid ""
> "Packages that must **not** be installed during `any` part of the build, including the `clean`\n"
> "target `clean`.\n"
> "\n"
> "Where possible, it is often better to configure the build so that it does not react to the package\n"
> "being present in the first place. Usually this is a question of using a `--without-foo` or\n"
> "`--disable-foo` or such to the build configuration.\n"
> msgstr ""

Shouldn't that be

  "Packages that must **not** be installed during **any** part of the build, including the `clean`\n"
  "target.\n"

"Or such" is one of those idioms that does occur in native-speaker
English, at least dialectally (and I suspect it used to be commoner),
but what you're after is probably "or similar".  Then you've got
"using a --flag to the configuration" where presumably you mean
"adding".

  "Where possible, it is often better to configure the build so that it does not react to the package\n"
  "being present in the first place. Usually this is a question of adding a `--without-foo` or\n"
  "`--disable-foo` or similar to the build configuration.\n"

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Build-Conflicts-Arch"
> msgid "Package versions that will break an arch:any build (use sparingly)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Build-Conflicts-Arch"
> msgid ""
> "Packages that must **not** be installed during the `build-arch` or `binary-arch` targets.\n"
> "This also applies when these targets are run implicitly such as via the `binary` target.\n"
> "\n"
> "Where possible, it is often better to configure the build so that it does not react to the package\n"
> "being present in the first place. Usually this is a question of using a `--without-foo` or\n"
> "`--disable-foo` or such to the build configuration.\n"
> "\n"
> "Note any package listed here *may* be installed while `clean` is run. Use `Build-Conflicts`\n"
> "to prevent them from being installed during `clean`.\n"
> msgstr ""

Again s/using/adding/ and s/such/similar/.

For consistency: "Note ⁁that⁁ any package..."

> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Build-Conflicts-Indep"
> msgid "Package versions that will break an arch:all build (use sparingly)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Build-Conflicts-Indep"
> msgid ""
> "Packages that must **not** be installed during the `build-indep` or `binary-indep` targets.\n"
> "This also applies when these targets are run implicitly such as via the `binary` target.\n"
> "\n"
> "Where possible, it is often better to configure the build so that it does not react to the package\n"
> "being present in the first place. Usually this is a question of using a `--without-foo` or\n"
> "`--disable-foo` or such to the build configuration.\n"
> "\n"
> "Note any package listed here *may* be installed while `clean` is run. Use `Build-Conflicts`\n"
> "to prevent them from being installed during `clean`.\n"
> msgstr ""

Again s/using/adding/ and s/such/similar/, and "Note ⁁that⁁".

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Rules-Requires-Root"
> msgid "Declare (fake)root requirements for the package building process"
> msgstr ""

Shouldn't that be "Declares"?

> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Rules-Requires-Root"
> msgid ""
> "Declare if and when the package build assumes it is run as root or fakeroot.\n"

  "Declares whether the package build should assume"?

> "\n"
> "Historically, packages had an implicit build dependency on `fakeroot` (or real root)\n"
> "for assembling `.deb` packages with the correct static ownership. Modern Debian packaging\n"
> "tooling no longer requires this implicit build dependency. This field can be used to\n"
> "advertise when a package still needs `fakeroot` for assembling the `.deb` files.\n"
> "\n"
> "Most packages do not need to run as root or fakeroot and the legacy behaviour comes with a\n"
> "performance cost. This field can be used to explicitly declare that the legacy behaviour is\n"
> "unnecessary.\n"
> "\n"

Assuming you're standardizing to en_US, s/behaviour/behavior/g.

> "**Example**:\n"
> "```\n"
> "Rules-Requires-Root: no\n"
> "```\n"
> "\n"
> "Setting this field to `no` *can* cause the package to stop building if it requires root or\n"
> "relied to `fakeroot` to work around upstream using `chown` or `install -o ... -g ...` commands.\n"
> "Depending on the situation, it might require some trivial or some complicated changes to fix that.\n"
> "If it breaks and you cannot figure out how to fix it, then reset the field to `binary-targets`\n"
> "and move on until you have time to fix it.\n"
> "\n"

Relying "on" definitely needs to be "to"; and the phrasing is
subtly awkward.  Probably it would work better if I just shortened
it a bit:

  "Setting this field to `no` *can* cause the package to stop building if it requires root or\n"
  "relied on `fakeroot` to work around upstream using `chown` or `install -o ... -g ...` commands.\n"
  "Depending on the situation, it might require trivial or complicated changes.\n"
  "If it breaks and you cannot figure out how to fix it, set the field to `binary-targets`\n"
  "until you have time to come back to it.\n"

> "The default value for this field depends on the `dpkg-build-api` version. If the package\n"
> "`Build-Depends` on `dpkg-build-api (>= 1)` or later, the default is `no`. Otherwise,\n"
> "the default is `binary-target`.\n"
> "\n"
> "This field is only relevant when when the `Build-Driver` is `debian-rules` (which it is by\n"
> "default).\n"
> "\n"
> "Note:\n"
> "  1) It is **not** possible to require running the package as \"true root\".\n"
> "  2) If the package explicitly needs `fakeroot` for running tests or upstream parts of the code\n"
> "     needs `fakeroot`, then it should add `fakeroot` to its build-dependencies (use\n"
> "     `fakeroot <!nocheck>` if only used for tests). There is no requirement that `fakeroot`\n"
> "     is used by the builder to implement `Rules-Requires-Root: binary-targets`. Additionally,\n"
> "     the build and tests stages of the Debian packaging build is not subject to the value of\n"
> "     `Rules-Requires-Root`. `Rules-Requires-Root` only applies to the `binary`, `binary-arch`,\n"
> "     or `binary-indep` targets).\n"
> msgstr ""

Strictly speaking thats two Notes.

Some flavours of Markdown insist on "1.", not "1)".

Number agreement errors: "if upstream parts NEED `fakeroot`", and
then "the stages ARE not subject..."
 
> #. [Synopsis] One-line description for the value "no" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Rules-Requires-Root"
> msgid "The package does not require fakeroot for package assembly"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "no" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Rules-Requires-Root"
> msgid ""
> "The build process will not require root or fakeroot implicitly during any step nor will it\n"
> "need the `DEB_GAIN_ROOT_CMD` environment variable for selectively running commands as root\n"
> "or fakeroot.  This enables `dpkg-buildpackage`, `debhelper` or/and `debputy` to perform several\n"
> "optimizations during the build.\n"

I'd add a comma before the "nor", and "and/or" rather than
"or/ang/utan", here and everywhere.

> "\n"
> "This value is the default with `dpkg-build-api` at version 1 or later. The value is exclusive\n"
> "and cannot be used with other values.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "binary-targets" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Rules-Requires-Root"
> msgid "The package requires fakeroot for package assembly (legacy behavior)"
> msgstr ""

Oh, you've got the non-legacy spelling!  But then:

> #. [Hover Doc] Extended description for the value "binary-targets" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Rules-Requires-Root"
> msgid ""
> "The build process assumes that `dpkg-buildpackage` will run the relevant binary\n"
> "target with root or fakeroot. This was the historical default behaviour.\n"
> "\n"
> "This value is the default with dpkg-build-api at version 0. The value is exclusive\n"
> "and cannot be used with other values.\n"
> msgstr ""

Relapsing to your old behaviour.
 
> #. [Synopsis] One-line description for the value "debputy/deb-assembly"
> #. [Plaintext]. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Rules-Requires-Root"
> msgid "Use assembly `fakeroot` when `debputy` assembles the deb if needed."
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "debputy/deb-assembly"
> #. [Markdown]. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Rules-Requires-Root"
> msgid ""
> "When using `debputy`, `debputy` is expected to use root or fakeroot when assembling\n"
> "a .deb or .udeb, where it is required to use `fakeroot` with `dpkg-deb`.\n"
> "\n"

Wait, debputy is using debputy?  I don't follow the logic of this. 
Is "where it is required..." a bonus piece of trivia or a
precondition?  Is it saying "it is mandatory to use fakeroot if you
are using dpkg-deb", or "debputy is required if you want to use
both fakeroot and dpkg-deb", or what?

It's possible that you just mean

  "Assembling a .deb or .udeb is expected to require root or fakeroot.\n"

> "Note: The `debputy` can always use `no` instead by falling back to an internal\n"
> "assembly method instead for .deb or .udebs that would need root or fakeroot with\n"
> "`dpkg-deb`.\n"
> msgstr ""

Wild guess:

  "Instead of using `dpkg-deb` with fakeroot to assemble .debs or .udebs, `debputy` can\n"
  "always use `no` instead and fall back on an internal assembly method."

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:X-Style"
> msgid "Declare packaging formatting style"
> msgstr ""

         Declares?
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:X-Style"
> msgid ""
> "This field is read by `debputy` to determine how it should format the files in the package.\n"
> "\n"
> "In its absence, `debputy` will attempt to determine the formatting style by looking at\n"
> "the maintainers and built-in style preferences.\n"
> "\n"

Looking at the maintainers sounds sinister; I'm hoping you mean
looking at the maintainer⁁'s style preferences and built-in ones.

> "This value influences commands such as `debputy reformat` and `debputy lsp server`. When this\n"
> "field is present, it will overrule any built-in style detection that `debputy` would otherwise\n"
> "have applied.\n"
> "\n"
> "Note that unknown styles will cause the styling to be disabled (and trigger a `debputy lint`\n"
> "warning).\n"
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "black" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:X-Style"
> msgid "Uncompromising file formatting of Debian packaging files"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "black" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:X-Style"
> msgid ""
> "Uncompromising file formatting of Debian packaging files\n"
> "\n"
> "By using it, you agree to cede control over minutiae of hand-formatting. In\n"
> "return, the formatter gives you speed, determinism, and freedom from style\n"
> "discussions about formatting.\n"
> "\n"
> "The `black` style is inspired by the `black` Python code formatter. Like with\n"
> "`black`, the style will evolve over time.\n"
> msgstr ""

I think you could get away with "Like with" in conversation, but
not combined with a style that spells "can't" as "cannot", so I'll
do some uncompromising copy-editing here:

  "The `black` style is inspired by the `black` Python code formatter. As with\n"
  "`black`, the style will evolve over time.\n"
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Uploaders"
> msgid "Names and emails of co-maintainers"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Uploaders"
> msgid ""
> "Comma separated list of uploaders associated with the package.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Uploaders:\n"
> " John Doe <john@doe.org>,\n"
> " Lisbeth Worker <lis@worker.org>,\n"
> "```\n"
> "\n"
> "Formally uploaders are considered co-maintainers for the package with the party listed in the\n"
> "`Maintainer` field being the primary maintainer. In practice, each maintainer or maintenance\n"
> "team can have their own ruleset about the difference between the `Maintainer` and the\n"
> "`Uploaders`. As an example, the Python packaging team historically had a different rule set\n"
> "for how to react to a package depending on whether the packaging team is the `Maintainer`\n"
> "or in the `Uploaders` field.\n"
> "\n"

Should these be backticks?  I'm fairly sure you ought to be
following a more consistent ruleset for the spelling of "ruleset".
And is "react to" the phrase you wanted, or should it be "treat"?

> "For team maintained packages with large packaging teams, the `Uploaders` field will often only\n"
> "contain a small subset of the team. Each team have their own rules for how people are added to\n"
> "or removed from `Uploaders`.\n"
> "\n"
> "Note: If a person is listed in the Maintainer field, they should *not* be listed in Uploaders field.\n"
> msgstr ""

In en_GB you'd get away with "the team have", but not "each team
have", and besides, this ought to be in en_US, so make it "Each team
has its own rules".

Again the "If a person" line, which I'd change to "anyone..."

Oh, and personally I'd hyphenate comma-separated and team-maintained, but I
don't think I'll bother changing it here.

> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Build-Driver"
> msgid ""
> "Which build-driver implementation dpkg should use for the package build"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Build-Driver"
> msgid ""
> "The name of the build driver that dpkg (`dpkg-buildpackage`) will use for assembling the\n"
> "package.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Vcs-Browser"
> msgid "URL for browsers to interact with the VCS used for Debian packaging"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Vcs-Browser"
> msgid ""
> "URL to the Version control system repo used for the Debian packaging. The URL should be usable\n"
> "with a web browser *without* requiring any login.\n"
> "\n"

Either "version control system" or "Version Control System".

> "It is a common mistake to use this field to list the upstream version control system rather\n"
> "than the Debian packaging version control system. The upstream URL should go into the\n"
> "`Repository-Browse` field of the `debian/upstream/metadata` file. In rare cases, the upstream\n"
> "and the packaging VCS uses the same URL. When that happens, the same URL would be used in both\n"
> "places.\n"
> "\n"
> "This should be used together with one of the other `Vcs-` fields.\n"
> msgstr ""

You only need to expand VCS once, and you did that already.  There's
also a number agreement problem:
:
  "It is a common mistake to use this field to list the upstream VCS rather than the Debian\n"
  "packaging VCS. The upstream URL should go into the `Repository-Browse` field of the\n"
  "`debian/upstream/metadata` file. In rare cases, the upstream and packaging VCS both use\n"
  "the same URL. When that happens, the same URL would be used in both places.\n"

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Vcs-Git"
> msgid "URL and options for cloning the packaging git repository"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Vcs-Git"
> msgid ""
> "URL to the git repo used for the packaging. The URL should be usable with `git clone`\n"
> "*without* requiring any login.\n"
> "\n"
> "Note it is possible to specify a branch via the `-b` option if the default branch is not the\n"
> "correct one. This can useful in the case the Debian packaging repository is also the upstream\n"
> "code git repository but the packaging lives on a non-default branch. An example:\n"
> "\n"

Here I'd drop the "Note" but add a "that" to "in the case ⁁that" (or
just say "when").

> "```\n"
> "Vcs-Git: https://github.com/some/upstream-project -b debian/unstable\n"
> "```\n"
> "\n"
> "It is a common mistake to use this field to list the upstream version control system rather\n"
> "than the Debian packaging version control system. The upstream URL should go into the\n"
> "`Repository` field of the `debian/upstream/metadata` file. In rare cases, the upstream and\n"
> "the packaging VCS uses the same URL. When that happens, the same URL would be used in both\n"
> "places.\n"

More overexpanded VCSs, and again I'd say "In rare cases, the
upstream and packaging VCS both use the same URL".

> "\n"
> "This should be used together with the `Vcs-Browser` field provided there is a web UI for the repo.\n"
> msgstr ""

Comma before "provided" (to avoid leading readers up the garden path
of "the field provided there").

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Vcs-Svn"
> msgid "URL for checking out the packaging Subversion (SVN) repository"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Vcs-Svn"
> msgid ""
> "URL to the git repo used for the packaging. The URL should be usable with `svn checkout`\n"
> "*without* requiring any login.\n"

s/git/subversion/.  I wish it was always that easy.

> "\n"
> "This should be used together with the `Vcs-Browser` field provided there is a web UI for the repo.\n"
                                                            ^,
> "\n"
> "It is a common mistake to use this field to list the upstream version control system rather\n"
> "than the Debian packaging version control system. The upstream URL should go into the\n"
> "`Repository` field of the `debian/upstream/metadata` file. In rare cases, the upstream and\n"
> "the packaging VCS uses the same URL. When that happens, the same URL would be used in both\n"
> "places.\n"

As above.

> "\n"
> "This should be used together with the `Vcs-Browser` field provided there is a web UI for the repo.\n"
> msgstr ""

You already said that.

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Vcs-Arch"
> msgid "URL for checking out the packaging VCS"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Vcs-Arch"
> msgid ""
> "URL to the git repo used for the packaging. The URL should be usable for getting a copy of the\n"
> "sources *without* requiring any login.\n"

s/git/arch/

> "\n"
> "It is a common mistake to use this field to list the upstream version control system rather\n"
> "than the Debian packaging version control system. The upstream URL should go into the\n"
> "`Repository` field of the `debian/upstream/metadata` file. In rare cases, the upstream and\n"
> "the packaging VCS uses the same URL. When that happens, the same URL would be used in both\n"
> "places.\n"
> "\n"
> "This should be used together with the `Vcs-Browser` field provided there is a web UI for the repo.\n"
> msgstr ""

As above.
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Vcs-Cvs"
> msgid "URL for checking out the packaging VCS"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Vcs-Cvs"
> msgid ""
> "URL to the git repo used for the packaging. The URL should be usable for getting a copy of the\n"
> "sources *without* requiring any login.\n"

s/git/CVS/, or should that be /cvs/?

> "\n"
> "It is a common mistake to use this field to list the upstream version control system rather\n"
> "than the Debian packaging version control system. The upstream URL should go into the\n"
> "`Repository` field of the `debian/upstream/metadata` file. In rare cases, the upstream and\n"
> "the packaging VCS uses the same URL. When that happens, the same URL would be used in both\n"
> "places.\n"
> "\n"
> "This should be used together with the `Vcs-Browser` field provided there is a web UI for the repo.\n"
> msgstr ""

As above..
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Vcs-Darcs"
> msgid "URL for checking out the packaging VCS"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Vcs-Darcs"
> msgid ""
> "URL to the git repo used for the packaging. The URL should be usable for getting a copy of the\n"
> "sources *without* requiring any login.\n"

s/git/Darcs/

> "\n"
> "It is a common mistake to use this field to list the upstream version control system rather\n"
> "than the Debian packaging version control system. The upstream URL should go into the\n"
> "`Repository` field of the `debian/upstream/metadata` file. In rare cases, the upstream and\n"
> "the packaging VCS uses the same URL. When that happens, the same URL would be used in both\n"
> "places.\n"
> "\n"
> "This should be used together with the `Vcs-Browser` field provided there is a web UI for the repo.\n"
> msgstr ""

As above.
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Vcs-Hg"
> msgid "URL for checking out the packaging VCS"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Vcs-Hg"
> msgid ""
> "URL to the git repo used for the packaging. The URL should be usable for getting a copy of the\n"
> "sources *without* requiring any login.\n"

s/git/hg/, or should it be "the Mercurial repo"?

> "\n"
> "It is a common mistake to use this field to list the upstream version control system rather\n"
> "than the Debian packaging version control system. The upstream URL should go into the\n"
> "`Repository` field of the `debian/upstream/metadata` file. In rare cases, the upstream and\n"
> "the packaging VCS uses the same URL. When that happens, the same URL would be used in both\n"
> "places.\n"
> "\n"
> "This should be used together with the `Vcs-Browser` field provided there is a web UI for the repo.\n"
> msgstr ""

As above.
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Vcs-Mtn"
> msgid "URL for checking out the packaging VCS"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Vcs-Mtn"
> msgid ""
> "URL to the git repo used for the packaging. The URL should be usable for getting a copy of the\n"
> "sources *without* requiring any login.\n"

Oh, Monotone!  I hadn't even noticed this one existed.  At least
that must mean we're near the end of the list.

In fact, what happened to Vcs-Bzr?

> "\n"
> "It is a common mistake to use this field to list the upstream version control system rather\n"
> "than the Debian packaging version control system. The upstream URL should go into the\n"
> "`Repository` field of the `debian/upstream/metadata` file. In rare cases, the upstream and\n"
> "the packaging VCS uses the same URL. When that happens, the same URL would be used in both\n"
> "places.\n"
> "\n"
> "This should be used together with the `Vcs-Browser` field provided there is a web UI for the repo.\n"
> msgstr ""

As above.

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:DM-Upload-Allowed"
> msgid "No longer functional authorization scheme for Debian Maintainers"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:DM-Upload-Allowed"
> msgid ""
> "The `DM-Upload-Allowed` field was historically used to enable Debian Maintainers to upload the\n"
> "package without requiring a Debian Developer to sign the package. This mechanism has been replaced\n"
> "by a new authorization mechanism. The field is now obsolete and should be removed unconditionally. \n"
> "\n"
> "Please see <https://lists.debian.org/debian-devel-announce/2012/09/msg00008.html> for details about the\n"
> "replacement.\n"
> msgstr ""

(This made me think "Really?  Uh-oh, did I update
https://wiki.debian.org/Glossary#dmua for this?" - yes, twelve years
ago, with a link to that same d-d-a message.)
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Testsuite"
> msgid "Announce autodep8 tests"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Testsuite"
> msgid ""
> "Declares that this package provides or should run install time tests via `autopkgtest`.\n"
> "\n"
> "This field can be used to request an automatically generated autopkgtests via the `autodep8` package.\n"
> "Please refer to the documentation of the `autodep8` package for which values you can put into\n"
> "this field and what kind of testsuite the keywords will provide.\n"
> "\n"
> "Declaring this field in `debian/control` is only necessary when you want additional tests beyond\n"
> "those in `debian/tests/control` as `dpkg` automatically records the package provided ones from\n"
> "`debian/tests/control`.\n"
> msgstr ""

It seems odd to talk about an autopkgtests, but okay, that is what
people say.

> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Homepage"
> msgid "URL to the homepage of the upstream project"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Homepage"
> msgid ""
> "Link to the upstream homepage for this source package.\n"
> "\n"
> "The URL will be presented to users when they view the package metadata, so they can access it\n"
> "when deciding whether to install the tool.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Homepage: https://www.janes-tools.org/frob-cleaner\n";
> "```\n"
> msgstr ""

Surprisingly not yet occupied by domain-resellers.
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Bugs"
> msgid "Custom bugtracker URL (for third-party packages)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Bugs"
> msgid ""
> "Provide a custom bug tracker URL\n"
> "\n"
> "This field is *not* used by packages uploaded to Debian or most derivatives as the distro tooling\n"
> "has a default bugtracker built-in. It is primarily useful for third-party provided packages such\n"
> "that bug reporting tooling can redirect the user to their bug tracker.\n"
> msgstr ""

"A built-in X", but "has an X built in".  Oh, and another rogue
such: this time s/such that/so that/.
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Origin"
> msgid "Custom origin (for third-party packages)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Origin"
> msgid ""
> "Declare the origin of the package.\n"
> "\n"
> "This field is *not* used by packages uploaded to Debian or most derivatives as the origin would\n"
> "be the distribution. It is primarily useful for third-party provided packages as some tools will\n"
> "detect this field and change behavior. Like informing the user that the package is a third-party\n"
> "package.\n"
> msgstr ""

No, a "like" I don't like.  Really it's the grammar that needs
fixing, though:
  "detect this field and change behavior, for instance by informing the user that the package is a
  "third-party package.\n"

(An expression that always makes me wonder which is the first party
and which is the second...)

> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:X-Python-Version"
> msgid "Supported Python2 versions (dh-python specific)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:X-Python-Version"
> msgid ""
> "Obsolete field for declaring the supported Python2 versions\n"
> "\n"
> "Since Python2 is no longer supported, this field is now redundant. For Python3, the field is\n"
> "called `X-Python3-Version`.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:X-Python3-Version"
> msgid "Supported Python3 versions (dh-python specific)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:X-Python3-Version"
> msgid ""
> "For declaring the supported Python3 versions\n"

Missing final stop?

> "\n"
> "This is used by the tools from `dh-python` package. Please see the documentation of that package\n"
> "for when and how to use it.\n"
> msgstr ""

That's either "from ⁁the package `dh-python`" or "from the
`dh-python` package".  Then again, if you're going to go on to refer
to it as a package in the next sentence you might equally well just say

  "This is used by the tools from `dh-python`. Please see the documentation of that package\n"
  "for when and how to use it.\n"
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:XS-Autobuild"
> msgid ""
> "Whether this non-free is auto-buildable on buildds (requires central "
> "registration)"
> msgstr ""

Huh?  Oh, is there a word missing?
  "Whether this non-free ⁁package is auto-buildable on buildds (requires central "

> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:XS-Autobuild"
> msgid ""
> "Used for non-free packages to denote that they may be auto-build on the Debian build infrastructure\n"

A build failure.  Here you wanted "may be auto-builded", spelled
"auto-built".

> "\n"
> "Note that adding this field **must** be combined with following the instructions at\n"
> "<https://www.debian.org/doc/manuals/developers-reference/pkgs.html#non-free-buildd>\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:XS-Ruby-Versions"
> msgid "Obsolete (unknown usage)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:XS-Ruby-Versions"
> msgid ""
> "Obsolete according to <https://bugs.debian.org/1075762>.\n"
> "\n"
> "Its historical purpose is not known but is probably related to supported Ruby versions.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Source|Field:Description"
> msgid "Common base description for all packages via substvar"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Source|Field:Description"
> msgid ""
> "This field contains a human-readable description of the package. However, it is not used directly.\n"
> "\n"
> "Binary packages can reference parts of it via the `${source:Synopsis}` and the\n"
> "`${source:Extended-Description}` substvars. Without any of these substvars, the `Description` field\n"
> "of the `Source` stanza remains unused.\n"
> "\n"
> "The first line immediately after the field is called the *Synopsis* and is a short \"noun-phrase\"\n"
> "intended to provide a one-line summary of a package. The lines after the *Synopsis* is known\n"
> "as the *Extended Description* and is intended as a longer summary of a package.\n"

Number agreement again.  "The lines [...] ARE known as".

> "\n"
> "**Example**:\n"
> "```\n"
> "Description: documentation generator for Python projects\n"
> "  Sphinx is a tool for producing documentation for Python projects, using\n"
> "  reStructuredText as markup language.\n"
> "  .\n"
> "  Sphinx features:\n"
> "   * HTML, CHM, LaTeX output,\n"
> "   * Cross-referencing source code,\n"
> "   * Automatic indices,\n"
> "   * Code highlighting, using Pygments,\n"
> "   * Extensibility. Existing extensions:\n"
> "     - automatic testing of code snippets,\n"
> "     - including docstrings from Python modules.\n"
> "  .\n"
> "  Build-depend on sphinx if your package uses /usr/bin/sphinx-*\n"
> "  executables. Build-depend on python3-sphinx if your package uses\n"
> "  the Python API (for instance by calling python3 -m sphinx).\n"
> "```\n"

(Someone should tell the Sphinx maintainer that the plural of index in
the list-of-crossreferences sense is indexes, not indices.  Wait, do
any of the sphinx package descriptions actually list any of those
features?)

Is this going to get Markdownified so that the first set of
bulletpoints are just ASCII asterisks but the second are magic
rendered-Markdown bulletpoints?

> "\n"
> "The *Synopsis* is usually displayed in cases where there is limited space such as when reviewing\n"
> "the search results from `apt search foo`.  It is often a good idea to imagine that the *Synopsis*\n"
> "part is inserted into a sentence like \"The package provides {Synopsis-goes-here}\". The\n"
> "*Extended Description* is a standalone description that should describe what the package does and\n"
> "how it relates to the rest of the system (in terms of, for example, which subsystem it is which part of).\n"
> "Please see <https://www.debian.org/doc/debian-policy/ch-controlfields.html#description> for more details\n"
> "about the description field and suggestions for how to write it.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Package"
> msgid "Declares the name of a binary package"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Architecture"
> msgid "Architecture of the package"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Architecture"
> msgid ""
> "Determines which architectures this package can be compiled for or if it is an architecture-independent\n"
> "package.  The value is a space-separated list of dpkg architecture names or wildcards.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Package: architecture-specific-package\n"
> "Architecture: any\n"
> "# ...\n"
> "\n"
> "\n"
> "Package: data-only-package\n"
> "Architecture: all\n"
> "Multi-Arch: foreign\n"
> "# ...\n"
> "\n"
> "\n"
> "Package: linux-only-package\n"
> "Architecture: linux-any\n"
> "# ...\n"
> "```\n"
> "\n"
> "When in doubt, stick to the values `all` (for scripts, data or documentation, etc.) or `any`\n"
> "(for anything that can be compiled).  For official Debian packages, it is often easier to attempt the\n"
> "compilation for unsupported architectures than to maintain the list of machine architectures that work.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "all" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Architecture"
> msgid ""
> "Independent of machine architecture (scripts, Java without JNI, data or "
> "documentation)"
> msgstr ""

This would be easier to parse as
                                       (scripts, data, documentation, or
  "Java without JNI"

> #. [Hover Doc] Extended description for the value "all" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Architecture"
> msgid ""
> "The package is an architecture independent package.  This is typically fitting for packages containing\n"
> "only scripts, data or documentation.\n"
> "\n"
> "This name `all` refers to the fact that the package can be used for *all* architectures at the same.\n"
> "Though note that it is still subject to the rules of the `Multi-Arch` field.\n"
> msgstr ""

"Fitting" isn't very fitting; say "This is typically appropriate".

  "The name `all` refers to the fact that the package can be used for *all* architectures at the same time.\n"

Hang on.  Surely *all* packages (well, most of them) are used on all
architectures at the same time?  gcc, for instance, is available for
amd64 and sh4 and so on, and runs on all of them.  Yes, it's a
different compiled .deb on each of those architectures, but they're
all the same package - the one named gcc!

I was going to write this off as impossible to disambiguate with the
jargon we've got handy, but maybe it's worth thinking in terms of
"reproducible builds" and saying

  "The name `all` refers to the fact that the same build of a package can be used for *all* architectures.\n"

> "Though note that it is still subject to the rules of the `Multi-Arch` field.\n"
> 
> #. [Synopsis] One-line description for the value "any" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Architecture"
> msgid ""
> "Build once per machine architecture (native code, such as C/C++, interpreter"
> " to C bindings)"
> msgstr ""

Is this commanding the reader to build once, or is it another
build failure?  It's got to be the latter; you want "Built".
 
> #. [Hover Doc] Extended description for the value "any" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Architecture"
> msgid ""
> "The package is an architecture dependent package and need to be compiled for each and every\n"
> "architecture it.\n"

Number error, rogue pronoun.

  "This is an architecture-dependent package, and needs to be compiled for each and every\n"
  "architecture.\n"

> "\n"
> "The name `any` refers to the fact that this is an architecture *wildcard* matching\n"
> "*any machine architecture* supported by dpkg.\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Pre-Depends"
> msgid "Very strong dependencies; prefer Depends when applicable"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Pre-Depends"
> msgid ""
> "**Advanced field**. *This field covers an advanced topic.  If you are new to packaging, you are*\n"
> "*probably not looking for this field (except to set a `${misc:Pre-Depends}` relation with*\n"
> "*`debhelper` in compat 13 or earlier).  Incorrect use of this field can cause issues - among other*\n"
> "*causing issues during upgrades that users cannot work around without passing `--force-*` options*\n"
> "*to dpkg.*\n"

"Among other" doesn't work there - you could say "among other things,"
or just switch to "including".

> "\n"
> "This field is like `Depends`, except that is also forces dpkg to complete installation of the packages\n"
> "named before even starting the installation of the package which declares the pre-dependency.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Package: foo\n"
> "Pre-Depends: ${misc:Pre-Depends}\n"
> "```\n"
> "\n"
> "Note this is a very strong dependency and not all packages support being a pre-dependency because it\n"
> "puts additional requirements on the package being depended on. Use of `${misc:Pre-Depends}` is\n"
> "pre-approved (but redundant with `debhelper` in compat 14+ or `debputy`). Essential packages are known\n"
> "to support being in `Pre-Depends`. However, careless use of `Pre-Depends` for essential packages can\n"
> "still cause dependency resolvers problems.\n"
> "\n"
> "Note `Pre-Depends` **cannot** be used to ensure that the package is upgraded by a given version of\n"
> "`dpkg` or `apt`. \n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Depends"
> msgid "Dependencies required to install and use this package"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Depends"
> msgid ""
> "Lists the packages that must be installed, before this package is installed.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Package: foo\n"
> "Architecture: any\n"
> "Depends: ${misc:Depends},\n"
> "         ${shlibs:Depends},\n"
> "         libfoo1 (= ${binary:Version}),\n"
> "         foo-data (= ${source:Version}),\n"
> "```\n"
> "\n"
> "This field declares an absolute dependency. Before installing the package, `dpkg` will require\n"
> "all dependencies to be in state `configured` first. Though, if there is a circular dependency between\n"
> "two or more packages, `dpkg` will break that circle at an arbitrary point where necessary based on\n"
> "built-in heuristics.\n"

Sentence-initial "though" is unpopular with styleguides.

Why do you say "a circular dependency between two or more packages"?
I mean, how could it be between fewer than two?  You might as well say
"a circular inter-package dependency"... and strictly speaking even
the word "inter-package" is redundant there.

> "\n"
> "This field should be used if the depended-on package is required for the depending package to provide a\n"
> "*significant amount of functionality* or when it is used in the `postinst` or `prerm` maintainer\n"
> "scripts.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Recommends"
> msgid "Optional dependencies most systems should have"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Recommends"
> msgid ""
> "Lists the packages that *should* be installed when this package is installed in all but\n"
> "*unusual* installations.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Package: foo\n"
> "Recommends: bar-optional\n"
> "```\n"
> "\n"
> "By default, APT will attempt to install recommends unless they cannot be installed or the user\n"
> "has configured APT skip recommends. Notably, during automated package builds for the Debian\n"
> "archive, `Recommends` are **not** installed.\n"

Missing word:
  "has configured APT ⁁to skip recommends. Notably, during automated package builds for the Debian\n"

I would prefer to capitalise "Recommends" there, because the
dictionary recognises no such English noun as "a recommend"; when we
talk about installing the Depends and Recommends and Suggests we're
using Debian-specific jargon based rather vaguely on the confrol-file
fieldnames (it's not at all clear what the singular is...)  But I'd be
fighting a losing battle, so never mind.

> "\n"
> "As implied, the package must have some core functionality that works **without** the\n"
> "`Recommends` being satisfied as they are not guaranteed to be there.  If the package cannot\n"
> "provide any functionality without a given package, that package should be in `Depends`.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Suggests"
> msgid "Optional dependencies that may be useful in some cases"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Suggests"
> msgid ""
> "Lists the packages that may make this package more useful but not installing them is perfectly\n"
> "reasonable as well. Suggests can also be useful for add-ons that only make sense in particular\n"
> "corner cases like supporting a non-standard file format.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Package: debputy\n"
> "Suggests: debputy-lsp\n"
> "```\n"
> "\n"
> "The `Suggests` field is complimented by the `Enhances` field that can be used for when you\n"
> "want to say the package improves another package.\n"
> msgstr ""

Gotcha!  Fields are almost never complimented, the poor things,
they're only ever complemented.  They aren't even different Latin
words, it's just an orthographic caltrop.
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Enhances"
> msgid "Packages enhanced by installing this package"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Enhances"
> msgid ""
> "This field is similar to Suggests but works in the opposite direction.  It is used to declare that\n"
> "this package can enhance the functionality of another package.\n"
> "\n"
> "**Example 1**:\n"
> "```\n"
> "Package: debputy-lsp\n"
> "Enhances: debputy\n"
> "```\n"
> "\n"
> "**Example 2**:\n"
> "```\n"
> "Package: foo\n"
> "Provides: debputy-plugin-foo, dh-sequence-foo\n"
> "Enhances: debputy, debhelper\n"
> "```\n"
> "\n"
> "This can be useful for cases where add-ons are created in a decentralized manner, such as with\n"
> "`debhelper` add-ons and `debputy` plugins.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Provides"
> msgid "Additional packages/versions this package dependency-wise satisfy"
> msgstr ""

This is at least a number agreement error, plus something more
contorted.  Is it trying to say:

  msgid "Additional packages/versions that this package satisfies dependencies for"
 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Provides"
> msgid ""
> "Declare this package also provide one or more other packages.  This means that this package can\n"
> "substitute for the provided package in some relations.\n"
> "\n"

More number disagreement: "Declares that this package also provides".

> "**Example**:\n"
> "```\n"
> "Package: foo\n"
> "...\n"
> "\n"
> "Package: foo-plus\n"
> "Provides: foo (= ${source:Upstream-Version})\n"
> "```\n"
> "\n"
> "If the provides relation is versioned, it must use a \"strictly equals\" version.  If it does not\n"
> "declare a version, then it *cannot* be used to satisfy a dependency with a version restriction.\n"
> "Consider the following example:\n"
> "\n"
> "**Archive scenario**:  (This is *not* a `debian/control` file, despite the resemblance)\n"
> "```\n"
> "Package foo\n"
> "Depends: bar (>= 1.0)\n"
> "\n"
> "Package: bar\n"
> "Version: 0.9\n"
> "\n"
> "Package: bar-plus\n"
> "Provides: bar (= 1.0)\n"
> "\n"
> "Package: bar-clone\n"
> "Provides: bar\n"
> "```\n"
> "\n"
> "In this archive scenario, the `bar-plus` package will satisfy the dependency of `foo` as the\n"
> "only one. The `bar` package fails because the version is only *0.9* and `bar-clone` because\n"
> "the provides is unversioned, but the dependency clause is versioned.\n"
> msgstr ""

I don't think you can say "as the only one" - make it

  "In this archive scenario, the `bar-plus` package is the only one that will satisfy the dependency\n"
  "of `foo`. The `bar` package fails because the version is only *0.9* and `bar-clone` because\n"
  "the provides is unversioned, but the dependency is versioned.\n"

(I've dropped the word "clause" because I don't see what it's doing
there.)

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Conflicts"
> msgid "Packages that this package is not co-installable with"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Conflicts"
> msgid ""
> "**Warning**: *You may be looking for Breaks instead of Conflicts*.\n"
> "\n"
> "This package cannot be installed together with the packages listed in the Conflicts field.  This\n"
> "is a *bigger hammer* than `Breaks` and is used sparingly.  Notably, if you want to do a versioned\n"
> "`Conflicts` then you *almost certainly* want `Breaks` instead.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Package: foo\n"
> "Conflicts: bar\n"
> "```\n"
> "\n"
> "Please see <https://wiki.debian.org/PackageTransition> for when to uses `Breaks`, `Conflicts`,\n"
> "or/and `Replaces`.\n"

   and/or

> "\n"
> "Note if a package conflicts with itself (indirectly or via `Provides`), then it is using a\n"
> "special rule for `Conflicts`.  See section\n"
> "7.6.2 \"[Replacing whole packages, forcing their removal]\" in the Debian Policy Manual for the\n"
> "details.\n"

"Note ⁁that".  (What's up with these linewraps?)

> "\n"
> "[Replacing whole packages, forcing their removal]: https://www.debian.org/doc/debian-policy/ch-relationships.html#replacing-whole-packages-forcing-their-removal\n";
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Breaks"
> msgid "Package/versions that does not work with this package"
> msgstr ""

Should that be... "Packages/versions"?  "Packages/package versions"?
"Package(-version)s"?  Whichever it is, if it counts as plural you
want "that do not work".
 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Breaks"
> msgid ""
> "This package cannot be installed together with the packages listed in the `Breaks` field.\n"
> "\n"
> "This is often use to declare versioned issues such as \"This package does not work with foo if\n"
> "it is version 1.0 or less\". In comparison, `Conflicts` is generally used to declare that\n"
> "\"This package does not work at all as long as foo is installed\".\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Breaks: bar (<= 1.0~)\n"
> "````\n"
> "\n"
> "Please see <https://wiki.debian.org/PackageTransition> for when to uses `Breaks`, `Conflicts`,\n"
> "or/and `Replaces`.\n"

  and/or

> "\n"
> "Note the use of `~` in version numbers in the example is used to ensure this works correctly in\n"
> "case of a backports (in the Debian archive), where the package is rebuilt with the `~bpo` suffix\n"
> "in its version.\n"
> msgstr ""

  "Note that the `~` in the version number in the example is used to ensure this works correctly in\n"
  "the case of a backport [...]
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Replaces"
> msgid "This package replaces content from these packages/versions"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Replaces"
> msgid ""
> "This package either replaces another package or overwrites files that used to be provided by\n"
> "another package.\n"
> "\n"
> "**Attention**: The `Replaces` field should `always` used with either `Breaks` or `Conflicts`\n"
> "field.\n"

Missing article: "with either the `Breaks` or `Conflicts` field".

> "\n"
> "**Example**:\n"
> "```\n"
> "Package: foo\n"
> "...\n"
> "\n"
> "# The foo package was split to move data files into foo-data in version 1.2-3\n"
> "Package: foo-data\n"
> "Replaces: foo (<< 1.2-3~)\n"
> "Breaks: foo (<< 1.2-3~)\n"
> "```\n"
> "\n"
> "Please see <https://wiki.debian.org/PackageTransition> for when to uses `Breaks`, `Conflicts`,\n"
> "or/and `Replaces`.\n"
> "\n"
> "Note the use of `~` in version numbers in the example is used to ensure this works correctly in\n"
> "case of a backports (in the Debian archive), where the package is rebuilt with the `~bpo` suffix\n"
> "in its version.\n"
> msgstr ""

Please see above for and/or, overuse of use, in case of emergency, and
overpluralisation.

> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Build-Profiles"
> msgid ""
> "Formula describing under which build profiles the package should be build"
> msgstr ""

Build failure.  "Should be built".  Or maybe it should be

  "Formula describing which profiles the package should be built under"

(Why do we build things *under* profiles, and *against* libraries?)

> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Build-Profiles"
> msgid ""
> "**Advanced field**. *This field covers an advanced topic. If you are new to packaging, you are*\n"
> "*advised to leave it at its default until you have a working basic package or lots of time to understand*\n"
> "*this topic.*\n"
> "\n"
> "Declare that the package will only be built when the given build-profiles are satisfied.\n"

   Declares

> "\n"
> "This field is primarily used in combination with build profiles inside the build dependency\n"
> "related fields to reduce the number of build dependencies required during bootstrapping of\n"
> "a new architecture.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Package: foo\n"
> "...\n"
> "\n"
> "Package: foo-udeb\n"
> "Package-Type: udeb\n"
> "# Skip building foo-udeb when the build profile \"noudeb\" is set (e.g., via dpkg-buildpackage -Pnoudeb)\n"
> "Build-Profiles: <!noudeb>\n"
> "```\n"
> "\n"
> "When adding or changing this field, please remember to ensure that the build instructions also match\n"
> "this formula. This is particularly important with `debhelper` or `debian/rules` where you have to\n"
> "implement part of the logic yourself. For `debputy`, this is often a matter of ensuring that all\n"
> "relevant entries in `builds:` have the proper packages listed in the `for:` attribute.\n"
> "\n"
> "Note that there is an official list of common build profiles with predefined purposes along with rules\n"
> "for how and when the can be used. This list can be found at\n"
> "<https://wiki.debian.org/BuildProfileSpec#Registered_profile_names>.\n"
> msgstr ""

Typo:  how and when the⁁y can be used.
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Section"
> msgid "Which archive section and component this package should be in"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Section"
> msgid ""
> "Define the section and component for this package.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Section: devel\n"
> "```\n"
> "\n"
> "By default, all packages are in the `main` component and then in the section denoted\n"
> "in this field. If the value contains a `/`, then the left-hand side is the component\n"
> "and the right-hand side is the section. As an example, `non-free/devel` means the\n"
> "package should be in the `non-free` component` and in the `devel` section.\n"
> "\n"
> "Explicitly listing the `main` section is redundant and is considered unnecessary by\n"
> "the Debian project.\n"
> "\n"
> "Please see <https://packages.debian.org/unstable> for more details about the sections.\n"

No, there's no python3-dunstable, you're thinking of python3-dulwich.

  "See <https://packages.debian.org/sid/> for more details about the sections.\n"

> "\n"
> "Debian Policy reference: <https://www.debian.org/doc/debian-policy/ch-archive.html#sections>\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Priority"
> msgid "The package's Priority (per Debian Policy §2.5)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Priority"
> msgid ""
> "Define the priority this package.\n"

  "Defines the priority ⁁of this package.\n"

> "\n"
> "The priority field describes how important the package is for the functionality of the system.\n"
> "Unless you know you need a different value, you should choose `optional` for your packages.\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Priority: optional\n"
> "```\n"
> "\n"
> "The priority is primarily used by the Debian Installer for installing smaller variants of\n"
> "Debian.\n"
> "\n"
> "Debian Policy reference: <https://www.debian.org/doc/debian-policy/ch-archive.html#priorities>\n"
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "required" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Priority"
> msgid ""
> "Package is de facto Essential or an Essential package needs it (and is not a"
> " library)"
> msgstr ""

Wait, haven't I been here before?  Am I going to be reviewing this
file forever?  Ah, no, right, this is the *Package* version, not the
*Source* version.  But yes, ditto ditto ditto ditto ditto.
 
> #. [Hover Doc] Extended description for the value "required" [Markdown]. Shown
> #. in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Priority"
> msgid ""
> "The package is necessary for the proper functioning of the system (read: dpkg needs it).\n"
> "\n"
> "Applicable if dpkg *needs* this package to function and it is not a library.\n"
> "\n"
> "No two packages that both have a priority of *standard* or higher may conflict with\n"
> "each other.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "important" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Priority"
> msgid "Bare minimum of commonly-expected and necessary tools"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "important" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Priority"
> msgid ""
> "The *important* packages are a bare minimum of commonly-expected and necessary tools.\n"
> "\n"
> "Applicable if 99% of all users in the distribution needs this package and it is not a library.\n"
> "\n"
> "No two packages that both have a priority of *standard* or higher may conflict with\n"
> "each other.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "standard" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Priority"
> msgid ""
> "The distribution installer should install this by default (not for "
> "libraries)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "standard" [Markdown]. Shown
> #. in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Priority"
> msgid ""
> "These packages provide a reasonable small but not too limited character-mode system.  This is\n"
> "what will be installed by default (by the debian-installer) if the user does not select anything\n"
> "else.  This does not include many large applications.\n"
> "\n"
> "Applicable if your distribution installer will install this package by default on a new system\n"
> "and it is not a library.\n"
> "\n"
> "No two packages that both have a priority of *standard* or higher may conflict with\n"
> "each other.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "optional" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Priority"
> msgid "The default priority"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "optional" [Markdown]. Shown
> #. in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Priority"
> msgid ""
> "This is the default priority and used by the majority of all packages in the Debian archive.\n"
> "\n"
> "It is used for most packages and means that the debian-installer should not directly install it\n"
> "by default on a system (it may still be pulled in as a dependency when relevant).\n"
> "\n"
> "All native shared libraries should have `optional` as their priority with a handful of exceptions\n"
> "like the libc library.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "extra" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Priority"
> msgid "Obsolete alias of optional"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "extra" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Priority"
> msgid ""
> "This priority was historically different from `optional`. However, the distinction in semantics\n"
> "between `extra` and `optional` turned out to be unnecessary bookkeeping and the two values were\n"
> "merged into `optional`.\n"
> "\n"
> "Any use of `extra` should unconditionally be replaced by `optional`.\n"
> msgstr ""

Ditto ditto ditto up to here.
 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid "Advanced field: How this package interacts with multi arch"
> msgstr ""

There's no agreement about whether multiarch has a hyphen, but it's
never two words.
 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid ""
> "**Advanced field**. *This field covers an advanced topic. If you are new to packaging, you are*\n"
> "*advised to leave it at its default until you have a working basic package or lots of time to understand*\n"
> "*this topic.*\n"
> "\n"
> "This field is used to declare the Multi-Arch interface of the package.\n"
> "\n"
> "The `Multi-Arch` field is used to inform the installation system (APT and dpkg) about how it should handle\n"
> "dependency relations involving this package and foreign architectures. This is useful for multiple purposes\n"
> "such as cross-building without emulation and installing 32-bit packages on a 64-bit system. The latter is\n"
> "often done to use legacy apps or old games that was never ported to 64-bit machines.\n"

One problem here, our old friend number agreement: were never ported.

> "\n"
> "**Example**:\n"
> "```\n"
> "Multi-Arch: foreign\n"
> "```\n"
> "\n"
> "The rules for `Multi-Arch` can be quite complicated, but in many cases the following simple rules of thumb\n"
> "gets you a long way:\n"

   get

Speaking of rules of thumb, the rule of thumb for number agreement is
that English likes to keep its -s endings evenly distributed.
Singular subjects take -s on the verb not the verb, plural ones take
-s on the noun not the verb.

> "\n"
> " * If the [Multi-Arch hinter] comes with a hint, then it almost certainly correct. You are recommended\n"
> "   to check the hint for further details (some changes can be complicated to do).  Note that the\n"
> "   Multi-Arch hinter is only run for official Debian packages and may not be applicable to your case.\n"
> "\n"

Does "comes with" here mean "comes up with"?  I'd suggest

  " * If the [Multi-Arch hinter] offers a hint, then it is almost certainly correct. You are recommended\n"

> " * If you have an `Architecture: all` data-only package, then it often want to be `Multi-Arch: foreign`\n"

Number: wants.

> "\n"
> " * If you have an architecture dependent package, where everything is installed in\n"
> "   `/usr/lib/${DEB_HOST_MULTIARCH}` (plus a bit of standard documentation in `/usr/share/doc`), then\n"
> "   you *probably* want `Multi-Arch: same`. Note that when using `debputy` as the build helper, `debputy`\n"
> "   will automatically detect the most common variants of this case and sets the field for you when\n"
> "    relevant.\n"

If that's "debputy will detect foo and will set bar" then you need the
infinitive: "and set the field for you".

> "\n"
> " * If none of the above applies, then omit the field unless you know what you are doing or you are\n"
> "   receiving advice from a Multi-Arch expert.\n"
> "\n"
> "\n"
> "There are 4 possible values for the Multi-Arch field, though not all values are applicable to all\n"
> "packages:\n"
> "\n"
> "  * `no` - The default. The package can be installed for at most one architecture at the time.  It can\n"
> "    *only* satisfy relations for the same architecture as itself. Note that `Architecture: all` packages\n"
> "    are considered as a part of the system's \"primary\" architecture (see output of\n"
> "    `dpkg --print-architecture`).\n"

Here and below, s/at the time/at a time/, but see pedantry above about
how *any* package can be installed on (for instance) both amd64 and
sh4 simultaneously - what we mean to say here is that any given
*build* can only be used on one particular architecture.

  "  * `no` - The default. A given build of this package can only be installed on one particular architecture.\n"

> "\n"
> "    Use of an explicit `no` over omitting the field is commonly done to signal that someone took the\n"
> "    effort to understand the situation and concluded `no` was the right answer.\n"

  "    Using an explicit `no` instead of omitting the field is commonly done to signal that someone took the\n"

> "\n"
> "    Note: Despite the `no`, the package *can* be installed for a foreign architecture (e.g. you can\n"
> "    install a 32-bit version of a package on a 64-bit system).  However, packages depending on it must\n"
> "    also be installed for the foreign architecture.\n"
> "\n"
> "  * `foreign` - The package can be installed for at most one architecture at the time.  However, it can\n"

  "  * `foreign` - A given build of this package can only be installed on one particular architecture."

> "    satisfy relations for packages regardless of their architecture.  This is often useful for packages\n"
> "    solely providing data or binaries that have \"Multi-Arch neutral interfaces\". Sadly, describing\n"
> "    a \"Multi-Arch neutral interface\" is hard and often only done by Multi-Arch experts on a case-by-case\n"
> "    basis. Among other, scripts despite being the same on all architectures can still have a\n"

              Among other things
or perhaps you really want
              For instance,

> "    \"non-neutral Multi-Arch\" interface if their output is architecture dependent or if their dependencies\n"
> "    force them out of the `foreign` role. The dependency issue usually happens when depending indirectly\n"
> "    on an `Multi-Arch: allowed` package.\n"
> "\n"
> "    Some programs have \"Multi-Arch dependent interfaces\" and are not safe to declare as\n"
> "    `Multi-Arch: foreign`. The name `foreign` refers to the fact that the package can satisfy relations\n"
> "    for native *and foreign* architectures at the same time.\n"
> "\n"
> "  * `same` - The same version of the package can be co-installed for multiple architecture. However,\n"

No, sorry, I give up.  I thought I understood what this was saying,
but then I can't see how "co-installed" fits in.  If it's one single
version of one binary package that works for multiple architectures,
what does it mean to talk about it being "co-installed"?  What *with*?

I can at least diagnose a number error: you want "multiple
architectures".

> "    for this to work, the package **must** ship all files in architecture unique paths (usually\n"
> "    beneath `/usr/lib/${DEB_HOST_MULTIARCH}`) **or** have bit-for-bit identical content in files\n"
> "    that are in non-architecture unique paths (e.g. `/usr/share/doc`). Note that these packages\n"
> "    typically do not contain configuration files or `dpkg` `conffile`s.\n"
> "\n"
> "    The name `same` refers to the fact that the package can satisfy relations only for the \"same\"\n"
> "    architecture as itself.  However, in this case, it is co-installable with itself as noted above.\n"

This makes no sense to me.

> "\n"
> "    Note: This value **cannot** be used with `Architecture: all`.\n"
> "\n"
> "  * `allowed` - **Advanced value**. This value is for a complex use-case that most people do not\n"
> "    need. Consider it only if none of the other values seem to do the trick.\n"
> "\n"
> "    The package is **NOT** co-installable with itself but can satisfy Multi-Arch `foreign` and Multi-Arch\n"
> "    `same` relations at the same. This is useful for implementations of scripting languages\n"
> "    (e.g. Perl or Python). Here the interpreter contextually need to satisfy some relations as\n"
> "    `Multi-Arch: foreign` and others as `Multi-Arch: same` (or `Multi-Arch: no`).\n"

I think that's "needs to satisfy", but if this is more complicated
than "same", I don't understand it and can't review it.

> "\n"
> "    Typically, native extensions or plugins will need a `Multi-Arch: same`-relation as they only work with\n"
> "    the interpreter compiled for the same machine architecture as themselves whereas scripts are usually\n"
> "    less picky and can rely on the `Multi-Arch: foreign` relation.  Packages wanting to rely on the\n"
> "    `Multi-Arch: foreign` interface must explicitly declare this adding a `:any` suffix to the package\n"
> "    name in the dependency relation (such as `Depends: python3:any`).  However, the `:any` suffix cannot\n"
> "    be used unconditionally and should not be used unless you know you need it.\n"

Should there be a "by" in "declare this by adding"?

*Advanced question*: and should "a `:any` suffix" be "an `:any`
suffix"?

> "\n"
> "    Note that depending indirectly on a `Multi-Arch: allowed` package can require a `Architecture: all` +\n"
> "    `Multi-Arch: foreign` package to be converted to a `Architecture: any` package. This case is named\n"
> "    the \"Multi-Arch interpreter problem\", since it is commonly seen with script interpreters. However,\n"
> "    despite the name, it can happen to any kind of package. The bug [Debian#984701] is an example of\n"
> "    this happen in practice.\n"

I'm fairly sure it's "a⁁n `Architecture: ..." (repeatedly).  Plus:

  "    this happening in practice.\n"

> "\n"
> "[Multi-Arch hinter]: https://wiki.debian.org/MultiArch/Hints\n";
> "[Debian#984701]: https://bugs.debian.org/984701\n";
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "same" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid ""
> "Co-installable with itself for different architectures (common for native "
> "libraries)"
> msgstr ""

I've bounced off "native libraries" before, and in this context I have
little hope that I'll guess what it means.

> #. [Hover Doc] Extended description for the value "same" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid ""
> "The exact same version of the package can be co-installed for multiple architecture. However,\n"

Same old same old.  Oh, except that this version is even more
insistent that the things that can be installed together are exactly
one thing.  On multiple but unpluralised architecture.

> "for this to work, the package *must* ship all files in architecture unique paths (usually\n"
> "beneath `/usr/lib/<DEB_HOST_MULTIARCH>`) or have bit-for-bit identical content\n"
> "in files that are in non-architecture unique paths (such as files beneath `/usr/share/doc`).\n"
> "\n"
> "The name `same` refers to the fact that the package can satisfy relations only for the `same`\n"
> "architecture as itself.  However, in this case, it is co-installable with itself as noted above.\n"
> "Note: This value **cannot** be used with `Architecture: all`.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description for the value "no" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid ""
> "No Multi-Arch support (often used for \"reviewed and no support "
> "possible/needed\")"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "no" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid ""
> "The default. The package can be installed for at most one architecture at the time.  It can\n"
> "*only* satisfy relations for the same architecture as itself. Note that `Architecture: all`\n"
> "packages are considered as a part of the system's \"primary\" architecture (see output of\n"
> "`dpkg --print-architecture`).\n"
> "\n"
> "Note: Despite the `no`, the package *can* be installed for a foreign architecture (as an example,\n"
> "you can install a 32-bit version of a package on a 64-bit system).  However, packages depending\n"
> "on it must also be installed for the foreign architecture.\n"
> msgstr ""

Perhaps this needs the same fixes as above.  Perhaps I need to give up
reviewing this and get some sleep - I am after all very near the
halfway point.

> #. [Synopsis] One-line description for the value "foreign" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid ""
> "Can satisfy dependencies for other architectures (common for data and some "
> "scripts)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the value "foreign" [Markdown]. Shown
> #. in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid ""
> "The package can be installed for at most one architecture at the time.  However, it can\n"
> "satisfy relations for packages regardless of their architecture.  This is often useful for packages\n"
> "solely providing data or binaries that have \"Multi-Arch neutral interfaces\".\n"
> "\n"
> "Sadly, describing a \"Multi-Arch neutral interface\" is hard and often only done by Multi-Arch\n"
> "experts on a case-by-case basis.  Some programs and scripts have \"Multi-Arch dependent interfaces\"\n"
> "and are not safe to declare as `Multi-Arch: foreign`.\n"
> "\n"
> "The name \"foreign\" refers to the fact that the package can satisfy relations for native\n"
> "*and foreign* architectures at the same time.\n"
> msgstr ""

As above, or before, or somewhere.
 
> #. [Synopsis] One-line description for the value "allowed" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid "Consumer decides whether it is same and foreign"
> msgstr ""

Same *and* foreign?  I'm not even going to *try* to understand.

> #. [Hover Doc] Extended description for the value "allowed" [Markdown]. Shown
> #. in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Multi-Arch"
> msgid ""
> "**Advanced and very rare value**. This value is exceedingly rare to the point that less\n"
> "than 0.40% of all packages in Debian used in it (May 2024). It is even rarer for for\n"

                                        use it (as of May 2024).

Is that an excess "for" or should it be "rarer than"?

> "`Architecture: all` packages, where the number an order of magnitude smaller. Unless\n"
                                                ⁁is 

> "a Multi-Arch expert or the Multi-Arch hinter suggested that you use this value, for\n"
> "this package, then probably it is not the right choice.\n"
> "\n"
> "The value means that the package is *not* co-installable with itself but can satisfy Multi-Arch\n"
> "`foreign` and Multi-Arch `same` relations at the same time.  This is useful for implementations of\n"
> "scripting languages (such as Perl or Python).  Here the interpreter contextually need to\n"

Number agreement: "needs".

> "satisfy some relations as `Multi-Arch: foreign` and others as `Multi-Arch: same`.\n"
> "\n"
> "Typically, native extensions or plugins will need a `Multi-Arch: same`-relation as they only\n"
> "work with the interpreter compiled for the same machine architecture as themselves whereas\n"
> "scripts are usually less picky and can rely on the `Multi-Arch: foreign` relation.  Packages\n"
> "wanting to rely on the \"Multi-Arch: foreign\" interface must explicitly declare this adding a\n"

Missing "by", and should that be "an"?

> "`:any` suffix to the package name in the dependency relation (e.g. `Depends: python3:any`).\n"
> "However, the `:any\"`suffix cannot be used unconditionally and should not be used unless you\n"
> "know you need it.\n"
> msgstr ""
> 
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:XB-Installer-Menu-Item"
> msgid "Package's order in the debian-installer menu (udeb-only)"
> msgstr ""
> 
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:XB-Installer-Menu-Item"
> msgid ""
> "This field is only relevant for `udeb` packages (debian-installer).\n"
> "\n"
> "The field is used to declare where in the installer menu this package's menu item should\n"
> "be placed (assuming it has any menu item). For packages targeting the Debian archive,\n"
> "any new package should have its menu item number aligned with the debian-installer team\n"
> "before upload.\n"
> "\n"
> "A menu item is 4-5 digits (In the range `1000 <= X <= 99999`). In rare cases, the menu\n"
> "item can be architecture dependent. For architecture dependent menu item values, use a\n"
> "custom substvar.\n"
> "\n"
> "See <https://d-i.debian.org/doc/internals/apa.html> for the full list of menu item ranges\n"
> "and for how to request a number.\n"
> msgstr ""

There!  By my reckoning this is the halfway point, so it seems like a
good place to call it a day.
-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
Reply to:
References:
- Review of debputy editor provided docs for packagers
  - From: Niels Thykier <niels@thykier.net>
- Re: Review of debputy editor provided docs for packagers
  - From: Niels Thykier <niels@thykier.net>
Prev by Date: Re: Review of debputy editor provided docs for packagers
Next by Date: Re: Review of debputy editor provided docs for packagers
Previous by thread: Re: Review of debputy editor provided docs for packagers
Next by thread: Re: Review of debputy editor provided docs for packagers
Index(es):
- Date
- Thread