Re: Bug#649325: Package description perhaps misleading
Martin Eberhard Schauer wrote:
> Description: GNU assembler, linker and binary utilities
Encouragingly it has lost the leading capitalised definite article
between Wheezy and Sid.
> This is easy to understand,
I wouldn't agree with that; the conjoined noun phrase has always
struck me as subtly confusing. I nearly submitted a bugreport back in
May.
> but in my opinion not entirely correct. One
> might think that assembler and linker are not binary utilities (programs
> to work with binaries). Having written the last sentence, perhaps the
> short description is ok - the assembler prepares the input for the
> linker, the linker provides the binary, other programs deal with the
> binaries. I think the description should not provide reasons for discussing
> it.
The question is, is it trying to say that the package contains
"assembler utilities, linker utilities, and binary ones", or "an
assembler, a linker, and some binary-utilities"? It's got to be the
latter, hasn't it? But this confusingly implies that "as" and "ld",
the most important executables in the package, are not themselves
binary utilities; which makes the package name a strange choice.
I am assuming of course that when it says "binary utilities" it means
"utilities for use on ELF binaries", not "utilities that are binary"
(that is, in a non-text format, or indeed base-2).
> There is also the name problem. Is the GNU assembler named GNU assembler or
> does it just mean the assembler written by the GNU folks? What is their
> name for the assembler?
If the initial "GNU" goes only with "assembler", that leaves "linker"
in a strange position. I've always assumed it describes all of them.
> The programs in this package are used to assemble, link and manipulate
> binary and object files. They may be used in conjunction with a compiler
> and various libraries to build programs.
>
> To me the long description is simply unfortunate. One could think
> (depending on the command of the English language and programming
> experience) that assemble, link and manipulate are valid operations for
> binaries as well as object files. "They *may be used* ... to build" is
> wrong - they *are* used.
Agreed about the strangeness of some of those verb/noun combinations -
besides, isn't "manipulate" a broad enough term to cover both
"assemble" and "link"? And aren't the object files themselves
technically (non-executable) ELF binary files?
I don't entirely agree about the "may" though - it only means that
they "can" be used, which is fair enough because having binutils
installed doesn't force me to use them.
> Perhaps a possible rewording for the description is (recycling the
> upstream (1) description:
>
> Description: GNU utilities to create and manipulate executable files
> The GNU binutils have been written to give the GNU system the facility to
> compile and link programs. They are used during the build process and have
> been ported most major Unix variants as well as Wintel systems.
>
> An alternative to the first sentence might be:
>
> The GNU binutils are used to compile assembly programs to object files, to
> link them to executable files and to manipulate the binaries.
Those are both a bit unclear about whether it includes a compiler.
The much less modified suggestion I was contemplating earlier this
year was one that went:
Description: GNU binary utilities, including assembler and linker tools
This package provides the GNU binary utilities, together with the
GNU assembler (as) and GNU linker (ld). These programs are used to
manipulate program object code, and in conjunction with a compiler
and various libraries to build executable binaries.
Homepage: http://www.gnu.org/software/binutils
I abandoned that because I wasn't convinced anyone else would care,
but it looks like I was wrong.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: