diff options
Diffstat (limited to 'man/tbl-dctrl.1')
| -rw-r--r-- | man/tbl-dctrl.1 | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/man/tbl-dctrl.1 b/man/tbl-dctrl.1 new file mode 100644 index 0000000..cca74ee --- /dev/null +++ b/man/tbl-dctrl.1 @@ -0,0 +1,203 @@ +.TH tbl\-dctrl 1 2006-04-02 "Debian Project" "Debian administrator's manual" +\" Copyright (C) 2005 Antti-Juhani Kaijanaho <ajk@debian.org> +\" This program is free software; you can redistribute it and/or modify +\" it under the terms of the GNU General Public License as published by +\" the Free Software Foundation; either version 2 of the License, or +\" (at your option) any later version. +\" +\" This program is distributed in the hope that it will be useful, +\" but WITHOUT ANY WARRANTY; without even the implied warranty of +\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +\" GNU General Public License for more details. +\" +\" You should have received a copy of the GNU General Public License +\" along with this program; see the file COPYING. If not, write to +\" the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +\" Boston, MA 02111-1307, USA. +.SH NAME +tbl\-dctrl \- generate tabular representations of data in dctrl format +.SH SYNOPSIS +.B tbl\-dctrl +[ +.I options +] +.B \-c +.IR column\-specification " ..." +[ +.I filename +] ... +.sp +.B tbl\-dctrl +.B \-\-version +.sp +.B tbl\-dctrl +.B \-\-help +.SH DESCRIPTION +.B tbl\-dctrl +creates tabular representations of data given to it in Debian control +file format. +.PP +By default, +.B tbl\-dctrl +reads the whole database, looking for the longest entry in each +requested column; it then outputs a table, with borders and column +titles, where each column is just wide enough to fit the longest +entry. +. +Most of this behaviour can be customized as described below. +.PP +A column is requested by specifying the +.BR \-c " (" \-\-column ) +switch with a column specification. +. +The simplest kind of a column specification consists solely of the name +of a field. +. +In such a case, +.B tbl\-dctrl +will include in the output a column whose title is the literal column +specification and whose data is drawn from fields with that name. +. +At least one column must be requested. +.PP +There are two optional additions one can make to a column +specification. +. +Prefixing the field name with some text followed by an equality sign +(for example, +.BR "\-c 'Package name=Package'" ) +modifies the column in such a way that the text before the equality +sign is used as the column title, while the text after the equality +sign is used as the name of the field from which data is drawn. +. +One can also append a colon followed by a positive whole number to the +field name. In such a case, the number after the colon specifies the +width of the column. +. +These two additions can be used separately or together. +. +If there are more than one colon, the last one is significant. +. +If there are more than one equals sign, the first one is significant. +. +Other colons and equals signs are used simply as data. +. +Note that the whole column specification must be given to +.B tbl\-dctrl +as one argument, so if it contains spaces, it must be quoted for the +shell. +.PP +If all requested columns have a specified width, +.B tbl\-dctrl +will produce output immediately, not waiting for the whole input to be +read in. +.SH OPTIONS +.TP +.BI \-d " DELIMITER, " \-\-delimiter= DELIMITER +Instead of drawing nice borders to the table, use the specified +delimiter string to delimit columns in a row. +.TP +.BI \-l " LEVEL, " \-\-errorlevel= LEVEL +Set debugging level to LEVEL. LEVEL is one of "fatal", "important", +"informational" and "debug", but the last may not be available, +depending on the compile-time options. These categories are given +here in order; every message that is emitted when "fatal" is in +effect, will be emitted in the "important" error level, and so on. +The default is "important". +.TP +.BI \-V ", " \-\-version +Print out version information. +.TP +.BI \-C ", " \-\-copying +Print out the copyright license. This produces much output; be sure +to redirect or pipe it somewhere (such as your favourite pager). +.TP +.Bi \-h ", " \-\-help +Print out a help summary. +.SH OPERANDS +.B tbl\-dctrl +will read its input from the files named on the command line, +in the specified order. +. +A file called +.B \- +represents the program's standard input stream. +. +If no files are named, the program behaves as if +.B \- +alone had been named, that is, input is read from the standard input +stream. +.SH STDIN +The standard input stream may be used as input as specified above in +the OPERANDS section. +.SH "INPUT FILES" +All input to +.B tbl\-dctrl +is in the format of a Debian control file. +.PP +A Debian control (dctrl) file is a semistructured single-table +database stored in a machine-parseable text file. +. +Such a database consists of a set of records; each record is a mapping +from field names to field content. +. +Textually, records are separated by empty lines, while each field is +encoded as one or more nonempty lines inside a record. +. +A field starts with its name, followed by a colon, followed by the +field content. +. +The colon must reside on the first line of the field, and the first +line must start with no whitespace. +. +Subsequent lines, in contrast, always start with linear whitespace +(one or more space or tab characters). +.PP +When input is read from multiple files, a record separator is implicit +between two adjacent files. +.SH "ENVIRONMENT VARIABLES" +The standard locale environment, specifically its character set +setting, affects the interpretation of input and output as character +streams. +.SH "ASYNCHRONOUS EVENTS" +Standard Unix signals have their usual meaning. +.SH STDOUT +All output is sent to the standard output stream. +. +The output is a tabular representation of the input database restricted +to the specified fields. Logically, the output is a table; when the +.B \-d +option is used, this table is represented simply by separating columns +in each row by the specified delimiter; when the option is not used, a +frame is drawn around the table. The order of the columns is the same +as the order of the column specifications on the command line. +.SH "OUTPUT FILES" +There are no output files. +.SH "EXIT STATUS" +This utility exits with 0 when successful. It uses a nonzero exit +code inconsistently when an error is noticed (this is a bug). +.SH "CONSEQUENCES OF ERRORS" +In case of errors in the input, the output will be partially or +completely garbage. In case of errors in invocation, the program will +refuse to function. +.SH "EXAMPLES" +The following command line pipe outputs a table of all packages, with +their maintainer data, sorted by the maintainer data, that have no +content: +.nf +% grep\-available \-FInstalled\-Size \-\-eq 0 | sort\-dctrl \-kMaintainer \- | + tbl\-dctrl \-cPackage \-cMaintainer +.fi +.SH "SEE ALSO" +.BR ara (1), +.BR apt\-cache (1), +.BR dpkg (8), +.BR dpkg\-awk (1), +.BR dpkg\-query (1), +.BR grep\-dctrl (1), +.BR sort\-dctrl (1) +.SH AUTHOR +The +.B tbl\-dctrl +program and this manual page were written by Antti-Juhani Kaijanaho. + |