expanded -m help text to cover landing page customization, example api queries

1 files changed, 150 insertions, 25 deletions

diff --git a/init.go b/init.go
index eacbea4..8122882 100644
--- a/init.go
+++ b/init.go
@@ -17,7 +17,7 @@ import (
 	"github.com/syndtr/goleveldb/leveldb"
 )
 
-const getwtxt = "0.2.0"
+const getwtxt = "0.2.1"
 
 var (
 	flagVersion  *bool   = pflag.BoolP("version", "v", false, "Display version information, then exit.")
@@ -284,25 +284,28 @@ func watchForInterrupt() {
 func titleScreen() {
 	fmt.Printf(`
     
-            _            _        _
-  __ _  ___| |___      _| |___  _| |_
- / _  |/ _ \ __\ \ /\ / / __\ \/ / __|
-| (_| |  __/ |_ \ V  V /| |_ >  <| |_
- \__, |\___|\__| \_/\_/  \__/_/\_\\__|
- |___/
-            version ` + getwtxt + `
-      github.com/getwtxt/getwtxt
-               GPL  v3  
+                       _            _        _
+             __ _  ___| |___      _| |___  _| |_
+            / _  |/ _ \ __\ \ /\ / / __\ \/ / __|
+           | (_| |  __/ |_ \ V  V /| |_ >  <| |_
+            \__, |\___|\__| \_/\_/  \__/_/\_\\__|
+            |___/
+                       version ` + getwtxt + `
+                 github.com/getwtxt/getwtxt
+                          GPL  v3  
+
 `)
 }
 
 func helpScreen() {
 	fmt.Printf(`
-              getwtxt Help
+                        getwtxt Help
+
+
+                 :: Command Line Options ::
 
-Command Line Options:
     -h               Print this help screen.
-		-m               Print the configuration manual.
+    -m               Print the configuration manual.
     -v               Print the version information and quit.
     -c [--config]    Path to an alternate configuration file
                        to use. May be relative or absolute.
@@ -311,10 +314,29 @@ Command Line Options:
 }
 func manualScreen() {
 	fmt.Printf(`
-Configuration File:
+                       :: Sections ::
+
+    >> Configuration File
+        Covers syntax and location of default configuration,
+        passing a specific configuration file to getwtxt, 
+        and acceptable formats for configuration files.
+
+    >> Customizing the Landing Page
+        Covers the location of the landing page template,
+        format of the template, and optional preprocessor
+        tags available to use when creating a new landing
+        page template.
+
+    >> Interacting With the Registry
+        Explains all API endpoints, their parameters,
+        and expected output.
+
+
+                  :: Configuration File ::
+
     The default configuration file is in YAML format, chosen for
-its clarity and its support of commenting (unlike JSON). It may
-be placed in any of the following locations by default:
+ its clarity and its support of commenting (unlike JSON). It may
+ be placed in any of the following locations by default:
 
     The same directory as the getwtxt executable
     /usr/local/getwtxt/
@@ -322,23 +344,23 @@ be placed in any of the following locations by default:
     /usr/local/etc/
 
     The paths are searched in that order. The first configuration
-file found is used by getwtxt, while the locations further down
-are ignored.
+ file found is used by getwtxt, while the locations further down
+ are ignored.
     
     Multiple configuration files may be used, however, with the
-'-c' command line flag. The path passed to getwtxt via '-c' may
-be relative or absolute. For example, both of the following are
-allowed:
+ '-c' command line flag. The path passed to getwtxt via '-c' may
+ be relative or absolute. For example, both of the following are
+ allowed:
 
     ./getwtxt -c myconfig.json
     ./getwtxt -c /etc/ExtraConfigsDir/mysecondconfig.toml
 
-The supported configuration types are:
+ The supported configuration types are:
     YAML, TOML, JSON, HCL
 
     The configuration file contains several options used to
-customize your instance of getwtxt. None are required, they will 
-simply use their default value unless otherwise specified.
+ customize your instance of getwtxt. None are required, they will 
+ simply use their default value unless otherwise specified.
 
     ListenPort: Defines the port getwtxt should bind to.
         Default: 9001
@@ -346,7 +368,7 @@ simply use their default value unless otherwise specified.
     DatabasePath: The location of the LevelDB structure
         used by getwtxt to back up registry data. This
         can be a relative or absolute path.
-                Default: getwtxt.db
+        Default: getwtxt.db
 
     StdoutLogging: Boolean used to determine whether
         getwtxt should send logging output to stdout.
@@ -403,5 +425,108 @@ simply use their default value unless otherwise specified.
             <br>
         Default: "A fast, resilient twtxt registry
             server written in Go!"
+
+
+             :: Customizing the Landing Page ::
+
+    If you like, feel free to customize the landing page
+ template provided at 
+
+        assets/tmpl/index.html
+
+    It must be standard HTML or XHTML. There are a few special 
+ tags available to use that will be replaced with specific values 
+ when the template is parsed by getwtxt.
+
+    Values are derived from the "Instance" section of the 
+ configuration file, except for the version of getwtxt used. The 
+ following will be in the form of:
+    
+    {{.TemplateTag}} What it will be replaced with when
+        the template is processed and the landing page is
+        served to a visitor.
+
+    The surrounding double braces and prefixed period are required 
+ if you choose to use these tags in your modified landing page. The
+ tags themselves are not required; access to them is provided simply
+ for convenience.
+
+    {{.Vers}} The version of getwtxt used. Does not include
+        the preceding 'v'. Ex: 0.2.0
+
+    {{.Name}} The name of the instance.
+
+    {{.Owner}} The instance owner's name.
+
+    {{.Mail}} Email address used for contacting the instance
+        owner if the need arises.
+
+    {{.Desc}} Short description placed in the configuration
+        file. This is why HTML tags are allowed.
+
+    {{.URL}} The publicly-accessible URL of your instance. In
+        the default landing page, example API calls are shown
+        using this URL for the convenience of the user.
+
+
+              :: Interacting with the Registry ::
+
+    The registry API is rather simple, and can be interacted with
+ via the command line using cURL. Example output of the calls will
+ not be provided. 
+
+    Pseudo line-breaks will be represented with a backslash. 
+ Examples with line-breaks are not syntactically correct and will
+ be rejected by cURL. Please concatenate the example calls without 
+ the backslash. This is only present to maintain consistent 
+ formatting for this manual text.
+
+    Ex: 
+        /api/plain/users\
+        ?q=FOO
+    Should be: 
+        /api/plain/users?q=FOO
+
+    All queries (every call except adding users) accept the
+ ?page=N parameter, where N > 0. The output is provided in groups 
+ of 20 results. For example, indexed at 1, ?page=2 (or &page=2 if 
+ it is not the first parameter) appended to any query will return 
+ results 21 through 40. If the page requested will exceed the 
+ bounds of the query output, the last 20 query results are returned.
+
+ Adding a user:
+    curl -X POST 'http://localhost:9001/api/plain/users\
+        ?url=https://gbmor.dev/twtxt.txt&nickname=gbmor'
+
+ Retrieve user list:
+    curl 'http://localhost:9001/api/plain/users'
+
+ Retrieve all statuses:
+    curl 'http://localhost:9001/api/plain/tweets'
+
+ Retrieve all statuses with mentions:
+    curl 'http://localhost:9001/api/plain/mentions'
+
+ Retrieve all statuses with tags:
+    curl 'http://localhost:9001/api/plain/tags'
+
+ Query for users by keyword:
+    curl 'http://localhost:9001/api/plain/users?q=FOO'
+
+ Query for users by URL:
+    curl 'http://localhost:9001/api/plain/users\
+        ?url=https://gbmor.dev/twtxt.txt'
+
+ Query for statuses by substring:
+    curl 'http://localhost:9001/api/plain/tweets\
+        ?q=SUBSTRING'
+
+ Query for statuses mentioning a user:
+    curl 'http://localhost:9001/api/plain/mentions\
+        ?url=https://gbmor.dev/twtxt.txt'
+
+ Query for statuses with a given tag:
+    curl 'http://localhost:9001/api/plain/tags/myTagHere'
+
 `)
 }