Re: Review of debputy editor provided docs for packagers
And now, the second half. I ought to be able to come up with a proper
revised version tomorrow, then I'll look at the README file.
> #. [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:X-DH-Build-For-Type"
> msgid "For cross-compiling cross-compilers"
> 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:X-DH-Build-For-Type"
> msgid ""
> "**Special-purpose only**. *This field is a special purpose field and is rarely needed.*\n"
> "*You are recommended to omit unless you know you need it or someone told you to use it.*\n"
Omit needs an object, and "you are recommended to omit" is stilted
anyway - I'd suggest just "Leave it out unless..."
(This loses the fact that it's at the "RECOMMENDED" level of official
advice, but that hardly matters when the rest of the sentence itemises
the circumstances under which the advice doesn't apply.)
> "\n"
> "This field is used when building a cross-compiling C-compiler (or similar cases), some packages need\n"
> "to be build for target (DEB_**TARGET**_ARCH) rather than the host (DEB_**HOST**_ARCH) architecture.\n"
> "\n"
Comma splice, build error, and I think a missing article.
"This field is used when building a cross-compiling C-compiler (or similar cases). Some packages need\n"
"to be built for the target (DEB_**TARGET**_ARCH) rather than the host (DEB_**HOST**_ARCH) architecture.\n"
> "**Example**:\n"
> "```\n"
> "Package: gcc\n"
> "Architecture: any\n"
> "# ...\n"
> "\n"
> "Package: libgcc-s1\n"
> "Architecture: any\n"
> "# When building a cross-compiling gcc, then this library needs to be built for the target architecture\n"
> "# as binaries compiled by gcc will link with this library.\n"
"When... then" doesn't work in English; drop "then".
> "X-DH-Build-For-Type: target\n"
> "# ...\n"
> "```\n"
> "\n"
> "If you are in doubt, then you probably do **not** need this field.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "host" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:X-DH-Build-For-Type"
> msgid "The package should be compiled for `DEB_HOST_ARCH`"
> msgstr ""
Wait, why is this getting Markdown backticks when it's plain text?
(By the way, plaintext doesn't mean the same thing as plain text; it
means "the unencrypted copy", as opposed to "ciphertext". Markdown
can be plaintext. But I suspect I can't fix this.)
> #. [Hover Doc] Extended description for the value "host" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:X-DH-Build-For-Type"
> msgid ""
> "The package should be compiled for `DEB_HOST_ARCH`, which is the default "
> "behavior.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "target" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:X-DH-Build-For-Type"
> msgid "The package should be compiled for DEB_TARGET_ARCH"
> msgstr ""
(No backticks this time.)
> #. [Hover Doc] Extended description for the value "target" [Markdown]. Shown
> #. in hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:X-DH-Build-For-Type"
> msgid ""
> "The package should be compiled for `DEB_TARGET_ARCH`.\n"
> "\n"
> "For steps that look at the values from `dpkg-architecture` **and** that are specific to this\n"
> "package, the `DEB_TARGET_` variants are used instead of the `DEB_HOST_` variants. In `debhelper`,\n"
> "that usually affects `dh_makeshlibs` and `dh_shlibdeps`. In `debputy`, it affects the parts of the\n"
> "manifest that are run a package specific context, such as the parts beneath the `packages`\n"
> "root-level keyword.\n"
I suspect you want "this" rather than "that", and there seems to be a
missing word...
"this usually affects `dh_makeshlibs` and `dh_shlibdeps`. In `debputy`, it affects the parts of the\n"
"manifest that are run in a package specific context, such as the parts beneath the `packages`\n"
> "\n"
> "This value is exceedingly rare to the point where if you do not know you need it,\n"
> "then you are not looking for this value (nor the field in general).\n"
> msgstr ""
"Nor" is a bit like that too - I'd just use "or" 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:X-Time64-Compat"
> msgid "(Special purpose) Compat name for time64_t transition"
> 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:X-Time64-Compat"
> msgid ""
> "Special purpose field related to the 64-bit time transition.\n"
> "\n"
> "It is used to inform packaging helpers what the original (non-transitioned) package name\n"
> "was when the auto-detection is inadequate. The non-transitioned package name is then\n"
> "conditionally provided in the `${t64:Provides}` substitution variable.\n"
> "\n"
> "The field only works for architecture dependent packages.\n"
> msgstr ""
All looks fine.
> #. [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:Description"
> msgid "Package synopsis and description"
> 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:Description"
> msgid ""
> "A human-readable description of the package. This field consists of two related but distinct parts.\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 the package. The lines after the *Synopsis* is known\n"
> "as the *Extended Description* and is intended as a longer summary of the package.\n"
> "\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"
This looks familiar. Ah yes, "Stanza:Source|Field:Description". So a
number error (the lines after the synopsis ARE), but otherwise okay.
> "\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"
> "\n"
> "Note: The synopsis part has its own hover doc that is specialized at aiding with writing and checking\n"
> "the synopsis.\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-Cnf-Visible-Pkgname"
> msgid "(Special purpose) Hint for command-not-found 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:XB-Cnf-Visible-Pkgname"
> msgid ""
> "**Special-case field**: *This field is only useful in very special circumstances.*\n"
> "*Consider whether you truly need it before adding this field.*\n"
> "\n"
> "This field is used by `command-not-found` and can be used to override which package\n"
> "`command-not-found` should propose the user to install.\n"
> "\n"
You can't "propose" somebody. Plain old "tell" works, though:
"`command-not-found` should tell the user to install.\n"
Oh, and then the same again for "suggest":
> "Normally, when `command-not-found` detects a missing command, it will suggest the\n"
> "user to install the package name listed in the `Package` field. In most cases, this\n"
We could use the same fix, but why not just leave out the mention of
the user?
"Normally, when `command-not-found` detects a missing command, it will suggest\n"
"installing the package name listed in the `Package` field. In most cases, this\n"
> "is what you want. However, in certain special-cases, the binary is provided by a\n"
> "minimal package for technical reasons (like `python3-minimal`) and the user should\n"
> "really install a package that provides more features (such as `python3` to follow\n"
> "the example).\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Package: python3-minimal\n"
> "XB-Cnf-Visible-Pkgname: python3\n"
> "```\n"
> "\n"
> "Related bug: <https://bugs.launchpad.net/ubuntu/+source/python-defaults/+bug/1867157>\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:X-DhRuby-Root"
> msgid "Obsolete (no documentation)"
> 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:X-DhRuby-Root"
> msgid ""
> "No documentation available for its original purpose.\n"
> "\n"
> "Obsolete according to https://bugs.debian.org/1075762\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-Type"
> msgid "Non-standard package type (such as udeb)"
> 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:Package-Type"
> msgid ""
> "**Special-purpose only**. *This field is a special purpose field and is rarely needed.*\n"
> "*You are recommended to omit unless you know you need it or someone told you to use it.*\n"
Again s/You are recommended to omit/Leave it out/
> "\n"
> "Determines the type of package. This field can be used to declare that a given package is a different\n"
> "type of package than usual. The primary case where this is known to be useful is for building\n"
> "micro-debs (`udeb`) to be consumed by the debian-installer.\n"
> msgstr ""
There's some debate about "different than", but at least it's more
widely accepted than "different to". I'd almost always use "different
from", myself, but then I'd want to rephrase things. Oh, wait, I do
want to edit this slightly, but only the last phrase: it's either "by
the Debian installer", if it's normal English descriptive words, or
"by debian-installer", if we're thinking of it as the name of a piece
of software. Mind you, usage here is wildly inconsistent; some
sources think it's called DebianInstaller, or Debian Installer, or
Debian-Installer, or d-i (but almost never D-I). It has never needed
to standardise since after all nobody ever invokes it by name.
> #. [Synopsis] One-line description for the value "deb" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Package-Type"
> msgid "The package is a regular deb."
> msgstr ""
>
> #. [Synopsis] One-line description for the value "udeb" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Package-Type"
> msgid ""
> "The package is a udeb (only packages required by the the debian-installer)"
> msgstr ""
s/the d-i/d-i/
> #. [Hover Doc] Extended description for the value "udeb" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Package-Type"
> msgid ""
> "The package is a micro-deb (also known as a `udeb`).\n"
Good thing you didn't say that the other way round, because it
isn't really true to claim (as d-i.debian.org does) that udebs are
ever "also known as micro-debs". In fact it's so rare that the second
hit I get on that word from a search engine (after d-i.debian.org) is
a page offering Micro(soft Edge as a) .deb!
> "\n"
> "These are solely used by the debian-installer for the purpose of running the installer\n"
> "itself. There is no need to produce `udeb` unless the Debian Installer team specifically\n"
> "asked for it or you know you need it.\n"
> msgstr ""
I wouldn't say d-i uses udebs to execute d-i; it uses udebs to do its
work of installing Debian.
"These are used solely by debian-installer as part of the process of installing Debian.\n"
"There is no need to produce a `udeb` unless the Debian Installer team specifically\n"
"asked for it or you know you need it.\n"
You'd think we'd say "Debian Installer Team", but we only ever seem to
do that with a small number of team names (such as DPT for Python...
you'd think that would be a contested namespace).
> #. [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:Essential"
> msgid "Whether the package is Essential (per Debian Policy §3.8)"
> 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:Essential"
> msgid ""
> "**Special-purpose only**. *This field is a special purpose field and is rarely needed.*\n"
> "*You are recommended to omit unless you know you need it or someone told you to use it.*\n"
> "\n"
Leave it out.
> "Whether the package should be considered Essential as defined by Debian Policy.\n"
> "\n"
> "Essential packages are subject to several distinct but very important rules:\n"
Oh, yes, that last one was Required, now we get to open the same can
of worms again from the other end, which turns out to be much safer.
Why are the rules distinct *but* important? Why do we need to say
"several distinct rules" at all, as if ordinary rules blurred into one
another?
"Essential packages are subject to several very important rules:\n"
> "\n"
> " * Essential packages are considered essential for the system to work. The packaging system\n"
> " (APT and dpkg) will refuse to uninstall it without some very insisting force options and warnings.\n"
> "\n"
"It" there suddenly switches to treating them individually, and
"insisting" should probably be "insistent".
" (APT and dpkg) will refuse to uninstall them without some very insistent force options and warnings.\n"
Or perhaps the warnings should go first?
" (APT and dpkg) will warn and refuse to uninstall them without some very insistent force options.\n"
> " * Other packages are not required to declare explicit dependencies on essential packages as a\n"
> " side-effect of the above except as to ensure that the given essential package is upgraded\n"
> " to a given minimum version.\n"
Surplus "as" (or perhaps make it "as needed"?)
> "\n"
> " * Once installed, essential packages must function at all times no matter where dpkg is in its\n"
> " installation or upgrade process. During bootstrapping or installation, this requirement is\n"
> " relaxed.\n"
> "\n"
> "Note if you are looking for a way to prevent accidental uninstallation, please consider using\n"
> "`Protected: yes` instead.\n"
This does feel like a case where you're entitled to label it as a
note, but it still needs either a colon or "that".
> "\n"
> "Policy reference: <https://www.debian.org/doc/debian-policy/ch-binary.html#essential-packages>\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "yes" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Essential"
> msgid "The package is essential as defined by Debian Policy"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "yes" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Essential"
> msgid ""
> "The package is an essential package as defined by the Debian Policy. The following\n"
> "rules applies to it:\n"
Debian Policy is the name of the document, and names don't need
articles. Then "rules" (plural) "apply".
> "\n"
> " * Essential packages are considered essential for the system to work. The packaging system\n"
> " (APT and dpkg) will refuse to uninstall it without some very insisting force options and warnings.\n"
> "\n"
As above.
> " * Other packages are not required to declare explicit dependencies on essential packages as a\n"
> " side-effect of the above except as to ensure that the given essential package is upgraded\n"
> " to a given minimum version.\n"
> "\n"
As above.
> " * Once installed, essential packages must function at all times no matter where dpkg is in its\n"
> " installation or upgrade process. During bootstrapping or installation, this requirement is\n"
> " relaxed.\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:Essential"
> msgid "The package is a regular package."
> 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:Essential"
> msgid ""
> "The package is a regular package. This is the default and recommended.\n"
> "\n"
> "Note that declaring a package to be `Essential: no` is the same as not having the field\n"
> "except omitting the field wastes fewer bytes on everyone's hard disk.\n"
> msgstr ""
To balance my added bytes I'll drop a repetition.
"Note that declaring a package to be `Essential: no` is the same as not having the field,\n"
"except that omitting it wastes fewer bytes on everyone's hard disks.\n"
(It may be illogical, but one each usually means plural in English.)
> #. [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-Important"
> msgid "Obsolete and incomplete variant of the Protected 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:Package|Field:XB-Important"
> msgid ""
> "This is the prototype field that lead to `Protected`, which should be used instead.\n"
> "\n"
> "It makes `apt` (but not `dpkg`) require extra confirmation before removing the package.\n"
> msgstr ""
English spelling catches you out by spelling this one sanely: "led".
Since we mean the infrastructure also used by aptitude we might in
theory want to say APT rather than `apt`, but maybe that would just
confuse people.
> #. [Synopsis] One-line description for the value "yes" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:XB-Important"
> msgid "Prevent trivial uninstallation of the package"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "yes" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:XB-Important"
> msgid ""
> "The package is protected and attempts to uninstall it will cause strong warnings to the\n"
> "user that they might be breaking the system.\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:XB-Important"
> msgid "Standard uninstallation rules"
> 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:XB-Important"
> msgid ""
> "The package is a regular package. This is the default and recommended.\n"
> "\n"
> "Note that declaring a package to be `XB-Important: no` is the same as not having the field\n"
> "except omitting the field wastes fewer bytes on everyone's hard disk.\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:Package|Field:Protected"
> msgid "Mark as Protected (uninstall protection)"
> 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:Protected"
> msgid ""
> "Declare this package as a potential system critical package. When set to `yes`, both `apt`\n"
> "and `dpkg` will assume that removing the package *may* break the system. As a consequence,\n"
> "they will require extra confirmation (or \"force\" options) before removing the package.\n"
> "\n"
I don't see what "potential" is doing in there - if it's trying to say
that a developer might potentially set the flag to "yes", it doesn't
work. Just leave it out.
Super-pedantically, "When set to `yes`" is a dangling modifier,
implying that it's apt and dpkg that are set to yes, but never mind.
> "This field basically provides a \"uninstall\" protection similar to that of `Essential` packages\n"
> "without the other benefits and requirements that comes with `Essential` packages. In Debian\n"
> "context, this field is generally applicable to packages like bootloaders, kernels, and other\n"
> "packages that might be necessary for booting the system.\n"
> msgstr ""
If you're going to use an indefinite article, it's a⁁n uninstall
protection, but protection is a non-count noun anyway, so just leave
it out. Benefits and requirements are plural, so "come". Rehouse the
article in "in ⁁a Debian context".
Wait, which bootloader/kernel packages are or might be "Protected"?
The only packages I see with this flag are libcrypt and libgcc-s1, at
least on stable...
> #. [Synopsis] One-line description for the value "yes" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> msgctxt "Stanza:Package|Field:Protected"
> msgid "Prevent trivial uninstallation of the package"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "yes" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Package|Field:Protected"
> msgid ""
> "The package is protected and attempts to uninstall it will cause strong warnings to the\n"
> "user that they might be breaking the system.\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:Protected"
> msgid "Standard uninstallation rules"
> 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:Protected"
> msgid ""
> "The package is a regular package. This is the default and recommended.\n"
> "\n"
> "Note that declaring a package to be `Protected: no` is the same as not having the field\n"
> "except omitting the field wastes fewer bytes on everyone's hard disk.\n"
> msgstr ""
As above ("except that... disks")
> #. [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:Homepage"
> msgid "(Special purpose) Upstream homepage URL for this binary 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:Homepage"
> msgid ""
> "Link to the upstream homepage for this binary package.\n"
> "\n"
> "This field is rarely used in Package stanzas as most binary packages should have the\n"
> "same homepage as the source package. Though, in the exceptional case where a particular\n"
> "binary package should have a more specific homepage than the source package, you can\n"
> "use this field to override the source package field.\n"
> msgstr ""
What did I recommend last time as a replacement for "Though,"? Oh, I
didn't give an alternative. I suppose there's "However,"...
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:Format"
> msgid "Declare the file uses the DEP-5 specification and which version"
> msgstr ""
msgid "Declares that the file uses the DEP-5 specification, and which version"
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:Format"
> msgid ""
> "URI of the format specification. The field that should be used for the current version of this\n"
> "document is:\n"
> "\n"
> "**Example**:\n"
> "```\n"
> "Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/\n";
> "```\n"
> "\n"
> "The original version of this specification used the non-https version of this URL as its URI, namely:\n"
> "\n"
> "```\n"
> "Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/\n";
> "```\n"
> "\n"
> "Both versions are valid and refer to the same specification, and parsers should interpret both as\n"
> "referencing the same format. The https URI is preferred.\n"
> "\n"
> "The value must be on a single line (that is, on same line as the field).\n"
Missing article: "on ⁁the same line".
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:Upstream-Name"
> msgid "The name upstream uses for the software"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:Upstream-Name"
> msgid ""
> "The name upstream uses for the software\n"
> "\n"
> "The value must be on a single line (that is, on same line as the field).\n"
> msgstr ""
As above. I hope upstreams don't start giving things names with
embedded newlines.
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:Upstream-Contact"
> msgid "Preferred contact points for the upstream project"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:Upstream-Contact"
> msgid ""
> "The preferred address(es) to reach the upstream project. May be free-form text, but by convention will\n"
> "usually be written as a list of email addresses (RFC5322 format) or URIs.\n"
> "\n"
> "The value should be written as a line-based list (one value per line).\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:Source"
> msgid "Origin of the upstream source (Debian Policy §12.5)"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:Source"
> msgid ""
> "An explanation of where the upstream source came from. Typically this would be a URL, but it might be\n"
> "a free-form explanation. The [Debian Policy section 12.5] requires this information unless there are\n"
> "no upstream sources, which is mainly the case for native Debian packages. If the upstream source has\n"
> "been modified to remove non-free parts, that should be explained in this field.\n"
You might argue for an article with "the Debian Policy", but there
certainly isn't one for "Debian Policy section 12.5".
> "\n"
> "The value should be written as \"Formatted text\" without no synopsis (when it is a free-form explanation).\n"
> "The \"Formatted text\" is similar to the extended description (the `Description` from `debian/control`).\n"
> "\n"
> "[Debian Policy section 12.5]: https://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile\n";
> msgstr ""
That reference to "Formatted text" with caps and quotes is bizarre.
Then "without no" ain't nohow standard English, and the parenthetical
phrase is oddly placed as if it was a caveat on the no-synopsis part.
I think it should be something like:
"When it is a free-form explanation, the value should be written in the same text format as defined\n"
"for a package's extended description (the `Description` from `debian/control` with no synopsis).\n"
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:Disclaimer"
> msgid ""
> "Disclaimer related to the package not being part of Debian main (Debian "
> "Policy §12.5)"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:Disclaimer"
> msgid ""
> "For `non-free`, `non-free-firmware` or `contrib` packages, this field is used to state that they are\n"
> "not part of Debian and to explain why (see [Debian Policy section 12.5])\n"
> "\n"
> "The value should be written as \"Formatted text\" without no synopsis. The \"Formatted text\" is similar\n"
> "to the extended description (the `Description` from `debian/control`).\n"
> "\n"
> "[Debian Policy section 12.5]: https://www.debian.org/doc/debian-policy/ch-docs#s-copyrightfile\n";
> msgstr ""
As above.
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:Comment"
> 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_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:Comment"
> msgid ""
> "Comment field to optionally provide additional information. For example, it might quote an e-mail from\n"
> "upstream justifying why the combined license is acceptable to the `main` archive, or an explanation of\n"
> "how this version of the package has been forked from a version known to be [DFSG]-free, even though the\n"
> "current upstream version is not.\n"
> "\n"
I'm not going to let you get away with using "email" to mean an
address AND "e-mail" to mean a message... It would be too pedantic to
say "Name and email address of the maintainer", so maybe you could say
"Comment field to optionally provide additional information. For example, it might quote a message from\n"
(After all, you *could* quote a letter or web forum thread.)
And I'd say "acceptable for", but I'm not sure it matters.
> "Note if the `Comment` is only applicable to a set of files or a particular license out of many,\n"
> "the `Comment` field should probably be moved to the relevant `Files` stanza or `License` stanza instead.\n"
> "\n"
"If the `Comment` is only applicable to one set of files or a particular license out of many,\n"
> "The value should be written as \"Formatted text\" without no synopsis. The \"Formatted text\" is similar\n"
> "to the extended description (the `Description` from `debian/control`).\n"
> "\n"
As above.
> "[DFSG]: https://www.debian.org/social_contract#guidelines\n";
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:License"
> msgid "Provide license information for the package as a whole"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:License"
> msgid ""
> "Provide license information for the package as a whole, which may be different or simplified form\n"
> "a combination of all the per-file license information.\n"
I can't follow what's happening in this sentence. Is it trying to say
something like "Provides license information for the package as a
whole, which may be in a form that is different or simplified relative
to the combination of all the per-file license information"?
Given that it goes on to explain what it can usefully do, all this
really needs to do is introduce the distinction between overall and
per-file licenses.
"Provide license information for the package as a whole, as distinct from to the per-file licenses.\n"
> "\n"
> "Using `License` in the `Header` stanza is useful when it records a notable difference or simplification\n"
> "of the other `License` fields in this files. However, it serves no purpose to provide the field for the\n"
> "sole purpose of aggregating the other `License` fields.\n"
"These files"; but then it repeats "purpose" in a vaguely
self-contradictory way... I'd suggest
"Using `License` in the `Header` stanza is useful when it records a notable difference or simplification\n"
"of the other files' `License` fields, but it is not useful when it merely aggregates those fields.\n"
> "\n"
> "The first line (the same line as the field name) should use an abbreviated license name or\n"
> "expression. The following lines can be used for the full license text. Though, to avoid repetition,\n"
> "the license text would generally be in its own `License` stanza after the `Header` stanza.\n"
> msgstr ""
s/Though/However/.
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:Copyright"
> msgid "Provide copyright statements for the package as a whole"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:Copyright"
> msgid ""
> "One or more free-form copyright statements that applies to the package as a whole.\n"
One or more counts for English grammar as plural, so "apply".
> "\n"
> "Using `Copyright` in the `Header` stanza is useful when it records a notable difference or simplification\n"
> "of the other `Copyright` fields in this files. However, it serves no purpose to provide the field for the\n"
> "sole purpose of aggregating the other `Copyright` fields.\n"
As above - that is.
"Using `Copyright` in the `Header` stanza is useful when it records a notable difference or simplification\n"
"of the other files' `Copyright` fields, but it is not useful when it merely aggregates those fields.\n"
> "\n"
> "Any formatting is permitted. Simple cases often end up effectively being one copyright holder per\n"
> "line; see the examples below for some ideas for how to structure the field to make it easier to read.\n"
> "\n"
> "If a work has no copyright holder (i.e., it is in the public domain), that information should be recorded\n"
> "here.\n"
> "\n"
> "The Copyright field collects all relevant copyright notices for the files of this stanza. Not all\n"
> "copyright notices may apply to every individual file, and years of publication for one copyright\n"
> "holder may be gathered together. For example, if file A has:\n"
> "\n"
> "```\n"
> "Copyright 2008 John Smith\n"
> "Copyright 2009 Angela Watts\n"
> "```\n"
> "\n"
> "and file B has:\n"
> "\n"
> "```\n"
> "Copyright 2010 Angela Watts\n"
> "```\n"
> "\n"
> "a single stanza may still be used for both files. The Copyright field for that stanza might be written\n"
> "as:\n"
Inexplicable use of "still" - omit.
> "\n"
> "```\n"
> "Files: A B\n"
> "Copyright:\n"
> " Copyright 2008 John Smith\n"
> " Copyright 2009, 2010 Angela Watts\n"
> "License: ...\n"
> "```\n"
> "\n"
> "The `Copyright` field may contain the original copyright statement copied exactly (including the word\n"
> "\"Copyright\"), or it may shorten the text or merge it with other copyright statements as described above,\n"
> "as long as it does not sacrifice information.\n"
> "\n"
> "Formally, the value should be written as \"Formatted text\" without no synopsis. Though, it often\n"
> "ends up resembling a line-based list. The \"Formatted text\" is similar to the extended description\n"
> "(the `Description` from `debian/control`).\n"
> msgstr ""
As above for the "without no" and so on.
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:Files-Excluded"
> msgid ""
> "Exclude files from the tarball when fetching or repacking (via `uscan` or "
> "`mk-origtargz`)"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:Files-Excluded"
> msgid ""
> "Remove the listed files from the tarball when repacking (commonly via `uscan`). This can be useful\n"
> "when the listed files are non-free but not necessary for the Debian package. In this case, the\n"
> "upstream version of the package should generally end with `~dfsg` or `+dfsg` (to mark the content\n"
> "changed due to the Debian Free Software Guidelines). The exclusion can also be useful to remove\n"
> "large files or directories that are not used by Debian or pre-built binaries. In this case, `~ds`\n"
> "or `+ds` should be added to the version instead of `~dfsg` or `+dfsg` for \"Debian Source\" to mark\n"
> "it as altered by Debian. If both reasons are used, the `~dfsg` or `+dfsg` version is used as that\n"
> "is the more important reason for the repacking.\n"
> "\n"
This needed a couple of reorderings to avoid misinterpretations, and
once I'd started I kept noticing things that needed repacking:
"Remove the listed files from the tarball when repacking (commonly via `uscan`). This can be useful\n"
"when the listed files are non-free but not necessary for the Debian package. In this case, the\n"
"upstream version of the package should generally end with `~dfsg` or `+dfsg` (to mark the content\n"
"changed due to the Debian Free Software Guidelines). The exclusion can also be useful to remove\n"
"pre-built binaries, or large files or directories that are not used by Debian. In this case, `~ds`\n"
"or `+ds` should be added to the version (to mark it as altered \"Debian Source\"). If both reasons\n"
"for repacking apply, the `~dfsg` or `+dfsg` version is used as that is the more important reason.\n"
> "**Example**:\n"
> "```\n"
> "Files-Excluded: exclude-this\n"
> " exclude-dir\n"
> " */exclude-dir\n"
> " .*\n"
> " */js/jquery.js\n"
> "```\n"
> "\n"
> "The `Files-Included` field can be used to \"re-include\" files matched by `Files-Excluded`.\n"
> "\n"
> "It is also possible to exclude files in specific \"upstream components\" for source packages\n"
> "with multiple upstream tarballs. This is done by adding a field called\n"
> "`Files-Excluded-<component>`. The `<component>` part should then match the component name\n"
> "exactly (case sensitive).\n"
> "\n"
> "The field uses the same syntax as the `Files` fields from the `Files` stanzas.\n"
> "\n"
> "Defined by: `mk-origtargz` (usually used via `uscan`)\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Header|Field:Files-Included"
> msgid ""
> "Unexclude files from the tarball when fetching or repacking (via `uscan` or "
> "`mk-origtargz`)"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Header|Field:Files-Included"
> msgid ""
> "Re-include files that were marked for exclusion by `Files-Excluded`. This can be useful for \"exclude\n"
> "everything except X\" style semantics where `Files-Excluded` has a very broad pattern and\n"
> "`Files-Included` then marks a few exceptions.\n"
> "\n"
> "It is also possible to re-include files in specific \"upstream components\" for source packages with multiple\n"
> "upstream tarballs. This is done by adding a field called `Files-Include-<component>` which is then used\n"
> "in tandem with `Files-Exclude-<component>`. The `<component>` part should then match the component name\n"
> "exactly (case sensitive).\n"
> "\n"
> "Example:\n"
> "```\n"
> "Files-Excluded: data/*\n"
> "Files-Included: data/keep-this-file.txt\n"
> "```\n"
> "\n"
> "The field uses the same syntax as the `Files` fields from the `Files` stanzas.\n"
> "\n"
> "Defined by: `mk-origtargz` (usually used via `uscan`)\n"
> msgstr ""
Well, all of that looks fine to me, and I'm halfway through this round
already.
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Files|Field:Files"
> msgid ""
> "List of files or files pattern relevant for this stanza (Makes the stanza a "
> "`Files` stanza)"
> msgstr ""
Inflecting the wrong bit of the noun pile.
"List of files or file patterns relevant for this stanza (Makes the stanza a "
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Files|Field:Files"
> msgid ""
> "Whitespace separated list of patterns indicating files covered by the license and copyright specified in\n"
> "this stanza.\n"
> "\n"
> "If multiple stanzas match the same file, then the *last* stanza is used. More general stanzas should\n"
> "therefore be given first, followed by more specific overrides. Accordingly, `Files: *` must be the\n"
> "first `Files` stanza when the `*` pattern is used.\n"
> "\n"
> "Filename patterns in the `Files` field are specified using a simplified shell glob syntax. Patterns are\n"
> "separated by whitespace.\n"
> "\n"
> " * Only the wildcards `*` and `?` apply; the former matches any number of characters (including none),\n"
> " the latter a single character. Both match slashes (`/`) and leading dots, unlike shell globs. The\n"
> " pattern `*.in` therefore matches any file whose name ends in `.in` anywhere in the source tree,\n"
> " not just at the top level.\n"
> "\n"
> " * Patterns match pathnames that start at the root of the source tree. Thus, `Makefile.in` matches only\n"
> " the file at the root of the tree, but `*/Makefile.in` matches at any depth.\n"
> "\n"
> " * The backslash (`\\`) is used to remove the magic from the next character; see below.\n"
> "\n"
> "Escape sequences:\n"
> " * `\\*` matches a single literal asterisk (`*`)\n"
> " * `\\?` matches a single literal question mark (`?`)\n"
> " * `\\\\` matches a single literal backslash (`\\`)\n"
> "\n"
(I'll assume you know what you're doing with the spacing of these
bulletpoints.)
> "Any other character following a backslash is an error.\n"
> "\n"
> "This is the same pattern syntax as [fnmatch(3)] without the FNM_PATHNAME flag, or the argument to the\n"
> "`-path` test of the GNU find command, except that `[]` wildcards are not recognized.\n"
> "\n"
> "Exclusions are only supported by adding `Files` stanzas to override the previous match:\n"
> "\n"
> "```\n"
> "Files: *\n"
> "Copyright: ...\n"
> "License: ...\n"
> " ... license that applies by default ...\n"
> "\n"
> "Files: data/*\n"
> "Copyright: ...\n"
> "License: ...\n"
> " ... license that applies to all paths in data/* ...\n"
> "\n"
> "Files: data/file-with-special-license\n"
> "Copyright: ...\n"
> "License: ...\n"
> " ... license that applies to this particular file ...\n"
> "```\n"
> "\n"
> "This syntax does not distinguish file names from directory names; a trailing slash in a pattern will\n"
> "never match any actual path. A whole directory tree may be selected with a pattern like `foo/*`.\n"
> "\n"
> "The space character, used to separate patterns, cannot be escaped with a backslash. A path like\n"
> "`foo bar` may be selected with a pattern like `foo?bar`.\n"
> "\n"
> "Adding the `Files` field to a standalone `License` stanza converts the stanza in to a `Files` stanza,\n"
> "which affects which fields are available.\n"
s/in to/into/
> "\n"
> "[fnmatch(3)]: https://manpages.debian.org/fnmatch.3\n";
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Files|Field:License"
> msgid ""
> "Provide license information for the files matched by this Files stanza."
> msgstr ""
Provides
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Files|Field:License"
> msgid ""
> "Provide license information for the files matched by this `Files` stanza.\n"
Provides
(In all these cases I'm assuming that the logic is that you're
introducing a definition of what this field "does", with an implicit
subject "this field..." The natural interpretation for "Provide" on
the other hand is that this is an instruction to the developer, which
is just plausible enough to be confusing.)
> "\n"
> "The first line is either an abbreviated name for the license or an expression giving\n"
> "alternatives.\n"
> "\n"
> "When there are additional lines, they are expected to give the fill license terms for\n"
> "the files matched or a pointer to `/usr/share/common-licences`. Otherwise, each license\n"
> "referenced in the first line must have a separate stand-alone `License` stanza describing\n"
> "the license terms.\n"
> "\n"
> "**Extended example**:\n"
> "```\n"
> "Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/\n";
> "\n"
> "Files: *\n"
> "Copyright: 2013, Someone\n"
> "License: GPL-2+\n"
> "\n"
> "Files: tests/*\n"
> "Copyright: 2013, Someone\n"
> "# In-line license\n"
> "License: MIT\n"
> " ... full license text of the MIT license here ...\n"
> "\n"
> "Files: tests/complex_text.py\n"
> "Copyright: 2013, Someone\n"
> "License: GPL-2+\n"
> "\n"
> "# Referenced license\n"
> "License: GPL-2+\n"
> " The code is licensed under GNU General Public License version 2 or, at your option, any\n"
> " later version.\n"
> " .\n"
> " On Debian systems the full text of the GNU General Public License version 2\n"
> " can be found in the `/usr/share/common-licenses/GPL-2' file.\n"
> "```\n"
> "\n"
> "The first line (the same line as the field name) should use the abbreviated license name that\n"
> "other stanzas use as reference.\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Files|Field:Comment"
> msgid "Provide extra context related to the details provided in this stanza."
> msgstr ""
Provides
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Files|Field:Comment"
> msgid ""
> "Comment field to optionally provide additional information. For example, it might quote an e-mail from\n"
> "upstream justifying why the license is acceptable to the `main` archive, or an explanation of how this\n"
> "version of the package has been forked from a version known to be [DFSG]-free, even though the current\n"
> "upstream version is not.\n"
> "\n"
As above (s/an e-mail/a message/) just for consistency.
> "The value should be written as \"Formatted text\" without no synopsis. The \"Formatted text\" is similar\n"
> "to the extended description (the `Description` from `debian/control`).\n"
This is very like the cases of "without no" that I've already dealt
with, but it doesn't have the part about "when it is a free-form
explanation" (presumably because that's always the case), so I suppose
it equates to
"The value should be written in the same text format as defined for a package's extended description (the\n"
"`Description` from `debian/control` with no synopsis).\n"
> "\n"
> "[DFSG]: https://www.debian.org/social_contract#guidelines\n";
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Files|Field:Copyright"
> msgid ""
> "Copyright statements relevant for the files matched by this Files stanza."
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Files|Field:Copyright"
> msgid ""
> "One or more free-form copyright statements that applies to the files matched by this `Files` stanza.\n"
As above, one or more is plural, so "apply".
> "Any formatting is permitted. Simple cases often end up effectively being one copyright holder per\n"
> "line; see the examples below for some ideas for how to structure the field to make it easier to read.\n"
> "\n"
> "If a work has no copyright holder (i.e., it is in the public domain), that information should be recorded\n"
> "here.\n"
> "\n"
> "The Copyright field collects all relevant copyright notices for the files of this stanza. Not all\n"
> "copyright notices may apply to every individual file, and years of publication for one copyright\n"
> "holder may be gathered together. For example, if file A has:\n"
> "\n"
> "```\n"
> "Copyright 2008 John Smith\n"
> "Copyright 2009 Angela Watts\n"
> "```\n"
> "\n"
> "and file B has:\n"
> "\n"
> "```\n"
> "Copyright 2010 Angela Watts\n"
> "```\n"
> "\n"
> "a single stanza may still be used for both files. The Copyright field for that stanza might be written\n"
Omit meaningless "still".
> "as:\n"
> "\n"
> "```\n"
> "Files: A B\n"
> "Copyright:\n"
> " Copyright 2008 John Smith\n"
> " Copyright 2009, 2010 Angela Watts\n"
> "License: ...\n"
> "```\n"
> "\n"
> "The `Copyright` field may contain the original copyright statement copied exactly (including the word\n"
> "\"Copyright\"), or it may shorten the text or merge it with other copyright statements as described above,\n"
> "as long as it does not sacrifice information.\n"
> "\n"
> "Formally, the value should be written as \"Formatted text\" without no synopsis. Though, it often\n"
> "ends up resembling a line-based list. The \"Formatted text\" is similar to the extended description\n"
> "(the `Description` from `debian/control`).\n"
> msgstr ""
As above, but again slightly divergent:
"Formally, the value should be written in the same text format as defined for a package's extended\n"
"description (the `Description` from `debian/control` with no synopsis). However, it often ends up\n"
"resembling a line-based list.\n"
("Line-based" as in "newline-separated" or maybe "line-by-line"?)
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:Files|Field:Package"
> msgid "Declares the name of a binary package"
> msgstr ""
What's this doing in here? Does it not have a Hover-Doc partner?
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:License|Field:License"
> msgid "Provide full license information for a short used in Files stanzas"
> msgstr ""
msgid "Provides full license information for a shortname used in Files stanzas"
Mind you, the version below says it might be in the Header stanza, so
maybe it should just say "used elsewhere".
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:License|Field:License"
> msgid ""
> "Provide the license text for a given license shortname referenced from either the `Header` stanza\n"
⁁s
> "or a `Files` stanza.\n"
> "\n"
> "**Extended example**:\n"
> "```\n"
> "Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/\n";
> "\n"
> "Files: *\n"
> "Copyright: 2013, Someone\n"
> "License: GPL-2+\n"
> "\n"
> "Files: tests/*\n"
> "Copyright: 2013, Someone\n"
> "# In-line license\n"
> "License: MIT\n"
> " ... full license text of the MIT license here ...\n"
> "\n"
> "Files: tests/complex_text.py\n"
> "Copyright: 2013, Someone\n"
> "License: GPL-2+\n"
> "\n"
> "# Referenced license\n"
> "License: GPL-2+\n"
> " The code is licensed under GNU General Public License version 2 or, at your option, any\n"
> " later version.\n"
> " .\n"
> " On Debian systems the full text of the GNU General Public License version 2\n"
> " can be found in the `/usr/share/common-licenses/GPL-2' file.\n"
> "```\n"
> "\n"
> "The first line (the same line as the field name) should use the abbreviated license name that\n"
> "other stanzas use as reference. In the `License`-stanza, this field must always contain the full\n"
> "license text in the following lines or a reference to a license in `/usr/share/common-licenses`.\n"
Is "in the `License`-stanza" trying to say "in the rest of the
stanza"? If so:
"The first line (the same line as the field name) should use the abbreviated license name that\n"
"other stanzas use as reference. The following lines must be either a reference to a license in\n"
"`/usr/share/common-licenses` or the full license text.\n"
> "\n"
> "By convention, stand-alone `License`-stanza are usually placed in the bottom of the file.\n"
> msgstr ""
"By convention, stand-alone `License` stanzas are usually placed at the bottom of the file.\n"
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> msgctxt "Stanza:License|Field:Comment"
> msgid "Provide extra context related to the details provided in this stanza."
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_copyright_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:License|Field:Comment"
> msgid ""
> "Comment field to optionally provide additional information. For example, it might quote an e-mail from\n"
> "upstream justifying why the license is acceptable to the `main` archive, or an explanation of how this\n"
> "version of the package has been forked from a version known to be [DFSG]-free, even though the current\n"
> "upstream version is not.\n"
Again for consistency "a message".
> "\n"
> "The value should be written as \"Formatted text\" without no synopsis. The \"Formatted text\" is similar\n"
> "to the extended description (the `Description` from `debian/control`).\n"
As above, shorter version.
> "\n"
> "[DFSG]: https://www.debian.org/social_contract#guidelines\n";
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Architecture"
> msgid "Test only runnable or useful on specific architectures"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Architecture"
> msgid ""
> "When package tests are only supported on a limited set of\n"
> "architectures, or are known to not work on a particular (set of)\n"
> "architecture(s), this field can be used to define the supported\n"
> "architectures. The autopkgtest will be skipped when the\n"
> "architecture of the testbed doesn't match the content of this\n"
> "field. The format is the same as in (Build-)Depends, with the\n"
> "understanding that `all` is not allowed, and `any` means that\n"
> "the test will be run on every architecture, which is the default\n"
> "when not specifying this field at all.\n"
> msgstr ""
These are suddenly much shorter lines, but I'll assume that doesn't
matter. Otherwise... well, there's a split infinitive, ditto.
> #. [Synopsis] One-line description for the value "all" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Architecture"
> msgid ""
> "Independent of machine architecture (scripts, Java without JNI, data or "
> "documentation)"
> msgstr ""
Again easier to follow as:
"Independent of machine architecture (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_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Architecture"
> msgid ""
> "The package is an architecture independent package. This is typically fitting for packages containing\n"
> "only scripts, data or documentation.\n"
Again s/fitting/appropriate/
> "\n"
> "This name `all` refers to the fact that the package can be used for *all* architectures at the same.\n"
I was suggesting
"The name `all` refers to the fact that the same build of a package can be used for *all* architectures.\n"
though it's quite possible I just don't understand Multi-Arch at all.
> "Though note that it is still subject to the rules of the `Multi-Arch` field.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "any" [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Architecture"
> msgid ""
> "Build once per machine architecture (native code, such as C/C++, interpreter"
> " to C bindings)"
> msgstr ""
Build failure: s/Build/Built/.
>
> #. [Hover Doc] Extended description for the value "any" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|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.
> "\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_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test restrictions and requirements"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "Declares some restrictions or problems with the tests defined in\n"
> "this stanza. Depending on the test environment capabilities, user\n"
> "requests, and so on, restrictions can cause tests to be skipped or\n"
> "can cause the test to be run in a different manner. Tests which\n"
> "declare unknown restrictions will be skipped.\n"
> "\n"
> "Restrictions are separated by commas and/or whitespace.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "allow-stderr" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Output on standard error should not trigger a test failure"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "allow-stderr" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "Output to stderr is not considered a failure. This is useful for\n"
> "tests which write e. g. lots of logging to stderr.\n"
> msgstr ""
Nonstandard spacing of "e.g.".
> #. [Synopsis] One-line description for the value "breaks-testbed" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test may break the running system, cause data loss, etc."
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "breaks-testbed" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test, when run, is liable to break the testbed system. This\n"
> "includes causing data loss, causing services that the machine is\n"
> "running to malfunction, or permanently disabling services; it does\n"
> "not include causing services on the machine to temporarily fail.\n"
You could avoid confusion by adding a word:
"not include merely causing services on the machine to temporarily fail.\n"
> "\n"
> "When this restriction is present the test will usually be skipped\n"
> "unless the testbed's virtualisation arrangements are sufficiently\n"
> "powerful, or alternatively if the user explicitly requests.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "build-needed" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Perform build before running the test (use sparingly)"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "build-needed" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The tests need to be run from a built source tree. The test runner\n"
> "will build the source tree (honouring the source package's build\n"
^
en_GB honour, en_US honor.
> "dependencies), before running the tests. However, the tests are\n"
> "*not* entitled to assume that the source package's build\n"
> "dependencies will be installed when the test is run.\n"
> "\n"
> "Please use this considerately, as for large builds it unnecessarily\n"
> "builds the entire project when you only need a tiny subset (like the\n"
> "`tests/` subdirectory). It is often possible to run `make -C tests`\n"
> "instead, or copy the test code to `$AUTOPKGTEST_TMP` and build it\n"
> "there with some custom commands. This cuts down the load on the\n"
> "Continuous Integration servers and also makes tests more robust as\n"
> "it prevents accidentally running them against the built source tree\n"
> "instead of the installed packages.\n"
> "\n"
> "Depending on the test, it may also need the `rw-build-tree` restriction\n"
> "may be relevant.\n"
> msgstr ""
Oops, stumbled at the last line there. Which should it be, "it may
also need the X" or "the X may be relevant"?
> #. [Synopsis] One-line description for the value "flaky" [Plaintext]. Shown
> #. with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test is unstable and fail intermittently"
> msgstr ""
Intermittent failure in number agreement.
> #. [Hover Doc] Extended description for the value "flaky" [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test is expected to fail intermittently, and is not suitable for\n"
> "gating continuous integration. This indicates a bug in either the\n"
> "package under test, a dependency or the test itself, but such bugs\n"
> "can be difficult to fix, and it is often difficult to know when the\n"
> "bug has been fixed without running the test for a while. If a\n"
> "`flaky` test succeeds, it will be treated like any other\n"
> "successful test, but if it fails it will be treated as though it\n"
> "had been skipped.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "hint-testsuite-triggers"
> #. [Plaintext]. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Pseudo test for adding extra dependencies for CI tracking purposes"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "hint-testsuite-triggers"
> #. [Markdown]. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "This test exists purely as a hint to suggest when rerunning the\n"
> "tests is likely to be useful. Specifically, it exists to\n"
> "influence the way dpkg-source generates the Testsuite-Triggers\n"
> ".dsc header from test metadata: the Depends for this test are\n"
> "to be added to Testsuite-Triggers. (Just as they are for any other\n"
> "test.)\n"
> "\n"
> "The test with the hint-testsuite-triggers restriction should not\n"
> "actually be run.\n"
> "\n"
> "The packages listed as Depends for this test are usually indirect\n"
> "dependencies, updates to which are considered to pose a risk of\n"
> "regressions in other tests defined in this package.\n"
> "\n"
> "There is currently no way to specify this hint on a per-test\n"
> "basis; but in any case the debian.org machinery is not able to\n"
> "think about triggering individual tests.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "isolation-container"
> #. [Plaintext]. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Container level isolation required"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "isolation-container"
> #. [Markdown]. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test wants to start services or open network TCP ports. This\n"
> "commonly fails in a simple chroot/schroot, so tests need to be run\n"
> "in their own container (e. g. autopkgtest-virt-lxc) or their own\n"
> "machine/VM (e. g. autopkgtest-virt-qemu or autopkgtest-virt-null).\n"
> "When running the test in a virtualization server which does not\n"
> "provide this (like autopkgtest-schroot) it will be skipped.\n"
Some more examples of oddly spaced "e.g." (and an especially harmless
dangling modifier).
> "\n"
> "Tests may assume that this restriction implies that process 1 in the\n"
> "container's process namespace is a system service manager (init system)\n"
> "such as systemd or sysvinit + sysv-rc, and therefore system services\n"
> "are available via the `service(8)`, `invoke-rc.d(8)` and\n"
> "`update-rc.d(8)` interfaces.\n"
I was going to say that "may" was slightly ambiguous, but the fact
that the following paragraph is a "must not" probably covers it.
> "\n"
> "Tests must not assume that a specific init system is in use: a\n"
> "dependency such as `systemd-sysv` or `sysvinit-core` does not work\n"
> "in practice, because switching the init system often cannot be done\n"
> "automatically. Tests that require a specific init system should use the\n"
> "`skippable` restriction, and skip the test if the required init system\n"
> "was not detected.\n"
> "\n"
> "Many implementations of the `isolation-container` restriction will\n"
> "also provide `systemd-logind(8)` or a compatible interface, but this\n"
> "is not guaranteed. Tests requiring a login session registered with\n"
> "logind should declare a dependency on `default-logind | logind`\n"
> "or on a more specific implementation of `logind`, and should use the\n"
> "`skippable` restriction to exit gracefully if its functionality is\n"
> "not available at runtime.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "isolation-machine"
> #. [Plaintext]. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Machine level isolation required"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "isolation-machine"
> #. [Markdown]. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test wants to interact with the kernel, reboot the machine, or\n"
> "other things which fail in a simple schroot and even a container.\n"
> "Those tests need to be run in their own machine/VM (e. g.\n"
> "autopkgtest-virt-qemu or autopkgtest-virt-null). When running the\n"
> "test in a virtualization server which does not provide this it will\n"
> "be skipped.\n"
More bad examples.
> "\n"
> "This restriction also provides the same facilities as\n"
> "`isolation-container`.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "needs-internet" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test needs internet access (often needs flaky as well)"
> msgstr ""
Styleguides say Internet should be capitalised. Then again, fewer and
fewer sources seem to be paying attention to this rule, and it never
really made any sense. (How is "the internet" any more of a proper
noun than "the sky"?)
> #. [Hover Doc] Extended description for the value "needs-internet" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test needs unrestricted internet access, e.g. to download test data\n"
> "that's not shipped as a package, or to test a protocol implementation\n"
> "against a test server. Please also see the note about Network access later\n"
> "in the [autopkgtests documentation], which covers details on restrictions and\n"
> "limitations for internet access.\n"
Mostly these strings have been avoiding contractions, and "that's not"
isn't one I would use here (I'd say "that isn't"); I'd suggest
compressing the relative clause into "test data not shipped as a
package". Oh, and then... lowercase internet but capitalised Network?
No, make both lowercase.
> "\n"
> "Note since the internet is generally unstable, this restriction should\n"
> "often be used together with `flaky`.\n"
Note ⁁that
> "\n"
> "[autopkgtests documentation]: https://salsa.debian.org/ci-team/autopkgtest/raw/master/doc/README.package-tests.rst\n";
> msgstr ""
>
> #. [Synopsis] One-line description for the value "needs-reboot" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test will need to perform a reboot"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "needs-reboot" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test wants to reboot the machine. Please see the `Reboot during a test` section\n"
> "of the [autopkgtests documentation] for details about how to do this and limitations.\n"
> "\n"
> "[autopkgtests documentation]: https://salsa.debian.org/ci-team/autopkgtest/raw/master/doc/README.package-tests.rst\n";
> msgstr ""
>
> #. [Synopsis] One-line description for the value "needs-recommends"
> #. [Plaintext]. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Obsolete way for requesting Recommends in the test dependencies"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "needs-recommends"
> #. [Markdown]. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "Historical way to add `Recommends` to the test dependencies. Please use "
> "`@recommends@` in your test `Depends:` instead.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "needs-root" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test needs root access"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "needs-root" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test script must be run as root.\n"
> "\n"
> "While running tests with this restriction, some test runners will\n"
> "set the `AUTOPKGTEST_NORMAL_USER` environment variable to the name\n"
> "of an ordinary user account. If so, the test script may drop\n"
> "privileges from root to that user, for example via the `runuser`\n"
> "command. Test scripts must not assume that this environment variable\n"
> "will always be set.\n"
> "\n"
> "For tests that declare both the `needs-root` and `isolation-machine`\n"
> "restrictions, the test may assume that it has \"global root\" with full\n"
> "control over the kernel that is running the test, and not just root\n"
> "in a container (more formally, it has uid 0 and full capabilities in\n"
> "the initial user namespace as defined in `user_namespaces(7)`).\n"
> "For example, it can expect that mounting block devices will succeed.\n"
> "\n"
> "For tests that declare the `needs-root` restriction but not the\n"
> "`isolation-machine` restriction, the test will be run as uid 0 in\n"
> "a user namespace with a reasonable range of system and user uids\n"
> "available, but will not necessarily have full control over the kernel,\n"
> "and in particular it is not guaranteed to have elevated capabilities\n"
> "in the initial user namespace as defined by `user_namespaces(7)`.\n"
> "For example, it might be run in a namespace where uid 0 is mapped to\n"
> "an ordinary uid in the initial user namespace, or it might run in a\n"
> "Docker-style container where global uid 0 is used but its ability to\n"
> "carry out operations that affect the whole system is restricted by\n"
> "capabilities and system call filtering. Tests requiring particular\n"
> "privileges should use the `skippable` restriction to check for\n"
> "required functionality at runtime.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "needs-sudo" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test needs to run as normal user with \"sudo to root\" access"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "needs-sudo" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test script needs to be run as a non-root user who is a member of\n"
> "the `sudo` group, and has the ability to elevate privileges to root\n"
> "on-demand.\n"
> "\n"
> "This is useful for testing user components which should not normally\n"
> "be run as root, in test scenarios that require configuring a system\n"
> "service to support the test. For example, gvfs has a test-case which\n"
> "uses sudo for privileged configuration of a Samba server, so that\n"
> "the unprivileged gvfs service under test can communicate with that server.\n"
> "\n"
> "While running a test with this restriction, `sudo(8)` will be\n"
> "installed and configured to allow members of the `sudo` group to run\n"
> "any command without password authentication.\n"
> "\n"
> "Because the test user is a member of the `sudo` group, they will\n"
> "also gain the ability to take any other privileged actions that are\n"
> "controlled by membership in that group. In particular, several packages\n"
> "install `polkit(8)` policies allowing members of group `sudo` to\n"
> "take administrative actions with or without authentication.\n"
> "\n"
> "If the test requires access to additional privileged actions, it may\n"
> "use its access to `sudo(8)` to install additional configuration\n"
> "files, for example configuring `polkit(8)` or `doas.conf(5)`\n"
> "to allow running `pkexec(1)` or `doas(1)` without authentication.\n"
> "\n"
> "Commands run via `sudo(8)` or another privilege-elevation tool could\n"
> "be run with either \"global root\" or root in a container, depending\n"
> "on the presence or absence of the `isolation-machine` restriction,\n"
> "in the same way described for `needs-root`.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "rw-build-tree" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test requires the build-tree to be writable"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "rw-build-tree" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test(s) needs write access to the built source tree (so it may\n"
> "need to be copied first). Even with this restriction, the test is\n"
> "not allowed to make any change to the built source tree which (i)\n"
> "isn't cleaned up by `debian/rules clean`, (ii) affects the future\n"
> "results of any test, or (iii) affects binary packages produced by\n"
> "the build tree in the future.\n"
> msgstr ""
(What no Markdown bulletpoints?)
> #. [Synopsis] One-line description for the value "skip-not-installable"
> #. [Plaintext]. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "Uninstallable test dependencies causes skip rather fail (use with caution)"
> msgstr ""
Number agreement failure, I think: cause.
>
> #. [Hover Doc] Extended description for the value "skip-not-installable"
> #. [Markdown]. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "This restrictions may cause a test to miss a regression due to\n"
> "installability issues, so use with caution. If one only wants to\n"
> "skip certain architectures, use the `Architecture` field for\n"
> "that.\n"
Rogue plural ending. Then I would avoid "one" here, since after all
it isn't even consistent with the "use X" instructions (imperative
verbs have the implicit subject "you", not "one").
"This restriction may cause a test to miss a regression due to\n"
"installability issues, so use with caution. If you only want to\n"
"skip certain architectures, use the `Architecture` field for\n"
"that.\n"
> "\n"
> "This test might have test dependencies that can't be fulfilled in\n"
> "all suites or in derivatives. Therefore, when apt-get installs the\n"
> "test dependencies, it will fail. Don't treat this as a test\n"
> "failure, but instead treat it as if the test was skipped.\n"
> msgstr ""
s/Therefore/If so/
> #. [Synopsis] One-line description for the value "skippable" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test may at runtime decide to be marked as skipped"
> msgstr ""
>
> #. [Hover Doc] Extended description for the value "skippable" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test might need to be skipped for reasons that cannot be\n"
> "described by an existing restriction such as isolation-machine or\n"
> "breaks-testbed, but must instead be detected at runtime. If the\n"
> "test exits with status 77 (a convention borrowed from Automake), it\n"
> "will be treated as though it had been skipped. If it exits with any\n"
> "other status, its success or failure will be derived from the exit\n"
> "status and stderr as usual. Test authors must be careful to ensure\n"
> "that `skippable` tests never exit with status 77 for reasons that\n"
> "should be treated as a failure.\n"
> msgstr ""
>
> #. [Synopsis] One-line description for the value "superficial" [Plaintext].
> #. Shown with completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid "Test only provides superficial or trival coverage"
> msgstr ""
Trivial typo.
>
> #. [Hover Doc] Extended description for the value "superficial" [Markdown].
> #. Shown in hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Restrictions"
> msgid ""
> "The test does not provide significant test coverage, so if it\n"
> "passes, that does not necessarily mean that the package under test\n"
> "is actually functional. If a `superficial` test fails, it will be\n"
> "treated like any other failing test, but if it succeeds, this is\n"
> "only a weak indication of success. Continuous integration systems\n"
> "should treat a package where all non-superficial tests are skipped as\n"
> "equivalent to a package where all tests are skipped.\n"
> "\n"
> "For example, a C library might have a superficial test that simply\n"
> "compiles, links and executes a \"hello world\" program against the\n"
> "library under test but does not attempt to make use of the library's\n"
> "functionality, while a Python or Perl library might have a\n"
> "superficial test that runs `import foo` or `require Foo;` but\n"
> "does not attempt to use the library beyond that.\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Classes"
> msgid "Hardware related tagging"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Classes"
> msgid ""
> "Most package tests should work in a minimal environment and are\n"
> "usually not hardware specific. However, some packages like the\n"
> "kernel, X.org, or graphics drivers should be tested on particular\n"
> "hardware, and also run on a set of different platforms rather than\n"
> "just a single virtual testbeds.\n"
I notice that this is using serial comma. That tends to be what
styleguides recommend; but I've been letting this text get away with
*not* using serial comma, on the grounds that it doesn't matter as
long as it's consistent. So maybe this should be
"kernel, X.org or graphics drivers"
Much more importantly, rogue plural ending on that last word.
> "\n"
> "This field can specify a list of abstract class names such as\n"
> "\"desktop\" or \"graphics-driver\". Consumers of autopkgtest can then\n"
> "map these class names to particular machines/platforms/policies.\n"
> "Unknown class names should be ignored.\n"
> "\n"
> "This is purely an informational field for autopkgtest itself and\n"
> "will be ignored.\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Depends"
> msgid "Dependencies for running the tests"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Depends"
> msgid ""
> "Declares that the specified packages must be installed for the test\n"
> "to go ahead. This supports all features of dpkg dependencies, including\n"
> "the architecture qualifiers (see\n"
> "<https://www.debian.org/doc/debian-policy/ch-relationships.html>),\n"
> "plus the following extensions:\n"
> "\n"
> "`@` stands for the package(s) generated by the source package\n"
> "containing the tests; each dependency (strictly, or-clause, which\n"
> "may contain `|`s but not commas) containing `@` is replicated\n"
> "once for each such binary package, with the binary package name\n"
> "substituted for each `@` (but normally `@` should occur only\n"
> "once and without a version restriction).\n"
> "\n"
> "`@builddeps@` will be replaced by the package's\n"
> "`Build-Depends:`, `Build-Depends-Indep:`, `Build-Depends-Arch:`, and\n"
> "`build-essential`. This is useful if you have many build\n"
> "dependencies which are only necessary for running the test suite and\n"
> "you don't want to replicate them in the test `Depends:`. However,\n"
> "please use this sparingly, as this can easily lead to missing binary\n"
> "package dependencies being overlooked if they get pulled in via\n"
> "build dependencies.\n"
> "\n"
> "`@recommends@` stands for all the packages listed in the\n"
> "`Recommends:` fields of all the binary packages mentioned in the\n"
> "`debian/control` file. Please note that variables are stripped,\n"
> "so if some required test dependencies aren't explicitly mentioned,\n"
> "they may not be installed.\n"
> "\n"
> "If no Depends field is present, `Depends: @` is assumed. Note that\n"
> "the source tree's Build-Dependencies are *not* necessarily\n"
> "installed, and if you specify any Depends, no binary packages from\n"
> "the source are installed unless explicitly requested.\n"
> msgstr ""
This all looks okay, thank goodness.
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Features"
> msgid "Declare test features"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Features"
> msgid ""
> "Declares some additional capabilities or good properties of the\n"
> "tests defined in this stanza. Any unknown features declared will be\n"
> "completely ignored.\n"
> "\n"
> "Features are separated by commas and/or whitespace.\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Comment"
> 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_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Comment"
> msgid ""
> "Comment field to optionally provide additional information. For example, it might quote an e-mail from\n"
> "upstream justifying why the combined license is acceptable to the `main` archive, or an explanation of\n"
> "how this version of the package has been forked from a version known to be [DFSG]-free, even though the\n"
> "current upstream version is not.\n"
I'm allowing "email" for "email address" in a synopsis, but not
when it's combined with "e-mail" meaning something else in the
extended description - s/e-mail/message/.
> "\n"
> "Note if the `Comment` is only applicable to a set of files or a particular license out of many,\n"
> "the `Comment` field should probably be moved to the relevant `Files` stanza or `License` stanza instead.\n"
Again,
"If the `Comment` is only applicable to one set of files or a particular license out of many,\n"
> "\n"
> "The value should be written as \"Formatted text\" without no synopsis. The \"Formatted text\" is similar\n"
> "to the extended description (the `Description` from `debian/control`).\n"
> "\n"
> "[DFSG]: https://www.debian.org/social_contract#guidelines\n";
> msgstr ""
Again,
"When it is a free-form explanation, the value should be written in the same text format as defined\n"
"for a package's extended description (the `Description` from `debian/control` with no synopsis).\n"
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Tests"
> msgid "List of test scripts to run"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Tests"
> msgid ""
> "This field names the tests which are defined by this stanza, and map\n"
> "to executables/scripts in the test directory. All of the other\n"
> "fields in the same stanza apply to all of the named tests. Either\n"
> "this field or `Test-Command:` must be present.\n"
> "\n"
Should that be "this field names things and mapS THEM to things"?
> "Test names are separated by comma and/or whitespace and should\n"
> "contain only characters which are legal in package names. It is\n"
> "permitted, but not encouraged, to use upper-case characters as well.\n"
> "\n"
> "The `Test-Directory` can be used to set a non-default directory as\n"
> "the path containing the tests.\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Test-Command"
> msgid "Run an inline piece of shell code as the test"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Test-Command"
> msgid ""
> "If your test only contains a shell command or two, or you want to\n"
> "reuse an existing upstream test executable and just need to wrap it\n"
> "with some command like `dbus-launch` or `env`, you can use this\n"
> "field to specify the shell command directly. It will be run under\n"
> "`bash -e`. This is mutually exclusive with the `Tests:` field.\n"
> "\n"
> "This is also useful for running the same script under different\n"
> "interpreters and/or with different dependencies, such as\n"
> "`Test-Command: python debian/tests/mytest.py` and\n"
> "`Test-Command: python3 debian/tests/mytest.py`.\n"
> msgstr ""
(Is that particular example still possible?)
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Test-Directory"
> msgid "The directory containing the tests listed in from Tests"
> msgstr ""
Huh? Maybe just a surplus word, s/from//?
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Test-Directory"
> msgid ""
> "Replaces the path segment `debian/tests` in the filenames of the\n"
> "test programs with `path`. I. e., the tests are run by executing\n"
> "`built/source/tree/path/testname`. `path` must be a relative\n"
> "path and is interpreted starting from the root of the built source\n"
> "tree.\n"
Oh, a new variant on misspaced e. g.
> "\n"
> "This allows tests to live outside the `debian/` metadata area, so that\n"
> "they can more palatably be shared with non-Debian distributions.\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Copyright"
> msgid "Provide copyright statements for the package as a whole"
> msgstr ""
Provides
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Copyright"
> msgid ""
> "One or more free-form copyright statements that applies to the package as a whole.\n"
One more time, "apply".
> "\n"
> "Using `Copyright` in the `Header` stanza is useful when it records a notable difference or simplification\n"
> "of the other `Copyright` fields in this files. However, it serves no purpose to provide the field for the\n"
> "sole purpose of aggregating the other `Copyright` fields.\n"
"Using `License` in the `Header` stanza is useful when it records a notable difference or simplification\n"
"of the other files' `License` fields, but it is not useful when it merely aggregates those fields.\n"
> "\n"
> "Any formatting is permitted. Simple cases often end up effectively being one copyright holder per\n"
> "line; see the examples below for some ideas for how to structure the field to make it easier to read.\n"
> "\n"
> "If a work has no copyright holder (i.e., it is in the public domain), that information should be recorded\n"
> "here.\n"
> "\n"
> "The Copyright field collects all relevant copyright notices for the files of this stanza. Not all\n"
> "copyright notices may apply to every individual file, and years of publication for one copyright\n"
> "holder may be gathered together. For example, if file A has:\n"
> "\n"
> "```\n"
> "Copyright 2008 John Smith\n"
> "Copyright 2009 Angela Watts\n"
> "```\n"
> "\n"
> "and file B has:\n"
> "\n"
> "```\n"
> "Copyright 2010 Angela Watts\n"
> "```\n"
> "\n"
> "a single stanza may still be used for both files. The Copyright field for that stanza might be written\n"
> "as:\n"
> "\n"
> "```\n"
> "Files: A B\n"
> "Copyright:\n"
> " Copyright 2008 John Smith\n"
> " Copyright 2009, 2010 Angela Watts\n"
> "License: ...\n"
> "```\n"
> "\n"
> "The `Copyright` field may contain the original copyright statement copied exactly (including the word\n"
> "\"Copyright\"), or it may shorten the text or merge it with other copyright statements as described above,\n"
> "as long as it does not sacrifice information.\n"
> "\n"
> "Formally, the value should be written as \"Formatted text\" without no synopsis. Though, it often\n"
> "ends up resembling a line-based list. The \"Formatted text\" is similar to the extended description\n"
> "(the `Description` from `debian/control`).\n"
This was the variant I was rewriting as:
"Formally, the value should be written in the same text format as defined for a package's extended\n"
"description (the `Description` from `debian/control` with no synopsis). However, it often ends up\n"
"resembling a line-based list.\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Files-Excluded"
> msgid ""
> "Exclude files from the tarball when fetching or repacking (via `uscan` or "
> "`mk-origtargz`)"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Files-Excluded"
> msgid ""
> "Remove the listed files from the tarball when repacking (commonly via `uscan`). This can be useful\n"
> "when the listed files are non-free but not necessary for the Debian package. In this case, the\n"
> "upstream version of the package should generally end with `~dfsg` or `+dfsg` (to mark the content\n"
> "changed due to the Debian Free Software Guidelines). The exclusion can also be useful to remove\n"
> "large files or directories that are not used by Debian or pre-built binaries. In this case, `~ds`\n"
> "or `+ds` should be added to the version instead of `~dfsg` or `+dfsg` for \"Debian Source\" to mark\n"
> "it as altered by Debian. If both reasons are used, the `~dfsg` or `+dfsg` version is used as that\n"
> "is the more important reason for the repacking.\n"
As above,
"Remove the listed files from the tarball when repacking (commonly via `uscan`). This can be useful\n"
"when the listed files are non-free but not necessary for the Debian package. In this case, the\n"
"upstream version of the package should generally end with `~dfsg` or `+dfsg` (to mark the content\n"
"changed due to the Debian Free Software Guidelines). The exclusion can also be useful to remove\n"
"pre-built binaries, or large files or directories that are not used by Debian. In this case, `~ds`\n"
"or `+ds` should be added to the version (to mark it as altered \"Debian Source\"). If both reasons\n"
"for repacking apply, the `~dfsg` or `+dfsg` version is used as that is the more important reason.\n"
Oh, and I recognise this lot, no problems here:
> "\n"
> "**Example**:\n"
> "```\n"
> "Files-Excluded: exclude-this\n"
> " exclude-dir\n"
> " */exclude-dir\n"
> " .*\n"
> " */js/jquery.js\n"
> "```\n"
> "\n"
> "The `Files-Included` field can be used to \"re-include\" files matched by `Files-Excluded`.\n"
> "\n"
> "It is also possible to exclude files in specific \"upstream components\" for source packages\n"
> "with multiple upstream tarballs. This is done by adding a field called\n"
> "`Files-Excluded-<component>`. The `<component>` part should then match the component name\n"
> "exactly (case sensitive).\n"
> "\n"
> "The field uses the same syntax as the `Files` fields from the `Files` stanzas.\n"
> "\n"
> "Defined by: `mk-origtargz` (usually used via `uscan`)\n"
> msgstr ""
>
> #. [Synopsis] One-line description of the field itself [Plaintext]. Shown with
> #. completion (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> msgctxt "Stanza:Tests|Field:Files-Included"
> msgid ""
> "Unexclude files from the tarball when fetching or repacking (via `uscan` or "
> "`mk-origtargz`)"
> msgstr ""
>
> #. [Hover Doc] Extended description for the field itself [Markdown]. Shown in
> #. hover docs (etc.)
> #: src/debputy/lsp/data/debian_tests_control_reference_data.yaml
> #, python-brace-format
> msgctxt "Stanza:Tests|Field:Files-Included"
> msgid ""
> "Re-include files that were marked for exclusion by `Files-Excluded`. This can be useful for \"exclude\n"
> "everything except X\" style semantics where `Files-Excluded` has a very broad pattern and\n"
> "`Files-Included` then marks a few exceptions.\n"
> "\n"
> "It is also possible to re-include files in specific \"upstream components\" for source packages with multiple\n"
> "upstream tarballs. This is done by adding a field called `Files-Include-<component>` which is then used\n"
> "in tandem with `Files-Exclude-<component>`. The `<component>` part should then match the component name\n"
> "exactly (case sensitive).\n"
> "\n"
> "Example:\n"
> "```\n"
> "Files-Excluded: data/*\n"
> "Files-Included: data/keep-this-file.txt\n"
> "```\n"
> "\n"
> "The field uses the same syntax as the `Files` fields from the `Files` stanzas.\n"
> "\n"
> "Defined by: `mk-origtargz` (usually used via `uscan`)\n"
> msgstr ""
Done!
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: