[OSM-dev] --help for various tools needed

Ulf Lamping ulf.lamping at googlemail.com
Sun Jan 25 12:30:13 GMT 2009


Joerg Ostertag (OSM Tettnang/Germany) schrieb:
> Hi,
> 
> as most of you already know, I am trying to compile and generate packages for 
> various software tools inside openstreetmap. For all these tools to be 
> helpfull, it is absoluteley necessary to have som documentation (man pages) 
> and Commandline --help output.
> So I would like to as al of you to recheck all the tools you wrote or added 
> some code to if they have a commandlinehelp or even better to have a small 
> man-page.
> If you don't know how to integrate these man-pages, please drop me a small 
> note and I can assist you in this.
> I only don't want to reverse engeneer every single too to find out what it 
> does.
> 

Perfectly agree with you here.

Some comments:
a) Man page in html format
It's a good idea to make the man page available in html format (often 
simply a conversion option). This way it can be made available on the 
web for a quick look and is also accessible on Windows systems where the 
normal man page format is usually not readable.

b) If no further command line options available - say so
Even if the program in question has no command line options (what a 
shame!), it is very nice if --help just says something like "we don't 
support further command line options" - so as a user you don't have to 
search the web to find out exactly that.

c) Balance between GUI help and man page
Trying to describe GUI programs in a man page doesn't work very well 
IMHO. To reduce double work, it's usually a good idea to make the GUI 
related help available from the main menu Help/Contents and put the 
command line options in the man page. Then link at the appropriate 
places to each other.

d) Windows uses /?
Programs especially intended towards windows systems (e.g. the .Net 
based programs), should better use /? to get the command help. That's 
the common way here. Of course, a help through --help is a lot better 
than nothing :-)

Regards, ULFL




More information about the dev mailing list