what to call an option to dump to stdout?

I'm working on our “view” command where you can view older versions of files as you want - as an example “h view foo.cs;C123” would view the version of foo.cs at changeset 123 “h view $/bar/ack.cs;Lfoo” would view that server item with the version pointed to by the “foo” label.  One of the things we've decided about view (and hence its name) is that we're going to fire off the registered viewer for the filetype.  This makes a lot of sense to us - if you're doing an “h view x.y” on some 16MB texture file, surely it's more useful that it get brought up in your registered viewer of texture files instead of dumped out to stdout.  On the subject though – do you have a preference for whether the default for the command (whatever the command is called) is “send to stdout” vs “invoke registered viewer”?  Our thoughts are the registered viewer is the right default with an option for stdout, but maybe there are very-common scenarios we’re missing.

However, for a default of “invoke registered viewer“ (going with that as how we behave) there are certainly scenarios where people will want to have the file dumped to standard out as well (redirect to a file, pipe through grep/findstr/whatever, etc.) so we want an option to dump the contents to standard out (aka file descriptor 1, /dev/stdout, etc. - where stuff goes when you “echo foo“).  The thing is, none of the options we've thought of seem most intuitively obvious if that's the goal.  What would you want it to be called?

- /stdout is good on the obvious-behavior front, but it's a bit of a unix-y term for a windows-centric product.  That doesn't make it bad, but it's potentially less discoverable and for developers that don’t have stdin/stdout/stderr knowledge, can be downright confusing.

- /dump is too overloaded in other contexts, mainly debugging scenarios (core dumps) and the like.  Also, it’s not very elegant of a term to put it nicely.

- /out isn’t obvious enough – out to what?  I would see an option with that name as needing a parameter to tell it where it should go.  /output fails on approximately the same reason.

- /console isn’t bad, but it’s another overloaded term.  In the terminal services world, the console session is the one specifically on the machine’s console (IOW, for the typical case, the one with the graphics in the machine’s primary video card’s memory J).  An option like /console may give the false impression that we’re interacting with the console session somehow.  Other teams in Microsoft have attempted to avoid “console” meaning “stdout” as well for basically the same reasons.

- /print was rejected because there’s an existing “Print” verb in Windows already that means (wait for it…) “send to the printer”.  Our internal source control (source depot, as mentioned in other blogs) uses “sd print” for sending the file to stdout (it has no ability to invoke a registered viewer)

- /type was rejected because it’s already used in Hatteras– we have the ability for the user to override what file type a particular file is, which is nice for saying things like “treat this as utf-8 even if you detect it as windows-1252”

- /display sounds too much like “invoke registered viewer” behavior and doesn’t imply “send to stdout”

- /text is rejected since there are binary files that you may want to send to stdout (say, to a perl script that does record-based parsing or something)

- /format was kind of considered – so we have an existing standard option /format that takes possible parameters brief and detailed, and we typically default to detailed.  Hence, you can “h workspaces” just to see you workspaces but “h workspaces /format:detailed” to show the workspaces with additional things like the workspace mappings ($/proj1/ -> c:\proj1, $/proj2/ -> c:\docs\foo, etc.) – the idea was /format:brief would do “stdout” behavior and /format:detailed would do “invoke viewer” behavior (or, heck, maybe even vice versa).  Yeah, discoverability near zero, we know. J

- /mode was a potential “make it obvious” brute-force approach.  /mode:stdout would send to stdout, /mode:viewer would invoke the viewer.  Of course, then the /mode: parameter that sends to stdout gets the same kind of argument – stdout? console? Something else?  Also, an option of /mode isn’t very discoverable on what its parameters should be.

We had also considered having a /file: option that would dictate where we would save the file to, and then stdout would become some special case of that. I liked “-“ since it’s pervasive in unix commands as “this means stdout/stdin as appropriate” but that doesn’t really help the windows developer and still fails the discoverability test because of that.  Another option was using the Win32 device con so people could /file:con to get stdout behavior, but that’s taking a dependency on that Win32 device is pretty silly, especially since we’re not sure if it’ll be around for Longhorn et al.  Also, a “file option with special case for stdout” is less discoverable than “stdout option than can be easily redirected to a file” – if you just saw there was a /file option, it’s not obvious that the parameter can be a special case that’ll make it switch to stdout.  However, if you have a stdout option, there’s an established habit that you can redirect/pipe/whatever the contents however you want.

That’s where we stand now – we’re very fortunate that there are a lot of excellent Windows developers among the group of people reading https://blogs.msdn.com/ so I’m hoping we can get some comments/feedback on this and make for a very-discoverable option that will make sense across the board.  What would you like an option to send a file’s contents to stdout to be called?

Comments

• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 16, 2004
  Suggestions:
  
  /show
  
  I intended to see if I could come up with more, but a few rounds with the thesaurus didn't /reveal anything else.
• Anonymous
  July 16, 2004
  I have to agree with the other fellow--a default for a CLI invocation should send output to stdout. The registered viewer should be the one with the switch. IMO.
  
  If this were less of a development tool, I'd expect something different. And, if this was context menu initiated behavior, obviously the viewer should be launched.
• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 16, 2004
  Anderson: Thanks! I'd be worried that "show" is just repetitive with "view" - IOW, there's nothing about "show" that implies "put this on stdout instead of displaying in a graphical way". Good idea, though - it's in the running :)
• Anonymous
  July 16, 2004
  ToddM: in terms of my examples to your suggestion, I wanted to point out that I understand we could /help:none and /paging:no - it's more about trying to figure out what people want to do most often and making that as easy as possible. Great ideas, though.
  
  I tend to just run things with no params to get help or a param of /? (so "h view" or "h view /?") myself, and the paging on/off is adding "|more" or not, but again it's more about trying to make the common case easiest, and it's hard to get a feel for exactly what's most common for everyone out there :)
• Anonymous
  July 16, 2004
  I say just pick some arbitrary switch like /E (which the C compiler uses). That way it has no semantic meaning and therefore cannot be misunderstood.
  
  Alternatively don't overload the "view" command with this. View is for viewing with a viewer. That's why it's called view. If you want to print to stdout, call it something else entirely, like "h cat ...".
• Anonymous
  July 16, 2004
  Well, since we're dealing with DOS-style commands here, not UNIX ones, it should really be "h type" but that repeats the problem - it helps the users with a degree of familiarity with one system, but confuses the heck out of people with no familiarity. "h list" has similar problems: produce a list of files?
  
  How about /here? Works well for the console, but less well for piping and redirecting to a file (but would you want to redirect anyway? It's a little pointless when you could just "h get").
  
  Anyway, some of the C++ compiler options are arbitrary, but others are a little mnemonic, e.g. /c to compile only, /O for optimisation options. Microsoft have generally been moving away from single-letter options, e.g. /showIncludes on CL.EXE 13.x and later, and the mnemonic /RTC for Run-Time Checks.
• Anonymous
  July 16, 2004
  don't be afraid to be wordy..
  
  /streamtothisconsole
  /streamtofile:[filename]
  etc
  
  it's clear and to the point
• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 16, 2004
  Your application can tell whether the user has redirected stdout, so anything like:
  
  h view x.y > f.y
  h view x.y | more
  
  should not launch a viewer and should redirect the output as expected.
  
  In the default case where output is not redirected:
  
  h view x.y
  
  launch the viewer, but also write a help message to stderr explaining that /stdout (or whatever) is required to output to the console.
  
  This is what I'd do anyway :)
• Anonymous
  July 16, 2004
  Why not "h view x.y" or "h start x.y" and "h type x.y" or "h cat x.y"?
  
  Then again, why not just integrate h into the filesystem, extend the naming convention and then "start x.y" and "type x.y" would just work and make versioning available to the user in any application.
• Anonymous
  July 16, 2004
  The comment has been removed
• Anonymous
  July 17, 2004
  It would be also nice to be able to send to a custom .NET type that implements some predefined interface, like sendto:"MyNamespace.MyClass, MyAssembly" where MyClass implements the interface "ITeamSystemFileViewer" or something similar.
  
  Cheers,
  Steve
  steve at dunnhq.com
• Anonymous
  July 17, 2004
  I think Dan's comments are great. Is there anything shared between Team System and WinFS?
• Anonymous
  July 19, 2004
  The comment has been removed
• Anonymous
  July 20, 2004
  The comment has been removed
• Anonymous
  July 21, 2004
  The comment has been removed
• Anonymous
  July 21, 2004
  The comment has been removed