Author :
Ingo Schwarze
Date :
2025-06-04 21:09:13
Hash :efdeb71d Message :man/pkgconf.1: improve the beginning of the DESCRIPTION
Replace the first paragraph with an adequate description of what the
program actually does, mention the main use case, and avoid vague
wordings like "helps to" and "allow" and misleading wordings like
"development libraries" (this is perfectly adequate for production
builds, too) and "detect" (nothing is automatically detected,
everything has to be specified explicitly in pc(5) configuration
files).
Add a second paragraph introducing the module search path
because that concept is really crucial for the program.
After that, add three paragraphs explaining the classification of
options, in particular how they behave with respect to early exit
and dependency resolution. Admittedly, this requires rather lengthy
text, which is clearly undesirable at this place in a manual page.
But the atrocious user interface design only leaves the choice of
either bothering the reader with a long, complicated description,
or not describing how the program behaves at all.
Postponing the description of these interactions until after the
option list would not be better. Understanding the classification
up front helps to understand the descriptions and purposes of the
individual options.
What is still sorely missing is a precise definition of what the
three different versions of the crucial term "dependency" mean,
and how resolution actually works.
Ingo Schwarze