Bug#663174: [apt] Documentation (apt.conf manual) refers to protocol internals ("Translation" files)
Package: apt
Version: 0.8.15.9
Severity: minor
APT's documentation contains a lot of references to APT protocol
internals, such as repository files. For example, apt.conf's manual page
contains:
Languages
The Languages subsection controls which Translation files are
downloaded and in which order APT tries to display the
Description-Translations. APT will try to display the first available
Description in the Language which is listed at first. Languages can be
defined with their short or long Languagecodes. Note that not all
archives provide Translation files for every Language - especially the
long Languagecodes are rare, so please inform you which ones are
available before you set here impossible values.
This is not very helpful unless one knows what "Translation files",
"Description-Translations", "Description", "Language" and
"Languagecodes" are, or guesses. Furthermore, guessing is not
necessarily easy; see
http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=656946 . As the latter
shows (if that was necessary), users should not be exposed to protocol
internals.
This is especially problematic for "Translation" files, which aren't
documented unless I'm missing something. In general, as reported in
#481129, the protocol is not documented, although it is in reality
documented to some degree in various places like apt-ftparchive's manual
page, the outdated repository HOWTO (
http://www.debian.org/doc/manuals/repository-howto/repository-howto )
and the Debian Reference, sections 2.5.1 to 2.5.4:
http://www.debian.org/doc/manuals/debian-reference/ch02.en.html#_archive_meta_data
Reply to: