Consolidate documentation on config folder (#345)

The semantics around `klog config` and `klog info config-folder` are a
bit confusing. This PR consolidates all config-related documentation
into the `klog config` command. `klog info config-folder` has now become
`klog config --location`.

Author: jotaen

klog/app/cli/bookmarks.go

@@ -35,12 +35,14 @@ A bookmark name is denoted by the prefix '@'. For example, if you have a bookmar
     klog edit @work
 
 You can specify as many bookmarks as you want. There can also be one “unnamed” default bookmark (which internally is identified by the name '@default').
-This is useful in case you only have one main file at a time, and allows you to use klog without any input arguments at all. E.g.:
+This is useful in case you only have one main file at a time, and allows you to use klog without any file-related input arguments at all. E.g.:
 
     klog total
     klog start --summary 'Started new project'
 
-When creating a bookmark, you can also create the respective target file by using the '--create' flag.
+When setting up a bookmark, you can also create the respective target file on the file system by using the '--create' flag.
+
+Note that klog keeps track of the bookmarks in an internal config file. Run 'klog config --help' to learn more.
 `
 }
 

klog/app/cli/config.go

@@ -4,26 +4,45 @@ import (
 	"github.com/jotaen/klog/klog/app"
 	tf "github.com/jotaen/klog/klog/app/cli/terminalformat"
 	"github.com/jotaen/klog/klog/app/cli/util"
+	"path/filepath"
+	"strings"
 )
 
 type Config struct {
+	Location bool `name:"location" help:"Print the location of the config folder."`
 	util.NoStyleArgs
 }
 
 func (opt *Config) Help() string {
+	lookupOrder := func() string {
+		lookups := make([]string, len(app.KLOG_CONFIG_FOLDER))
+		for i, f := range app.KLOG_CONFIG_FOLDER {
+			lookups[i] = filepath.Join(f.EnvVarSymbol(), f.Location)
+		}
+		return strings.Join(lookups, "  ->  ")
+	}()
+
 	return `
-You are able to configure some of klog’s behaviour by providing a configuration file.
+klog relies on file-based configuration to customise some of its default behaviour and to keep track of its internal state.
 
-If you run 'klog config', you can learn about the supported properties in the file, and which of those you have set.
-You may use the output of that command as template for setting up your config file, as its format is valid syntax.
+Run 'klog config --location' to print the path of the folder where klog looks for the configuration.
+The config folder can contain one or both of the following files:
+  - '` + app.CONFIG_FILE_NAME + `': you can create this file manually to override some of klog’s default behaviour. You may use the output of the 'klog config' command as template for setting up this file, as its output is in valid syntax. 
+  - '` + app.BOOKMARKS_FILE_NAME + `': if you use the bookmarks functionality, then klog uses this file as database. You are not supposed to edit this file by hand! Instead, use the 'klog bookmarks' command to manage your bookmarks.
 
-The configuration file is named 'config.ini' and resides in your klog config folder.
-Run 'klog info config-folder' to learn where your klog config folder is located.
+You can customise the location of the config folder via environment variables. klog uses the following lookup precedence:
+  ` + lookupOrder + `
 `
 }
 
 func (opt *Config) Run(ctx app.Context) app.Error {
 	opt.NoStyleArgs.Apply(&ctx)
+
+	if opt.Location {
+		ctx.Print(ctx.KlogConfigFolder().Path() + "\n")
+		return nil
+	}
+
 	styler, _ := ctx.Serialise()
 	for i, e := range app.CONFIG_FILE_ENTRIES {
 		ctx.Print(styler.Props(tf.StyleProps{Color: tf.TEXT_SUBDUED}).Format(util.Reflower.Reflow(e.Help.Summary, []string{"# "})))

klog/app/cli/index.go

@@ -8,6 +8,8 @@ import (
 	kc "github.com/jotaen/kong-completion"
 )
 
+var INTRO_SUMMARY = "klog is a command-line tool for time tracking in a human-readable, plain-text file format.\nSee " + KLOG_WEBSITE_URL + " for documentation.\n"
+
 // Guideline for help texts and descriptions:
 // - Command and flag descriptions are phrased in imperative style, and they
 //   end in a period. Examples:
@@ -54,11 +56,10 @@ type Default struct {
 }
 
 func (opt *Default) Help() string {
-	return `
-klog: command line app for time tracking with plain-text files. See also ` + KLOG_WEBSITE_URL + `
+	return INTRO_SUMMARY + `
 
 Time-tracking data is stored in files ending in the '.klg' extension.
-You can use the subcommands below to evaluate, manipulate and manage your files.
+You can use the subcommands listed below to evaluate, manipulate and manage your files.
 Use the '--help' flag on the subcommands to learn more.
 
 You can specify input data in one of these 3 ways:
@@ -80,7 +81,7 @@ func (opt *Default) Run(ctx app.Context) app.Error {
 		versionCmd := Version{}
 		return versionCmd.Run(ctx)
 	}
-	ctx.Print("klog: command line app for time tracking with plain-text files.\n")
+	ctx.Print(INTRO_SUMMARY)
 	ctx.Print("Run 'klog --help' to learn usage.\n")
 	return nil
 }

klog/app/cli/info.go

@@ -2,58 +2,23 @@ package cli
 
 import (
 	"github.com/jotaen/klog/klog/app"
-	"github.com/jotaen/klog/klog/app/cli/util"
-	"path/filepath"
-	"strings"
 )
 
 type Info struct {
-	Spec         InfoSpec         `cmd:"" name:"spec" help:"Print the .klg file format specification."`
-	License      InfoLicense      `cmd:"" name:"license" help:"Print license / copyright information."`
-	ConfigFolder InfoConfigFolder `cmd:"" name:"config-folder" help:"Print the path of the klog config folder."`
+	Spec    bool `name:"spec" help:"Print the .klg file format specification."`
+	License bool `name:"license" help:"Print license / copyright information."`
+	About   bool `name:"about" help:"Print meta information about klog."`
 }
 
-func (opt *Info) Help() string {
-	return `
-Run 'klog info config-folder' to see the location of your klog config folder.
-The location of the config folder depends on your operating system and environment settings.
-You can customise the folder’s location via environment variables – run the command to learn which ones klog relies on.
-
-The config folder is used to store two files:
-  - 'config.ini' (optional) – you can create this file manually to override some of klog’s default behaviour. Run 'klog config' to learn more.
-  - 'bookmarks.json' (optional) – if you use bookmarks, then klog uses this file as database. You are not supposed to edit this file by hand! Instead, use the 'klog bookmarks' command to manage your bookmarks.
-
-Run 'klog info spec' to read the formal specification of the klog file format.
-If you want to review klog’s license and copyright information, run 'klog info license'.
-`
-}
-
-type InfoConfigFolder struct {
-	util.QuietArgs
-}
-
-func (opt *InfoConfigFolder) Run(ctx app.Context) app.Error {
-	ctx.Print(ctx.KlogConfigFolder().Path() + "\n")
-	if !opt.Quiet {
-		lookups := make([]string, len(app.KLOG_CONFIG_FOLDER))
-		for i, f := range app.KLOG_CONFIG_FOLDER {
-			lookups[i] = filepath.Join(f.EnvVarSymbol(), f.Location)
-		}
-		ctx.Print("(Lookup order: " + strings.Join(lookups, ", ") + ")\n")
+func (opt *Info) Run(ctx app.Context) app.Error {
+	if opt.Spec {
+		ctx.Print(ctx.Meta().Specification + "\n")
+	} else if opt.License {
+		ctx.Print(ctx.Meta().License + "\n")
+	} else if opt.About {
+		ctx.Print(INTRO_SUMMARY)
+	} else {
+		ctx.Print("Use --spec or --license\n")
 	}
 	return nil
 }
-
-type InfoSpec struct{}
-
-func (opt *InfoSpec) Run(ctx app.Context) app.Error {
-	ctx.Print(ctx.Meta().Specification + "\n")
-	return nil
-}
-
-type InfoLicense struct{}
-
-func (opt *InfoLicense) Run(ctx app.Context) app.Error {
-	ctx.Print(ctx.Meta().License + "\n")
-	return nil
-}