CLI: discoverability and consistency #2542

hackergrrl · 2016-04-08T23:14:38Z

CLI: Discoverability & Consistency

Hi everyone!

I've made some changes to the ipfs CLI tool's output. These aren't major changes, but they're maybe enough to warrant talking about: nobody likes their CLI tool's output suddenly changing from underneath them. These changes are not major, but do represent a change.

That's very fair, so I wanted to share my design approach and goals to better justify the changes I've made here. I'm a fan of esr's unix rules, and so my commits here reflect that (In particular, discoverability). The changes are broken down by the high level goal they fit under below.

I expect this to take several rounds to complete -- CLI output is not a standardized thing and is also ripe for bikeshedding. Let's try to focus on the goals below and not quibble on style too much.

Goals

Discoverability

New users start using ipfs every day. CLI tools don't expose their affordances the same way GUI apps do (no toolbar along the top), so enabling users to discover the functionality of the tool is paramount, via both showing subcommands and showing short-help where ever possible.

Subcommands

running a command without arugments should show its subcommands
- ipfs block
- ipfs file
- ipfs pin
- ipfs repo
- ipfs dht
- ipfs diag
- 'ipfs bootstrap' should show help, not alias 'ipfs bootstrap list'
removes redundant cases where subcommands are manually listed in SYNOPSIS
(in favour of using autogen everywhere)

Short-Help

Formatting

Terminals come in many shapes and sizes. 80x25 is the default terminal size on most older curses-based displays, and is the yard stick that many terminal programs are aimed to display reasonably on. Where possible, horizontal wrapping at ~80 characters has been done, and needless vertical whitespace is minimized. This also tackles consistency of output across the various command outputs.

Terminal formatting / sizing
- reduce horizontal indent on help docs
- reduce vertical whitespace on help docs (ipfs in particular)
Consistency
- main 'ipfs' cmd doesn't use colons on subheadings; let's not use them for
  subcommands either
move long tagline details into DESCRIPTION
split long ShortDescriptions into Short+Long Description text

hackergrrl · 2016-04-08T23:15:32Z

cc @whyrusleeping @jbenet @dignifiedquire @diasdavid

daviddias · 2016-04-12T09:47:07Z

commands/cli/helptext.go

@@ -20,7 +20,7 @@ const (

 	whitespace = "\r\n\t "

-	indentStr = "    "


This seems to be more of enforcing a personal opinion or habit.

No -- this falls under "Terminal formatting / sizing: reduce horizontal indent on help docs".

Let's reduce the tool's horizontal footprint so 80 char terminals don't experience weird line wrap. (Fully dynamic smart wrapping would be even cooler, but that's a bit bigger scope than this.)

I don't think that the commands lib should change the formatting of the helptext at all, otherwise we might try to format things a certain way only to have the code screw things up.

A better option I think is to have a commands_test.go file (or similar) that goes through each command and ensures their helptext looks correct (tabs vs spaces, etc)

Agreed that this should be a concern of the library user and not the core commands lib. I can file an issue for that -- it seems like a bigger job than what's in scope for this PR.

hackergrrl · 2016-04-12T15:41:57Z

Thanks for taking a look and feedback, @diasdavid!

whyrusleeping · 2016-04-12T17:39:52Z

should we just remove the synopsis field entirely?

hackergrrl · 2016-04-12T18:25:43Z

Yeah, we kind of use the Usage and Tagline to mean Synopsis throughout. I don't think it's a bad thing to expose to the CLI API's users though, if they choose to use Usage/Tagline/Synopsis differently.

RichardLitt · 2016-04-13T14:57:17Z

I <3 you, Noffle. This is great work.

RichardLitt · 2016-04-13T14:58:35Z

core/commands/ping.go

-Send pings to a peer using the routing system to discover its address
-		`,
+		Tagline:  "Send echo request packets to IPFS hosts.",
+		Synopsis: "Send pings to a peer using the routing system to discover its address",


Fixed. I also went through the other commands to check for consistent perioding.

hackergrrl · 2016-04-20T18:52:00Z

All green!

whyrusleeping · 2016-04-20T20:34:57Z

core/commands/add.go

@@ -30,11 +30,9 @@ const (

 var AddCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "Add a file to ipfs.",
+		Tagline: "Add a file or directory hierarchy to ipfs.",


I'd drop hierarchy from this, Add a file or directory to ipfs is short sweet and to the point.

whyrusleeping · 2016-04-24T00:11:34Z

t0235 is failing for some reason

hackergrrl · 2016-04-25T19:32:59Z

I was trying out developing on my NixOS laptop and I think it's using a different netcat (gnu vs bsd), so I chose flags that didn't exist here. Reverted that work in favour of figuring it out another day.

whyrusleeping · 2016-04-27T23:38:17Z

core/commands/bootstrap.go

 	},

-	Run:        bootstrapListCmd.Run,


i'm not so sure i'm onboard with this change still.. I like commands being able to have an effect when run without arguments.

If only we had aliases!

$ ipfs alias set bootstrap = bootstrap list

I can revert this though, if that's going to block the PR.

whyrusleeping · 2016-04-28T16:19:27Z

@noffle now this needs to be rebased.. theres a bunch of commits here that don't seem right at all

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

hackergrrl · 2016-04-28T18:38:10Z

Fixed -- not sure what happened there.

whyrusleeping · 2016-04-28T20:16:31Z

test/sharness/t0120-bootstrap.sh

@@ -29,14 +29,6 @@ test_bootstrap_list_cmd() {
    echo "$BP" >>list_expected
  done

-  test_expect_success "'ipfs bootstrap' succeeds" '


we should put these back in now that the functionality has been restored.

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

hackergrrl · 2016-04-28T20:48:30Z

Pulled out my bootstrap list commits.

whyrusleeping · 2016-04-28T21:08:20Z

sweet, LGTM. Thanks!

hackergrrl force-pushed the cli branch from ffebf98 to be3a5bf Compare April 8, 2016 23:15

hackergrrl mentioned this pull request Apr 8, 2016

Sprint: April 6 → April 18 ipfs/team-mgmt#101

Closed

daviddias reviewed Apr 12, 2016
View reviewed changes

RichardLitt reviewed Apr 13, 2016
View reviewed changes

hackergrrl force-pushed the cli branch from 3a6db2a to 9994f41 Compare April 13, 2016 16:21

hackergrrl force-pushed the cli branch 2 times, most recently from ad61af2 to 76b52af Compare April 20, 2016 16:59

whyrusleeping reviewed Apr 20, 2016
View reviewed changes

hackergrrl mentioned this pull request Apr 25, 2016

Sprint: April 18 → May 3 ipfs/team-mgmt#104

Closed

hackergrrl force-pushed the cli branch 2 times, most recently from f4f4890 to 0e4e778 Compare April 25, 2016 19:32

whyrusleeping reviewed Apr 27, 2016
View reviewed changes

hackergrrl added 3 commits April 28, 2016 20:36

reduces help indent from 4 to 2 spaces

4d38ee5

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

reduces horz/vert space taken by "ipfs" cmd

e124292

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

show subcommands on shorthelp

d1a296e

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Removes redundant synopsis from "swarm"

1a268b0

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

hackergrrl force-pushed the cli branch from c006803 to 836a924 Compare April 28, 2016 18:37

whyrusleeping reviewed Apr 28, 2016
View reviewed changes

hackergrrl force-pushed the cli branch from 836a924 to 281de4a Compare April 28, 2016 20:46

hackergrrl and others added 21 commits April 28, 2016 22:47

Removes trailing newline in ping help.

23dca67

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Prints shorthelp on parse error.

726bebd

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

tiny comment fixes

2b201bc

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

updates README usage

233989b

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Don't include extra whitespace if no .MoreHelp

20b3e98

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

description improvements

eb9de5f

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Hides the obscure 'file' subcommand.

124c51d

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Splits 'ipfs daemon' into Short and Long help.

60f1fc1

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Removes redundant synopsis from "config"

2a41d45

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Wraps lines to keep from going over 80.

bd70017

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

specify repo separately

be15ed8

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

s/structure/hierarchy

4aa5733

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

missing .

479ef39

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Removes trailing colon from 'usage' test.

cdb8625

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Updates sharness test error messages.

cb029a0

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Removes trailing colon from 'usage' test.

73d1d96

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Updates add-symlink to use /bin/sh.

17509ec

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Removes "hierarchy".

0b861e4

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

Updates "ipfs ping" synopsis.

af79a84

Updates t0040 with latest wording.

bd08815

Removes unnecessary daemon setup.

20eb0c8

License: MIT Signed-off-by: Stephen Whitmore <noffle@ipfs.io>

hackergrrl force-pushed the cli branch from 281de4a to 20eb0c8 Compare April 28, 2016 20:48

whyrusleeping merged commit 0a45ada into ipfs:master Apr 28, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI: discoverability and consistency #2542

CLI: discoverability and consistency #2542

hackergrrl commented Apr 8, 2016

hackergrrl commented Apr 8, 2016

daviddias Apr 12, 2016

hackergrrl Apr 12, 2016

whyrusleeping Apr 12, 2016

hackergrrl Apr 12, 2016

hackergrrl commented Apr 12, 2016

whyrusleeping commented Apr 12, 2016

hackergrrl commented Apr 12, 2016

RichardLitt commented Apr 13, 2016

RichardLitt Apr 13, 2016

hackergrrl Apr 13, 2016

hackergrrl commented Apr 20, 2016

whyrusleeping Apr 20, 2016

hackergrrl Apr 20, 2016

whyrusleeping commented Apr 24, 2016

hackergrrl commented Apr 25, 2016 •

edited

whyrusleeping Apr 27, 2016

hackergrrl Apr 28, 2016 •

edited

hackergrrl Apr 28, 2016

whyrusleeping commented Apr 28, 2016

hackergrrl commented Apr 28, 2016

whyrusleeping Apr 28, 2016

hackergrrl commented Apr 28, 2016

whyrusleeping commented Apr 28, 2016

		@@ -20,7 +20,7 @@ const (

		whitespace = "\r\n\t "

		indentStr = " "

CLI: discoverability and consistency #2542

CLI: discoverability and consistency #2542

Conversation

hackergrrl commented Apr 8, 2016

CLI: Discoverability & Consistency

Goals

Discoverability

Subcommands

Short-Help

Formatting

hackergrrl commented Apr 8, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hackergrrl commented Apr 12, 2016

whyrusleeping commented Apr 12, 2016

hackergrrl commented Apr 12, 2016

RichardLitt commented Apr 13, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hackergrrl commented Apr 20, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whyrusleeping commented Apr 24, 2016

hackergrrl commented Apr 25, 2016 • edited

Choose a reason for hiding this comment

hackergrrl Apr 28, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whyrusleeping commented Apr 28, 2016

hackergrrl commented Apr 28, 2016

Choose a reason for hiding this comment

hackergrrl commented Apr 28, 2016

whyrusleeping commented Apr 28, 2016

hackergrrl commented Apr 25, 2016 •

edited

hackergrrl Apr 28, 2016 •

edited