Improving documentation

Italicizing every use of the project name, and breaking out the examples into one very generic one and one very specific one, with an explanation about the specific one.
project-open-data · 4c0ddbdb72e73bed0e4d07d5c1241dc02f3ef7cc · waldoj committed Dec 27, 2012 · Dec 27, 2012 · 4c0ddbd
1 parent d352924
commit 4c0ddbdb72e73bed0e4d07d5c1241dc02f3ef7cc
Unified Split

Showing with 26 additions and 7 deletions.

+26 −7 readme.md
diff --git a/readme.md b/readme.md
@@ -11,9 +11,9 @@ Creating an API to access information within existing database tables is laborio
 How This Solves It
 ------------------
 
-Database to API acts as a filter, sitting between a database and the browser, allowing users to interact with that database as if it was a native API. The column names function as the key names. This obviates the need for custom code for each database layer.
+*Database to API* acts as a filter, sitting between a database and the browser, allowing users to interact with that database as if it was a native API. The column names function as the key names. This obviates the need for custom code for each database layer.
 
-When Alternative PHP Cache (APC) is installed, parsed data is stored within APC, which accellerates substantially its functionality.
+When Alternative PHP Cache (APC) is installed, parsed data is stored within APC, which accellerates  its functionality substantially. While APC is not required, it is recommended highly.
 
 
 Databases Supported
@@ -59,7 +59,7 @@ Usage
 -----
 
 1. Copy `config.sample.php` to `config.php`
-2. Follow the inline example to register a new dataset. Tip: It's best to provide read-only database credentials here.
+2. Follow the below example to register a new dataset in `config.php`. Tip: It's best to provide read-only database credentials here.
 3. Document the API.
 
 How to Register a Dataset
@@ -70,22 +70,41 @@ Edit `config.php` to include a a single instance of the following for each datas
 ```php
 
 $args = array( 
-			'name' => null,
-		    'username' => 'root',
-			'password' => 'root',
+			'name' => database_name,
+		    'username' => 'username',
+			'password' => 'password',
 			'server' => 'localhost',
 			'port' => 3306,
 			'type' => 'mysql',
 			'table_blacklist' => array(),
 			'column_blacklist' => array(),
 );
 
-register_db_api( 'dataset-name', $args );
+register_db_api( 'dataset_name', $args );
 
 ```
 
 *Note: All fields (other than the dataset name) are optional and will default to the above.*
 
+Here is a `config.php` file for a MySQL database named “inspections,” accessed with a MySQL user named “website” and a password of “s3cr3tpa55w0rd,” with MySQL running on the same server as the website, with the standard port of 3306. All tables may be accessed by *Database to API* except for “cache” and “passwords,” and among the accessible tables, the “password_hint” column may not be accessed via *Database to API*. All of this is registered to create an API named “facility-inspections”.
+
+```php
+
+$args = array( 
+			'name' => 'inspections',
+		    'username' => 'website',
+			'password' => 's3cr3tpa55w0rd',
+			'server' => 'localhost',
+			'port' => 3306,
+			'type' => 'mysql',
+			'table_blacklist' => array('cache', 'passwords'),
+			'column_blacklist' => array('password_hint'),
+);
+
+register_db_api( 'facility-inspections', $args );
+
+```
+
 For a SQLite database, simply provide the path to the database in `name`.
 
 For an Oracle database, you can either specify a service defined in tsnames.ora (e.g. `dept_spending`) or you can define an Oracle Instant Client connection string (e.g., `//localhost:1521/dept_spending`).