Most importantly, the old description line “Using LD, the GNU linker” was completely bogus:
The word "using" is useless. It goes without saying that a manual page first and foremost intends to help with using a program; however, it may also help when changing or replacing the program.
It is useless to repeat the name in the one-line description, and a particularly bad idea to vary the spelling in this place.
The one-line description must never specify the source of the software. Such information belongs into the AUTHORS and HISTORY sections.
What remains is just one single word, “linker”. While the one-line description should indeed be concise, it should also be clear. Even though it is not usually a complete sentence, having some kind of a predicate (which action is performed) and some kind of an object (what does the program operate on) is often helpful.
When designing a one-line description, keep in mind that people often search for it with apropos(1)
, so try to include relevant search terms — of course, without making it sound awkward. For this reason, “linker for binary object files” is minimally better than “link binary object files” because people might search for both “link” or “linker”. While “binary object files” might seem slightly redundant, it is arguably better than just “object files” for the same reason, and because it avoids the inherent ambiguity of the term “object”.
Time spent polishing the one-line description to be as descriptive and concise as possible is almost always well spent. It is the very first thing people see of the manual page, and in the context of apropos(1)
, it's all people have to judge whether that's the page they want to read.
Also note the following details:
The date format changes.
A source string like “binutils-2.17” is no longer needed.
The volume string cannot be overridden, no replacement is needed for “GNU Development Tools”.
Section headers need no quoting.