From a4aff1c4af365b66dde1b8751a7a495de280f946 Mon Sep 17 00:00:00 2001 From: Ben Morrison Date: Tue, 4 Jun 2019 01:41:56 -0400 Subject: expanded -m help text to cover landing page customization, example api queries --- init.go | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file 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.
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' + `) } -- cgit 1.4.1-2-gfad0