Improve formatting of Hugo command descriptions

Trying to make them look good both in the terminal (`hugo help [command]`)
and in the web browser (http://gohugo.io/commands/).  :-)

11 files changed, 61 insertions, 48 deletions

diff --git a/commands/benchmark.go b/commands/benchmark.go
index 1e0cc8d7b..b76c9e884 100644
--- a/commands/benchmark.go
+++ b/commands/benchmark.go
@@ -25,9 +25,9 @@ var benchmarkTimes int
 
 var benchmark = &cobra.Command{
 	Use:   "benchmark",
-	Short: "Benchmark hugo by building a site a number of times",
-	Long: `Hugo can build a site many times over and analyze the
-running process creating a benchmark.`,
+	Short: "Benchmark hugo by building a site a number of times.",
+	Long: `Hugo can build a site many times over and analyze the running process
+creating a benchmark.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		InitializeConfig()
 		bench(cmd, args)
diff --git a/commands/check.go b/commands/check.go
index ee5a6d5d8..1bb43298a 100644
--- a/commands/check.go
+++ b/commands/check.go
@@ -21,8 +21,8 @@ import (
 var check = &cobra.Command{
 	Use:   "check",
 	Short: "Check content in the source directory",
-	Long: `Hugo will perform some basic analysis on the
-    content provided and will give feedback.`,
+	Long: `Hugo will perform some basic analysis on the content provided
+and will give feedback.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		InitializeConfig()
 		site := hugolib.Site{}
diff --git a/commands/convert.go b/commands/convert.go
index 6268fb2a2..188ab7a72 100644
--- a/commands/convert.go
+++ b/commands/convert.go
@@ -32,16 +32,18 @@ var unsafe bool
 
 var convertCmd = &cobra.Command{
 	Use:   "convert",
-	Short: "Convert will modify your content to different formats",
-	Long:  `Convert will modify your content to different formats`,
+	Short: "Convert your content to different formats",
+	Long:  `Convert your content (e.g. front matter) to different formats.
+
+See convert's subcommands toJSON, toTOML and toYAML for more information.`,
 	Run:   nil,
 }
 
 var toJSONCmd = &cobra.Command{
 	Use:   "toJSON",
 	Short: "Convert front matter to JSON",
-	Long: `toJSON will convert all front matter in the content
-	directory to use JSON for the front matter`,
+	Long: `toJSON converts all front matter in the content directory
+to use JSON for the front matter.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		err := convertContents(rune([]byte(parser.JSON_LEAD)[0]))
 		if err != nil {
@@ -53,8 +55,8 @@ var toJSONCmd = &cobra.Command{
 var toTOMLCmd = &cobra.Command{
 	Use:   "toTOML",
 	Short: "Convert front matter to TOML",
-	Long: `toTOML will convert all front matter in the content
-	directory to use TOML for the front matter`,
+	Long: `toTOML converts all front matter in the content directory
+to use TOML for the front matter.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		err := convertContents(rune([]byte(parser.TOML_LEAD)[0]))
 		if err != nil {
@@ -66,8 +68,8 @@ var toTOMLCmd = &cobra.Command{
 var toYAMLCmd = &cobra.Command{
 	Use:   "toYAML",
 	Short: "Convert front matter to YAML",
-	Long: `toYAML will convert all front matter in the content
-	directory to use YAML for the front matter`,
+	Long: `toYAML converts all front matter in the content directory
+to use YAML for the front matter.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		err := convertContents(rune([]byte(parser.YAML_LEAD)[0]))
 		if err != nil {
diff --git a/commands/genautocomplete.go b/commands/genautocomplete.go
index 69e9e6f0f..d2a8704f3 100644
--- a/commands/genautocomplete.go
+++ b/commands/genautocomplete.go
@@ -14,19 +14,23 @@ var genautocompleteCmd = &cobra.Command{
 	Use:   "genautocomplete",
 	Short: "Generate shell autocompletion script for Hugo",
 	Long: `Generates a shell autocompletion script for Hugo.
-	
-	NOTE: The current version supports Bash only. This should work for *nix systems with Bash installed.
-	
-	By default the file is written directly to /etc/bash_completion.d for convenience and the command may need superuser rights, e.g:
-	
-	sudo hugo genautocomplete
-	
-	Add --completionfile=/path/to/file flag to set alternative file-path and name.
-	
-	Logout and in again to reload the completion scripts or just source them in directly:
-	
-	. /etc/bash_completion
-	`,
+
+NOTE: The current version supports Bash only.
+      This should work for *nix systems with Bash installed.
+
+By default, the file is written directly to /etc/bash_completion.d
+for convenience, and the command may need superuser rights, e.g.:
+
+	$ sudo hugo genautocomplete
+
+Add ` + "`--completionfile=/path/to/file`" + ` flag to set alternative
+file-path and name.
+
+Logout and in again to reload the completion scripts,
+or just source them in directly:
+
+	$ . /etc/bash_completion`,
+
 	Run: func(cmd *cobra.Command, args []string) {
 		if autocompleteType != "bash" {
 			jww.FATAL.Fatalln("Only Bash is supported for now")
diff --git a/commands/gendoc.go b/commands/gendoc.go
index b8b07a0b7..34f9c1229 100644
--- a/commands/gendoc.go
+++ b/commands/gendoc.go
@@ -24,11 +24,12 @@ var gendocCmd = &cobra.Command{
 	Use:   "gendoc",
 	Short: "Generate Markdown documentation for the Hugo CLI.",
 	Long: `Generate Markdown documentation for the Hugo CLI.
-	
-	This command is, mostly, used to create up-to-date documentation for gohugo.io.
-	
-	It creates one Markdown file per command with front matter suitable for rendering in Hugo.
-	`,
+
+This command is, mostly, used to create up-to-date documentation
+of Hugo's command-line interface for http://gohugo.io/.
+
+It creates one Markdown file per command with front matter suitable
+for rendering in Hugo.`,
 
 	Run: func(cmd *cobra.Command, args []string) {
 		if !strings.HasSuffix(gendocdir, helpers.FilePathSeparator) {
diff --git a/commands/hugo.go b/commands/hugo.go
index 7caae5d16..e1a75a097 100644
--- a/commands/hugo.go
+++ b/commands/hugo.go
@@ -43,11 +43,12 @@ import (
 var HugoCmd = &cobra.Command{
 	Use:   "hugo",
 	Short: "hugo builds your site",
-	Long: `hugo is the main command, used to build your Hugo site. 
-	
-Hugo is a Fast and Flexible Static Site Generator built with love by spf13 and friends in Go.
+	Long: `hugo is the main command, used to build your Hugo site.
 
-Complete documentation is available at http://gohugo.io`,
+Hugo is a Fast and Flexible Static Site Generator
+built with love by spf13 and friends in Go.
+
+Complete documentation is available at http://gohugo.io/.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		InitializeConfig()
 		build()
diff --git a/commands/list.go b/commands/list.go
index d3510420a..7499080b1 100644
--- a/commands/list.go
+++ b/commands/list.go
@@ -30,14 +30,16 @@ func init() {
 var listCmd = &cobra.Command{
 	Use:   "list",
 	Short: "Listing out various types of content",
-	Long:  `Listing out various types of content. List requires a subcommand, eg. hugo list drafts`,
+	Long:  `Listing out various types of content.
+
+List requires a subcommand, e.g. ` + "`hugo list drafts`.",
 	Run:   nil,
 }
 
 var listDraftsCmd = &cobra.Command{
 	Use:   "drafts",
 	Short: "List all drafts",
-	Long:  `List all of the drafts in your content directory`,
+	Long:  `List all of the drafts in your content directory.`,
 	Run: func(cmd *cobra.Command, args []string) {
 
 		InitializeConfig()
@@ -62,7 +64,8 @@ var listDraftsCmd = &cobra.Command{
 var listFutureCmd = &cobra.Command{
 	Use:   "future",
 	Short: "List all posts dated in the future",
-	Long:  `List all of the posts in your content directory who will be posted in the future`,
+	Long:  `List all of the posts in your content directory which will be
+posted in the future.`,
 	Run: func(cmd *cobra.Command, args []string) {
 
 		InitializeConfig()
diff --git a/commands/list_config.go b/commands/list_config.go
index 8dad011cd..c8208f124 100644
--- a/commands/list_config.go
+++ b/commands/list_config.go
@@ -24,7 +24,7 @@ import (
 var config = &cobra.Command{
 	Use:   "config",
 	Short: "Print the site configuration",
-	Long:  `Print the site configuration, both default and custom settings`,
+	Long:  `Print the site configuration, both default and custom settings.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		InitializeConfig()
 		allSettings := viper.AllSettings()
diff --git a/commands/new.go b/commands/new.go
index 0e9f4d58b..f22a36f56 100644
--- a/commands/new.go
+++ b/commands/new.go
@@ -48,9 +48,11 @@ var newCmd = &cobra.Command{
 	Short: "Create new content for your site",
 	Long: `Create a new content file and automatically set the date and title.
 It will guess which kind of file to create based on the path provided.
-You can also specify the kind with -k KIND
-If archetypes are provided in your theme or site, they will be used.
-`,
+
+You can also specify the kind with ` + "`-k KIND`" + `.
+
+If archetypes are provided in your theme or site, they will be used.`,
+
 	Run: NewContent,
 }
 
@@ -59,8 +61,7 @@ var newSiteCmd = &cobra.Command{
 	Short: "Create a new site (skeleton)",
 	Long: `Create a new site in the provided directory.
 The new site will have the correct structure, but no content or theme yet.
-Use 'hugo new [contentPath]' to create new content.
-	`,
+Use ` + "`hugo new [contentPath]`" + ` to create new content.`,
 	Run: NewSite,
 }
 
@@ -70,8 +71,7 @@ var newThemeCmd = &cobra.Command{
 	Long: `Create a new theme (skeleton) called [name] in the current directory.
 New theme is a skeleton. Please add content to the touched files. Add your
 name to the copyright line in the license and adjust the theme.toml file
-as you see fit.
-	`,
+as you see fit.`,
 	Run: NewTheme,
 }
 
diff --git a/commands/undraft.go b/commands/undraft.go
index 4dbdf45c9..f10728d82 100644
--- a/commands/undraft.go
+++ b/commands/undraft.go
@@ -26,7 +26,9 @@ import (
 var undraftCmd = &cobra.Command{
 	Use:   "undraft path/to/content",
 	Short: "Undraft changes the content's draft status from 'True' to 'False'",
-	Long:  `Undraft changes the content's draft status from 'True' to 'False' and updates the date to the current date and time. If the content's draft status is 'False', nothing is done`,
+	Long:  `Undraft changes the content's draft status from 'True' to 'False'
+and updates the date to the current date and time.
+If the content's draft status is 'False', nothing is done.`,
 	Run:   Undraft,
 }
 
diff --git a/commands/version.go b/commands/version.go
index 24a900cad..dd6d91cf3 100644
--- a/commands/version.go
+++ b/commands/version.go
@@ -31,7 +31,7 @@ var timeLayout string // the layout for time.Time
 var version = &cobra.Command{
 	Use:   "version",
 	Short: "Print the version number of Hugo",
-	Long:  `All software has versions. This is Hugo's`,
+	Long:  `All software has versions. This is Hugo's.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		if hugolib.BuildDate == "" {
 			setBuildDate() // set the build date from executable's mdate