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 http://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?