Professional IronPython

Creating an Application Description
Many of the command line applications you see lack this essential feature. You ask for help and 
the application provides you with syntax and a quick overview of the command line switches. 
At the outset, you have little idea of what the application actually does and how the developer 
548592c10.indd 203
2/24/10 12:48:30 PM
www.finebook.ir

---

204
❘
CHAPTER 10
Using ironPython for AdministrAtion tAsks
envisioned your using it. After a little experimentation, you might still be confused and have a 
damaged system as well.
An application description doesn’t have to be long. In fact, you can make it a single sentence. If you 
can’t describe your command line application in a single sentence, it might actually be too big — 
characteristically, command line applications are small and agile. Of course, there are exceptions 
and you may very well need an entire paragraph to describe your application. The big mistake is 
writing a huge tome. Most people using your application have worked with computers for a long 
time, so a shorter description normally works fine.
As a minimum, your application description should include the application name so the user can 
look for additional information online. The description should tell the user what the application 
does and why you created it. These three elements can fit quite easily in a single sentence as you see 
in the “Showing Usage Examples” section of this chapter.
Describing the Application Calling Syntax
Applications have a calling syntax — a protocol used to interact with the application. Unfortunately, 
you won’t have access to any formatting when writing your application help screen. Developers have 
come up with some methods to show certain elements over the years and you should use these methods 
for your command line syntax. Consider the following command line:
MyApp [-S] [-s] [-D [-U[:]]] [-X | -Y | -Z | ] [-?]
Believe it or not, all these strange looking symbols do have a meaning and you need to consider 
them for your application. Any item that appears in square brackets ([]), such as 
[–S]
, is optional. 
The user doesn’t need to provide it to use the application.
Anything that appears in angle brackets (<>), such as 

, is a variable. The user replaces 
this value with some other value. Normally, you provide a descriptive name for the variable. For 
example, when you see 

, you know that you need to provide the name of a file. In this 
case, 

isn’t optional — the user must provide it unless asking for help. It’s understood 
that requesting help, normally 
–?
or 
/?
, doesn’t require any other input.
Command line switches within other command line switches are dependent on that command line 
switch. For example, you can use 
–D
alone. However, if you want to use 
–U
, you must also provide 
–D
. In this case, 
–U
is dependent on 
–D
. Notice that you can use 
–U
alone or you can include a 

variable with it. When you use the 

variable, the command line switch sequence must appear 
as 
–D –U:
.
Sometimes a command line switch is mutually exclusive with other command line switches or even 
variables. For example, the 
[–X | –Y | –Z | 

]
sequence says that you can provide 
–X
or 
–Y
or 
–Z
or 

, but you can’t provide more than one of them.
Most Windows command line applications are case insensitive. However, there are notable excep-
tions to this rule. If you find that you must make your application case sensitive, be sure to use the 
correct case for the command line syntax. For example, 
–S
isn’t the same as 
–s
for this application 
and the command line syntax shows that. You should also note that the application is case sensitive 
in other areas of your help screen because some users won’t notice the difference in case.
548592c10.indd 204
2/24/10 12:48:30 PM
www.finebook.ir

---