« back to all changes in this revision
Viewing changes to doc/refman.html
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Package Import Robot
- Author(s): Stéphane Glondu, Stéphane Glondu, Mehdi Dogguy
- Date: 2012-07-01 22:10:36 UTC
- Revision ID: package-import@ubuntu.com-20120701221036-qwibgq0sf2x6mkyr
Tags: 0.6.1
[ Stéphane Glondu ]
* Initial packaging
[ Mehdi Dogguy ]
* Initial Release (Closes: #679547)
* Initial packaging
[ Mehdi Dogguy ]
* Initial Release (Closes: #679547)
- files added:
- bin
- debian
- debian/source
- doc
- examples
- examples/download
- examples/monitor
- examples/tracker
- frontends
- lib
- media
added
removed
doc/refman.html
1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4
<head>
5
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
6
<meta name="generator" content="AsciiDoc 8.6.7" />
7
<title>Ben’s reference manual</title>
8
<style type="text/css">
9
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
10
11
/* Default font. */
12
body {
13
font-family: Georgia,serif;
14
}
15
16
/* Title font. */
17
h1, h2, h3, h4, h5, h6,
18
div.title, caption.title,
19
thead, p.table.header,
20
#toctitle,
21
#author, #revnumber, #revdate, #revremark,
22
#footer {
23
font-family: Arial,Helvetica,sans-serif;
24
}
25
26
body {
27
margin: 1em 5% 1em 5%;
28
}
29
30
a {
31
color: blue;
32
text-decoration: underline;
33
}
34
a:visited {
35
color: fuchsia;
36
}
37
38
em {
39
font-style: italic;
40
color: navy;
41
}
42
43
strong {
44
font-weight: bold;
45
color: #083194;
46
}
47
48
h1, h2, h3, h4, h5, h6 {
49
color: #527bbd;
50
margin-top: 1.2em;
51
margin-bottom: 0.5em;
52
line-height: 1.3;
53
}
54
55
h1, h2, h3 {
56
border-bottom: 2px solid silver;
57
}
58
h2 {
59
padding-top: 0.5em;
60
}
61
h3 {
62
float: left;
63
}
64
h3 + * {
65
clear: left;
66
}
67
h5 {
68
font-size: 1.0em;
69
}
70
71
div.sectionbody {
72
margin-left: 0;
73
}
74
75
hr {
76
border: 1px solid silver;
77
}
78
79
p {
80
margin-top: 0.5em;
81
margin-bottom: 0.5em;
82
}
83
84
ul, ol, li > p {
85
margin-top: 0;
86
}
87
ul > li { color: #aaa; }
88
ul > li > * { color: black; }
89
90
pre {
91
padding: 0;
92
margin: 0;
93
}
94
95
#author {
96
color: #527bbd;
97
font-weight: bold;
98
font-size: 1.1em;
99
}
100
#email {
101
}
102
#revnumber, #revdate, #revremark {
103
}
104
105
#footer {
106
font-size: small;
107
border-top: 2px solid silver;
108
padding-top: 0.5em;
109
margin-top: 4.0em;
110
}
111
#footer-text {
112
float: left;
113
padding-bottom: 0.5em;
114
}
115
#footer-badges {
116
float: right;
117
padding-bottom: 0.5em;
118
}
119
120
#preamble {
121
margin-top: 1.5em;
122
margin-bottom: 1.5em;
123
}
124
div.imageblock, div.exampleblock, div.verseblock,
125
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
126
div.admonitionblock {
127
margin-top: 1.0em;
128
margin-bottom: 1.5em;
129
}
130
div.admonitionblock {
131
margin-top: 2.0em;
132
margin-bottom: 2.0em;
133
margin-right: 10%;
134
color: #606060;
135
}
136
137
div.content { /* Block element content. */
138
padding: 0;
139
}
140
141
/* Block element titles. */
142
div.title, caption.title {
143
color: #527bbd;
144
font-weight: bold;
145
text-align: left;
146
margin-top: 1.0em;
147
margin-bottom: 0.5em;
148
}
149
div.title + * {
150
margin-top: 0;
151
}
152
153
td div.title:first-child {
154
margin-top: 0.0em;
155
}
156
div.content div.title:first-child {
157
margin-top: 0.0em;
158
}
159
div.content + div.title {
160
margin-top: 0.0em;
161
}
162
163
div.sidebarblock > div.content {
164
background: #ffffee;
165
border: 1px solid #dddddd;
166
border-left: 4px solid #f0f0f0;
167
padding: 0.5em;
168
}
169
170
div.listingblock > div.content {
171
border: 1px solid #dddddd;
172
border-left: 5px solid #f0f0f0;
173
background: #f8f8f8;
174
padding: 0.5em;
175
}
176
177
div.quoteblock, div.verseblock {
178
padding-left: 1.0em;
179
margin-left: 1.0em;
180
margin-right: 10%;
181
border-left: 5px solid #f0f0f0;
182
color: #888;
183
}
184
185
div.quoteblock > div.attribution {
186
padding-top: 0.5em;
187
text-align: right;
188
}
189
190
div.verseblock > pre.content {
191
font-family: inherit;
192
font-size: inherit;
193
}
194
div.verseblock > div.attribution {
195
padding-top: 0.75em;
196
text-align: left;
197
}
198
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
199
div.verseblock + div.attribution {
200
text-align: left;
201
}
202
203
div.admonitionblock .icon {
204
vertical-align: top;
205
font-size: 1.1em;
206
font-weight: bold;
207
text-decoration: underline;
208
color: #527bbd;
209
padding-right: 0.5em;
210
}
211
div.admonitionblock td.content {
212
padding-left: 0.5em;
213
border-left: 3px solid #dddddd;
214
}
215
216
div.exampleblock > div.content {
217
border-left: 3px solid #dddddd;
218
padding-left: 0.5em;
219
}
220
221
div.imageblock div.content { padding-left: 0; }
222
span.image img { border-style: none; }
223
a.image:visited { color: white; }
224
225
dl {
226
margin-top: 0.8em;
227
margin-bottom: 0.8em;
228
}
229
dt {
230
margin-top: 0.5em;
231
margin-bottom: 0;
232
font-style: normal;
233
color: navy;
234
}
235
dd > *:first-child {
236
margin-top: 0.1em;
237
}
238
239
ul, ol {
240
list-style-position: outside;
241
}
242
ol.arabic {
243
list-style-type: decimal;
244
}
245
ol.loweralpha {
246
list-style-type: lower-alpha;
247
}
248
ol.upperalpha {
249
list-style-type: upper-alpha;
250
}
251
ol.lowerroman {
252
list-style-type: lower-roman;
253
}
254
ol.upperroman {
255
list-style-type: upper-roman;
256
}
257
258
div.compact ul, div.compact ol,
259
div.compact p, div.compact p,
260
div.compact div, div.compact div {
261
margin-top: 0.1em;
262
margin-bottom: 0.1em;
263
}
264
265
tfoot {
266
font-weight: bold;
267
}
268
td > div.verse {
269
white-space: pre;
270
}
271
272
div.hdlist {
273
margin-top: 0.8em;
274
margin-bottom: 0.8em;
275
}
276
div.hdlist tr {
277
padding-bottom: 15px;
278
}
279
dt.hdlist1.strong, td.hdlist1.strong {
280
font-weight: bold;
281
}
282
td.hdlist1 {
283
vertical-align: top;
284
font-style: normal;
285
padding-right: 0.8em;
286
color: navy;
287
}
288
td.hdlist2 {
289
vertical-align: top;
290
}
291
div.hdlist.compact tr {
292
margin: 0;
293
padding-bottom: 0;
294
}
295
296
.comment {
297
background: yellow;
298
}
299
300
.footnote, .footnoteref {
301
font-size: 0.8em;
302
}
303
304
span.footnote, span.footnoteref {
305
vertical-align: super;
306
}
307
308
#footnotes {
309
margin: 20px 0 20px 0;
310
padding: 7px 0 0 0;
311
}
312
313
#footnotes div.footnote {
314
margin: 0 0 5px 0;
315
}
316
317
#footnotes hr {
318
border: none;
319
border-top: 1px solid silver;
320
height: 1px;
321
text-align: left;
322
margin-left: 0;
323
width: 20%;
324
min-width: 100px;
325
}
326
327
div.colist td {
328
padding-right: 0.5em;
329
padding-bottom: 0.3em;
330
vertical-align: top;
331
}
332
div.colist td img {
333
margin-top: 0.3em;
334
}
335
336
@media print {
337
#footer-badges { display: none; }
338
}
339
340
#toc {
341
margin-bottom: 2.5em;
342
}
343
344
#toctitle {
345
color: #527bbd;
346
font-size: 1.1em;
347
font-weight: bold;
348
margin-top: 1.0em;
349
margin-bottom: 0.1em;
350
}
351
352
div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
353
margin-top: 0;
354
margin-bottom: 0;
355
}
356
div.toclevel2 {
357
margin-left: 2em;
358
font-size: 0.9em;
359
}
360
div.toclevel3 {
361
margin-left: 4em;
362
font-size: 0.9em;
363
}
364
div.toclevel4 {
365
margin-left: 6em;
366
font-size: 0.9em;
367
}
368
369
span.aqua { color: aqua; }
370
span.black { color: black; }
371
span.blue { color: blue; }
372
span.fuchsia { color: fuchsia; }
373
span.gray { color: gray; }
374
span.green { color: green; }
375
span.lime { color: lime; }
376
span.maroon { color: maroon; }
377
span.navy { color: navy; }
378
span.olive { color: olive; }
379
span.purple { color: purple; }
380
span.red { color: red; }
381
span.silver { color: silver; }
382
span.teal { color: teal; }
383
span.white { color: white; }
384
span.yellow { color: yellow; }
385
386
span.aqua-background { background: aqua; }
387
span.black-background { background: black; }
388
span.blue-background { background: blue; }
389
span.fuchsia-background { background: fuchsia; }
390
span.gray-background { background: gray; }
391
span.green-background { background: green; }
392
span.lime-background { background: lime; }
393
span.maroon-background { background: maroon; }
394
span.navy-background { background: navy; }
395
span.olive-background { background: olive; }
396
span.purple-background { background: purple; }
397
span.red-background { background: red; }
398
span.silver-background { background: silver; }
399
span.teal-background { background: teal; }
400
span.white-background { background: white; }
401
span.yellow-background { background: yellow; }
402
403
span.big { font-size: 2em; }
404
span.small { font-size: 0.6em; }
405
406
span.underline { text-decoration: underline; }
407
span.overline { text-decoration: overline; }
408
span.line-through { text-decoration: line-through; }
409
410
div.unbreakable { page-break-inside: avoid; }
411
412
413
/*
414
* xhtml11 specific
415
*
416
* */
417
418
tt {
419
font-family: "Courier New", Courier, monospace;
420
font-size: inherit;
421
color: navy;
422
}
423
424
div.tableblock {
425
margin-top: 1.0em;
426
margin-bottom: 1.5em;
427
}
428
div.tableblock > table {
429
border: 3px solid #527bbd;
430
}
431
thead, p.table.header {
432
font-weight: bold;
433
color: #527bbd;
434
}
435
p.table {
436
margin-top: 0;
437
}
438
/* Because the table frame attribute is overriden by CSS in most browsers. */
439
div.tableblock > table[frame="void"] {
440
border-style: none;
441
}
442
div.tableblock > table[frame="hsides"] {
443
border-left-style: none;
444
border-right-style: none;
445
}
446
div.tableblock > table[frame="vsides"] {
447
border-top-style: none;
448
border-bottom-style: none;
449
}
450
451
452
/*
453
* html5 specific
454
*
455
* */
456
457
.monospaced {
458
font-family: "Courier New", Courier, monospace;
459
font-size: inherit;
460
color: navy;
461
}
462
463
table.tableblock {
464
margin-top: 1.0em;
465
margin-bottom: 1.5em;
466
}
467
thead, p.tableblock.header {
468
font-weight: bold;
469
color: #527bbd;
470
}
471
p.tableblock {
472
margin-top: 0;
473
}
474
table.tableblock {
475
border-width: 3px;
476
border-spacing: 0px;
477
border-style: solid;
478
border-color: #527bbd;
479
border-collapse: collapse;
480
}
481
th.tableblock, td.tableblock {
482
border-width: 1px;
483
padding: 4px;
484
border-style: solid;
485
border-color: #527bbd;
486
}
487
488
table.tableblock.frame-topbot {
489
border-left-style: hidden;
490
border-right-style: hidden;
491
}
492
table.tableblock.frame-sides {
493
border-top-style: hidden;
494
border-bottom-style: hidden;
495
}
496
table.tableblock.frame-none {
497
border-style: hidden;
498
}
499
500
th.tableblock.halign-left, td.tableblock.halign-left {
501
text-align: left;
502
}
503
th.tableblock.halign-center, td.tableblock.halign-center {
504
text-align: center;
505
}
506
th.tableblock.halign-right, td.tableblock.halign-right {
507
text-align: right;
508
}
509
510
th.tableblock.valign-top, td.tableblock.valign-top {
511
vertical-align: top;
512
}
513
th.tableblock.valign-middle, td.tableblock.valign-middle {
514
vertical-align: middle;
515
}
516
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
517
vertical-align: bottom;
518
}
519
520
521
/*
522
* manpage specific
523
*
524
* */
525
526
body.manpage h1 {
527
padding-top: 0.5em;
528
padding-bottom: 0.5em;
529
border-top: 2px solid silver;
530
border-bottom: 2px solid silver;
531
}
532
body.manpage h2 {
533
border-style: none;
534
}
535
body.manpage div.sectionbody {
536
margin-left: 3em;
537
}
538
539
@media print {
540
body.manpage div#toc { display: none; }
541
}
542
@media screen {
543
body {
544
max-width: 50em; /* approximately 80 characters wide */
545
margin-left: 16em;
546
}
547
548
#toc {
549
position: fixed;
550
top: 0;
551
left: 0;
552
bottom: 0;
553
width: 13em;
554
padding: 0.5em;
555
padding-bottom: 1.5em;
556
margin: 0;
557
overflow: auto;
558
border-right: 3px solid #f8f8f8;
559
background-color: white;
560
}
561
562
#toc .toclevel1 {
563
margin-top: 0.5em;
564
}
565
566
#toc .toclevel2 {
567
margin-top: 0.25em;
568
display: list-item;
569
color: #aaaaaa;
570
}
571
572
#toctitle {
573
margin-top: 0.5em;
574
}
575
}
576
</style>
577
<script type="text/javascript">
578
/*<+'])');
621
// Function that scans the DOM tree for header elements (the DOM2
622
// nodeIterator API would be a better technique but not supported by all
623
// browsers).
624
var iterate = function (el) {
625
for (var i = el.firstChild; i != null; i = i.nextSibling) {
626
if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
627
var mo = re.exec(i.tagName);
628
if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
629
result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
630
}
631
iterate(i);
632
}
633
}
634
}
635
iterate(el);
636
return result;
637
}
638
639
var toc = document.getElementById("toc");
640
if (!toc) {
641
return;
642
}
643
644
// Delete existing TOC entries in case we're reloading the TOC.
645
var tocEntriesToRemove = [];
646
var i;
647
for (i = 0; i < toc.childNodes.length; i++) {
648
var entry = toc.childNodes[i];
649
if (entry.nodeName.toLowerCase() == 'div'
650
&& entry.getAttribute("class")
651
&& entry.getAttribute("class").match(/^toclevel/))
652
tocEntriesToRemove.push(entry);
653
}
654
for (i = 0; i < tocEntriesToRemove.length; i++) {
655
toc.removeChild(tocEntriesToRemove[i]);
656
}
657
658
// Rebuild TOC entries.
659
var entries = tocEntries(document.getElementById("content"), toclevels);
660
for (var i = 0; i < entries.length; ++i) {
661
var entry = entries[i];
662
if (entry.element.id == "")
663
entry.element.id = "_toc_" + i;
664
var a = document.createElement("a");
665
a.href = "#" + entry.element.id;
666
a.appendChild(document.createTextNode(entry.text));
667
var div = document.createElement("div");
668
div.appendChild(a);
669
div.className = "toclevel" + entry.toclevel;
670
toc.appendChild(div);
671
}
672
if (entries.length == 0)
673
toc.parentNode.removeChild(toc);
674
},
675
676
677
/////////////////////////////////////////////////////////////////////
678
// Footnotes generator
679
/////////////////////////////////////////////////////////////////////
680
681
/* Based on footnote generation code from:
682
* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
683
*/
684
685
footnotes: function () {
686
// Delete existing footnote entries in case we're reloading the footnodes.
687
var i;
688
var noteholder = document.getElementById("footnotes");
689
if (!noteholder) {
690
return;
691
}
692
var entriesToRemove = [];
693
for (i = 0; i < noteholder.childNodes.length; i++) {
694
var entry = noteholder.childNodes[i];
695
if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
696
entriesToRemove.push(entry);
697
}
698
for (i = 0; i < entriesToRemove.length; i++) {
699
noteholder.removeChild(entriesToRemove[i]);
700
}
701
702
// Rebuild footnote entries.
703
var cont = document.getElementById("content");
704
var spans = cont.getElementsByTagName("span");
705
var refs = {};
706
var n = 0;
707
for (i=0; i<spans.length; i++) {
708
if (spans[i].className == "footnote") {
709
n++;
710
var note = spans[i].getAttribute("data-note");
711
if (!note) {
712
// Use [\s\S] in place of . so multi-line matches work.
713
// Because JavaScript has no s (dotall) regex flag.
714
note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
715
spans[i].innerHTML =
716
"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
717
"' title='View footnote' class='footnote'>" + n + "</a>]";
718
spans[i].setAttribute("data-note", note);
719
}
720
noteholder.innerHTML +=
721
"<div class='footnote' id='_footnote_" + n + "'>" +
722
"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
723
n + "</a>. " + note + "</div>";
724
var id =spans[i].getAttribute("id");
725
if (id != null) refs["#"+id] = n;
726
}
727
}
728
if (n == 0)
729
noteholder.parentNode.removeChild(noteholder);
730
else {
731
// Process footnoterefs.
732
for (i=0; i<spans.length; i++) {
733
if (spans[i].className == "footnoteref") {
734
var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
735
href = href.match(/#.*/)[0]; // Because IE return full URL.
736
n = refs[href];
737
spans[i].innerHTML =
738
"[<a href='#_footnote_" + n +
739
"' title='View footnote' class='footnote'>" + n + "</a>]";
740
}
741
}
742
}
743
},
744
745
install: function(toclevels) {
746
var timerId;
747
748
function reinstall() {
749
asciidoc.footnotes();
750
if (toclevels) {
751
asciidoc.toc(toclevels);
752
}
753
}
754
755
function reinstallAndRemoveTimer() {
756
clearInterval(timerId);
757
reinstall();
758
}
759
760
timerId = setInterval(reinstall, 500);
761
if (document.addEventListener)
762
document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
763
else
764
window.onload = reinstallAndRemoveTimer;
765
}
766
767
}
768
asciidoc.install(2);
769
/*]]>*/
770
</script>
771
</head>
772
<body class="article">
773
<div id="header">
774
<h1>Ben’s reference manual</h1>
775
<span id="author">Mehdi Dogguy and Stéphane Glondu</span><br />
776
<span id="revnumber">version 0.6,</span>
777
<span id="revdate">May 30, 2012</span>
778
<div id="toc">
779
<div id="toctitle">Table of Contents</div>
780
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
781
</div>
782
</div>
783
<div id="content">
784
<div id="preamble">
785
<div class="sectionbody">
786
<div class="paragraph"><p>This manual is free software; you may redistribute it and/or modify it
787
under the terms of the GNU General Public License as published by the
788
Free Software Foundation; either version 2, or (at your option) any
789
later version.</p></div>
790
<div class="paragraph"><p>This is distributed in the hope that it will be useful, but without
791
any warranty; without even the implied warranty of merchantability or
792
fitness for a particular purpose. See the GNU General Public License
793
for more details.</p></div>
794
<div class="paragraph"><p>A copy of the GNU General Public License is available as
795
/usr/share/common-licenses/GPL-2 in the Debian GNU/Linux distribution
796
or on the World Wide Web at the GNU web site. You can also obtain it
797
by writing to the Free Software Foundation, Inc., 51 Franklin Street,
798
Fifth Floor, Boston, MA 02110-1301, USA.</p></div>
799
<div class="admonitionblock">
800
<table><tr>
801
<td class="icon">
802
<img src="./images/icons/warning.png" alt="Warning" />
803
</td>
804
<td class="content">This document is still work in progress!</td>
805
</tr></table>
806
</div>
807
</div>
808
</div>
809
<div class="sect1">
810
<h2 id="_introduction">Introduction</h2>
811
<div class="sectionbody">
812
<div class="paragraph"><p><em>Ben</em> is the name of a set of utilities written in
813
<a href="http://caml.inria.fr">OCaml</a> and available through the <tt>ben</tt>
814
command. The major feature of <em>Ben</em> is to provide a full featured
815
transition tracker to follow the evolution of a set of packages in the
816
Debian archive.</p></div>
817
<div class="paragraph"><p>The aim of this document is to describe the features of <em>Ben</em> and its
818
configuration.</p></div>
819
</div>
820
</div>
821
<div class="sect1">
822
<h2 id="_getting_the_source_code">1. Getting the source code</h2>
823
<div class="sectionbody">
824
<div class="paragraph"><p><em>Ben</em> is maintained in a Git repository available online at
825
<a href="http://anonscm.debian.org/gitweb/?p=collab-maint/ben.git">http://anonscm.debian.org/gitweb/?p=collab-maint/ben.git</a>. Getting the
826
sources is as simple as:</p></div>
827
<div class="listingblock">
828
<div class="content"><!-- Generator: GNU source-highlight 3.1.6
829
by Lorenzo Bettini
830
http://www.lorenzobettini.it
831
http://www.gnu.org/software/src-highlite -->
832
<pre><tt>git clone git<span style="color: #990000">:</span>//anonscm<span style="color: #990000">.</span>debian<span style="color: #990000">.</span>org/collab-maint/ben<span style="color: #990000">.</span>git</tt></pre></div></div>
833
<div class="paragraph"><p>The source tree has a <tt>debian/</tt> directory. It is a native
834
Debian package, so you can use the standard building tools in order to
835
build it.</p></div>
836
</div>
837
</div>
838
<div class="sect1">
839
<h2 id="_query_language">2. Query language</h2>
840
<div class="sectionbody">
841
<div class="paragraph"><p>The main feature of <em>Ben</em> is a transition tracker. The
842
transition tracker selects a set of affected packages and computes a
843
state for each of them. There exist already various ways to do
844
that. One solution would be to use the
845
<a href="http://packages.debian.org/sid/dctrl-tools">dctrl-tools</a>. We chose to
846
make our own language. This allows us to perform more fine-grained
847
queries, optimize queries and extend the query language easily.</p></div>
848
<div class="paragraph"><p>A ben query is decribed by the following
849
<a href="http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form">BNF</a> formulae:</p></div>
850
<div class="literalblock">
851
<div class="content">
852
<pre><tt><query> ::= "true"
853
| "false"
854
| "!" <query> /* Boolean negation */
855
| <query> "|" <query> /* Boolean OR operator */
856
| <query> "&" <query> /* Boolean AND operator */
857
| "(" <query> ")"
858
/*set 2*/ | <field> "~" "/" <regex> "/"
859
| <field> "~" '"' <string> '"'
860
| "source"
861
| <comparison> '"' <string> '"'</tt></pre>
862
</div></div>
863
<div class="literalblock">
864
<div class="content">
865
<pre><tt><field> ::= '.' <string></tt></pre>
866
</div></div>
867
<div class="literalblock">
868
<div class="content">
869
<pre><tt><comparison> ::= '<<' | '<' | '>' | '>>' | '=' | '<=' | '>='</tt></pre>
870
</div></div>
871
<div class="paragraph"><p>The first rules are the usual boolean constants and operators. The
872
sixth rule is useful to group queries and override boolean operators'
873
priotity.</p></div>
874
<div class="paragraph"><p>The second set are the various type of queries implemented to match
875
against different criteria. It matches against a package field (in
876
lowercase).</p></div>
877
<div class="paragraph"><p>We believe the syntax of queries is easy to grasp. Nonetheless,
878
here are some exemples:</p></div>
879
<div class="ulist"><ul>
880
<li>
881
<p>
882
<tt>.build-depends ~ /lib.*ocaml-dev/</tt><br />
883
This query matches all packages that build-depend on a package
884
whose name matches the <a href="http://perldoc.perl.org/perlre.html">Perl
885
regular expression</a> <tt>lib.*ocaml-dev</tt>.
886
</p>
887
</li>
888
<li>
889
<p>
890
<tt>.depends ~ "libapt-pkg4.12"</tt><br />
891
This one is simpler than the first one in the sense that
892
<tt>libapt-pkg4.12</tt> is considered as a plain string and not a regular
893
experssion.
894
</p>
895
</li>
896
</ul></div>
897
<div class="admonitionblock">
898
<table><tr>
899
<td class="icon">
900
<img src="./images/icons/important.png" alt="Important" />
901
</td>
902
<td class="content">Note the symbols around the selectors: /…/ for
903
regular expressions and "…" for plain strings.</td>
904
</tr></table>
905
</div>
906
<div class="admonitionblock">
907
<table><tr>
908
<td class="icon">
909
<img src="./images/icons/warning.png" alt="Warning" />
910
</td>
911
<td class="content">Packages fields may contain a list of values
912
comma-separated. <em>Ben</em> splits the list before looking with
913
"…" for a match.</td>
914
</tr></table>
915
</div>
916
<div class="ulist"><ul>
917
<li>
918
<p>
919
<tt>>= "3.0"</tt><br />
920
The query <tt>>= "3.0"</tt> matches all packages with a version number
921
equal to or higher than "3.0".
922
</p>
923
</li>
924
<li>
925
<p>
926
<tt>source</tt><br />
927
This matches all source packages.
928
</p>
929
</li>
930
</ul></div>
931
<div class="paragraph"><p>Now that the concept of query is explained, we will focus on other
932
parts of <em>Ben</em>. We will see how we can use the queries for each
933
frontend.</p></div>
934
</div>
935
</div>
936
<div class="sect1">
937
<h2 id="_frontends">3. Frontends</h2>
938
<div class="sectionbody">
939
<div class="paragraph"><p><em>Ben</em> is a set of utilities available through the <tt>ben</tt> command. Each
940
utility is called a <em>frontend</em> and there are four:</p></div>
941
<div class="ulist"><ul>
942
<li>
943
<p>
944
<tt>download</tt>
945
</p>
946
</li>
947
<li>
948
<p>
949
<tt>query</tt>
950
</p>
951
</li>
952
<li>
953
<p>
954
<tt>monitor</tt>
955
</p>
956
</li>
957
<li>
958
<p>
959
<tt>tracker</tt>
960
</p>
961
</li>
962
</ul></div>
963
<div class="paragraph"><p>All frontends share a set of options and each one defines its own
964
specific set. The shared set of command-line options is:</p></div>
965
<div class="tableblock">
966
<table rules="all"
967
width="100%"
968
frame="border"
969
cellspacing="0" cellpadding="4">
970
<col width="50%" />
971
<col width="50%" />
972
<thead>
973
<tr>
974
<th align="left" valign="top"> Option </th>
975
<th align="left" valign="top"> Action</th>
976
</tr>
977
</thead>
978
<tbody>
979
<tr>
980
<td align="left" valign="top"><p class="table">--dry-run</p></td>
981
<td align="left" valign="top"><p class="table">Dry run</p></td>
982
</tr>
983
<tr>
984
<td align="left" valign="top"><p class="table">--quiet|-q</p></td>
985
<td align="left" valign="top"><p class="table">Quiet mode</p></td>
986
</tr>
987
<tr>
988
<td align="left" valign="top"><p class="table">--verbose</p></td>
989
<td align="left" valign="top"><p class="table">Verbose mode</p></td>
990
</tr>
991
<tr>
992
<td align="left" valign="top"><p class="table">--mirror uri</p></td>
993
<td align="left" valign="top"><p class="table">Package mirror to use</p></td>
994
</tr>
995
<tr>
996
<td align="left" valign="top"><p class="table">--mirror-binaries uri</p></td>
997
<td align="left" valign="top"><p class="table">Package mirror to use for binaries</p></td>
998
</tr>
999
<tr>
1000
<td align="left" valign="top"><p class="table">--mirror-sources uri</p></td>
1001
<td align="left" valign="top"><p class="table">Package mirror to use for sources</p></td>
1002
</tr>
1003
<tr>
1004
<td align="left" valign="top"><p class="table">--areas a,…</p></td>
1005
<td align="left" valign="top"><p class="table">Areas to consider (comma separated)</p></td>
1006
</tr>
1007
<tr>
1008
<td align="left" valign="top"><p class="table">--archs a,…</p></td>
1009
<td align="left" valign="top"><p class="table">Architectures to consider (comma separated)</p></td>
1010
</tr>
1011
<tr>
1012
<td align="left" valign="top"><p class="table">--suite a</p></td>
1013
<td align="left" valign="top"><p class="table">Suite</p></td>
1014
</tr>
1015
<tr>
1016
<td align="left" valign="top"><p class="table">--cache-dir d</p></td>
1017
<td align="left" valign="top"><p class="table">Path to cache dir</p></td>
1018
</tr>
1019
<tr>
1020
<td align="left" valign="top"><p class="table">--config|-c c</p></td>
1021
<td align="left" valign="top"><p class="table">Config file</p></td>
1022
</tr>
1023
</tbody>
1024
</table>
1025
</div>
1026
<div class="paragraph"><p>The rest of this section describes each frontend.</p></div>
1027
<div class="sect2">
1028
<h3 id="_download">3.1. download</h3>
1029
<div class="paragraph"><p>This frontend is the simplest one as it has no command-line options,
1030
except the shared ones. It downloads all Sources.bz2 files and all
1031
Packages.bz2 files for selected architectures and areas. You may
1032
invoke it by running:</p></div>
1033
<div class="literalblock">
1034
<div class="content">
1035
<pre><tt>$ ben download [options]</tt></pre>
1036
</div></div>
1037
<div class="paragraph"><p>The requested files will be downloaded in $BEN_CACHE_DIR, if set, or
1038
in the current directory.</p></div>
1039
<div class="admonitionblock">
1040
<table><tr>
1041
<td class="icon">
1042
<img src="./images/icons/note.png" alt="Note" />
1043
</td>
1044
<td class="content"><tt>ben download</tt> doesn’t read <tt>ben.cache</tt> files yet.</td>
1045
</tr></table>
1046
</div>
1047
</div>
1048
<div class="sect2">
1049
<h3 id="_query">3.2. query</h3>
1050
<div class="paragraph"><p>This utility is pretty much like
1051
<a href="http://man.cx/grep-dctrl(1)"><tt>grep-dctrl(1)</tt></a>. Given a list of Packages
1052
or Sources files, it performs a query and outputs the result.</p></div>
1053
<div class="paragraph"><p>Using it is as simple as shown below:</p></div>
1054
<div class="literalblock">
1055
<div class="content">
1056
<pre><tt>$ ben query ".package ~ /gentoo/" Packages</tt></pre>
1057
</div></div>
1058
<div class="paragraph"><p>Unlike <tt>grep-dctrl(1)</tt>, <tt>ben query</tt> doesn’t have the necessary
1059
machinery to filter its output yet.</p></div>
1060
<div class="admonitionblock">
1061
<table><tr>
1062
<td class="icon">
1063
<img src="./images/icons/note.png" alt="Note" />
1064
</td>
1065
<td class="content"><tt>ben query</tt> doesn’t read .gz or .bz2 files or on its standard
1066
input yet.</td>
1067
</tr></table>
1068
</div>
1069
<div class="admonitionblock">
1070
<table><tr>
1071
<td class="icon">
1072
<img src="./images/icons/note.png" alt="Note" />
1073
</td>
1074
<td class="content"><tt>ben query</tt> doesn’t read <tt>ben.cache</tt> files yet.</td>
1075
</tr></table>
1076
</div>
1077
</div>
1078
<div class="sect2">
1079
<h3 id="_monitor">3.3. monitor</h3>
1080
<div class="paragraph"><p>The <tt>monitor</tt> fontend builds a monitoring page for a transition. A
1081
transition is decribed by three queries:</p></div>
1082
<div class="ulist"><ul>
1083
<li>
1084
<p>
1085
<tt>is_affected</tt>: matches source packages that are part of this
1086
transition; this query is evaluated against all source and binary
1087
packages and, for binary packages, their source package is picked;
1088
</p>
1089
</li>
1090
<li>
1091
<p>
1092
<tt>is_good</tt>: matches binary packages that are considered to be
1093
ready (fixed) for this transition;
1094
</p>
1095
</li>
1096
<li>
1097
<p>
1098
<tt>is_bad</tt>: matches binary packages that are considered to be broken
1099
(not fixed) for this transition.
1100
</p>
1101
</li>
1102
</ul></div>
1103
<div class="paragraph"><p>Not that some packages can be neither good nor bad. For example, there
1104
are many packages that build-depend on some library but do not link
1105
against it. Thus, they do not need any dependency on the library at
1106
runtime.</p></div>
1107
<div class="paragraph"><p>An example of a complete description of a transition is:</p></div>
1108
<div class="literalblock">
1109
<div class="content">
1110
<pre><tt>is_affected = .build-depends ~ /libicu-dev/;
1111
is_good = .depends ~ /libicu44/;
1112
is_bad = .depends ~ /libicu42/;</tt></pre>
1113
</div></div>
1114
<div class="paragraph"><p>There are other optional fields:</p></div>
1115
<div class="ulist"><ul>
1116
<li>
1117
<p>
1118
<tt>title</tt><br />
1119
This puts a nice title in the HTML page.
1120
</p>
1121
</li>
1122
<li>
1123
<p>
1124
<tt>notes</tt><br />
1125
This can be used to put
1126
remarks about the transition or notes about the status of some
1127
packages or the whole transition.<br />
1128
<br />
1129
<em>Ben</em> recognizes some special texts and turns them into links.
1130
The following formats are recognized:
1131
</p>
1132
</li>
1133
</ul></div>
1134
<div class="tableblock">
1135
<table rules="all"
1136
width="100%"
1137
frame="border"
1138
cellspacing="0" cellpadding="4">
1139
<col width="50%" />
1140
<col width="50%" />
1141
<thead>
1142
<tr>
1143
<th align="left" valign="top"> Original text </th>
1144
<th align="left" valign="top"> Result</th>
1145
</tr>
1146
</thead>
1147
<tbody>
1148
<tr>
1149
<td align="left" valign="top"><p class="table">pts:ocaml</p></td>
1150
<td align="left" valign="top"><p class="table"><a href="http://packages.qa.debian.org/ocaml">pts:ocaml</a></p></td>
1151
</tr>
1152
<tr>
1153
<td align="left" valign="top"><p class="table">buildd:ocaml</p></td>
1154
<td align="left" valign="top"><p class="table"><a href="http://buildd.debian.org/ocaml">buildd:ocaml</a></p></td>
1155
</tr>
1156
<tr>
1157
<td align="left" valign="top"><p class="table">#123456</p></td>
1158
<td align="left" valign="top"><p class="table"><a href="http://bugs.debian.org/123456">#123456</a></p></td>
1159
</tr>
1160
<tr>
1161
<td align="left" valign="top"><p class="table"><msg-id></p></td>
1162
<td align="left" valign="top"><p class="table"><a href="http://lists.debian.org/msg-id">http://lists.debian.org/msg-id</a></p></td>
1163
</tr>
1164
<tr>
1165
<td align="left" valign="top"><p class="table">http://example.com</p></td>
1166
<td align="left" valign="top"><p class="table"><a href="http://example.com">http://example.com</a></p></td>
1167
</tr>
1168
</tbody>
1169
</table>
1170
</div>
1171
<div class="paragraph"><p><tt>monitor</tt> understands the following list of command-line options:</p></div>
1172
<div class="tableblock">
1173
<table rules="all"
1174
width="100%"
1175
frame="border"
1176
cellspacing="0" cellpadding="4">
1177
<col width="50%" />
1178
<col width="50%" />
1179
<thead>
1180
<tr>
1181
<th align="left" valign="top"> Option </th>
1182
<th align="left" valign="top"> Action</th>
1183
</tr>
1184
</thead>
1185
<tbody>
1186
<tr>
1187
<td align="left" valign="top"><p class="table">--use-cache</p></td>
1188
<td align="left" valign="top"><p class="table">Use cache</p></td>
1189
</tr>
1190
<tr>
1191
<td align="left" valign="top"><p class="table">--run-debcheck</p></td>
1192
<td align="left" valign="top"><p class="table">Run edos-debcheck and add virtual <tt>.edos-debcheck</tt> field</p></td>
1193
</tr>
1194
<tr>
1195
<td align="left" valign="top"><p class="table">--use-projectb</p></td>
1196
<td align="left" valign="top"><p class="table">Get package lists from Projectb database</p></td>
1197
</tr>
1198
<tr>
1199
<td align="left" valign="top"><p class="table">--color</p></td>
1200
<td align="left" valign="top"><p class="table">Color if text output</p></td>
1201
</tr>
1202
<tr>
1203
<td align="left" valign="top"><p class="table">--text</p></td>
1204
<td align="left" valign="top"><p class="table">Select text output format</p></td>
1205
</tr>
1206
<tr>
1207
<td align="left" valign="top"><p class="table">--html</p></td>
1208
<td align="left" valign="top"><p class="table">Select HTML output format</p></td>
1209
</tr>
1210
</tbody>
1211
</table>
1212
</div>
1213
</div>
1214
<div class="sect2">
1215
<h3 id="_tracker">3.4. tracker</h3>
1216
<div class="paragraph"><p>This frontend uses <tt>monitor</tt> to generate a summary page about all
1217
known transitions. An example of such summary can be found at
1218
<a href="http://release.debian.org/transitions/">http://release.debian.org/transitions/</a>.</p></div>
1219
<div class="paragraph"><p><tt>tracker</tt> has a notion of <tt>profiles</tt> that gives a hint on the
1220
actual state of the transition. The default profiles are:</p></div>
1221
<div class="ulist"><ul>
1222
<li>
1223
<p>
1224
<tt>planned</tt> for known planned transitions or requested but not
1225
processed or acknowledged yet;
1226
</p>
1227
</li>
1228
<li>
1229
<p>
1230
<tt>permanent</tt> is a special profile made to keep an eye on some set of
1231
packages, not necessarily a transition;
1232
</p>
1233
</li>
1234
<li>
1235
<p>
1236
<tt>ongoing</tt> for the actual list of (known) on-going transitions;
1237
</p>
1238
</li>
1239
<li>
1240
<p>
1241
<tt>finished</tt> has a list of some transitions that are almost finished
1242
(e.g. new binary packages migrated but old binary packages left in
1243
testing to not decrease installability, or a finished transition
1244
with a number of still broken packages in testing).
1245
</p>
1246
</li>
1247
</ul></div>
1248
<div class="paragraph"><p>Technically, each <tt>profile</tt> is a sub-directory of the global config
1249
directory<span class="footnote"><br />[<a href="http://release.debian.org/transitions/config/">http://release.debian.org/transitions/config/</a>]<br /></span>. The
1250
latter can be specified by a command-line option.</p></div>
1251
<div class="paragraph"><p>By default, <tt>tracker</tt> looks for a directory named <tt>config</tt> which
1252
should contain a file named <tt>global.conf</tt>, unless otherwise told. It
1253
reads data (<tt>.ben</tt> files) from the <tt>config</tt> directory and outputs the
1254
result in the <tt>base</tt> directory.</p></div>
1255
<div class="paragraph"><p><tt>tracker</tt> has the following command-line options:</p></div>
1256
<div class="tableblock">
1257
<table rules="all"
1258
width="100%"
1259
frame="border"
1260
cellspacing="0" cellpadding="4">
1261
<col width="50%" />
1262
<col width="50%" />
1263
<thead>
1264
<tr>
1265
<th align="left" valign="top"> Option </th>
1266
<th align="left" valign="top"> Action</th>
1267
</tr>
1268
</thead>
1269
<tbody>
1270
<tr>
1271
<td align="left" valign="top"><p class="table">--base|-b [dir]</p></td>
1272
<td align="left" valign="top"><p class="table">Specifies the "base" directory</p></td>
1273
</tr>
1274
<tr>
1275
<td align="left" valign="top"><p class="table">--config-dir|-cd [dir]</p></td>
1276
<td align="left" valign="top"><p class="table">Location of ben trackers</p></td>
1277
</tr>
1278
<tr>
1279
<td align="left" valign="top"><p class="table">--transition|-t [profile/transition]</p></td>
1280
<td align="left" valign="top"><p class="table">Generate only that tracker page</p></td>
1281
</tr>
1282
<tr>
1283
<td align="left" valign="top"><p class="table">--update|-u</p></td>
1284
<td align="left" valign="top"><p class="table">Updates cache files</p></td>
1285
</tr>
1286
<tr>
1287
<td align="left" valign="top"><p class="table">--use-projectb</p></td>
1288
<td align="left" valign="top"><p class="table">Get package lists from Projectb database</p></td>
1289
</tr>
1290
</tbody>
1291
</table>
1292
</div>
1293
</div>
1294
</div>
1295
</div>
1296
<div class="sect1">
1297
<h2 id="_reporting_issues">4. Reporting issues</h2>
1298
<div class="sectionbody">
1299
<div class="paragraph"><p><em>Ben</em> doesn’t have a bug tracker yet. If you experience a bug or if
1300
you’re looking for some help, feel free to contact us directly.</p></div>
1301
</div>
1302
</div>
1303
</div>
1304
<div id="footnotes"><hr /></div>
1305
<div id="footer">
1306
<div id="footer-text">
1307
Version 0.6<br />
1308
Last updated 2012-06-30 19:41:14 CEST
1309
</div>
1310
</div>
1311
</body>
1312
</html>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1