From 1520d46763397172410e269d59e0cd7281a04494 Mon Sep 17 00:00:00 2001
From: Bryan Ashby <bryan.ashby@storagecraft.com>
Date: Tue, 4 Dec 2018 16:56:05 -0700
Subject: [PATCH] File base doc updates

---
 docs/filebase/first-file-area.md | 58 +++++++++++++++++++-------------
 1 file changed, 35 insertions(+), 23 deletions(-)

diff --git a/docs/filebase/first-file-area.md b/docs/filebase/first-file-area.md
index 7d7a133d..c494bbe8 100644
--- a/docs/filebase/first-file-area.md
+++ b/docs/filebase/first-file-area.md
@@ -2,34 +2,38 @@
 layout: page
 title: Configuring a File Base
 ---
+## Configuring a File Base
+ENiGMA½ offers a powerful and flexible file base. Configuration of file the file base and areas is handled via the `fileBase` section of `config.hjson`. 
+
 ## ENiGMA½ File Base Key Concepts
-Like many things in ENiGMA½, configuration of file base(s) is handled via `config.hjson` — specifically 
-in the `fileBase` section. First, there are a couple of concepts you should understand:
+First, there are some core concepts you should understand:
+* Storage Tags
+* Areas (and Area Tags)
 
+### Storage Tags
+*Storage Tags* define paths to physical (file) storage locations that are referenced in a file *Area* entry. Each entry may be either a fully qualified path or a relative path. Relative paths are relative to the value set by the `areaStoragePrefix` key (defaults to `/path/to/enigma-bbs/file_base`). 
 
-### Storage tags
-
-**Storage Tags** define paths to physical (file) storage locations that are referenced in a 
-file *Area* entry. Each entry may be either a fully qualified path or a relative path. Relative paths 
-are relative to the value set by the `areaStoragePrefix` key (defaults to `<enigma_install_dir/file_base`). 
-Below is an example defining a both a relative and fully qualified path each attached to a storage tag:
+Below is an example defining some storage tags using the relative and fully qualified forms:
 
 ```hjson
 storageTags: {
-	retro_pc: "retro_pc" // relative
-	retro_pc_bbs: "retro_pc/bbs" // still relative!
+	retro_pc_dos: "dos" // relative
+	retro_pc_bbs: "pc/bbs" // still relative!
 	bbs_stuff: "/path/to/bbs_stuff_storage" // fully qualified
 }
 ```
 
-Note that on their own, storage tags don't do anything — they are simply pointers to storage locations on your system. 
+:information_source: On their own, storage tags don't do anything — they are simply pointers to storage locations on your system.
 
 ### Areas
+File base *Areas* are configured using the `fileBase::areas` configuration block in `config.hjson`. Valid members for an area are as follows:
 
-File base **Areas** are configured using the `fileBase::areas` configuration block in `config.hjson`. 
-Each entry within `areas` must contain a `name`, `desc`, and `storageTags`. Remember that in ENiGMA½ 
-while areas are important, they should generally be used less than in tradditional BBS software. It is 
-recommended to favor the use of more **tags** over more areas. 
+| Item | Required | Description |
+|--------|---------------|------------------|
+| `name` | :+1: | Friendly area name. |
+| `desc` | :-1: | Friendly area description. |
+| `storageTags` : | :+1: | An array of storage tags for physical storage backing of the files in this area. If uploads are enabled for this area, **first ** storage tag location is utilized!** |
+| `sort` | :-1: | If present, provides the sort key for ordering. `name` is used otherwise. |
 
 Example areas section:
 
@@ -38,31 +42,39 @@ areas: {
 	retro_pc: {
 		name: Retro PC
 		desc: Oldschool PC/DOS
-		storageTags: [ "retro_pc", "retro_pc_bbs" ]
+		storageTags: [ "retro_pc_dos", "retro_pc_bbs" ]
 	}
 }
 ```
+The above example defines an area called "Retro PC" which is referenced via the *area tag* of `retro_pc`. Two storage tags are used: `retro_pc_dos`, and `retro_pc_bbs`. These storage tags can be seen in the Storage Tags example above.
 
 ## Example Configuration
-
-This combines the two concepts described above. When viewing the file areas from ENiGMA½ a user will 
-only see the "Retro PC" area, but the files in the area are stored in the two locations defined in the 
-`storageTags` section.
+This combines the two concepts described above. When viewing the file areas from ENiGMA½ a user will only see the "Retro PC" area, but the files in the area are stored in the two locations defined in the `storageTags` section. We also show a uploads area. Uploads are allowed do to the [ACS](acs.md) block. See [Uploads](uploads.md) for more information.
 
 ```hjson
 fileBase: {
 	areaStoragePrefix: /enigma-bbs/file_base
 
 	storageTags: {
-		retro_pc: "retro_pc"
-		retro_pc_bbs: "retro_pc/bbs"
+		retro_pc_dos: "dos"
+		retro_pc_bbs: "pc/bbs"
 	}
 
 	areas: {
 		retro_pc: {
 			name: Retro PC
 			desc: Oldschool PC/DOS
-			storageTags: [ "retro_pc", "retro_pc_bbs" ]
+			storageTags: [ "retro_pc_dos", "retro_pc_bbs" ]
+		}
+
+		uploads: {
+			name: Uploads
+			desc: User uploads
+			acs: {
+				// allow any user to upload here
+				write: GM[users]
+			}
+			storageTags: [ "user_uploads" ]
 		}
 	}
 }