Author: wyoung
Date: Tue Feb 17 18:33:36 2009
New Revision: 2446
URL: http://svn.gna.org/viewcvs/mysqlpp?rev=2446&view=rev
Log:
Userman clarity tweaks
Modified:
trunk/doc/userman/ssqls.dbx
trunk/doc/userman/tutorial.dbx
Modified: trunk/doc/userman/ssqls.dbx
URL:
http://svn.gna.org/viewcvs/mysqlpp/trunk/doc/userman/ssqls.dbx?rev=2446&r1=2445&r2=2446&view=diff
==============================================================================
--- trunk/doc/userman/ssqls.dbx (original)
+++ trunk/doc/userman/ssqls.dbx Tue Feb 17 18:33:36 2009
@@ -52,32 +52,30 @@
<para>The parameter before each field name in the
<function>sql_create_#</function> call is the C++ data type that
- will be used to hold that value in the SSQLS. MySQL++ defines C++
- types for almost every data type MySQL understands, of the form
- <type>sql_*</type>. We’re using them for all of the columns
- above for reasons given in <xref linkend="sql-types"/>. While you
- could use plain old C++ data types for most of these columns
- (<type>long int</type> instead of <type>mysqlpp::sql_bigint</type>,
- for example) the MySQL++ equivalents have <link
- linkend="sql-types">several advantages</link>.</para>
-
- <para>Consider the <varname>description</varname> field definition
- above. It uses two MySQL++ features in combination to express a data
- type that has no exact C++ type equivalent. The difference between
- SQL’s <type>MEDIUMTEXT</type> and C++’s
- <type>std::string</type> type is small, so MySQL++’s typedef
- just aliases the two. However, there’s no equivalent of
- SQL’s “null” in the C++ type system. MySQL++
- offers the <ulink type="classref" url="Null"/> template, which
- bridges this difference between the two type systems. For more on
- this topic, see <xref linkend="sql-null"/>.</para>
-
- <para>The general format of this set of macros is:</para>
+ will be used to hold that value in the SSQLS. While you could use
+ plain old C++ data types for most of these columns (<type>long
+ int</type> instead of <type>mysqlpp::sql_bigint</type>, for
+ example) it’s <link linkend="sql-types">best to use the
+ MySQL++ typedefs</link>.</para>
+
+ <para>Sometimes you have no choice but to use special MySQL++
+ data types to fully express the database schema. Consider
+ the <varname>description</varname> field. MySQL++’s
+ <type>sql_mediumtext</type> type is just an alias for
+ <type>std::string</type>, since we don’t need anything
+ fancier to hold a SQL <type>MEDIUMTEXT</type> value.
+ It’s the SQL NULL attribute that causes trouble:
+ it <link linkend="sql-null">has no equivalent in the C++
+ type system</link>. MySQL++ offers the <ulink type="classref"
+ url="Null"/> template, which bridges this difference between the
+ two type systems.</para>
+
+ <para>The general format of this macro is:</para>
<programlisting>
sql_create_#(NAME, COMPCOUNT, SETCOUNT, TYPE1, ITEM1, ... TYPE#,
ITEM#)</programlisting>
- <para>Where # is the number of member variables,
+ <para>where # is the number of member variables,
<parameter>NAME</parameter> is the name of the structure you wish to
create, <parameter>TYPEx</parameter> is the type of a member
variable, and <parameter>ITEMx</parameter> is that variable’s
Modified: trunk/doc/userman/tutorial.dbx
URL:
http://svn.gna.org/viewcvs/mysqlpp/trunk/doc/userman/tutorial.dbx?rev=2446&r1=2445&r2=2446&view=diff
==============================================================================
--- trunk/doc/userman/tutorial.dbx (original)
+++ trunk/doc/userman/tutorial.dbx Tue Feb 17 18:33:36 2009
@@ -57,11 +57,11 @@
<screen>./exrun resetdb [-s server_addr] [-u user] [-p password]</screen>
- <para>That's the typical form for a Unixy system. You leave off the
- <command>./</command> bit on Windows. You can leave it off on a
- Unixy system, too, if you have <filename>.</filename> in your
- <varname>PATH</varname>. (Not a recommendation, just an
- observation.)</para>
+ <para>That’s the typical form for a Unixy system. You leave
+ off the <command>./</command> bit on Windows. You can leave it
+ off on a Unixy system, too, if you have <filename>.</filename>
+ in your <varname>PATH</varname>. (Not a recommendation, just
+ an observation.)</para>
<para>All of the program arguments are optional.</para>
@@ -350,7 +350,7 @@
<para>Quoting is pretty simple, but SQL syntax also often requires
that certain characters be “escaped”. Imagine if the
- string in the previous example was “Frank's Brand Hotdog
+ string in the previous example was “Frank’s Brand Hotdog
Buns” instead. The resulting query would be:</para>
<programlisting>
@@ -490,15 +490,15 @@
<para>There is no equivalent of SQL’s null in the standard C++
type system.</para>
- <para>The primary distinction is one of type: in SQL, null is a
- column attribute, which affects whether that column can hold a SQL
- null. Just like the <symbol>const</symbol> keyword in the C++ type
- system, this effectively doubles the number of SQL data types. To
- emulate this, MySQL++ provides the <ulink type="classref"
- url="null">Null</ulink> template to allow the creation of distinct
- “nullable” versions of existing C++ types. So for
- example, if you have a <type>TINYINT UNSIGNED</type> column that can
- have nulls, the proper declaration for MySQL++ would be:</para>
+ <para>The primary distinction is one of type. In SQL,
+ “NULL” is a type modifier, which affects whether
+ a column can hold a SQL null. C++ also defines something called
+ “NULL”, but it is not a type modifier. To emulate this,
+ MySQL++ provides the <ulink type="classref" url="null">Null</ulink>
+ template to allow the creation of distinct “nullable”
+ versions of existing C++ types. So for example, if you have a
+ <type>TINYINT UNSIGNED</type> column that can have nulls, the
+ proper declaration for MySQL++ would be:</para>
<programlisting>
mysqlpp::Null<mysqlpp::sql_tinyint_unsigned> myfield;</programlisting>
_______________________________________________
Mysqlpp-commits mailing list
[email protected]
https://mail.gna.org/listinfo/mysqlpp-commits
