Add squeeze-updates. Closes: #619693.
[deb/packages.git] / SEARCHES
1
2 SEARCHES
3 ========
4
5 Overview over all types of searches that are supported and which
6 parameters they use.
7
8 general TODO: allow to search for a specific version?
9
10 parameter types:
11 ----------------
12
13 PKG_NAME =~ ^[\w+.-]+$
14 SUITE_NAME =~ ^[\w-]+$
15 ARCHIVE_NAME =~ ^[\w-]+$
16 SECTION_NAME =~ ^[\w-]+$
17 ARCH_NAME =~ ^[\w-]+$
18 PATH_NAME =~ ^[\w.:+/-]+$ <-- what to allow here?
19
20 if an parameter type is suffixes with (s) this means you can
21 specify an array of values separated by commas.
22
23 package, suite, archive, section, and arch can also be specified via
24 PATH_INFO (mode too?). They can not take more than one value then, though.
25
26
27 search for package name:
28 ------------------------
29
30 searchon=names
31
32 required parameters:
33  keywords [PKG_NAME]
34 optional parameters:
35  suite    [SUITE_NAME(s) | 'all']    default='all'
36  archive  [ARCHIVE_NAME(s) | 'all' ] default='all'
37  section  [SECTION_NAME(s) | 'all' ] default='all'
38  arch     [ARCH_NAME(s) | 'any' ]    default='any'
39  exact    [BOOL]                     default=1
40
41 TODO: Allow more than one keyword
42 -> hm? Example?
43 J: If exact is not specified, lookup exact and if that fails show
44 substring matches -- search is cheap? Maybe totally drop exact parameter, and
45 do this always? Less options == easier interface (or so gnome devs say)
46
47         Only in case of $ROOT/<pkg>, exact should be forced and
48         substring/description searches only offered (not performed by default)
49
50 full text search in package names and descriptions:
51 ---------------------------------------------------
52
53 searchon=all (fixme)
54
55 required parameters:
56  keywords [STRING]
57 optional parameters:
58  suite    [SUITE_NAME(s) | 'all']    default='all'
59  archive  [ARCHIVE_NAME(s) | 'all' ] default='all'
60  section  [SECTION_NAME(s) | 'all' ] default='all'
61  arch     [ARCH_NAME(s) | 'any' ]    default='any'
62  exact    [BOOL]                     default=1
63
64 TODO: Allow more than one keyword
65  J: should already work? Only gives hits where keywords are subsequent
66  though...
67
68 display one package:
69 --------------------
70
71 required parameters:
72  package  [PKG_NAME]
73  suite    [SUITE_NAME]
74 optional parameters:
75  archive  [ARCHIVE_NAME(s) | 'default' | 'all' ] default=( us security non-US )
76  section  [SECTION_NAME(s) | 'all' ]             default='all'
77  arch     [ARCH_NAME(s) | 'any' ]                default='any'
78
79 J: Do we really want random path-element order here? Why not force order like
80 in URLS?
81
82 download one package:
83 ---------------------
84
85 required parameters:
86  package  [PKG_NAME]
87  suite    [SUITE_NAME]
88  arch     [ARCH_NAME]
89 optional parameters:
90  archive  [ARCHIVE_NAME(s) | 'default' | 'all' ] default=( us security non-US )
91
92 TODO: support section?
93
94 J: same comments as with one-package-page
95
96 show file list for one package:
97 -------------------------------
98
99 required parameters:
100  package  [PKG_NAME]
101  suite    [SUITE_NAME]
102  arch     [ARCH_NAME]
103 optional parameters:
104  archive  [ARCHIVE_NAME(s) | 'default' | 'all' ] default=( us security non-US )
105
106 TODO: support section?
107
108 J: Same comments as with one-package-page
109
110 search for file:
111 ----------------
112
113 searchon=contents
114
115 required parameters:
116  keyword [PATH_NAME]
117 ?suite   [SUITE_NAME]
118 ?arch    [ARCH_NAME]
119 ?mode    [ 'file' | 'dir' | 'full' ]
120 optional parameters:
121  archive  [ARCHIVE_NAME(s) | 'default' | 'all' ] default=( us security non-US )
122
123 TODO: support section?
124       suite/arch were required in the old version, still are?
125       which modes do we want? The old ones were "files", "dirs+files", "full"
126
127 J: suite is still required, arch is not (it's not even supported atm, but
128 trivially would be). An easy crosslink a la [stable][testing][unstable] would
129 be adviseable
130
131 mode is implemented via exact and fullfilename parameters currently (both
132 cannot be set at the same time), mode would be better indeed. Possibilities
133 are currently "ends-with", "exact filename" and "filename substring". I don't
134 think more would be useful, with 'bin/foo' for example you can then find
135 /usr/bin/foo and /bin/foo and /sbin/foo, but simply not /bin/foobar