auto-prefix $(SITE) for indextargets Description field

[apt.git] / doc / acquire-additional-files.txt

diff --git a/doc/acquire-additional-files.txt b/doc/acquire-additional-files.txt
index f9a16318db74b28792fbac62bc79961eda946e4b..1b2494535329984723eb8679642ec91931899f45 100644 (file)
--- a/doc/acquire-additional-files.txt
+++ b/doc/acquire-additional-files.txt
@@ -26,19 +26,19 @@ they would be written in a configuration file the configuration
 instructing the Acquire system to download the Packages files would look
 like this (see also apt.conf(5) manpage for configuration file syntax):
 
 instructing the Acquire system to download the Packages files would look
 like this (see also apt.conf(5) manpage for configuration file syntax):
 

-       APT::Acquire::Targets::deb::Packages {
+       Acquire::IndexTargets::deb::Packages {

                MetaKey "$(COMPONENT)/binary-$(ARCHITECTURE)/Packages";
                ShortDescription "Packages";
                MetaKey "$(COMPONENT)/binary-$(ARCHITECTURE)/Packages";
                ShortDescription "Packages";

-               Description "$(SITE) $(RELEASE)/$(COMPONENT) $(ARCHITECTURE) Packages";
+               Description "$(RELEASE)/$(COMPONENT) $(ARCHITECTURE) Packages";

 
                flatMetaKey "Packages";
 
                flatMetaKey "Packages";

-               flatDescription "$(SITE) $(RELEASE) Packages";
+               flatDescription "$(RELEASE) Packages";

 
                Optional "false";
        };
 
 All files which should be downloaded (nicknamed 'Targets') are mentioned
 
                Optional "false";
        };
 
 All files which should be downloaded (nicknamed 'Targets') are mentioned

-below the APT::Acquire::Targets scope. 'deb' is here the type of the
+below the Acquire::IndexTargets scope. 'deb' is here the type of the

 sources.list entry the file should be acquired for. The only other
 supported value is hence 'deb-src'. Beware: You can't specify multiple
 types here and you can't download the same (evaluated) MetaKey from
 sources.list entry the file should be acquired for. The only other
 supported value is hence 'deb-src'. Beware: You can't specify multiple
 types here and you can't download the same (evaluated) MetaKey from


@@ -47,7 +47,7 @@ multiple types!
 After the type you can pick any valid and unique string which preferable
 refers to the file it downloads (In the example we picked 'Packages').
 This string is used as identifier for the target class and accessible as
 After the type you can pick any valid and unique string which preferable
 refers to the file it downloads (In the example we picked 'Packages').
 This string is used as identifier for the target class and accessible as

-'Created-By' e.g. in the "apt-get files" output as detailed below.
+'Created-By' e.g. in the "apt-get indextargets" output as detailed below.

 
 All targets have three main properties you can define:
 * MetaKey: The identifier of the file to be downloaded as used in the
 
 All targets have three main properties you can define:
 * MetaKey: The identifier of the file to be downloaded as used in the


@@ -63,6 +63,10 @@ All targets have three main properties you can define:
   of which file is acquired exactly. Mainly used for progress reporting
   and error messages. apt will e.g. use this string in the Get/Hit/Err
   progress lines.
   of which file is acquired exactly. Mainly used for progress reporting
   and error messages. apt will e.g. use this string in the Get/Hit/Err
   progress lines.

+  An identifier of the site accessed as seen in the sources.list (e.g.
+  "http://example.org/debian" or "file:/path/to/a/repository") is
+  automatically prefixed for this property.
+

 
 Additional optional properties:
 * flat{MetaKey,Description}: APT supports two types of repositories:
 
 Additional optional properties:
 * flat{MetaKey,Description}: APT supports two types of repositories:


@@ -85,30 +89,38 @@ file if it is available and uncompress it for you, just as it will also
 use pdiff patching if provided by the repository and enabled by the
 user. You only have to ensure that the Release file contains the
 information about the compressed files/pdiffs to make this happen.
 use pdiff patching if provided by the repository and enabled by the
 user. You only have to ensure that the Release file contains the
 information about the compressed files/pdiffs to make this happen.

-NO properties have to be set to enable this.
+*NO* properties have to be set to enable this!
+
+
+Additional properties exist, but these should *NOT* be set by frontends
+requesting files. They exist for internal and end-user usage only:
+* PDiffs: controls if apt will try to use pdiffs for this target.
+  Defaults to the value of Acquire::PDiffs which is true by default.
+  Can be overridden per-source by the sources.list option of the same
+  name. See the documentation for both of these for details.

 
 # More examples
 
 The stanzas for Translation-* files as well as for Sources files would
 look like this:
 
 
 # More examples
 
 The stanzas for Translation-* files as well as for Sources files would
 look like this:
 

-APT::Acquire::Targets {
+Acquire::IndexTargets {

        deb::Translations {
                MetaKey "$(COMPONENT)/i18n/Translation-$(LANGUAGE)";
                ShortDescription "Translation-$(LANGUAGE)";
        deb::Translations {
                MetaKey "$(COMPONENT)/i18n/Translation-$(LANGUAGE)";
                ShortDescription "Translation-$(LANGUAGE)";

-               Description "$(SITE) $(RELEASE)/$(COMPONENT) Translation-$(LANGUAGE)";
+               Description "$(RELEASE)/$(COMPONENT) Translation-$(LANGUAGE)";

 
                flatMetaKey "$(LANGUAGE)";
 
                flatMetaKey "$(LANGUAGE)";

-               flatDescription "$(SITE) $(RELEASE) Translation-$(LANGUAGE)";
+               flatDescription "$(RELEASE) Translation-$(LANGUAGE)";

        };
 
        deb-src::Sources {
                MetaKey "$(COMPONENT)/source/Sources";
                ShortDescription "Sources";
        };
 
        deb-src::Sources {
                MetaKey "$(COMPONENT)/source/Sources";
                ShortDescription "Sources";

-               Description "$(SITE) $(RELEASE)/$(COMPONENT) Sources";
+               Description "$(RELEASE)/$(COMPONENT) Sources";

 
                flatMetaKey "Sources";
 
                flatMetaKey "Sources";

-               flatDescription "$(SITE) $(RELEASE) Sources";
+               flatDescription "$(RELEASE) Sources";

 
                Optional "false";
        };
 
                Optional "false";
        };


@@ -121,10 +133,6 @@ by the acquire system. The following variables are known; note that
 unknown variables have no default value nor are they touched: They are
 printed as-is.
 
 unknown variables have no default value nor are they touched: They are
 printed as-is.
 

-* $(SITE): An identifier of the site we access as seen in sources.list,
-  e.g. "http://example.org/debian" or "file:/path/to/a/repository". You
-  can't use this field in {,flat}MetaKey, it is for description proposes
-  only.

 * $(RELEASE): This is usually an archive- or codename, e.g. "stable" or
   "stretch".  Note that flat-style repositories do not have a archive-
   or codename per-se, so the value might very well be just "/" or so.
 * $(RELEASE): This is usually an archive- or codename, e.g. "stable" or
   "stretch".  Note that flat-style repositories do not have a archive-
   or codename per-se, so the value might very well be just "/" or so.


@@ -152,7 +160,7 @@ design so multiple applications can download and use the same file
 rather than each and every one of them potentially downloads and uses
 its own copy somewhere on disk.
 
 rather than each and every one of them potentially downloads and uses
 its own copy somewhere on disk.
 

-"apt-get files" can be used to get the location as well as other
+"apt-get indextargets" can be used to get the location as well as other

 information about all files downloaded (aka: you will see Packages,
 Sources and Translation-* files here as well). Provide a line of the
 default output format as parameter to filter out all entries which do
 information about all files downloaded (aka: you will see Packages,
 Sources and Translation-* files here as well). Provide a line of the
 default output format as parameter to filter out all entries which do


@@ -161,12 +169,16 @@ own output style. The variables are what you see in the output, just all
 uppercase and wrapped in $(), as in the configuration file.
 
 To get all the filenames of all Translation-en files you can e.g. call:
 uppercase and wrapped in $(), as in the configuration file.
 
 To get all the filenames of all Translation-en files you can e.g. call:

-       apt-get files --format '$(FILENAME)' "Created-By: Translations" "Language: en"
+       apt-get indextargets --format '$(FILENAME)' "Created-By: Translations" "Language: en"
+
+The line-based filtering and the formating is rather crude and feature-
+less by design, so it is recommend to use dedicated and more powerful
+tools like 'grep-dctrl'.

 
 Accessing this information via libapt is done by reading the
 sources.lists (pkgSourceList), iterating over the metaIndex objects this
 creates and calling GetIndexTargets() on them. See the sourcecode of
 
 Accessing this information via libapt is done by reading the
 sources.lists (pkgSourceList), iterating over the metaIndex objects this
 creates and calling GetIndexTargets() on them. See the sourcecode of

-"apt-get files" for a complete example.
+"apt-get indextargets" for a complete example.

 
 Note that by default targets are not listed if they weren't downloaded.
 If you want to see all targets, you can use the --no-release-info, which
 
 Note that by default targets are not listed if they weren't downloaded.
 If you want to see all targets, you can use the --no-release-info, which