Re: Bug#749826: Documenting `Multi-Arch: foreign`

[Richard Lewis <richard.lewis.debian@googlemail.com>]

Some suggestions to make it easier to follow:

> diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst
> index 3151816..d43acac 100644
> --- a/policy/ch-controlfields.rst
> +++ b/policy/ch-controlfields.rst
> @@ -1307,6 +1307,150 @@ This list is intentionally incomplete. You should consult the
>  documentation of the tool or package in question for which keywords it
>  defines and when they are needed.
>  
> +.. _s-f-Multi-Arch:
> +
> +``Multi-Arch``
> +~~~~~~~~~~~~~~
> +
> +A Debian installation may combine packages from multiple architectures.

> +The ``Multi-Arch`` header enables individual packages to declare their
> +support for this feature.

isnt it more like

"The ``Multi-Arch`` field declares how a package supports this feature",

given the value of the field is not only yes/no?

> It

this "it" couls be more specific to help the reader know which of the
nouns in the prev sentence are meant: the package, the field or the
feature? (without having backtrack)


> may occur only in the control file of a
> +binary package or in the per-package fields paragraph of a source
> +package control file. The semantics of permitted values are ``no``

i dont think you actually mean "semantics" here: just "the permitted
values are"?


> +(default), ``foreign``, ``same`` and ``allowed``

> as described individually.

you could omit these 3 words, or replace "individully" with "below"

> +
> +.. _s-f-Multi-Arch-no:
> +
> +``Multi-Arch: no``
> +^^^^^^^^^^^^^^^^^^
> +
> +When satisfying a dependency (using ``Depends``, ``Pre-Depends``,
> +``Provides``, ``Recommends``, or ``Suggests``), the architecture of the
> +depender and the architecture of the dependee

> being thus marked are
> +required to be equal.

i think it would be clearer to avoid "depender" and "dependee" and
"thus" (and "satsifying" reads as passive voice). my guess is you mean:

If package B declares ``Multi-arch: no`` and package A declares a
dependency on B (using ``Depends``, ``Pre-Depends``, `Provides``,
``Recommends``, or ``Suggests``) then only a version of B with the same
architecture as A will be considered to satisfy the dependency.

(but who/what does the "considering"?)




>For negative dependency relations (``Breaks``,
> +``Conflicts``, and ``Replaces``) the architecture does not have to match
> +for the relation to take effect.

("the relation"? do you just mean:

The field has no effect on ``Breaks`` ``Conflicts``, or ``Replaces``.?



> Architecture-independent packages are
> +treated as if they had the architecture value of the installed `dpkg`
> +package.


>Furthermore, multiple instances of a package with the same
> +name and different architectures are not considered coinstallable.

?? isnt this always true?


> +Note that due to limitations in the archive management software, this
> +value cannot currently be specified explicitly in binary package control
> +files.

this doent make sense as:

- the archive mangement software (can you name this software?) does not
'control' what a developer write and uploads
    do you mean the software ignores the field or that uploads are rejected
- using 'explicitly' hints that there is a way to specify it in some other way?


> +
> +``Multi-Arch: foreign``
> +^^^^^^^^^^^^^^^^^^^^^^^
> +
> +A binary package may be marked with a ``Multi-Arch: foreign`` control

s/may/should?

you might want to make the text use a similar style for each option

> +header if the provided interfaces are independent of the architecture
> of

interface? oh it is explained below, it would help to have it in markup,
and move the "Any...property" later

> +the package. Any provided virtual packages (see :ref:`s-virtual`)
> +inherit this property.

property means the value of the field? or the indepence?

"packages" plural is not compatible with "any": use "Any provided
virtual package" or "Provided virtual packages"

> Given this header value, dependencies on this
> +package are considered satisfied even when the depender's architecture
> +differs from the marked package.

the term 'header' has not been defined before this point?
'this package' is causing some confusion, is itthe depender or the dependee?

> +
> +There are five main areas that can contribute to the interface of a
> +package and if any of them provides an architecture-dependent
> interface,
> +a package must not be marked with ``Multi-Arch: foreign``.

think there are too many "interfaces" in this sentence?

i think you mean:

"A package must not be marked as ``Multi-Arch: foreign`` if it provides
an 'architecture-dependent interface'. The five main ways that a
packages' interface can be architecture-dependent are:"

> +
> +- The installed files of a package: Architecture-dependent packages
> may
> +  install different sets of files or files with different content for
> +  multiple architectures


some odd wording in this bit, the colon seems in the wrong place, and
package/packages is confusing. do you perhaps just mean:

"- The package does not install identical files on every architecture"?


> > and these differences may contribute to the
> +  interface  (e.g. an endianess-dependent database file).

is this example really intended to be an example of the interface, or should
the bit in brackets have gone earlier?

- The package does not install identical files on every architecture
(e.g. a database may have endianess that depends on the architectute).


> > For
> +  architecture-independent binary packages, there is aspect does not
> +  apply.

"is an aspect" or "are aspects". but the sentence is missing the key
information: what aspect(s) do not/does not apply?

> +
> +- The behavior of installed files of a packag

not convincd that an installed file can really "behave",

> > When interfacing with
> +  installed files by executing them,

(this bit i could not guess a meaning for at all).
is "interfacing" being used with a different meaning here?

> > their behavior may contribute to
> +  the provided interface.  For instance, interfacing with shared and
> +  static libraries necessarily is architecture-dependent.  Whilst binary
> +  executables generally differ with architectures

"depend on the" not "with", i think?

> > , the exposed interface
> +  (for example the command line interface, the content on standard
> +  input/output, the way they process files)
> > may be independent of the
> +  architecture used to execute

this sentence is missing an end, execute what? (the bit in brackets is a
biy confusing i think. what is "they"? why is "the content on standard
input/output" relevant?)

> .  In that case, their interface may be
> +  considered architecture-independent.

another "their" that needs explaining

> +
> +- Maintainer scripts and triggers:

This is mean to be a "reason", so just saying "maintainer scripts and
triggers" reads as incomplete.


> A package may behave in an
> +  architecture dependent way, when the maintainer scripts or invoked

i think you dont want a comma there. 

> +  triggers behave differently on different architectures.

> + For instance,
> +  byte-compiling source files into architecture-dependent bytecode
> +  during ``postinst`` may turn the interface of a package
> +  architecture-dependent.

This reads as if it is the user's fault - if i byte-compile emacs files
from a package did i really "turn the interface" incomplete? should this
say

"A package that byte-compiles source files into architecture-dependent
bytecode during ``postinst`` may have an architecture-dependent
interface"?


> +
> +- The dependencies of a package: A package may expose functionality of
> +  other packages by depending on them. In general, an executable does
> +  not expose its linked shared libraries and therefore they do not
> +  usually contribute to the interface.

"expose" has some connotations you may want to avoid.
why is this tlaking about executables and not packages?

> + On the other hand, the whole
> +  point of transitional packages is to expose such functionality.

i dont think this is what you mean. the "whole point" is surely more
likely to be to help upgrades

> +  Likewise, development packages for shared libraries necessarily expose
> +  their own dependencies.

i dont think "likewise" works in this context


> +
> +- Implicit and foreign dependencies of a package: Essential packages are
> +  implicitly depended upon and need not show up in ``Depends``.

i think this is introducing a non-standard concept of "implicitly
depended upon" that is maybe not really helpful. Is this really a
separate point or is this just an add-on to the previous point about
dependencies that says "as well as package dependencies, you also need
to consider essential packages that are used but do not show up in
``Depends``"

The "foreign dependencies" part doesnt seem to be explained in the words that follow

> + Yet
> +  their behaviour can be architecture-dependent. For instance, using
> +  ``dpkg --print-architecture`` can be used to emit the native
> +  architecture even though ``dpkg`` is marked ``Multi-Arch: foreign``.
> +  Similarly, calling ``pkgconf`` (without a prefix) will behave
> +  differently on different architectures as its search path is
> +  architecture-dependent even though ``pkgconf-bin`` is considered
> +  ``Multi-Arch: foreign``.
> +
> +The interfaces of a package are determined by its maintainer.

interface singular (if there is more than one then you need to explain
something much better above!)

surely the text needs to say how this determination is made?

> > However,
> +some packages might expose architecture dependencies when other packages
> +use them in a manner not intended by the maintainer.  This can happen
> +when it is not clear which parts of the package are its interfaces.

this is rather confusing! is it up to the maintainer or not?


> +
> +In such cases, where the package satisfies the criterion for
> +``Multi-Arch: foreign`` but might expose architecture dependency,
> +because it is not clear which parts of the package are its interfaces,
> +the interfaces of the package should be described in the file
> +``debian/README.multiarch``.

is this just saying:

the maintainer must/should define the interface in
debian/README.multiarch``? any hints on what they should write there?


> +
> +conversely, justifying the use of functionality that is not covered by
> +its offered interface with a dependency on such a package is not
> +allowed.

not sure 'conversely' helps here. i think it is unclear what is meant
here

> +
> +``Multi-Arch: same``
> +^^^^^^^^^^^^^^^^^^^^
> +
> +Multiple binary packages with the same name and version may be installed
> +concurrently if all of them carry this header valued ``same``.

another "header"? do you just mean "if all of them are marked
``Multi-Arch: same``"

> Any set
> +of packages with matching name and version being thus marked must
> +support two properties.

can one "support" a property? surely this should say "must have two
properties"?

> +
> +- All filenames that are present in multiple of these packages must

"in multiple of these" isnt correct english. do you mean "in more than
one of these packages"?  Do you really mean filename (which is ambiguous
and suggests only basename) instead of file?

> +  contain bit-identical content across architectures. [#]_

"Any files that are installed by more than one of these packages must be
identical"



> +
> +  For files whose name is unique within this set

i was baffled by "this set". I after re-reading several times i think
you are saying "no requirement is placed on files that are only
installed on one architecture" (and actually i think that is then
obvious, and can be dropped, once the previous sentence is made more
readable)



> > , no such requirement
> +  exists. Therefore, such packages usually install most of their files
> +  below ``/usr/lib/${DEB_HOST_MULTIARCH}``.

An odd use of 'therefore'. I think you simply mean:

"Packages marked ``Multi-Arch: same`` usually install most of their
files below ``/usr/lib/${DEB_HOST_MULTIARCH}`` becasue <REASON>"



> +
> +- The maintainer scripts must be prepared to be configured or
> +  deconfigured multiple times. In particular, ``postrm`` must consider
> +  that another instance may still be present.

dont understand this part: instance refers to postrm? present means
installed?  or should this say "running"? that cant be right?

> It may check the

it = postrm? or the other instance?

> +  ``DPKG_MAINTSCRIPT_PACKAGE_REFCOUNT`` environment variable set by
> +  ``dpkg``.

and then do what? (sentence is missing an explanation of why something
is checking the environment variable)


> +``Multi-Arch: allowed``
> +^^^^^^^^^^^^^^^^^^^^^^^
> +
> +A package annotated this way behaves as if it were annotated with the
> +``no``

Is this really what you mean? ie "allowed" is
similar to "no"? that seems like such a confusing naming scheme i assume
"no" is a typo(?) for "same"?

> value except that a depender may now append ``:any`` to the
> +package name in a dependency relation field. In that case, the
> +dependency is considered satisfied even when the architecture of the
> +depender differs from the dependee's.
> Dependencies carrying a ``:any``
> +suffix can only be satisfied by packages marked ``Multi-Arch: allowed``.
> +

I think i understand this!: would

A package marked ``Multi-Arch: allowed`` is similar to ``Multi-Arch:
no`` but also allows other packages to declare dependencies on it with
':any'.  If package B has ``Depends: A:any`` and A is marked
``Multi-Arch: allowed`` then the dependency can be satisfied by a
version of A from any architecture.

be simpler?


> +This value should be used rarely for cases where the package can be used
> +in an architecture-dependent way or in an architecture-independent
> way

"used rarely for cases" can be read as either
   is used rarely, and only for cases where <stuff>
or
   is used for cases where <stuff>, but only rarely

saying "should" is probably not helping this sentence...

> +and the decision of which applies is deferred to the depender.

by decision did you mean 'choice'? but to when is it 'deferred'? how
does the depender choose which applies?

> The most
> +common use is with programming language interpreters that enable loading
> +architecture-dependent plugins.

but a 'programme language interpreter' (i assume you just mean something
like 'python3' or 'bash') could have been installed in many ways, so
it's hard to see a link to a debian-specific field from what is written
here. I think you at least need to say if the package providing the
interpreter is the depender or the dependee

> +
> +Since removing this value tends to break reverse dependencies that
> +employ ``:any``, uses of it should be discussed with
> +*debian-devel@lists.debian.org* first.

it is not clear if this means to discuss adding or removing the field or
both?  (would also benefit from more active voice phrasing) (can you
really discuss "with" an email address? not sure that is correct!)

How about:

The maintainer must obtain approval from participants on the mailing
list *debian-devel@lists.debian.org* before setting ``Multi-Arch:
allowed``. This is because once this value is set, it cannot be removed
without breaking reverse-dependencies that used ``:any``.


> +
>  .. _s5.7:
>  
>  User-defined fields
> @@ -1443,3 +1587,9 @@ details.
>  
>  .. [#]
>     That is, the parts which are not the ``.dsc``.
> +
> +.. [#]
> +   As an exception, the ``libc6`` package is marked ``Multi-Arch: same``
> +   despite not fully complying with this requirement, because the
> +   location of the dynamic loader is not universally unique and cannot
> +   be changed without breakig ABI.

'universally unique' - in debian(?), differs between distributions?
users can choose?

also a typo: "breakig"