[docs] xmldocs - docelic modified glossary/database

Sun Apr 10 18:45:56 EDT 2005

User:      docelic
Date:      2005-04-10 22:45:56 GMT
Modified:  glossary database
Log:
More documentation ported from icdatabase.sdf

Revision  Changes    Path
1.2       +159 -14   xmldocs/glossary/database


rev 1.2, prev_rev 1.1
Index: database
===================================================================
RCS file: /var/cvs/xmldocs/glossary/database,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2

--- database	10 Apr 2005 20:37:21 -0000	1.1
+++ database	10 Apr 2005 22:45:56 -0000	1.2
@@ -49,25 +49,71 @@
 By default, all database source files are kept in the 
 <filename class='directory'>products/</filename> subdirectory of your
 &glos-CATROOT;. The &conf-ProductDir; directive controls the exact location.
+</para><para>
+The ASCII files can have
+<literal>^M</literal> (carriage return) characters, but must have a
+newline character at the end of the line to work. <emphasis role='bold'>
+Mac users uploading files must use ascii mode, not binary mode</emphasis>.
+</para>
+<para>
+Interchange's default ASCII delimiter is TAB. <emphasis role='bold'>Keep in
+mind that the items must be separated by a single delimiter (that is, a single
+TAB by default)</emphasis>. Due to the nature of TABs, TAB-delimited files
+look messy and unaligned when viewed in a text editor. Do not try to fix these;
+better use the <command>te</command> utility that comes as part of the 
+&IC; distribution to edit files more conveniently.
+</para>
+Format examples:
+<itemizedlist>
+	<listitem>
+	<para>TAB-delimited file:
+Fields are separated by TAB characters. No whitespace is allowable
+at the beginning of the line.
 </para>
+<screen>
+code	description	price image
+SH543	Men's fine cotton shirt	14.95	shirts.jpg
+</screen>
+<para>
+Using the default TAB delimiter is recommended if you plan on
+searching the ASCII source file of the database.
+	</para></listitem>
 
-<note>
-<title>Database updates</title>
+	<listitem>
+	<para>PIPE-delimited file:
+Fields are separated by the pipe ("<literal>|</literal>") characters which 
+resemble vertical lines. No whitespace is allowable at the beginning of the
+line.
+</para>
+<screen>
+code|description|price|image
+SH543|Men's fine cotton shirt|14.95|shirts.jpg
+</screen>
 <para>
-It is important to note that, when using &IC; internal database methods 
-(which are some variant of DB_File or DBM, depending on what's available
-on your system), changes to text files cause databases to be resynchronized
-with plaintext file contents.
-</para><para>
-This behavior can be controlled via the &conf-NoImport; config directive,
-but by default, changes in text files will trigger a 
-rewrite of DBM or DB_File databases. This might lead to unexpected problems
-if you edit databases from &IC; and don't sync <emphasis>files</emphasis>
-with the databases first, or have a larger data sets
-(say, over a few thousand records) which take noticeable time to get
-re-imported.
+PIPE-delimited files perform fairly well with ASCII text searching routines.
+	</para></listitem>
+	<listitem>
+	<para>CVS-delimited file:
+Fields are enclosed in quotes and separated by commas. Again, no whitespace
+should be at the beginning of the line.
+</para>
+<screen>
+"code","description","price","image"
+"SH543","Men's fine cotton shirt","14.95","shirts.jpg"
+</screen>
+<para>
+CSV-delimiter schemes might cause problems with ASCII text searching routines.
+	</para></listitem>
+	</itemizedlist>
+
+<note>
+	<para>
+Field names are usually case-sensitive. Use
+consistency when naming or you might encounter problems. All lower or
+all upper case names are recommended.
 </para>
 </note>
+
 </section>
 
 <section>
@@ -155,7 +201,25 @@
 actual DB file itself.
 When it happens that it is, the database table is re-imported
 from the text source file.
+</para>
+<note>
+<title>Database updates</title>
+<para>
+It is important to note that, when using &IC; internal database methods 
+(which are some variant of DB_File or DBM, depending on what's available
+on your system), changes to text files cause databases to be resynchronized
+with plaintext file contents.
 </para><para>
+This behavior can be controlled via the &conf-NoImport; config directive,
+but by default, changes in text files will trigger a 
+rewrite of DBM or DB_File databases. This might lead to unexpected problems
+if you edit databases from &IC; and don't sync <emphasis>files</emphasis>
+with the databases first, or have a larger data sets
+(say, over a few thousand records) which take noticeable time to get
+re-imported.
+</para>
+</note>
+<para>
 For a complete discussion, please see the &conf-Database; configuration
 directive.
 </para>
@@ -180,5 +244,86 @@
 </section>
 
 
+<section>
+	<title>Interchange Database Conventions</title>
+<para>
+This section describes naming and file usage conventions used with
+&IC;. This is very important for both understanding &IC; and developing
+your own custom solutions which build upon officially recommended practices.
+</para><para>
+Term definitions:
+</para>
+<itemizedlist>
+<listitem>
+	<para><emphasis>key</emphasis> or <emphasis>code</emphasis></para>
+	<para>
+	The words reference the database key. In &IC;, the key is usually the
+	product <emphasis>code</emphasis> or &glos-SKU;, which is the product
+	part number. Otherwise, key values may be used to generate relationships
+	to other database tables.
+	</para><para>
+	It is recommended that the key be the first column of the database
+	text source file, since Interchange's import, export, and search
+	facilities rely on this practice.
+	</para>
+</listitem>
+<listitem>
+	<para><emphasis>field</emphasis> or <emphasis>column</emphasis></para>
+	<para>
+	The vertical row of a database. One of the columns is always the key
+	and it is usually the first one, as explained above.
+	</para>
+</listitem>
+<listitem>
+	<para><emphasis>table</emphasis> or <emphasis>database</emphasis></para>
+	<para>
+	A table in the database. Because &IC; has evolved from a
+	single-table database to an access method for an unlimited number of
+	tables (and databases, for that matter), a table will occasionally be
+	referred to as a database. The only time the term database refers to
+	something different is when describing the concept as it relates to
+	SQL, where a database contains a series of tables. While &IC;
+	cannot create SQL databases, it can drop and create tables with that
+	database if given the proper permissions.
+	</para>
+</listitem>
+</itemizedlist>
+
+
+<para>
+	&IC; uses one mandatory database, which is referred to as the
+	<database>products</database> database. In the supplied catalog, the
+	database is directly called <literal>products</literal> 
+	and the ASCII source is kept in the file <filename>products.txt</filename>
+	This is also the default file for searching contents with
+	the search engine, such as Glimpse or HTDig.
+</para><para>
+	Interchange also has a two of standard, but optional, databases that
+	are <emphasis role='bold'>in fixed formats</emphasis>:
+	</para>
+	<itemizedlist>
+<listitem>
+<para>
+	<database>shipping.asc</database> database contains shipping options that are
+	accessed if the	&conf-CustomShipping; directive is in use.
+	This is a fixed-format database, and must be created as specified.
+	For more information, see &glos-shipping; glossary entry and the 
+	&tag-shipping; tag.
+</para>
+</listitem>
+<listitem><para>
+	<database>salestax.asc</database> database contains 
+	sales tax information if the &tag-salestax; tag is to
+	be used. A default is supplied.
+	<emphasis role='bold'>Caution, these things change and need 
+	periodic updating!</emphasis> See &glos-tax; glossary entry for more
+	information.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+	The two above tables are never stored in SQL or DBM.
+</para>
+</section>
 
 <para>






