For my own projects (which includes two DBD's), I have been working on spell-check issues. I'm not born in an English-speaking country, nor was I raised in one, so I make errors. Probably quite a few.
spell-checkers help a lot, but most work on en_US, not en_EN, and I try to at least be consistent inside a project. When I was done with my own projects, I threw my newly built utility at the perl source tree itself, and found a few mistakes as well. Then I implemented Text::Aspell into it and fixed all that it found that was obviously wrong. It supports reading local aspell lists of words that are considered to be correct for the given project. DBI documentation is written in en_EN instead of en_US, so the spell-checker will see "behaviour" as wrong and suggests "behavior". Same for "ACKNOWLEDGEMENT" vs "ACKNOWLEDGMENT". That was my trigger to implement project specific language support. Done. Before I try to get deeper into DBI docs and its spelling, would it be considered good-work? As an example to start (this part DOES contain real errors, like abreviate (one b) and unlikey (instead of unlikely)): --8<--- diff --git a/DBI.pm b/DBI.pm index ad14fed..0cf59e9 100644 --- a/DBI.pm +++ b/DBI.pm @@ -1101,7 +1101,7 @@ sub data_diff { sub data_string_diff { # Compares 'logical' characters, not bytes, so a latin1 string and an - # an equivalent unicode string will compare as equal even though their + # an equivalent Unicode string will compare as equal even though their # byte encodings are different. my ($a, $b) = @_; unless (defined $a and defined $b) { # one undef @@ -2267,7 +2267,7 @@ Perl supports binary data in Perl strings, and the DBI will pass binary data to and from the driver without change. It is up to the driver implementors to decide how they wish to handle such binary data. -Perl supports two kinds of strings: unicode (utf8 internally) and non-unicode +Perl supports two kinds of strings: Unicode (utf8 internally) and non-Unicode (defaults to iso-8859-1 if forced to assume an encoding). Drivers should accept both kinds of strings and, if required, convert them to the character set of the database being used. Similarly, when fetching from the database @@ -2303,7 +2303,7 @@ use by the DBI. Extensions and related modules use the C<DBIx::> namespace (see L<http://www.perl.com/CPAN/modules/by-module/DBIx/>). Package names beginning with C<DBD::> are reserved for use by DBI database drivers. All environment variables used by the DBI -or by individual DBDs begin with "C<DBI_>" or "C<DBD_>". +or by individual DBD's begin with "C<DBI_>" or "C<DBD_>". The letter case used for attribute names is significant and plays an important part in the portability of DBI scripts. The case of the @@ -2416,7 +2416,7 @@ Binding an C<undef> (NULL) to the placeholder will I<not> select rows which have a NULL C<age>! At least for database engines that conform to the SQL standard. Refer to the SQL manual for your database engine or any SQL book for the reasons for this. To explicitly select -NULLs you have to say "C<WHERE age IS NULL>". +NULL's you have to say "C<WHERE age IS NULL>". A common issue is to have a code fragment handle a value that could be either C<defined> or C<undef> (non-NULL or NULL) at runtime. @@ -2651,7 +2651,7 @@ It is recommended that drivers support the ODBC style, shown in the last example above. It is also recommended that that they support the three common names 'C<host>', 'C<port>', and 'C<database>' (plus 'C<db>' as an alias for C<database>). This simplifies automatic construction -of basic DSNs: C<"dbi:$driver:database=$db;host=$host;port=$port">. +of basic DSN's: C<"dbi:$driver:database=$db;host=$host;port=$port">. Drivers should aim to 'do something reasonable' when given a DSN in this form, but if any part is meaningless for that driver (such as 'port' for Informix) it should generate an error if that part @@ -4933,7 +4933,7 @@ B<NUM_PREC_RADIX>: The radix for numeric precision. The value is 10 or 2 for numeric data types and NULL (C<undef>) if not applicable. -B<NULLABLE>: Indicates if a column can accept NULLs. +B<NULLABLE>: Indicates if a column can accept NULL's. The following values are defined: SQL_NO_NULLS 0 @@ -4969,7 +4969,7 @@ data type column. B<ORDINAL_POSITION>: The column sequence number (starting with 1). -B<IS_NULLABLE>: Indicates if the column can accept NULLs. +B<IS_NULLABLE>: Indicates if the column can accept NULL's. Possible values are: 'NO', 'YES' and ''. SQL/CLI defines the following additional columns: @@ -5548,7 +5548,7 @@ would return C<'Don''t'> (including the outer quotation marks). For others it may return something like C<'Don\'t'> An undefined C<$value> value will be returned as the string C<NULL> (without -single quotation marks) to match how NULLs are represented in SQL. +single quotation marks) to match how NULL's are represented in SQL. If C<$data_type> is supplied, it is used to try to determine the required quoting behaviour by using the information returned by L</type_info>. @@ -6818,7 +6818,7 @@ and values). It is possible that the values in the hash returned by C<ParamTypes> are not exactly the same as those passed to bind_param() or execute(). -Param attributes specified using the abreviated form, like this: +Param attributes specified using the abbreviated form, like this: $sth->bind_param(1, SQL_INTEGER); @@ -7081,10 +7081,10 @@ Here's a complete example program to insert some data from a file. $dbh->commit; $dbh->disconnect; -Here's how to convert fetched NULLs (undefined values) into empty strings: +Here's how to convert fetched NULL's (undefined values) into empty strings: while($row = $sth->fetchrow_arrayref) { - # this is a fast and simple way to deal with nulls: + # this is a fast and simple way to deal with NULL's: foreach (@$row) { $_ = '' unless defined } print "@$row\n"; } @@ -7210,7 +7210,7 @@ to be delivered $seconds in the future. For example: if ( $@ eq "TIMEOUT\n" ) { ... } elsif ($@) { ... } # some other error -The first (outer) eval is used to avoid the unlikey but possible +The first (outer) eval is used to avoid the unlikely but possible chance that the "code to execute" dies and the alarm fires before it is cancelled. Without the outer eval, if this happened your program will die if you have no ALRM handler or a non-local alarm handler @@ -7463,7 +7463,7 @@ Currently the DBI only defines two trace flags: ALL - turn on all DBI and driver flags (not recommended) SQL - trace SQL statements executed - (not yet implemented in DBI but implemented in some DBDs) + (not yet implemented in DBI but implemented in some DBD's) The L</parse_trace_flags> and L</parse_trace_flag> methods are used to convert trace flag names into the corresponding integer bit flags. -->8--- -- H.Merijn Brand http://tux.nl Perl Monger http://amsterdam.pm.org/ using 5.00307 through 5.12 and porting perl5.13.x on HP-UX 10.20, 11.00, 11.11, 11.23, and 11.31, OpenSuSE 10.3, 11.0, and 11.1, AIX 5.2 and 5.3. http://mirrors.develooper.com/hpux/ http://www.test-smoke.org/ http://qa.perl.org http://www.goldmark.org/jeff/stupid-disclaimers/