Bug#54824: man pages omit information

[Ross Boylan <RossBoylan@stanfordalumni.org>]

Package: apt
Version: Debian

apt.conf(5) refers to apt-get(8), apt-cache(8), and apt-cdrom(8) for
further information.  They refer back to apt.conf, so it seems nobody has
the information.

For example, apt.conf, "The Apt Group," subhead "get"  says to see
apt-get(8) for information about the options.  apt-get, under "OPTIONS" for
-d says "See APT::Get::Download-Only"  
Now maybe this is just a question of wording--that is, apt-get(8) includes
all relevant information about how those options work.  Even if this is so,
 I think the section (8) pages need two things:

1) They need to say "This man page contains entries like APT::xxx::yyy.
This notation refers to section in the apt.conf(5) file, which describes
the meaning of this syntax more fully."   My concern here is that "See
APT::..." is a meaningless cross-reference for someone who hasn't looked at
apt.conf.

2) Use a phrase such as "The corresponding apt.conf entry is
APT::Get::Download-Only" in the individual item entries.  This clarifies
that apt.conf offers no additional information about how those options work
(if that is the case).  I can't really tell from the current docs what the
correct syntax is.   Is it
   APT::Get::Download-Only   ;
or   APT::Get::Download-Only "true" ;

Finally, as wishlist item, I think the apt.conf page should have a
complete, self-contained description of the options.