--- ORIG/recutils.texi 2013-11-03 06:03:29.000000000 -0800 +++ recutils.texi 2014-02-15 08:42:57.255160622 -0800 @@ -34,5 +34,5 @@ -Copyright @copyright{} 2009-2013 Jose E. Marchesi +Copyright @copyright{} 2009-2014 Jose E. Marchesi -Copyright @copyright{} 1994-2013 Free Software Foundation, Inc. +Copyright @copyright{} 1994-2014 Free Software Foundation, Inc. @@ -346,3 +346,3 @@ @item -On occasions we loose track to the physical location of a book. Did +On occasions we lose track of the physical location of a book. Did we loan it to anyone? Was it lost in the last move? Is it in some @@ -402,3 +402,3 @@ -A recfile is nothing but a text file, which conforms to a few simple +A recfile is nothing but a text file which conforms to a few simple rules. This chapter shows you how, by observing these rules, recfiles @@ -620,5 +620,5 @@ found in the stream of records. This allows you to store different kinds -of records in the same database. For example, consider you have to -maintain a depot. You will need to keep records of both the current -articles and their stock. +of records in the same database. For example, suppose you are +maintaining a depot. You will need to keep track of both what items +are available and when they are sold or restocked. @@ -648,3 +648,3 @@ The collection of records having same types in recfiles are known as -@dfn{record sets} in the recutils jargon. In the example above two +@dfn{record sets} in recutils jargon. In the example above two record sets are defined: one containing articles and the other @@ -652,3 +652,3 @@ -Nothing prevents to have empty record sets in databases. This is +Nothing prevents having empty record sets in databases. This is in fact usually the case when a new recfile is written but no data exists yet. @@ -664,3 +664,4 @@ @cindex default record types -Many simple recfiles do not feature special record. This is because +Special records are not required, and many recfiles do not have them. +This is because all the records contained in the file are of the same type, and their @@ -694,3 +695,3 @@ ``default'' type, whereas the records following the record descriptor -are of type @code{Movement}. Even if it is supported by the format +are of type @code{Movement}. Even though it is supported by the format and the utilities, it is generally not recommended to mix non-typed @@ -708,3 +709,3 @@ -The used noun shall be specific enough in order to characterize the +The used noun should be specific enough in order to characterize the property of the records which matters. For example, in a @@ -726,3 +727,3 @@ As well as a name, it is a good idea to provide a description of the record set. -This is sometimes call the record set's @dfn{documentation} and is specified +This is sometimes called the record set's @dfn{documentation} and is specified using the @code{%doc} field. @@ -735,3 +736,3 @@ It is somewhat similar to a -comment (@pxref{Comments}), but it can be managed easier +comment (@pxref{Comments}), but it can be managed more easily in a programmatic way. @@ -744,3 +745,3 @@ %rec: Contact -%doc: Family, friends and aqaintances (other than business). +%doc: Family, friends and acquaintances (other than business). @@ -836,3 +837,3 @@ you could use a standard tool such as @command{grep} to extract -strings matching a pattern. However, recutils provide a more powerful +strings matching a pattern. However, recutils provides a more powerful and flexible way to lookup data. The following sections explore how @@ -855,3 +856,3 @@ @command{recsel} is an utility whose primary purpose is to select -records from a recfile and print them in the standard output. +records from a recfile and print them on standard output. Consider the following example record set, which we shall assume is @@ -860,3 +861,3 @@ @example -# This database contains a list of both real and fictional persons +# This database contains a list of both real and fictional people # along with their age. @@ -902,6 +903,6 @@ part of the output produced by @command{recsel}. This is because -@command{recsel} is concerned only by the data. +@command{recsel} is concerned only with the data. @command{recsel} will also ``pack'' the records so any extra empty -line that may be between records is not echoed in the output: +lines that may be between records are not echoed in the output: @@ -931,3 +932,3 @@ @noindent -It is a common situation to store data gathered in several recfiles. +It is common to store data gathered in several recfiles. For example, we could have a @file{contacts.rec} file containing @@ -980,4 +981,5 @@ @noindent -This is commutative, so @command{recsel work-contacts.rec -contacts.rec} would output the records of the business contacts first +As mentioned above, the output follows the ordering on the command +line, so @command{recsel work-contacts.rec +contacts.rec} would output the records of @file{work-contacts.rec} first and then the ones from @file{contacts.rec}. @@ -998,3 +1000,3 @@ -Name: Luca Saiou +Name: Luca Saiu Email: positron@@gnu.org @@ -1034,3 +1036,3 @@ because most of the time the user is only interested in the data. -However, using the @code{-d} command line output the record descriptor +However, with the @code{-d} command line option, the record descriptor of the selected type is printed preceding the data records: @@ -1044,3 +1046,3 @@ -Name: Luca Saiou +Name: Luca Saiu Email: positron@@gnu.org @@ -1055,3 +1057,3 @@ @noindent -Note also that if a non-existing record type is specified in @code{-t} +Note also that if a nonexistent record type is specified in @code{-t} then @command{recsel} does nothing. @@ -1064,7 +1066,7 @@ same order they are written in the recfile. However, often it is -desirable to select a subset of the records determined by the position +desirable to select a subset of the records, determined by the position they occupy in their record set. -The @code{-n} command line argument to @command{recsel} allows to do -this in a very easy way. This is how we would retrieve the first +The @code{-n} command line option to @command{recsel} supports doing +this in a natural way. This is how we would retrieve the first contact listed in a contacts database using @command{recsel}: @@ -1078,5 +1080,5 @@ @noindent -Note that the index is 0-based. In case we want to retrieve more +Note that the index is zero-based. If we want to retrieve more records we can specify several indexes to @code{-n} separated by -commas. In case an index is too big then it is simply ignored: +commas. If a given index is too big, it is simply ignored: @@ -1091,5 +1093,5 @@ -@noindent Note that the order in which the records are echoed does not +@noindent With @code{-n}, the order in which the records are echoed does not depend on the order of the indexes passed to @code{-n}. -This means that the output of @command{recsel -n 0,1} will be +For example, the output of @command{recsel -n 0,1} will be identical to the output of @command{recsel -n 1,0}. @@ -1112,6 +1114,5 @@ -@noindent Note that it is possible to mix concrete indexes and index +@noindent It is possible to mix single indexes and index ranges in the same call. For example, @command{recsel -n 0,5-6} would -select the first, the fourth and the fifth records in some record -descriptor. +select the first, sixth and seventh records. @@ -1123,3 +1124,3 @@ if we could ask @command{recsel} to pick up a random recipe. This can -be achieved using the @code{-m} or @code{--random} command line option +be achieved using the @code{-m} (@code{--random}) command line option of @command{recsel}: @@ -1134,3 +1135,3 @@ -@noindent In case we need two recipes, because we will be cooking for +@noindent If we need two recipes, because we will be cooking at both lunch and dinner, we can pass a different number to @code{-m}: @@ -1146,3 +1147,3 @@ Title: Pasta with ragu -Ingredient: 500 gr of Spaghetti. +Ingredient: 500 gr of spaghetti. Ingredient: 2 tomatoes. @@ -1153,3 +1154,3 @@ @noindent -Note that the algorithm used to implement @code{-m} guarantees that +The algorithm used to implement @code{-m} guarantees that you will never get multiple instances of the same record. This means @@ -1162,5 +1163,5 @@ @cindex selection expressions -@dfn{Selection expressions}, also known as ``sexes'' in the recutils +@dfn{Selection expressions}, also known as ``sexes'' in recutils jargon, are infix expressions that can be applied to a record. -A ``sex'' is a predicate which select a subset of records within a recfile. +A ``sex'' is a predicate which selects a subset of records within a recfile. They can be simple expressions involving just one operator and a pair of @@ -1193,3 +1194,2 @@ @example -$ recfix acquaintances.rec $ recsel -e "Age < 18" -P Name acquaintances.rec @@ -1199,8 +1199,5 @@ -@noindent Before the @command{recsel} command there is a call to -@command{recfix}, just in case @file{acquaintances.rec} contains -something problematic. -Let us look at each of the arguments to @command{recsel} in turn: +@noindent Let us look at each of the arguments to @command{recsel} in turn. Firstly we have @code{-e} which tells @command{recsel} to lookup records -matching the expression @code{Age < 18} --- in other words all those persons +matching the expression @code{Age < 18} --- in other words all those people whose ages are less than 18. @@ -1208,4 +1205,5 @@ This is an example of a @dfn{selection expression}. -In this case it is a very simple one, but it can be as complex as needed. -Next there is @code{-P} which tells recsel to print out the value of +In this case it is a simple test, but it can be as complex as needed. + +Next, there is @code{-P} which tells @command{recsel} to print out the value of the @code{Name} field --- because we want just the name, not the entire record. @@ -1216,3 +1214,4 @@ might have the date of birth instead -(otherwise it would be necessary to update the people's ages in the recfile every year). +(otherwise it would be necessary to update the people's ages in the +recfile on every birthday). @@ -1244,3 +1243,3 @@ @noindent Now we can achieve a similar result as before, by looking up -the names of all those persons who were born after a particular date: +the names of all those people who were born after a particular date: @example @@ -1256,11 +1255,13 @@ Note also that this example uses a lower case @code{-p} whereas the preceding example -used the upper case @code{-P}. The difference is, that @code{-p} prints the field name +used the upper case @code{-P}. The difference is that @code{-p} prints the field name and field value, whereas @code{-P} prints just the value. -@command{Recsel} accepts more than one @code{-e} argument, + +@command{recsel} accepts more than one @code{-e} argument, each introducing a selection expression, -in which case records which satisfy all expressions are selected. +in which case the records which satisfy all expressions are selected. You can provide more than one field label to @code{-P} or @code{-p} in order to select additional fields to be displayed. -For example, if you wanted to send an email to all children 14 years of age or older, -and today's date were @w{1st August} 1994, then you could use the following command to get +For example, if you wanted to send an email to all children 14 to 18 +years of age, +and today's date were @w{1st August} 2012, then you could use the following command to get the name and email address of all such children: @@ -1269,3 +1270,4 @@ $ recfix acquaintances.rec -$ recsel -e "Dob >> '31 July 1994' && Dob << '01 August 1998'" -p Name,Email acquaintances.rec +$ recsel -e "Dob >> '31 July 1994' && Dob << '01 August 1998'" \ + -p Name,Email acquaintances.rec Name: Charles Spencer @@ -1274,3 +1276,3 @@ -@noindent As you can see, there is only one such child in the record set. +@noindent As you can see, there is only one such child in our record set. @@ -1281,3 +1283,5 @@ The double quotes are interpreted by the shell (@eg{} @command{bash}) and -the single quotes are part of the string which forms the two dates being compared. +the single quotes are interpreted by @command{recsel}, defining a +string. (And the backslash is interpreted by the shell, the usual +continuation character so that this manual doesn't have a too-long line.) @@ -1285,3 +1289,3 @@ @node SEX Operands -@subsection Operands +@subsection SEX Operands @@ -1314,6 +1318,6 @@ String values are delimited by either the @code{'} character or the -@code{"} character. Whatever delimiter is used, the delimiter closing -the literal shall equal to the delimiter used to open it. +@code{"} character. Whichever delimiter is used, the delimiter closing +the literal must be the same as the delimiter used to open it. -Note that newlines and tabs can be part of a string literal. +Newlines and tabs can be part of a string literal. @@ -1329,3 +1333,3 @@ The @code{'} and @code{"} characters can be part of a string if they -are escaped with a backslash, like in: +are escaped with a backslash, as in: @@ -1340,4 +1344,4 @@ by writing its name. The field name is replaced by a string -containing the field value, covering any possibility with records with -more than one field featuring that name. Examples: +containing the field value, to handle the possibility of records with +more than one field by that name. Examples: @@ -1358,3 +1362,3 @@ @noindent -instead of using the full field name: +instead of using a full field name: @@ -1373,4 +1377,4 @@ @noindent -Will match any record in which there is a field named @samp{Email} -whose value terminates in @samp{.org}. +matches any record in which there is a field named @samp{Email} +whose value terminates in (the literal string) @samp{.org}. If we are interested in the value of some specific email, we can specify @@ -1402,4 +1406,4 @@ -The regexp flavor supported in selection expressions are the POSIX -EREs plus several GNU extensions. @xref{Regular Expressions}. +The regexp syntax supported in selection expressions is POSIX +EREs, with several GNU extensions. @xref{Regular Expressions}. @@ -1434,3 +1438,3 @@ The boolean operators @strong{and} (@code{&&}), @strong{or} -(@code{||}) and @strong{not} (@code{!}) are supported with the same +(@code{||}) and @strong{not} (@code{!})@: are supported with the same semantics as their C counterparts. @@ -1438,10 +1442,5 @@ A compound boolean operator @code{=>} is also supported in order to -ease the elaboration of constraints in records. @code{A => B}, which +ease the elaboration of constraints in records: @code{A => B}, which can be read as ``A implies B'', translates into @code{!A || (A && B)}. -@example -A => B -@end example - - The boolean operators expect integer operands, and will try to convert @@ -1462,4 +1461,3 @@ The match operator (@code{~}) can be used to match a string with a -given regular expression. The supported regexp syntax is described in -the GNU C library manual. +given regular expression (@pxref{Regular Expressions}). @@ -1519,5 +1517,6 @@ @item It is possible to refer to fields by name in selection expressions. -@item Records can have several fields featuring the same name. +@item Records can have several fields with the same name. @end itemize +@noindent It is clear that some backtracking mechanism is needed in the @@ -1525,3 +1524,3 @@ following expression that is deciding whether a ``registration'' in a -webpage shall be rejected: +webpage should be rejected: @@ -1616,3 +1615,3 @@ -And so on. Note that it is possible to select the same field (or +And so on. It is possible to select the same field (or range of fields) more than once just by repeating them in a field @@ -1644,3 +1643,3 @@ -Since the rewrite rules only affect to the fields selected in a single +Since the rewrite rules only affect the fields selected in a single element of the field expression, it is possible to define different @@ -1699,4 +1698,4 @@ sorting is always done in ascending order, and there may be records -not featuring the involved fields, it is not mandatory for the sorting -fields to be mandatory :D. +that lack the involved fields, @ie{} the sorting +fields need not be mandatory. @@ -1706,3 +1705,3 @@ -Consider for example that we want to keep the records in our stockage +Consider for example that we want to keep the records in our inventory system ordered by entry date. We could achieve that by using the @@ -1731,6 +1730,4 @@ problem, and thus the diagnosis tools must not declare a recfile as -invalid because of this. Some tools may provide a way to physically -order the fields in the file. That is certainly the case of the GNU -recutils, where @command{recfix} can be used for that purpose. -@xref{recfix}. +invalid because of this. The utility @command{recfix} provides a way +to physically order the fields in the file (@pxref{recfix}). @@ -1742,3 +1739,3 @@ @example -$ recsel stockage.rec +$ recsel inventory.rec Id: 2 @@ -1826,3 +1823,3 @@ @noindent -Note that the order of the fields in the @code{%sort} field is +The order of the fields in the @code{%sort} field is significant. If we reverse the order in the example above then we get @@ -1860,3 +1857,3 @@ class @code{A} -comes before the class @code{B} even if they got the same score (@code{6.8}). +comes before the class @code{B} even though the score is the same (@code{6.8}). @@ -1889,3 +1886,3 @@ This is really the best way to add contents to a recfile containing -very simple data. However, complex databases may introduce some +simple data. However, complex databases may introduce some difficulties: @@ -1904,5 +1901,5 @@ -To facilitate the insertion of new data a command line utility called +Thus, to facilitate the insertion of new data a command line utility called @command{recins} is included in the recutils. The usage of @command{recins} is -very simple, and can be both used in the command line or called from +very simple, and can be used both in the command line or called from another program. The following subsections discuss several aspects of @@ -1934,3 +1931,3 @@ @noindent -If we invoke recins again on the same database we will be adding a +If we invoke @command{recins} again on the same database we will be adding a second record: @@ -1952,3 +1949,3 @@ The field values provided using @code{-v} are encoded to follow the -rec format conventions. this included multi-line field values. +rec format conventions, including multi-line field values. Consider the following example: @@ -1983,3 +1980,3 @@ -Note that at this moment it is not possible to add new records +At this time, it is not possible to add new records containing comments. @@ -1997,4 +1994,4 @@ @example -$ recins -e "Email = 'foo@@bar.baz'" -f Name -v "Mr. Foo" -f Email -v \ - "new@@bar.baz" contacts.rec +$ recins -e "Email = 'foo@@bar.baz'" -f Name -v "Mr. Foo" \ + -f Email -v "new@@bar.baz" contacts.rec @end example @@ -2010,3 +2007,3 @@ -The records to be replaced can also be specified by index, or by a +The records to be replaced can also be specified by index, or a range of indexes. For example, the following command replaces the @@ -2032,3 +2029,3 @@ the file. If the recfile contains records of just one type the -command assumes that the user is referring these records. +command assumes that the user is referring to these records. @@ -2109,3 +2106,3 @@ Suppose we wanted to delete all items -with an Expiry before a certain date, we could do this with the following command: +with an @code{Expiry} value before a certain date, we could do this with the following command: @@ -2119,3 +2116,3 @@ @footnote{`5/12/2009' means the 12th day of May 2009, @emph{not} the fifth day of December, -even if your LC_TIME environment variable has been set to suggest otherwise.} +even if your @env{LC_TIME} environment variable has been set to suggest otherwise.} The @command{-t} option can be omitted if, and only if, there is no @code{%rec} field @@ -2123,3 +2120,3 @@ -@command{recdel} tries to warn you, if you attempt to perform a delete operation +@command{recdel} tries to warn you if you attempt to perform a delete operation which it deems to be too pervasive. In such cases, it will refuse to run, @@ -2128,4 +2125,5 @@ always correctly guess that you might be deleting more records than intended. -For this reason, you might consider it wise, to use the @command{-c} flag, which causes -the relevant records to be commented out, rather than deleted. +For this reason, it may be wise to use the @command{-c} flag, which causes +the relevant records to be commented out, rather than deleted. (And +of course backups are always wise.) @@ -2175,4 +2173,4 @@ not follow any particular pattern. -If however a large number of similar changes to several records are required then the -there exists the @command{recset} command to make the job easier. +If, however, a large number of similar changes to several records are +required,the @command{recset} command can make the job easier. @@ -2180,5 +2178,5 @@ chapter some typical usage examples are discussed. -As with @command{recdel}, @command{recset} if used erroneously has the potential to make +As with @command{recdel}, erroneously use of @command{recset} has the potential to make very pervasive changes, which could result in a large loss of data. -It is prudent therefore to take a copy of a recfile before running such commands. +It is therefore prudent to take a copy of a recfile before running such commands. @@ -2186,4 +2184,4 @@ @menu -* Setting Fields:: Editing field values. * Adding Fields:: Adding new fields to records. +* Setting Fields:: Editing field values. * Deleting Fields:: Removing or commenting-out fields. @@ -2197,5 +2195,6 @@ -The command @command{recins} adds new records to a recfile. It cannot however -add fields to an existent record, and it would be cumbersome to do so manually. -Such a task can be achieved automatically using @command{recset} and its @command{-a} flag. +As mentioned above, the command @command{recins} adds new records to a +recfile, but it cannot +add fields to an existing record. +This task can be achieved automatically using @command{recset} with its @command{-a} flag. @@ -2208,4 +2207,4 @@ @noindent -Note that, because no record selection flag was provided, the command affected @emph{all} the -records (of type `Item'). +Here, because no record selection flag was provided, the command affected @emph{all} the +records of type `Item'. We could limit the effect of the command using the @command{-e}, @command{-q}, @@ -2213,3 +2212,3 @@ For example to add the `Inspected' field to only the first item the following command -is possible: +would work: @example @@ -2221,3 +2220,3 @@ -If you use @command{recset} with the @command{-a} flag on a field which already exists, a +If you use @command{recset} with the @command{-a} flag on a field that already exists, a new field (in addition to those already present) will be appended with the given value. @@ -2241,6 +2240,6 @@ only affect those records for which a `Inspected' field exists. -This is because the @command{-s} flag only sets field values. +This is because the @command{-s} flag only sets values of existing fields. It will not create any fields. -If instead, the @command{-S} flag is used, this will create the field +If instead the @command{-S} flag is used, this will create the field (if it does not already exist) @emph{and} set its value. @@ -2278,3 +2277,4 @@ @command{-r} flag. -To rename all instances of the @code{Expiry} field occurring in any record of type @code{Item}, +To rename all instances of the @code{Expiry} field occurring in any +record of type @code{Item} to @code{UseBy}, the following command suffices: @@ -2307,3 +2307,4 @@ typically be in the range @code{0..120}, and there are only a few -valid values for @code{MaritalStatus}: single, married and widow. +valid values for @code{MaritalStatus}: single, married, divorced, and +widow(er). Phones may be restricted to some standard format as well to be valid. @@ -2380,3 +2381,3 @@ Both @code{Item_t} and @code{Transaction_t} are aliases for the type -@code{Id_t}. Which is in place an alias for the type @code{int}. +@code{Id_t}. Which is in turn an alias for the type @code{int}. So, they are both numeric identifiers. @@ -2384,4 +2385,4 @@ The order of the @code{%typedef} fields is not relevant. In -particular, a type definition can reference other type that is defined -below. The previous example could have been written as: +particular, a type definition can forward-reference another type that is defined +subsequently. The previous example could have been written as: @@ -2505,6 +2506,6 @@ @example -%type Negative MIN -1 -%type Positive 0 MAX -%type AnyInt MIN MAX -%type Impossible MAX MIN +%typedef: Negative range MIN -1 +%typedef: Positive range 0 MAX +%typedef: AnyInt range MIN MAX +%typedef: Impossible range MAX MIN @end example @@ -2683,4 +2684,5 @@ @cindex boolean types -@dfn{Boolean} fields can be seen as special enumerations holding the -binary values. +@dfn{Boolean} fields, declared with the type specifier @code{bool}, +can be seen as special enumerations holding the +binary values true and false. @@ -2715,8 +2717,10 @@ @noindent -There are many permitted date formats which are described in detail later in this manual (@pxref{Date input formats}). +There are many permitted date formats, described in detail later in this manual (@pxref{Date input formats}). Of particular note are the following: @itemize @minus -@item Dates and times read from recfiles are not affected by the locale or the timezone. This means that the LC_TIME and the TZ environment variables are ignored. +@item Dates and times read from recfiles are not affected by the +locale or the timezone. This means that the @env{LC_TIME} and the +@env{TZ} environment variables are ignored. If you wish, for example, to specify a time which must be interpreted as UTC, you -must explicitly append the time zone correction: @eg{} `2001-1-10 12:09Z'. +must explicitly append the time zone correction: @eg{} @samp{2001-1-10 12:09Z}. @item The field value `1/10/2001' means January 10, 2001, @strong{not} October 1, 2001. @@ -2731,3 +2735,3 @@ The @dfn{Email} field type specifier is used to declare electronic -addresses such as emails. The synopsis is: +addresses. The synopsis is: @@ -2757,4 +2761,4 @@ @noindent -The format of the uuids is conformed by 32 hexadecimal digits, -displayed in 5 groups separated by hyphens. For example: +The format of the uuids is specified as 32 hexadecimal digits, +displayed in five groups separated by hyphens. For example: @@ -2766,6 +2770,6 @@ @cindex foreign key -There is one other possible field type @viz{} a foreign key. +There is one other possible field type, @viz{} a foreign key. The following example -defines the type @code{Maintainer_t} to be of type ``record @code{Hacker}'' or -in other words a foreign key referring to a record in the @code{Hacker} record set. +defines the type @code{Maintainer_t} to be of type ``record @code{Hacker}''; +in other words, a foreign key referring to a record in the @code{Hacker} record set. @example @@ -2773,5 +2777,5 @@ @end example -@noindent This basically means that the values +@noindent This essentially means that the values to be stored in fields of type @code{Maintainer_t} are of whatever -type defined for the primary key of the @code{Hacker} record set. +type is defined for the primary key of the @code{Hacker} record set. Why this is useful is discussed later. @xref{Queries which Join Records}. @@ -2784,4 +2788,4 @@ except that they must contain one or more fields and optional comments. -This provides the format a huge expressive power, -but in many cases it is also desirable to impose some restrictions in +This provides the format with huge expressive power; +but in many cases, it is also desirable to impose some restrictions in order to reflect some of the properties of the data stored in the @@ -2791,3 +2795,3 @@ The following sections describe the usage of some predefined special -fields whose purpose is to impose that kind of restrictions in the +fields whose purpose is to impose this kind of restriction in the structure of the records. @@ -2826,3 +2830,3 @@ The fields listed in a @code{%mandatory} entry are -non-optional; @ie{}, at least one field with this name shall be present +non-optional; @ie{} at least one field with this name shall be present in any record of this kind. @@ -2835,4 +2839,4 @@ stores the information associated with a contact. The records will be -heterogeneous, in the sense they won't feature exactly the same -fields: the contact of an internet shop will probably have a +heterogeneous, in the sense they won't all contain exactly the same +fields: the contact of an Internet shop will probably have a @code{URL} field, while the entry for our grandmother probably won't. @@ -2862,4 +2866,4 @@ Otherwise, -a data entry clerk faced with this situation, will have to make the choice between -dropping the entry entirely, or entering some fake data to keep the system happy. +a data entry clerk faced with this situation will have to make the choice between +dropping the entry entirely or entering some fake data to keep the system happy. @@ -2874,3 +2878,3 @@ -The converse of @code{%mandatory} is @code{%prohibit}. +The inverse of @code{%mandatory} is @code{%prohibit}. Prohibited fields may not occur in @emph{any} record of the given type. @@ -2885,3 +2889,3 @@ Fields listed in a @code{%prohibit} entry are -forbidden; @ie{}, no field with this name should be present +forbidden; @ie{} no field with this name should be present in any record of this kind. @@ -2920,3 +2924,3 @@ @noindent -At the start of the event, the @code{%mandatory} line can be deleted, to +At the start of the event, the @code{%prohibit} line can be deleted, to allow results to be entered. @@ -2968,3 +2972,3 @@ Additionally, there is further restriction, @viz{} -The value of a primary key field may appear no more than once within a +a given value of a primary key field may appear no more than once within a record set. @@ -2994,3 +2998,3 @@ same record descriptor. -It is also forbidden for two items to share the same `Id' value +It is also forbidden for two items to share the same `Id' value. @cindex integrity problems @@ -2999,3 +3003,3 @@ -Later, you will learn how primary keys can be used to link one record set to +Elsewhere, we discuss how primary keys can be used to link one record set to another using primary keys together with foreign keys. @xref{Queries which Join Records}. @@ -3009,3 +3013,3 @@ @cindex record size -Sometimes it is desireable to place constraints on entire records. +Sometimes it is desirable to place constraints on entire records. This can be done with the @code{%size} special field which is used to limit the @@ -3053,6 +3057,6 @@ -Occasionally @code{%mandatory}, @code{%prohibit} and @code{%size} are just not flexible enough. +Occasionally, @code{%mandatory}, @code{%prohibit} and @code{%size} are just not flexible enough. We might, for instance, want to ensure that @emph{if} a field is present, then it must have a certain relationship to other fields. -Or we might want to stipulate that only under certain conditions, a record contains +Or we might want to stipulate that under certain conditions only, a record contains a particular field. @@ -3105,3 +3109,3 @@ -Note that it is acceptable to declare several constraints in the same record +It is acceptable to declare several constraints in the same record set. @@ -3164,5 +3168,5 @@ However @command{recfix} checks more than the syntactical integrity of the recfile. -If also checks certain semantics and that the data is self consistent. +It also checks certain semantics and that the data is self-consistent. To do this, it uses the special fields of the record, some of which were introduced -in above (@pxref{Constraints on Record Sets}). +above (@pxref{Constraints on Record Sets}). It is a good idea to use the special fields to stipulate the ``enterprise rules'' @@ -3179,3 +3183,3 @@ There is more than one field in a single record of the given name. -@item %keys +@item %key Two or more records share the same value of the field which is the key field. @@ -3289,3 +3293,3 @@ -If you are using the GNU recutils (@pxref{Invoking the Utilities}) to +If you are using GNU recutils (@pxref{Invoking the Utilities}) to process your recfiles, any URL @@ -3296,4 +3300,4 @@ -Grouping and aggregate functions are two related functionalities which -are very useful in order to extract statistics from a record set, or a +Grouping and aggregate functions are two related features which +are useful to extract statistics from a record set, or a subset of that record set. @@ -3309,4 +3313,4 @@ -Consider a recfile containing a relation of items in a shop -stockage. For each item it is stored its type, its category, its +Consider a recfile containing a list of items in a shop +inventory. For each item it is stored its type, its category, its price, the date of the last selling operation of an item of that type, @@ -3386,5 +3390,5 @@ @noindent -Note how the output are three records, which correspond to the three -different categories of items which are present in the database. -However, we are interested in the types of products in each category, +We can see that the output is three records, corresponding to the three +different categories of items present in the database. +However, we are only interested in the types of products in each category, so we can remove unwanted information using @code{-p}: @@ -3436,5 +3440,5 @@ -recutils support @dfn{aggregate functions}. These are so called +recutils supports @dfn{aggregate functions}. These are so called because they accept a record set and a field name as inputs and -generate a single result. Most of the times this result is numerical. +generate a single result. Usually this result is numerical. @@ -3444,5 +3448,5 @@ @item Count(FIELD) -Counts the number of occurences of a field. +Counts the number of occurrences of a field. @item Avg(FIELD) -Calculates the average of the numerical values of a field. +Calculates the average (mean) of the numerical values of a field. @item Sum(FIELD) @@ -3455,6 +3459,6 @@ -The aggregate functions are invoked in the field expressions in +The aggregate functions are to be invoked in the field expressions in @command{recsel}. By default they are applied to the totality of the records in a record set. For example, using the items database from -the previous section, we can calculate the number of entries +the previous section, we can do calculations as in the following examples. @@ -3473,3 +3477,3 @@ the field passed as its parameter, separated by an underline. This -name scheme is probably ok for most purposes, but it is always +name scheme probably suffices for most purposes, but it is always possible to use a rewrite rule to obtain something different: @@ -3482,4 +3486,4 @@ @noindent -You can use different casing writing the name of the aggregate, but -that will be reflected in the field name: +You can use different letter case in writing the name of the aggregate, and +this will be reflected in the field name: @@ -3502,3 +3506,3 @@ @noindent -Now lets add a field along with an aggregate function to the field +Now let's add a field along with an aggregate function to the field expression and see what we get: @@ -3525,7 +3529,7 @@ We get five records! The reason is that when @emph{only} aggregate -functions are part of the field expression they are applied the single -record that would result concatenating all the records in the record +functions are part of the field expression, they are applied to the single +record that would result from concatenating all the records in the record set together. However, when a regular field appears in the field expression the aggregate functions are applied to the individual -records. This is still useful in some cases, like in a database of +records. This is still useful in some cases, such as a database of maintainers: @@ -3537,3 +3541,3 @@ -Name: Luca Saiou +Name: Luca Saiu Email: positron@@gnu.org @@ -3549,3 +3553,3 @@ -Name: Luca Saiou +Name: Luca Saiu Count_Email: 1 @@ -3557,3 +3561,3 @@ of the records in the database. For example, the average prices of -the several item categories stored in the database can be obtained by +each item category stored in the database can be obtained by executing: @@ -3574,3 +3578,3 @@ If we were interested in the actual prices that result in each average -we can: +we can do: @@ -3649,3 +3653,3 @@ @item Should a family move house, then you would have to update the addresses (and telephone number) of all the family members. -@item A typing error in one of the addresses would lead an automatic query to erroneously suggest that the persons lived at different addresses. +@item A typing error in one of the addresses would lead an automatic query to erroneously suggest that the people lived at different addresses. @item It unnecessarily increases the size of the recfile. @@ -3664,3 +3668,3 @@ @cindex record sets -A better way would be to separate the addresses and persons into different record sets. +A better way would be to separate the addresses and people into different record sets. @cindex duplication, avoiding @@ -3707,3 +3711,3 @@ -@noindent and the second (which follows in the same file), like this: +@noindent and the second (following in the same file), like this: @@ -3728,3 +3732,3 @@ and @code{Residence}. -There are six persons, but only three residences, because some residences +There are six people, but only three residences, because some residences accommodate more than one person. @@ -3747,3 +3751,3 @@ Yet since the @code{Id} field is declared using the @code{%key} special field -name, you can be sure that you don't accidentally reuse an existent key. +name, you can be sure that you don't accidentally reuse an existing key. @@ -3759,10 +3763,9 @@ -If we want to look up the name and address of persons in our recfile, we can +If we want to look up the name and address of a person in our recfile, we can use @command{recsel} as before. Because we now have more than one record set in the @file{acquaintances.rec} -file, we have to tell @command{recsel} from which record set we want to lookup +file, we have to tell @command{recsel} in which record set we want to +look up records. We do this with the @code{-t} flag as follows: -@footnote{For clarity, the examples will not call @code{recfix} before the other recutils commands. -However we suggest that you continue to do so, so that you are aware typing mistakes or other problems.} @@ -3855,3 +3858,3 @@ @cindex automatically generated values -Consider for example a list of articles in stock in a toys store: +Consider for example a list of articles in stock in a toy store: @@ -3879,4 +3882,4 @@ @cindex ID numbers -It is quite common in databases to use some kind of numeric ``Id'' to -uniquely identify items like those ones. That is because numbers are +Thus it is quite common in databases to use some kind of numeric ``Id'' to +uniquely identify items like those ones, because numbers are easy to increment and manipulate. So we could add a new @@ -3900,3 +3903,3 @@ -A problem of this approach is that we must be careful to not assign +A problem with this approach is that we must be careful to not assign already used ids when we introduce more articles in the @@ -3920,3 +3923,3 @@ -Note that the auto fields are generated at the beginning of the new +Such auto fields are generated at the beginning of the new records, in the same order they are found in the @code{%auto} @@ -3938,7 +3941,7 @@ If an auto field is of type @code{integer} or @code{range} then any -newly generated field will use the biggest non-used number in the +newly generated field will use the ``next biggest'' unused number in the record set. -Consider the toys stockage database introduced above. We could -declare that the @code{Id} field must be generated automatically: +Consider the toy inventory database introduced above. We could +declare the @code{Id} field to be generated automatically: @@ -3957,8 +3960,8 @@ @noindent -Next time a new item is introduced in the database, the conforming -application will note the @code{%auto}, and will create a new -@code{Id} field for the new record with the bigger unused integer -available, since @code{Id} is declared to be of type @code{int}. In -this example, the new record will have an Id of @code{1}. The -application can still provide an explicit Id for the new record. In +When the next new item is introduced in the database, the conforming +application will note the @code{%auto}, and create a new +@code{Id} field for the new record with the next-biggest unused integer, +since @code{Id} is declared to be of type @code{int}. In +this example, the new record would have an Id of @code{1}. The +database can still provide an explicit Id for the new record. In that case the field is not generated automatically. @@ -4004,3 +4007,3 @@ However, suppose that we want to share our events with other people, -i.e. to send them event records and to incorporate their records into +@ie{} to send them event records and to incorporate their records into our own database. In this case the @code{Id}s would collide. A good @@ -4046,3 +4049,3 @@ For ethical or security reasons it is sometimes necessary that information -in a recfile should not be readable by unauthorized persons. +in a recfile should not be readable by unauthorized people. One way to prevent a recfile from being read is to use the security features of @@ -4115,3 +4118,3 @@ @item The value of any encrypted field shall begin with the string -@code{encrypted-} followed by the encrypted data. +@samp{encrypted-} followed by the encrypted data. @item The encrypted data must be encoded in some ASCII encoding such @@ -4168,3 +4171,3 @@ @command{recins} allows the insertion of encrypted fields in a -database. When the @option{-s|--password} command line option is +database. When the @option{-s} (@option{--password}) command line option is specified in the command line any field declared as confidential in @@ -4176,3 +4179,4 @@ @example -$ recins -t Account -s mypassword -f Login -v foo -f Password -v secret accounts.rec +$ recins -t Account -s mypassword -f Login -v foo -f Password \ + -v secret accounts.rec @end example @@ -4180,3 +4184,3 @@ @noindent -Will encrypt the value of the @code{Password} field with +will encrypt the value of the @code{Password} field with @code{mypassword} as long as the field is declared as confidential. @@ -4192,3 +4196,3 @@ The contents of confidential fields can be read using the -@option{-s|--password} command line option to @command{recsel}. When +@option{-s} (@option{--password}) command line option to @command{recsel}. When used, any selected record containing encrypted fields will try to @@ -4253,9 +4257,10 @@ -Note that nothing prevents to have confidential fields encrypted with -different passwords. As discussed in @pxref{Confidential Fields} this can -be useful to implement several ``levels'' of security. For example, +As mentioned above, a confidential field may be encrypted with +different passwords in different records (@pxref{Confidential Fields}). +For example, we may have an entry in our database with data about the account of -the administrator of the online service. In that case we could want +the administrator of the online service. In that case we might want to store the password associated with that account using a -differentiated password. In that case the output of the last command +different password than that for users. In that case the output of +the last command would have been: @@ -4284,3 +4289,3 @@ to address envelopes -(perhaps, to send annual greeting cards). +(say, to send annual greeting cards). Since addresses are normally written on several lines, it would be appropriate @@ -4309,6 +4314,6 @@ A business enterprise might want to go one step further and generate letters -(such an advertisement or a recall notice) to customers. +(such as an advertisement or a recall notice) to customers. Since @command{recsel} merely selects records and fields from record sets, on -its own it cannot do this. -There is another command designed for this purpose called @command{recfmt}. +its own it cannot do this; so +there is another command designed for this purpose, called @command{recfmt}. @cindex @command{recfmt} @@ -4339,3 +4344,3 @@ as you wish. -Notice the instances of double braces enclosing a field name (@eg{} @code{@{@{Name@}@}}). +Notice the instances of double braces enclosing a field name, @eg{} @code{@{@{Name@}@}}. These are called @dfn{spots} and indicate places where the respective field's @@ -4425,3 +4430,3 @@ -Note that you can use any selection expression in the slots, including +You can use any selection expression in the slots, including conditionals and string concatenation. @@ -4431,4 +4436,5 @@ -Included in the recutils package are a number of utilities to assist the creation -of recfiles using data which already exists in other formats +Included in the recutils package are a number of utilities to assist +in the creation +of recfiles using data which already exists in other formats, and for exporting data from recfiles so that it can be used in other applications. @@ -4539,3 +4545,3 @@ -Note that missing fields are implemented as empty columns in the generated +As shown, missing fields are implemented as empty columns in the generated csv. @@ -4599,3 +4605,3 @@ A @dfn{record descriptor} is created for the record set containing the -generated records, called Products. Note that @command{mdb2rec} is +generated records, called Products. As seen in the example, @command{mdb2rec} is able to generate type information for the fields. The list of @@ -4619,3 +4625,3 @@ the tables in the file are processed, with the exception of the system -tables, for which @kbd{-s} shall be used: +tables, which requires @kbd{-s} to be used: @@ -4676,8 +4682,8 @@ The bash built-in @command{read}, when invoked with no options, -consumes one line from the standard input and makes it available in +consumes one line from standard input and makes it available in the predefined @code{REPLY} environment variable, or any other -variable whose name is passed as an argument. This allows to process +variable whose name is passed as an argument. This allows processing data structured in lines in a quite natural way. For example, the -following program prints the third field of each line (fields are -separated by commas) until the standard input is exhausted: +following program prints the third field of each line, with fields +separated by commas, until standard input is exhausted: @@ -4691,7 +4697,7 @@ -Unfortunately @command{read} is not very useful when it comes to -process recutils records in the shell. Even though it is indeed +However, @command{read} is not very useful when it comes to +processing recutils records in the shell. Even though it is possible to customize the character used by @command{read} to split the input into records, we would need to ignore the empty records in -the probable cases where more than one empty line separates records. +the likely case of more than one empty line separating records. Also, we would need to use @command{recsel} to access to the record @@ -4699,3 +4705,3 @@ -The @command{readrec} bash built-in is similar to @command{read} with +Thus, the @command{readrec} bash built-in is similar to @command{read} with the difference that it reads records instead of lines. It also @@ -4705,3 +4711,3 @@ @itemize @minus -@item @code{REPLY_REC} is set to the record read from the standard input. +@item @code{REPLY_REC} is set to the record read from standard input. @item A set of variables @code{FIELD} named after each field found in @@ -4738,3 +4744,3 @@ then - mail -s "You are been checked." $@{Email[0]@} < email.txt + mail -s "You are being checked." $@{Email[0]@} < email.txt recset -e "Email = '$Email'" -f Checked -S yes contacts.rec @@ -4746,5 +4752,6 @@ @noindent -Note the usage of the bash array when accessing to the primary email -address of each contact. Note also how we update each contact to -figure as ``checked'' so she won't get spammed the next time the +Note the usage of the bash array when accessing the primary email +address of each contact. Note also that we update each contact to +figure as ``checked'', using @command{recset}, so she won't get +pestered again the next time the script is run. @@ -4787,4 +4794,4 @@ -@command{recinf} reads the given rec files (or the data in the -standard input if no file is specified) and prints a resume of the +@command{recinf} reads the given rec files (or the data from +standard input if no file is specified) and prints a summary of the record types contained in the input. @@ -4797,3 +4804,3 @@ -The default behavior of the tool is to emit a line per record type in +The default behavior is to emit a line per record type in the input containing its name and the number of records of that type: @@ -4807,3 +4814,3 @@ If the input contains anonymous records, @ie{} records that are before -the first record descriptor, the corresponding line resume won't have +the first record descriptor, the corresponding output line won't have a type name: @@ -4815,3 +4822,3 @@ -In addition of the common options described earlier the program accepts the following options. +In addition to the common options described earlier the program accepts the following options. @@ -4827,8 +4834,7 @@ Output just the names of the record types found in the input. If the -input is contains anonymous records only then don't emit any -output. +input contains only anonymous records then output nothing. @item -S @itemx @w{@kbd{--print-sexps}} -Print the data in the form of sexps (lisp expressions) instead of rec -format. This option is intended to be used by lisp programs. +Print the data in the form of sexps (Lisp expressions) instead of rec +format. This option can be useful for, of course, Lisp programs. @end table @@ -4848,3 +4854,5 @@ @example -recsel [@var{option}]@dots{} [-n @var{indexes} | -e @var{record_expr} | -q @var{str} | -m @var{num}] [-c | (-p|-P|-R) @var{field_expr}] \ +recsel [@var{option}]@dots{} \ + [-n @var{indexes} | -e @var{record_expr} | -q @var{str} | -m @var{num}] \ + [-c | (-p|-P|-R) @var{field_expr}] \ [@var{file}]@dots{} @@ -4852,9 +4860,9 @@ -In addition of the common options described earlier (@pxref{Common -Options}) the program accepts the following options. - If no @var{file} is specified then the command acts like a filter, getting -the data from the standard input and writing the result in the +the data from standard input and writing the result to standard output. +In addition to the common options described earlier (@pxref{Common +Options}) the program accepts the following options. + @noindent @@ -4865,3 +4873,3 @@ @itemx @w{@kbd{--case-insensitive}} -Make strings case-insensitive in selection expressions. +Make string matching case-insensitive in selection expressions. @cindex case, in selection expressions @@ -4872,3 +4880,3 @@ @itemx @w{@kbd{--include-descriptors}} -Print record descriptors along with the matched records +Print record descriptors along with the matched records. @item -s @var{secret} @@ -4878,6 +4886,6 @@ @itemx @w{@kbd{--sort}=@var{fields}} -Sort the output by the comma separated list of fields names -@var{fields}. This option has precedence to whatever sorting criteria -is specified in the corresponding record descriptor with @code{%sort}. @cindex sorting +Sort the output by the comma-separated list of field names, +@var{fields}. This option takes precedence over any sorting criteria +specified in the corresponding record descriptor with @code{%sort}. @item -U @@ -4885,3 +4893,3 @@ Remove duplicated fields in the output records. Fields are -duplicated if there are more than one featuring the same field name +duplicated if they have the same field name and the same value. @@ -4889,4 +4897,4 @@ @itemx @w{@kbd{--group-by}=@var{fields}} -Group the output records by the provided comma separated set of -@var{fields}. Note that grouping is performed before sorting. +Group the output records by the provided comma-separated list of +@var{fields}. Grouping is performed before sorting. @end table @@ -4900,6 +4908,6 @@ Match the records occupying the given positions in its record set. -@var{indexes} must be a comma-separated list of numbers or ranges, the +@var{indexes} must be a comma-separated list of numbers or ranges, with ranges being two numbers separated with dashes. For example, the following list denotes the first, the third, the fourth and all -records up to the tenth: @code{-n 0,2,4-9}. +records up to the tenth: @samp{-n 0,2,4-9}. @item -e @var{expr} @@ -4922,3 +4930,3 @@ @itemx @w{@kbd{--field}=@var{field}} -Perform an inner join of the record set selected in @option{-t} and +Perform an inner join of the record set selected by @option{-t} and the record set for which @var{field} is a foreign key. @var{field} @@ -4942,12 +4950,13 @@ @noindent -means to print the Name and the Email of every matching record. +means to print the Name and the Email of every matching record, both +the field names and values. If this option is not specified then all the fields of the matching -records are printed in the standard output. +records are printed to standard output. @item -P @var{name_list} @itemx @w{@kbd{--print-values}=@var{name_list}} -Same than @samp{-p}, but print the values of the selected fields. +Same as @samp{-p}, but print only the values of the selected fields. @item -R @var{name_list} @itemx @w{@kbd{--print-row}=@var{name_list}} -Same than @samp{-P}, but print the values separated by single +Same as @samp{-P}, but print the values separated by single spaces instead of newlines. @@ -4955,3 +4964,3 @@ @itemx @w{@kbd{--count}} -If this option is specified then recsel will print the number of +If this option is specified then @command{recsel} will print the number of matching records instead of the records themselves. This option is @@ -4960,5 +4969,5 @@ -Some @dfn{special options} are available to ease the communication -between the recutils and other programs, such as lisp interpreters. -Those options are not intended to be used by human operators. +This @dfn{special option} is available to ease the communication +between the recutils and other programs, namely Lisp interpreters. +This option is not intended to be used by human operators. @@ -4975,11 +4984,13 @@ @command{recins} adds new records to a rec file or to rec data read -from the standard input. Synopsis: +from standard input. Synopsis: @example -recins [@var{option}]@dots{} [t @var{type}] [-n @var{indexes} | -e @var{record_expr} | -q @var{str} | -m @var{num}] \ - [(-f @var{str} -v @var{str}]|[-r @var{recdata})]@dots{} [@var{file}] +recins [@var{option}]@dots{} [-t @var{type}] \ + [-n @var{indexes} | -e @var{record_expr} | -q @var{str} | -m @var{num}] \ + [( -f @var{str} -v @var{str}]|[-r @var{recdata} )]@dots{} \ + [@var{file}] @end example -The new record that will be inserted by the command is constructed by -using pairs of @samp{-f} and @samp{-v} options. Each pair defines a +The new record to be inserted by the command is constructed by +using pairs of @samp{-f} and @samp{-v} options, or @samp{-r}. Each pair defines a field. The order of the parameters is significant. @@ -4987,3 +4998,3 @@ If no @var{file} is specified then the command acts like a filter, getting -the data from the standard input and writing the result in the +the data from standard input and writing the result to standard output. @@ -5004,3 +5015,3 @@ @itemx @w{@kbd{--field}=@var{name}} -Declares the name of a field. This option shall be followed by a +Declares the name of a field. This option must be followed by a @samp{-v}. @@ -5025,6 +5036,6 @@ Record selection arguments are supported too. If they are used -then @command{recins} enters ``replacement mode''. Instead of +then @command{recins} uses ``replacement mode'': instead of appending the new record, matched records are replaced by copies of -the provided record. The selection arguments are summarized in the -next table. +the provided record. The selection arguments are the same as in +@command{recsel}: @@ -5065,6 +5076,8 @@ @command{recdel} removes records from a rec file, or from rec data -read from the standard input. Synopsis: +read from standard input. Synopsis: @example -recdel [OPTIONS]@dots{} [-t @var{type}] [-n @var{indexes} | -e @var{record_expr} | -q @var{str} | -m @var{num}] [@var{file}] +recdel [OPTIONS]@dots{} [-t @var{type}] \ + [-n @var{indexes} | -e @var{record_expr} | -q @var{str} | -m @var{num}] \ + [@var{file}] @end example @@ -5072,3 +5085,3 @@ If no @var{file} is specified then the command acts like a filter, -getting the data from the standard input and writing the result in the +getting the data from standard input and writing the result to standard output. @@ -5106,4 +5119,4 @@ @item @w{@kbd{--force}} -Delete even in potentially dangerous situations, such as the request -to delete all the records of some type, for example. +Delete even in potentially dangerous situations, such as a request +to delete all the records of some type. @item @w{@kbd{--no-external}} @@ -5123,3 +5136,3 @@ @command{recset} manipulates the fields of records in a rec file, or -rec data read from the standard input. Synopsis: +rec data read from standard input. Synopsis: @@ -5130,3 +5143,3 @@ If no @var{file} is specified then the command acts like a filter, -getting the data from the standard input and writing the result in the +getting the data from standard input and writing the result to standard output. @@ -5167,3 +5180,3 @@ -Fields selection options: +Field selection options: @@ -5191,4 +5204,4 @@ @itemx @w{@kbd{--rename}=@var{value}} -Rename a field. @var{value} shall be a valid field name. The field -expression associated with this action shall contain a single field +Rename a field; @var{value} must be a valid field name. The field +expression associated with this action must contain a single field name and an optional subscript. If an entire record set is selected @@ -5224,3 +5237,3 @@ If no @var{file} is specified then the command acts like a filter, -getting the data from the standard input and writing the result in the +getting the data from standard input and writing the result to standard output. @@ -5246,3 +5259,3 @@ Perform a physical sort of all the records contained in the file (or -the standard input) after checking for its integrity. The sorting +standard input) after checking for its integrity. The sorting criteria are provided by the @code{%sort} special field, if any. If @@ -5251,20 +5264,14 @@ -Note that this is a destructive operation. -@item @w{@kbd{--encrypt}} -Encrypt all the non encrypted fields in the database which are marked +This is a destructive operation. +@item @w{@kbd{--decrypt}} +@itemx @w{@kbd{--encrypt}} +Decrypt (encrypt) all the (non-)encrypted fields in the database which are marked as confidential. This operation requires a password. If no password is specified with @option{-s} and the program is run in a terminal, a -prompt is used to get the password from the user. +prompt is given to get the password from the user. -If this operation is performed to a file having encrypted fields, the +If encryption is performed on a file having encrypted fields, the operation will fail unless @w{@kbd{--force}} is used. -Note that this is a destructive operation. -@item @w{@kbd{--decrypt}} -Decrypt all the encrypted fields in the database which are marked as -confidential. This operation requires a password. If no password is -specified with @option{-s} and the program is run in a terminal, a -prompt is used to get the password from the user. - -Note that this is a destructive operation. +These are destructive operations. @item @w{@kbd{--auto}} @@ -5273,7 +5280,6 @@ -Note that this is a destructive operation. +This is a destructive operation. @end table -Some operations make use of certain specific options, which are -described in the table below. +As described above, some operations make use of these additional options: @@ -5299,3 +5305,3 @@ This program always works as a filter, getting the data from the -standard input and writing the result in the standard output. +standard input and writing the result to standard output. @@ -5318,3 +5324,3 @@ @command{csv2rec} reads the given comma-separated-values file (or the -data in the standard input if no file is specified) and prints out the +data from standard input if no file is specified) and prints out the converted rec data, if possible. Synopsis: @@ -5325,3 +5331,3 @@ -In addition of the common options described earlier (@pxref{Common +In addition to the common options described earlier (@pxref{Common Options}) the program accepts the following options. @@ -5357,6 +5363,6 @@ The rec data can be read from files specified in the command line, or -in the standard input. The program echoes the converted data in the +from standard input. The program writes the converted data to standard output. -In addition of the common options described earlier (@pxref{Common +In addition to the common options described earlier (@pxref{Common Options}) the program accepts the following options. @@ -5370,3 +5376,3 @@ @itemx @w{@kbd{--sort}=@var{fields}} -Sort the output by the comma separated list of field names +Sort the output by the comma-separated list of field names @var{fields}. This option has precedence to whatever sorting criteria @@ -5391,3 +5397,3 @@ -In addition of the common options described earlier (@pxref{Common +In addition to the common options described earlier (@pxref{Common Options}) the program accepts the following options. @@ -5417,5 +5423,5 @@ @item + -indicates that the regular expression should match one or more occurrences of the previous atom or regexp. +match one or more occurrences of the previous atom or regexp. @item ? -indicates that the regular expression should match zero or one occurrences of the previous atom or regexp. +match zero or one occurrences of the previous atom or regexp. @item \+ @@ -5429,15 +5435,23 @@ Within square brackets, @samp{\} is taken literally. -Character classes are supported; for example @samp{[[:digit:]]} will match a single decimal digit. +Character classes are supported; for example @samp{[[:digit:]]} matches a single decimal digit. GNU extensions are supported: -@enumerate -@item @samp{\w} matches a character within a word -@item @samp{\W} matches a character which is not within a word -@item @samp{\<} matches the beginning of a word -@item @samp{\>} matches the end of a word -@item @samp{\b} matches a word boundary -@item @samp{\B} matches characters which are not a word boundary -@item @samp{\`} matches the beginning of the whole input -@item @samp{\'} matches the end of the whole input -@end enumerate +@table @samp +@item \w +matches a character within a word +@item \W +matches a character which is not within a word +@item \< +matches the beginning of a word +@item \> +matches the end of a word +@item \b +matches a word boundary +@item \B +matches characters which are not a word boundary +@item \` +matches the beginning of the whole input +@item \' +matches the end of the whole input +@end table @@ -5447,3 +5461,3 @@ a back-reference and matches the same thing as the previous grouped -expression indicated by that number. For example @samp{\2} matches +expression indicated by that number. For example, @samp{\2} matches the second group expression. The order of group expressions is @@ -5455,4 +5469,4 @@ and end of a string respectively, except within square brackets. -Within brackets, @samp{^} can be used to invert the membership of the -character class being specified. +Within brackets, an initial @samp{^} inverts the +character class being matched. @@ -5462,4 +5476,4 @@ @item At the beginning of a regular expression -@item After an open-group, signified by @samp{(} -@item After the alternation operator @samp{|} +@item After an open-group, @samp{(} +@item After the alternation operator, @samp{|} @end enumerate Diff finished at Sat Feb 15 08:43:06