[CLI Help] Usage Tips and Tricks

Discuss anything related to command line tools here.
Post Reply
Message
Author
vevy
Posts: 572
Joined: Tue Sep 10, 2019 11:17 am

[CLI Help] Usage Tips and Tricks

#1 Post by vevy » Tue Oct 13, 2020 7:16 pm

1. y/N prompt capitalization is a relevant convention:
  • Capital N = default is "No". If you just press Enter without choosing/typing, it will be interpreted as No. Same with Y.
  • Equal capitalization "Y/N" means you have to choose.

2. In help, arguments in square brackets are optional, pipe=alternatives:
  • Code: Select all

    pdftohtml [options] <PDF-file> <html-dir>
    means options can be omitted, but you have to provide file and dir.
  • Code: Select all

    netcfg [-v] [-winpe] [-l <full-path-to-component-INF>] -c <p|s|c>
    means:
    -v, -winpe are optional.
    -l is optional, but if you use it you must provide the path.
    -c is mandatory and you have to provide an argument for it by picking one of p or s or c.

3. Often, you don't have to enter the full switch as long as it is unique.
can be entered as:
wget.exe --http-k {URL} or wget.exe --http-kee {URL}, etc.
If you try --http only, it will throw an error because there are multiple switches beginning with --http, for example, --http-password.
Last edited by vevy on Sun Oct 18, 2020 2:58 am, edited 1 time in total.
I do NOT have other accounts.

User avatar
webfork
Posts: 9424
Joined: Wed Apr 11, 2007 8:06 pm
Location: US, Texas
Contact:

Re: [CLI Help] Tips and Tricks

#2 Post by webfork » Fri Oct 16, 2020 7:46 pm

Hey could you put a little text together describing what's happening in this entry? You obviously put a fair amount of work into this and I'm just not clear what problem it's trying to solve.

vevy
Posts: 572
Joined: Tue Sep 10, 2019 11:17 am

Re: [CLI Help] Tips and Tricks

#3 Post by vevy » Fri Oct 16, 2020 7:51 pm

I am not sure what you mean. Like what do you see as ambiguous?
I do NOT have other accounts.

User avatar
Cornflower
Posts: 169
Joined: Fri Aug 31, 2007 7:58 am
Location: Canada's capital

Re: [CLI Help] Tips and Tricks

#4 Post by Cornflower » Sat Oct 17, 2020 5:32 am

I really like this, and the inclusion of Angle Brackets as a standard I totally agree with.
Let me see if I understand the post by restating them in what I hope are lay terms, using the same examples. I tend to rewrite many of the CLI help documentation for my personal documentation file so that if I don't use something for a year, I can understand and don't have to relearn the syntax and parameters.My pre-Windows DOS batch files always had a help screen if parameters were omitted. Here goes.

1. If there is a CLI prompt, such as "Answer y/N" or "Direction? L/r" , the default response (that is, if you simply press {enter}) will be the response that is capitalized. In the first example, pressing {enter} will return a No response, and in the second, {enter} will return a L (for left) response.

2. In CLI help, there are a few punctuation standards for command parameters. These are
a. Square brackets [ ] mean that whatever is inside is optional.

b. Angle brackets < > mean that whatever is inside is mandatory and something must be put there. Anything without brackets is also mandatory.
e.g.

Code: Select all

pdftohtml [options] <PDF-file> <html-dir> 
; You don't have to include any options but you must include a pdf file and an html directory for this command
note that I added the ; as in ignore this in the command, everything to the right of it is a comment. This is more for documentation than for CLI help

c. Things in pipes | are alternatives for the parameter(s). They can reside withing optional [] or mandatory <> parameters
e.g.

Code: Select all

netcfg [-v] [-winpe] [-l <full-path-to-component-INF>] -c <p|s|c>
In this example the command has optional parameters, but must include one of -cp or -cs or -cc
Note that in this example, because there are no brackets, -c is mandatory. the example, if I understand it correctly, could also be written like this below with the same meaning

Code: Select all

 netcfg [-v] [-winpe] [-l <full-path-to-component-INF>] <-cp|-cs|-cc>
Question: Is there a standard for curly brackets { } ? The Wget example uses them for the URL, indicating in that case mandatory. In other cases, they can designate a key, such as {Tab} or {Enter}, but this is used primarily for GUI help screens. Otherwise, we might want to steer clear of them, or designate them for use solely for URLs.

3. Some commands are written so that you can use a shortened parameter instead of the full one, as long as that shortened parameter only refers to that one choice (it is a unique choice)
Wget is one of those commands
e.g.

Code: Select all

wget.exe --http-keep-alive {URL}
When you look at the complete set of parameter options for Wget, there are a number of them that begin with "--http", but only one of them that begins with "--http-k"
This means that --http-keep-alive requires at least the string "--http-k" or more for it to work.

I personally don't shorten parameters unless you can shorten them to a single letter. I find remembering them too confusing. I am tempted to leave them out in any help I write.

vevy
Posts: 572
Joined: Tue Sep 10, 2019 11:17 am

Re: [CLI Help] Tips and Tricks

#5 Post by vevy » Sat Oct 17, 2020 11:45 am

@Cornflower You are pretty much on point for most things.

Just a few notes:
- Microsoft syntax.
- POSIX syntax.

Cornflower wrote:
Sat Oct 17, 2020 5:32 am
or "Direction? L/r"
I don't know if it applies to more than Yes/No. :?:
Angle brackets < > mean that whatever is inside is mandatory
Not necessarily. It is a placeholder. It means that it needs to be substituted with an actual value.
Question: Is there a standard for curly brackets { } ? The Wget example uses them for the URL, indicating in that case mandatory. In other cases, they can designate a key, such as {Tab} or {Enter}, but this is used primarily for GUI help screens. Otherwise, we might want to steer clear of them, or designate them for use solely for URLs.
:oops: That was just me! Based on the above, I guess I should have used wget.exe --http-keep-alive <URL> or so.
I do NOT have other accounts.

User avatar
webfork
Posts: 9424
Joined: Wed Apr 11, 2007 8:06 pm
Location: US, Texas
Contact:

Re: [CLI Help] Tips and Tricks

#6 Post by webfork » Sat Oct 17, 2020 3:05 pm

vevy wrote:
Fri Oct 16, 2020 7:51 pm
I am not sure what you mean. Like what do you see as ambiguous?
As in who is this for? Tips and tricks for what situation? Is this for help authors/documentation, developers, users?

vevy
Posts: 572
Joined: Tue Sep 10, 2019 11:17 am

Re: [CLI Help] Usage Tips and Tricks

#7 Post by vevy » Sun Oct 18, 2020 3:00 am

I forgot you write documentation! :mrgreen: Updated Title.

It is for users. To be able to understand some of the syntax and conventions used when they type tool.exe --help or so.
I do NOT have other accounts.

Post Reply