Update README.md

README.md

@@ -35,7 +35,7 @@ Prerequisites:
 
 If you want you can change the npm run commands (under scripts) to anything you'd like.
 
-3) Run the following commands and follow the prompts. The app id, parsing_schema, workspace_name and database connection info should all correspond to the app you want to download (see <a href="#configuration">Configuration</a> )
+3) Run the following commands and follow the prompts. The app id, parsing_schema, workspace_name and database connection info should all correspond to the app you want to download (see <a href="#configuration">Configuration</a>)
 
 	npm install
 	cd node_modules/apex-source-control
@@ -65,7 +65,7 @@ You can now set up the application as a git or other version-control repository.
 	   "uninstall-apex" : "apex-source-control uninstall-apex"
 	},
 
-If you want you can change the npm run commands (under scripts) to anything you'd like.
+If you want you can change the npm run commands (under scripts) to anything you'd like (see <a href="#npm-scripts-commands">npm scripts Commands</a>).
 
 3) Run:
 
@@ -98,7 +98,7 @@ From here you can now either set up the project as a git/subversion/etc. reposit
 	npm run switch-conf-file
 	npm run file-to-apex
 
-### Working with existing apex-source-control project
+## Working with existing apex-source-control project
 
 1) Clone the repository locally
 
@@ -111,27 +111,35 @@ From here you can now either set up the project as a git/subversion/etc. reposit
 	npm run file-to-apex 		#download the app locally
 That's it!
 
-When you run 'npm run new-conf-file' you can either enter the info of the app you are already using to develop (your version will be overwritten by the one in version control) or enter in the info of a non-existent app which will be automatically created after running 'npm run file-to-apex'
+When you run `npm run new-conf-file` you can either enter the info of the app you are already using to develop (your version will be overwritten by the one in version control) or enter in the info of a non-existent app which will be automatically created after running `npm run file-to-apex` (see <a href="#configuration">Configuration</a>).
 
 ## npm scripts Commands
+Note: You can change these commands to anything you like by editing the scripts value of `package.json`.
+For example if you replaced `"apex-to-file" : "apex-source-control apex-to-file"` with `"atf" : "apex-source-control apex-to-file"` then your new command would be `npm run atf`.
 ##### npm run apex-to-file
-Turn your apex workspace project into a file directory suitable for version control tools
+Turn your apex workspace project into a file directory suitable for version control tools.
 ##### npm run file-to-apex
-Import your file directory into apex as an apex application. This command will only work with a $PROJECT_HOME/apex/ dir which was generated by APEXExportSplitter
+Import your file directory into apex as an apex application.
+Will overwrite any existing app in the same workspace with the same id.
+
+This command will only work with a $PROJECT_HOME/apex/ dir which was generated by `npm run apex-to-file` or is setup as described in steps 6 to 8 of <a href="#setting-up-from-an-apex-export-file">Setting up from an APEX export file</a>.
 ##### npm run uninstall-apex
 Uninstall your app from apex
 ##### npm run new-conf-file
-Creates a new config file using user input. NOTE: As of right now you must run 'npm run switch-conf-file' command to change to the new config file after creating a new one
+Creates a new config file using user input. 
+
+Note: As of right now you must run `npm run switch-conf-file` command to change to the new config file after creating a new one
 ##### npm run switch-conf-file
 Switches the symlink to the config file of user's choice
 ##### npm run read-conf-file
 Outputs the name and contents of the config file currently being used
 ##### npm run generate-app-id
-Logs into your database and automatically generates and unused app-id in order to avoid accidentaly overwritting someone else's app.
+Logs into your database and automatically generates an unused app-id.
-Can only be run if your config file is set up with proper database login info (apexappid, parsing_schema & workspace_name not needed).
+Used in order to avoid accidentaly overwritting someone else's app.
+Can only be run if your config file is set up with proper database login info (see <a href="#config-file-examples">Config file examples</a>).
 
 Note: As of right now the app-id will not automatically be written to your config file (TODO) so you must manually input the number the program gives you.
-This script also needs your database login info (in order to check app-ids and whatnot) so your config file must be set up before it can be run.
+This script also needs your database login info (in order to check availible app-ids) so your config file must be set up before it can be run.
 
 ###Workflow & Project Sanitation
 * Ignore config files in version control (.gitignore for git) since you'll likely not want to share login info in version control
@@ -140,7 +148,7 @@ TODO write workflow section
 
 ## Configuration
 Config files are placed in a top level config/ directory.
-Each developer has their own config file with their app data which is then refrenced by a symlink named asc.conf (TODO change symlink name).
+Each developer has their own config file with their app data which is then refrenced by a symlink named asc.conf (short for apex-source-control.conf).
 Config files should never be put under version control (unless you want to share connection data for some reason).
 ##### apexappid
 The unique application id # of your APEX app in Oracle.
@@ -151,13 +159,6 @@ It can be the same as a pre-existing APEX app in the same workspace, but be care
 ##### workspace_name
 Name of the workspace where the app is installed or is to be installed to.
 The workspace should already exist before usage
-##### database_connection
-The database_connection info in [JDBC](http://www.orafaq.com/wiki/JDBC) format, i.e. Hostname:Port/SID. Example: `myhost:1521/orcl`.
-Used in connect statements such as `sqlplus $username/$password@$database_connection`
-##### username
-Username of database login
-##### password
-Password of database login
 ##### parsing_schema
 The parsing_schema used by APEX for this app.
 If set incorrectly the app may not function at all when imported into APEX.
@@ -165,7 +166,45 @@ If set incorrectly the app may not function at all when imported into APEX.
 The app alias to be used by APEX. Should usually not be set.
 
 Since aliases must be unique within a workspace (and recommended to be unique within an instance) this should only be set for important versions of the app (i.e. production or dev versions).
-If the field is left blank an app_alias will be auto-generated ('F' + $apexappid) to avoid conflicts.
+If this field is left blank an app_alias will be auto-generated ('F' + $apexappid) to avoid conflicts.
+##### database_connection
+The database_connection info in [JDBC](http://www.orafaq.com/wiki/JDBC) format, i.e. Hostname:Port/SID. Example: `myhost:1521/orcl`.
+Used in connect statements such as `sqlplus $username/$password@$database_connection`
+##### username
+Username of database login
+##### password
+Password of database login
+#### Config file examples
+A normal developer config file
+
+	apexappid=116
+	workspace_name=TEST_WORKSPACE
+	parsing_schema=PARSER
+	app_alias=
+	database_connection=localhost:1521/xe
+	username=the_coolest_guy
+	password=no_really_the_coolest
+
+A config file for using `npm run generate-app-id`
+
+	apexappid=
+	workspace_name=
+	parsing_schema=
+	app_alias=
+	database_connection=localhost:1521/xe
+	username=the_coolest_guy
+	password=no_really_the_coolest
+
+A config file for a production version of an app
+
+	apexappid=113
+	workspace_name=PROD_APPS
+	parsing_schema=PARSER
+	app_alias=Hello_World
+	database_connection=localhost:1521/xe
+	username=i_wanna_be_the_very_best
+	password=that_no_one_ever_was
+
 ###Known Issues
 #### Deleting a page will always win merges
 **To Reproduce**: 
@@ -189,7 +228,7 @@ If you do end up accidently deleting a page then you will have to manually re-ad
 #### Random version control noise in application meta-data
 TODO expand this section
 
-### Inspiration
+## Inspiration
 These scripts were designed using [this paper] (http://www.rwijk.nl/AboutOracle/psdua.pdf) as reference.
 There's a lot of good information about directory structure and general developer workflow so it's definitely worth a read.