lib: Add short description to godoc headers.
The auto-generated doc.go file for cmdline tools is formatted
specially so that godoc will interpret each command as a header,
which gets automatically linked to a table of contents. This
change adds the short description from each command or help
topic, to make the TOC more useful.
Note that godoc has heurisitics for what it considers an
appropriate header; e.g. if the line contains certain puncutation
it won't be extracted as a header. For these cases we fall back
and only use the command path, since it's better to have a less
descriptive header than to have no header at all.
Also added LineWriter.ForceVerbatim, which lets us force verbatim
mode. This is used to ensure the header line we generate isn't
wrapped into more than one line.
MultiPart: 2/3
Change-Id: I66b4555fdf281604d384f65a51accec4f1fff542
diff --git a/cmdline/cmdline_test.go b/cmdline/cmdline_test.go
index acec00c..0f2af2e 100644
--- a/cmdline/cmdline_test.go
+++ b/cmdline/cmdline_test.go
@@ -428,7 +428,7 @@
-global2=0
global test flag 2
================================================================================
-Cmdrun echo
+Cmdrun echo - Print strings on stdout
Echo prints any strings passed in to stdout.
@@ -437,7 +437,7 @@
[strings] are arbitrary strings that will be echoed.
================================================================================
-Cmdrun help
+Cmdrun help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -665,7 +665,7 @@
-global2=0
global test flag 2
================================================================================
-Onecmd echo
+Onecmd echo - Print strings on stdout
Echo prints any strings passed in to stdout.
@@ -674,7 +674,7 @@
[strings] are arbitrary strings that will be echoed.
================================================================================
-Onecmd help
+Onecmd help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -767,7 +767,7 @@
var cmdEchoOpt = &Command{
Runner: RunnerFunc(runEcho),
Name: "echoopt",
- Short: "Print strings on stdout, with opts",
+ Short: "Print strings on stdout with opts",
// Try varying number of header/trailer newlines around the long description.
Long: `Echoopt prints any args passed in to stdout.
@@ -799,7 +799,7 @@
The multi commands are:
echo Print strings on stdout
- echoopt Print strings on stdout, with opts
+ echoopt Print strings on stdout with opts
help Display help for commands or topics
Run "multi help [command]" for command usage.
@@ -823,7 +823,7 @@
The multi commands are:
echo Print strings on stdout
- echoopt Print strings on stdout, with opts
+ echoopt Print strings on stdout with opts
help Display help for commands or topics
Run "multi help [command]" for command usage.
@@ -847,7 +847,7 @@
The multi commands are:
echo Print strings on stdout
- echoopt Print strings on stdout, with opts
+ echoopt Print strings on stdout with opts
help Display help for commands or topics
Run "multi help [command]" for command usage.
@@ -861,7 +861,7 @@
-global2=0
global test flag 2
================================================================================
-Multi echo
+Multi echo - Print strings on stdout
Echo prints any strings passed in to stdout.
@@ -870,7 +870,7 @@
[strings] are arbitrary strings that will be echoed.
================================================================================
-Multi echoopt
+Multi echoopt - Print strings on stdout with opts
Echoopt prints any args passed in to stdout.
@@ -883,7 +883,7 @@
-n=false
Do not output trailing newline
================================================================================
-Multi help
+Multi help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -957,7 +957,7 @@
The multi commands are:
echo Print strings on stdout
- echoopt Print strings on stdout, with opts
+ echoopt Print strings on stdout with opts
help Display help for commands or topics
Run "multi help [command]" for command usage.
@@ -1051,7 +1051,7 @@
The multi commands are:
echo Print strings on stdout
- echoopt Print strings on stdout, with opts
+ echoopt Print strings on stdout with opts
help Display help for commands or topics
Run "multi help [command]" for command usage.
@@ -1084,7 +1084,7 @@
cmdEchoOpt := &Command{
Runner: RunnerFunc(runEcho),
Name: "echoopt",
- Short: "Print strings on stdout, with opts",
+ Short: "Print strings on stdout with opts",
// Try varying number of header/trailer newlines around the long description.
Long: `Echoopt prints any args passed in to stdout.
@@ -1097,7 +1097,7 @@
cmdHello := &Command{
Runner: RunnerFunc(runHello),
Name: "hello",
- Short: "Print strings on stdout preceded by \"Hello\"",
+ Short: "Print strings on stdout preceded by Hello",
Long: `
Hello prints any strings passed in to stdout preceded by "Hello".
`,
@@ -1139,7 +1139,7 @@
The toplevelprog commands are:
echoprog Set of echo commands
- hello Print strings on stdout preceded by "Hello"
+ hello Print strings on stdout preceded by Hello
help Display help for commands or topics
Run "toplevelprog help [command]" for command usage.
@@ -1168,7 +1168,7 @@
The toplevelprog commands are:
echoprog Set of echo commands
- hello Print strings on stdout preceded by "Hello"
+ hello Print strings on stdout preceded by Hello
help Display help for commands or topics
Run "toplevelprog help [command]" for command usage.
@@ -1197,7 +1197,7 @@
The toplevelprog commands are:
echoprog Set of echo commands
- hello Print strings on stdout preceded by "Hello"
+ hello Print strings on stdout preceded by Hello
help Display help for commands or topics
Run "toplevelprog help [command]" for command usage.
@@ -1216,7 +1216,7 @@
-global2=0
global test flag 2
================================================================================
-Toplevelprog echoprog
+Toplevelprog echoprog - Set of echo commands
Echoprog has two variants of echo.
@@ -1225,7 +1225,7 @@
The toplevelprog echoprog commands are:
echo Print strings on stdout
- echoopt Print strings on stdout, with opts
+ echoopt Print strings on stdout with opts
The toplevelprog echoprog additional help topics are:
topic3 Help topic 3 short
@@ -1234,7 +1234,7 @@
-extra=false
Print an extra arg
================================================================================
-Toplevelprog echoprog echo
+Toplevelprog echoprog echo - Print strings on stdout
Echo prints any strings passed in to stdout.
@@ -1243,7 +1243,7 @@
[strings] are arbitrary strings that will be echoed.
================================================================================
-Toplevelprog echoprog echoopt
+Toplevelprog echoprog echoopt - Print strings on stdout with opts
Echoopt prints any args passed in to stdout.
@@ -1256,11 +1256,11 @@
-n=false
Do not output trailing newline
================================================================================
-Toplevelprog echoprog topic3 - help topic
+Toplevelprog echoprog topic3 - Help topic 3 short
Help topic 3 long.
================================================================================
-Toplevelprog hello
+Toplevelprog hello - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1269,7 +1269,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Toplevelprog help
+Toplevelprog help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -1294,11 +1294,11 @@
Defaults to the terminal width if available. Override the default by setting
the CMDLINE_WIDTH environment variable.
================================================================================
-Toplevelprog topic1 - help topic
+Toplevelprog topic1 - Help topic 1 short
Help topic 1 long.
================================================================================
-Toplevelprog topic2 - help topic
+Toplevelprog topic2 - Help topic 2 short
Help topic 2 long.
`,
@@ -1312,7 +1312,7 @@
The toplevelprog echoprog commands are:
echo Print strings on stdout
- echoopt Print strings on stdout, with opts
+ echoopt Print strings on stdout with opts
help Display help for commands or topics
Run "toplevelprog echoprog help [command]" for command usage.
@@ -1350,7 +1350,7 @@
The toplevelprog echoprog commands are:
echo Print strings on stdout
- echoopt Print strings on stdout, with opts
+ echoopt Print strings on stdout with opts
help Display help for commands or topics
Run "toplevelprog echoprog help [command]" for command usage.
@@ -1368,7 +1368,7 @@
-global2=0
global test flag 2
================================================================================
-Toplevelprog echoprog echo
+Toplevelprog echoprog echo - Print strings on stdout
Echo prints any strings passed in to stdout.
@@ -1377,7 +1377,7 @@
[strings] are arbitrary strings that will be echoed.
================================================================================
-Toplevelprog echoprog echoopt
+Toplevelprog echoprog echoopt - Print strings on stdout with opts
Echoopt prints any args passed in to stdout.
@@ -1390,7 +1390,7 @@
-n=false
Do not output trailing newline
================================================================================
-Toplevelprog echoprog help
+Toplevelprog echoprog help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -1415,7 +1415,7 @@
Defaults to the terminal width if available. Override the default by setting
the CMDLINE_WIDTH environment variable.
================================================================================
-Toplevelprog echoprog topic3 - help topic
+Toplevelprog echoprog topic3 - Help topic 3 short
Help topic 3 long.
`,
@@ -1478,7 +1478,7 @@
The toplevelprog commands are:
echoprog Set of echo commands
- hello Print strings on stdout preceded by "Hello"
+ hello Print strings on stdout preceded by Hello
help Display help for commands or topics
Run "toplevelprog help [command]" for command usage.
@@ -1573,7 +1573,7 @@
The toplevelprog commands are:
echoprog Set of echo commands
- hello Print strings on stdout preceded by "Hello"
+ hello Print strings on stdout preceded by Hello
help Display help for commands or topics
Run "toplevelprog help [command]" for command usage.
@@ -1600,7 +1600,7 @@
func TestMultiLevelCommandsOrdering(t *testing.T) {
cmdHello11 := &Command{
Name: "hello11",
- Short: "Print strings on stdout preceded by \"Hello\"",
+ Short: "Print strings on stdout preceded by Hello",
Long: `
Hello prints any strings passed in to stdout preceded by "Hello".
`,
@@ -1610,7 +1610,7 @@
}
cmdHello12 := &Command{
Name: "hello12",
- Short: "Print strings on stdout preceded by \"Hello\"",
+ Short: "Print strings on stdout preceded by Hello",
Long: `
Hello prints any strings passed in to stdout preceded by "Hello".
`,
@@ -1620,7 +1620,7 @@
}
cmdHello21 := &Command{
Name: "hello21",
- Short: "Print strings on stdout preceded by \"Hello\"",
+ Short: "Print strings on stdout preceded by Hello",
Long: `
Hello prints any strings passed in to stdout preceded by "Hello".
`,
@@ -1630,7 +1630,7 @@
}
cmdHello22 := &Command{
Name: "hello22",
- Short: "Print strings on stdout preceded by \"Hello\"",
+ Short: "Print strings on stdout preceded by Hello",
Long: `
Hello prints any strings passed in to stdout preceded by "Hello".
`,
@@ -1640,7 +1640,7 @@
}
cmdHello31 := &Command{
Name: "hello31",
- Short: "Print strings on stdout preceded by \"Hello\"",
+ Short: "Print strings on stdout preceded by Hello",
Long: `
Hello prints any strings passed in to stdout preceded by "Hello".
`,
@@ -1650,7 +1650,7 @@
}
cmdHello32 := &Command{
Name: "hello32",
- Short: "Print strings on stdout preceded by \"Hello\"",
+ Short: "Print strings on stdout preceded by Hello",
Long: `
Hello prints any strings passed in to stdout preceded by "Hello".
`,
@@ -1689,8 +1689,8 @@
prog1 <command>
The prog1 commands are:
- hello11 Print strings on stdout preceded by "Hello"
- hello12 Print strings on stdout preceded by "Hello"
+ hello11 Print strings on stdout preceded by Hello
+ hello12 Print strings on stdout preceded by Hello
prog2 Set of hello commands
help Display help for commands or topics
Run "prog1 help [command]" for command usage.
@@ -1710,8 +1710,8 @@
prog1 <command>
The prog1 commands are:
- hello11 Print strings on stdout preceded by "Hello"
- hello12 Print strings on stdout preceded by "Hello"
+ hello11 Print strings on stdout preceded by Hello
+ hello12 Print strings on stdout preceded by Hello
prog2 Set of hello commands
help Display help for commands or topics
Run "prog1 help [command]" for command usage.
@@ -1731,8 +1731,8 @@
prog1 <command>
The prog1 commands are:
- hello11 Print strings on stdout preceded by "Hello"
- hello12 Print strings on stdout preceded by "Hello"
+ hello11 Print strings on stdout preceded by Hello
+ hello12 Print strings on stdout preceded by Hello
prog2 Set of hello commands
help Display help for commands or topics
Run "prog1 help [command]" for command usage.
@@ -1743,7 +1743,7 @@
-global2=0
global test flag 2
================================================================================
-Prog1 hello11
+Prog1 hello11 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1752,7 +1752,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 hello12
+Prog1 hello12 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1761,7 +1761,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2
+Prog1 prog2 - Set of hello commands
Prog2 has two variants of hello and a subprogram prog3.
@@ -1769,11 +1769,11 @@
prog1 prog2 <command>
The prog1 prog2 commands are:
- hello21 Print strings on stdout preceded by "Hello"
+ hello21 Print strings on stdout preceded by Hello
prog3 Set of hello commands
- hello22 Print strings on stdout preceded by "Hello"
+ hello22 Print strings on stdout preceded by Hello
================================================================================
-Prog1 prog2 hello21
+Prog1 prog2 hello21 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1782,7 +1782,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 prog3
+Prog1 prog2 prog3 - Set of hello commands
Prog3 has two variants of hello.
@@ -1790,10 +1790,10 @@
prog1 prog2 prog3 <command>
The prog1 prog2 prog3 commands are:
- hello31 Print strings on stdout preceded by "Hello"
- hello32 Print strings on stdout preceded by "Hello"
+ hello31 Print strings on stdout preceded by Hello
+ hello32 Print strings on stdout preceded by Hello
================================================================================
-Prog1 prog2 prog3 hello31
+Prog1 prog2 prog3 hello31 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1802,7 +1802,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 prog3 hello32
+Prog1 prog2 prog3 hello32 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1811,7 +1811,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 hello22
+Prog1 prog2 hello22 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1820,7 +1820,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 help
+Prog1 help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -1854,9 +1854,9 @@
prog1 prog2 <command>
The prog1 prog2 commands are:
- hello21 Print strings on stdout preceded by "Hello"
+ hello21 Print strings on stdout preceded by Hello
prog3 Set of hello commands
- hello22 Print strings on stdout preceded by "Hello"
+ hello22 Print strings on stdout preceded by Hello
help Display help for commands or topics
Run "prog1 prog2 help [command]" for command usage.
@@ -1866,7 +1866,7 @@
-global2=0
global test flag 2
================================================================================
-Prog1 prog2 hello21
+Prog1 prog2 hello21 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1875,7 +1875,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 prog3
+Prog1 prog2 prog3 - Set of hello commands
Prog3 has two variants of hello.
@@ -1883,10 +1883,10 @@
prog1 prog2 prog3 <command>
The prog1 prog2 prog3 commands are:
- hello31 Print strings on stdout preceded by "Hello"
- hello32 Print strings on stdout preceded by "Hello"
+ hello31 Print strings on stdout preceded by Hello
+ hello32 Print strings on stdout preceded by Hello
================================================================================
-Prog1 prog2 prog3 hello31
+Prog1 prog2 prog3 hello31 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1895,7 +1895,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 prog3 hello32
+Prog1 prog2 prog3 hello32 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1904,7 +1904,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 hello22
+Prog1 prog2 hello22 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1913,7 +1913,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 help
+Prog1 prog2 help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -1947,8 +1947,8 @@
prog1 prog2 prog3 <command>
The prog1 prog2 prog3 commands are:
- hello31 Print strings on stdout preceded by "Hello"
- hello32 Print strings on stdout preceded by "Hello"
+ hello31 Print strings on stdout preceded by Hello
+ hello32 Print strings on stdout preceded by Hello
help Display help for commands or topics
Run "prog1 prog2 prog3 help [command]" for command usage.
@@ -1958,7 +1958,7 @@
-global2=0
global test flag 2
================================================================================
-Prog1 prog2 prog3 hello31
+Prog1 prog2 prog3 hello31 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1967,7 +1967,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 prog3 hello32
+Prog1 prog2 prog3 hello32 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1976,7 +1976,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 prog3 help
+Prog1 prog2 prog3 help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -2010,8 +2010,8 @@
prog1 prog2 prog3 <command>
The prog1 prog2 prog3 commands are:
- hello31 Print strings on stdout preceded by "Hello"
- hello32 Print strings on stdout preceded by "Hello"
+ hello31 Print strings on stdout preceded by Hello
+ hello32 Print strings on stdout preceded by Hello
help Display help for commands or topics
Run "prog1 prog2 prog3 help [command]" for command usage.
@@ -2021,7 +2021,7 @@
-global2=0
global test flag 2
================================================================================
-Prog1 prog2 prog3 hello31
+Prog1 prog2 prog3 hello31 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -2030,7 +2030,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 prog3 hello32
+Prog1 prog2 prog3 hello32 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -2039,7 +2039,7 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Prog1 prog2 prog3 help
+Prog1 prog2 prog3 help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -2073,8 +2073,8 @@
prog1 <command>
The prog1 commands are:
- hello11 Print strings on stdout preceded by "Hello"
- hello12 Print strings on stdout preceded by "Hello"
+ hello11 Print strings on stdout preceded by Hello
+ hello12 Print strings on stdout preceded by Hello
prog2 Set of hello commands
help Display help for commands or topics
@@ -2084,7 +2084,7 @@
-global2=0
global test flag 2
-Prog1 hello11
+Prog1 hello11 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -2093,7 +2093,7 @@
[strings] are arbitrary strings that will be printed.
-Prog1 hello12
+Prog1 hello12 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -2102,7 +2102,7 @@
[strings] are arbitrary strings that will be printed.
-Prog1 prog2
+Prog1 prog2 - Set of hello commands
Prog2 has two variants of hello and a subprogram prog3.
@@ -2110,11 +2110,11 @@
prog1 prog2 <command>
The prog1 prog2 commands are:
- hello21 Print strings on stdout preceded by "Hello"
+ hello21 Print strings on stdout preceded by Hello
prog3 Set of hello commands
- hello22 Print strings on stdout preceded by "Hello"
+ hello22 Print strings on stdout preceded by Hello
-Prog1 prog2 hello21
+Prog1 prog2 hello21 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -2123,7 +2123,7 @@
[strings] are arbitrary strings that will be printed.
-Prog1 prog2 prog3
+Prog1 prog2 prog3 - Set of hello commands
Prog3 has two variants of hello.
@@ -2131,10 +2131,10 @@
prog1 prog2 prog3 <command>
The prog1 prog2 prog3 commands are:
- hello31 Print strings on stdout preceded by "Hello"
- hello32 Print strings on stdout preceded by "Hello"
+ hello31 Print strings on stdout preceded by Hello
+ hello32 Print strings on stdout preceded by Hello
-Prog1 prog2 prog3 hello31
+Prog1 prog2 prog3 hello31 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -2143,7 +2143,7 @@
[strings] are arbitrary strings that will be printed.
-Prog1 prog2 prog3 hello32
+Prog1 prog2 prog3 hello32 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -2152,7 +2152,7 @@
[strings] are arbitrary strings that will be printed.
-Prog1 prog2 hello22
+Prog1 prog2 hello22 - Print strings on stdout preceded by Hello
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -2161,7 +2161,7 @@
[strings] are arbitrary strings that will be printed.
-Prog1 help
+Prog1 help - Display help for commands or topics
Help with no args displays the usage of the parent command.
diff --git a/cmdline/help.go b/cmdline/help.go
index 20955fb..178c02b 100644
--- a/cmdline/help.go
+++ b/cmdline/help.go
@@ -5,8 +5,10 @@
package cmdline
import (
+ "bytes"
"flag"
"fmt"
+ "go/doc"
"io"
"regexp"
"strings"
@@ -120,9 +122,36 @@
return usageErrorf(stderr, fn, "%s: unknown command or topic %q", pathName(path), subName)
}
-func godocHeader(s string) string {
+func godocHeader(path, short string) string {
// The first rune must be uppercase for godoc to recognize the string as a
// section header, which is linked to the table of contents.
+ switch {
+ case path == "":
+ return firstRuneToUpper(short)
+ case short == "":
+ return firstRuneToUpper(path)
+ }
+ // Godoc has special heurisitics to extract headers from the comments, from
+ // which it builds a nice table of contents. Headers must be single
+ // unindented lines with unindented paragraphs both before and after, and the
+ // line must not include certain characters.
+ //
+ // We try our best to create a header that includes both the command path and
+ // the short description, but if godoc won't extract a header out of the line,
+ // we fall back to just returning the command path.
+ //
+ // For more details see the comments and implementation of doc.ToHTML:
+ // http://golang.org/pkg/go/doc/#ToHTML
+ header := firstRuneToUpper(path + " - " + short)
+ var buf bytes.Buffer
+ doc.ToHTML(&buf, "before\n\n"+header+"\n\nafter", nil)
+ if !bytes.Contains(buf.Bytes(), []byte("<h")) {
+ return firstRuneToUpper(path)
+ }
+ return header
+}
+
+func firstRuneToUpper(s string) string {
if s == "" {
return ""
}
@@ -164,7 +193,9 @@
cmd, cmdPath := path[len(path)-1], pathName(path)
if !firstCall {
lineBreak(w, config.style)
- fmt.Fprintln(w, godocHeader(cmdPath))
+ w.ForceVerbatim(true)
+ fmt.Fprintln(w, godocHeader(cmdPath, cmd.Short))
+ w.ForceVerbatim(false)
fmt.Fprintln(w)
}
usage(w, path, config, firstCall)
@@ -177,7 +208,9 @@
}
for _, topic := range cmd.Topics {
lineBreak(w, config.style)
- fmt.Fprintln(w, godocHeader(cmdPath+" "+topic.Name+" - help topic"))
+ w.ForceVerbatim(true)
+ fmt.Fprintln(w, godocHeader(cmdPath+" "+topic.Name, topic.Short))
+ w.ForceVerbatim(false)
fmt.Fprintln(w)
fmt.Fprintln(w, topic.Long)
}
diff --git a/cmdline/help_test.go b/cmdline/help_test.go
new file mode 100644
index 0000000..8412a50
--- /dev/null
+++ b/cmdline/help_test.go
@@ -0,0 +1,30 @@
+// Copyright 2015 The Vanadium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package cmdline
+
+import "testing"
+
+func TestGodocHeader(t *testing.T) {
+ tests := []struct {
+ Path, Short, Want string
+ }{
+ {"", "", ""},
+ {"path", "", "Path"},
+ {"", "short", "Short"},
+ {"path", "short", "Path - short"},
+ {"path a b c", "short x y z", "Path a b c - short x y z"},
+ // Try some cases where the short string contains characters that godoc
+ // disallows, so we fall back on just the path.
+ {"path", "bad.", "Path"},
+ {"path", "bad;", "Path"},
+ {"path", "bad,", "Path"},
+ {"path", "(bad)", "Path"},
+ }
+ for _, test := range tests {
+ if got, want := godocHeader(test.Path, test.Short), test.Want; got != want {
+ t.Errorf("(%q, %q) got %q, want %q", test.Path, test.Short, got, want)
+ }
+ }
+}
diff --git a/textutil/.api b/textutil/.api
index cf2fdcc..cc033a5 100644
--- a/textutil/.api
+++ b/textutil/.api
@@ -9,6 +9,7 @@
pkg textutil, func RuneChunkWrite(RuneChunkDecoder, func(rune) error, []byte) (int, error)
pkg textutil, func TerminalSize() (int, int, error)
pkg textutil, method (*LineWriter) Flush() error
+pkg textutil, method (*LineWriter) ForceVerbatim(bool) error
pkg textutil, method (*LineWriter) SetIndents(...string) error
pkg textutil, method (*LineWriter) SetLineTerminator(string) error
pkg textutil, method (*LineWriter) SetParagraphSeparator(string) error
diff --git a/textutil/line_writer.go b/textutil/line_writer.go
index 6cb93c9..0742af8 100644
--- a/textutil/line_writer.go
+++ b/textutil/line_writer.go
@@ -54,12 +54,13 @@
// http://www.unicode.org/versions/Unicode4.0.0/ch05.pdf [5.8 Newline Guidelines]
type LineWriter struct {
// State configured by the user.
- w io.Writer
- runeDecoder RuneChunkDecoder
- width runePos
- lineTerm []byte
- paragraphSep string
- indents []string
+ w io.Writer
+ runeDecoder RuneChunkDecoder
+ width runePos
+ lineTerm []byte
+ paragraphSep string
+ indents []string
+ forceVerbatim bool
// The buffer contains a single output line.
lineBuf byteRuneBuffer
@@ -183,6 +184,17 @@
return nil
}
+// ForceVerbatim forces w to stay in verbatim mode if v is true, or lets w
+// perform its regular line writing algorithm if v is false. This is useful if
+// there is a sequence of lines that should be written verbatim, even if the
+// lines don't start with spaces.
+//
+// Calls Flush internally, and returns any Flush error.
+func (w *LineWriter) ForceVerbatim(v bool) error {
+ w.forceVerbatim = v
+ return w.Flush()
+}
+
// Write implements io.Writer by buffering data into the LineWriter w. Actual
// writes to the underlying writer may occur, and may include data buffered in
// either this Write call or previous Write calls.
@@ -332,10 +344,13 @@
// Note that Flush calls behave exactly as if an explicit U+2028 line separator
// were added to the end of all buffered data.
func (w *LineWriter) nextState(r rune, forceLineBreak bool) (state, bool) {
+ kind := runeKind(r)
+ if w.forceVerbatim {
+ return stateVerbatim, forceLineBreak || kind == kindEOL
+ }
if forceLineBreak {
return stateWordWrap, true
}
- kind := runeKind(r)
// Handle non word-wrap states, which are easy.
switch w.prevState {
case stateVerbatim:
diff --git a/textutil/line_writer_test.go b/textutil/line_writer_test.go
index 9633096..50f4184 100644
--- a/textutil/line_writer_test.go
+++ b/textutil/line_writer_test.go
@@ -175,6 +175,47 @@
}
}
+func TestLineWriterForceVerbatim(t *testing.T) {
+ tests := []struct {
+ In string // See xlateIn for details on the format
+ Want string // See xlateIn for details on the format
+ }{
+ {"", ""},
+ {"a", "a."},
+ {"a.", "a."},
+ {"ab", "ab."},
+ {"ab.", "ab."},
+ {"abc", "abc."},
+ {"abc.", "abc."},
+ {"a c", "a c."},
+ {"a c.", "a c."},
+ {"a cde", "a cde."},
+ {"a cde.", "a cde."},
+ {"a c e", "a c e."},
+ {"a c e.", "a c e."},
+ {"a c ef", "a c ef."},
+ {"a c ef.", "a c ef."},
+ {"a c f", "a c f."},
+ {"a c f.", "a c f."},
+ {"a f", "a f."},
+ {"a f.", "a f."},
+ {"a c e.g i k", "a c e.g i k."},
+ {"a c e.g i k.", "a c e.g i k."},
+ }
+ for _, test := range tests {
+ // Run with a variety of chunk sizes.
+ for _, sizes := range [][]int{nil, {1}, {2}, {1, 2}, {2, 1}} {
+ var buf bytes.Buffer
+ w := newUTF8LineWriter(t, &buf, 1, lp{}, nil)
+ w.ForceVerbatim(true)
+ lineWriterWriteFlush(t, w, xlateIn(test.In), sizes)
+ if got, want := buf.String(), xlateIn(test.Want); got != want {
+ t.Errorf("%q sizes:%v got %q, want %q", test.In, sizes, got, want)
+ }
+ }
+ }
+}
+
// xlateIn translates our test.In pattern into an actual input string to feed
// into the writer. The point is to make it easy to specify the various control
// sequences in a single character, so it's easier to understand.
