Analyze/test cmdline tutorial code excerpts

[chalin]

Resolves first item of #1803. (Builds on #1900, #1901.)

Staged at https://dart-dev-staging-0.firebaseapp.com/tutorials/server/cmdline
Original https://dart.dev/tutorials/server/cmdline

---

• Added dcat.dart example, which comes from https://github.com/dart-lang/dart-tutorials-samples/tree/master/cmdline/bin (we should consider removing it from that repo).
• Created other examples sources (not found under dart-tutorials-samples, etc.) as necessary.
• Updated cmdline.md page links to ensure that they all reference the proper API version (based on the channel). Also ensured that all links to external sites consistently open in a new tab. (We aren't doing that elsewhere, but at least the links in this page will be consistent in their behavior).

Note: dcat, and the rest of the newly added code, is analyzed but NOT tested; we don't test other command line apps in this repo -- doing so would require some refactoring or additional recripting, which probably isn't worth it at this point.

I've ensured that all external links in the page are valid:

~ > blc -fgi http://localhost:4000/tutorials/server/cmdline
Getting links from: http://localhost:4000/tutorials/server/cmdline
├───OK─── http://www.google.com/intl/en/policies/privacy/
├───OK─── https://dartpad.dev/
├───OK─── https://pub.dev/
├───OK─── https://dart-lang.github.io/server
├───OK─── https://flutter.dev/
├───OK─── https://pub.dev/packages/args
├───OK─── http://creativecommons.org/licenses/by/3.0/
├───OK─── https://api.dart.dev/
├───OK─── https://github.com/dart-lang/site-www/tree/master/src/_tutorials/server/cmdline.md
├───OK─── https://pub.dev/documentation/args/latest/args/ArgParser-class.html
├───OK─── https://medium.com/dartlang/announcing-dart-2-5-super-charged-development-328822024970
├───OK─── https://github.com/dart-lang/site-www/issues/new?...
├───OK─── https://api.dart.dev/stable/dart-async/Future-class.html
├───OK─── https://medium.com/dartlang
├───OK─── https://pub.dev/documentation/args/latest/args/ArgResults-class.html
├───OK─── https://github.com/dart-lang/site-www
├───OK─── https://pub.dev/documentation/args/latest/
├───OK─── https://api.dart.dev/stable/dart-async/Stream-class.html
├───OK─── https://github.com/dart-lang/site-www/issues
├───OK─── https://api.dart.dev/stable/dart-io/stdout.html
├───OK─── https://api.dart.dev/stable/dart-io/stderr.html
├───OK─── https://api.dart.dev/stable/dart-io/stdin.html
├───OK─── https://api.dart.dev/stable/dart-io/FileSystemEntity-class.html
├───OK─── https://api.dart.dev/stable/dart-io/File-class.html
├───OK─── https://api.dart.dev/stable/dart-io/Platform-class.html
├───OK─── https://api.dart.dev/stable/dart-io/Platform/environment.html
├───OK─── https://api.dart.dev/stable/dart-io/Platform/isMacOS.html
├───OK─── https://api.dart.dev/stable/dart-io/Platform/numberOfProcessors.html
├───OK─── https://api.dart.dev/stable/dart-io/Platform/script.html
├───OK─── https://api.dart.dev/stable/dart-io/IOSink-class.html
├───OK─── https://api.dart.dev/stable/dart-io/Directory-class.html
├───OK─── https://api.dart.dev/stable/dart-io/exitCode.html
├───OK─── https://api.dart.dev/stable/dart-io/exit.html
├───OK─── https://api.dart.dev/stable/dart-io/dart-io-library.html

[chalin]

@kwalrath: I've tried to stage my changes but I can't seem to get that to work (even if I re-login, and update to the latest firebase-tools).

Edit: for the record, I had to logout before re-logging in; then deployment worked once again.

[chalin]

Notes for @kwalrath.

[chalin]

Staged at https://dart-dev-staging-0.firebaseapp.com/tutorials/server/cmdline (link added to opening comment).

[kwalrath]

I like most of your changes very much. Most of my comments are of the nitpicky variety, and some of them don't involve your changes. But since we're in there...

[chalin]

General question: should references to dart:foo packages be in backticks in the text? I my first pass over the page I chose not to make that change. The list in Some specific items to put in code font would seem to suggest that dart:foo should be in backticks. What's your call?

[chalin]

Updates done and staging server refreshed. I've added a few questions as comments. (External links rechecked ✔️)

[kwalrath]

Just curious... What's up with the date in the footer? Is your system time off?

[kwalrath]

LGTM!

[kwalrath]

We should probably have a DPE check the code... :/

[kwalrath]

General question: should references to dart:foo packages be in backticks in the text? I my first pass over the page I chose not to make that change. The list in Some specific items to put in code font would seem to suggest that dart:foo should be in backticks. What's your call?

I'm inclined to avoid using backticks for them, although I suspect backticks have been creeping in. Here's my thinking:

• Libraries aren't mentioned by name in the style guide.
• There's no way that dart:something can be confused for anything but a core library.
• We have so much code font in the docs already, and it's quite distracting.

But I'm not convinced I'm right. :) What do you think, @chalin?

[chalin]

Just curious... What's up with the date in the footer? Is your system time off?

No it's because when I build for a PR, I used a fixed "site generation" date. That makes it easier to do full-generated-site file diffs (which I do regularly).

Here is the command line I use:

$ ./tool/serve.sh --pin-now --dev

[chalin]

I'm inclined to avoid using backticks ...

Let's go with your preference for now. Thanks for the feedback.

[chalin]

@johnpryan - do you think that you'll be able review this today? It should be quick to review. The dcat code was copied from https://github.com/dart-lang/dart-tutorials-samples/tree/master/cmdline/bin. Thanks.

[johnpryan]

Looks good to me, just a minor nitpick.