Update StyleGuide.md to note preference for curl over wget #18479
Conversation
Files changed:
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify site configuration. |
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify site configuration. |
| In an example command to download an artifact using the command line, `curl` is preferred over `wget` because it is included in Linux, macOS, and recent builds of Windows. Use syntax like: | ||
|
|
||
| ``` | ||
| curl -o {optional_output_path}/{output_file_name} [-H {header_keys_and_values}] {url} |
There was a problem hiding this comment.
I'm not clear regarding which of these vars would be printed verbatim in the docs, vs. replaced in the docs with context-specific values, vs. a case by case decision on this. Worth any clarification here?
There was a problem hiding this comment.
By (Linux man page) convention, options in square brackets are optional and I tried to use that convention here. I wanted to give some hints for writers who may be more used to wget than curl.
- I don't consider
-ooptional because leaving it off outputs the stream to standard output (including if it's a binary), for a very ugly experience, so I didn't surround it with square brackets.wgethas a behavior difference here: By default, a binary is always downloaded, and the download has the same file name as the file portion of the download URL. - I added the
{optional_output_path}part to the-oargument to show how to specify a local download path withcurlif you are used to passing-Ptowgetto designate a path. I was trying to show that you don't need an extra argument to specify the path incurl, just reference it. - We have some CC API examples where explicitly pass in headers, so I wanted to give a clue about how you would do that with
curl's-Hargument, but I didn't want to imply that the header is always required. - I don't consider
{url}to be optional as it shows what to download or what REST URL to hit.
| - If you do not specify `-o` or `--output`, the URL's contents are printed to standard output, even if it is a binary file. This can corrupt your terminal session and is useful only when piping or redirecting the output to a subsequent command. | ||
| - If you do not include a path in your output file name, the file is saved to the current working directory. | ||
| - Headers are optional, but certain APIs such as the CockroachDB Cloud API require certain header fields to be set. |
There was a problem hiding this comment.
These are great points and good to know.
Are these intended as 'reasons why we should always include the parameters above' or 'considerations when deciding whether to include the parameters above'?
Perhaps a single-sentence intro to the list can clarify that?
There was a problem hiding this comment.
Neither. I was taking into consideration the different types of wget examples I updated to use curl and to show what to do when their behavior differs, but I wanted to keep it very narrow to the sorts of ways our docs use curl rather than exhaustively document all the options to each command, and to try to prevent you from streaming the download binary to standard output.
- We had several
wgetexamples that specify an output file name, path, or both. - We had several examples where passing extra headers is a key part of the example, so I wanted to show how you'd do that with
curl.
Part of the motivation for why I did it this way is that this is very specific info about one specific type of code example, and there isn't a great home for it in the style guide's TOC. I was hoping the info would come up in searches. WDYT?
Relates to #18477