Re: usage examples versus syntax

[David Fifield <david () bamsoftware com>]

On Thu, Aug 11, 2011 at 08:44:39PM +0300, Toni Ruottu wrote:
> The usage example in bittorrent-discovery script got my attention. It
> looks as follows...
>
> nmap --script bittorrent-discovery --script-args
> bittorrent-discovery.torrent=<filename>,
> bittorrent-discovery.magnet=<magnet_link>[,bittorrent-discovery.dht_timeout=<seconds>]
> [,bittorrent-discovery.nodes-only][,bittorrent-discovery.peers-only][,newtargets]
>
> The usage example has lots of slots to be filled in. I have understood
> that the usage examples should show how a user might typically run the
> script, not the full potential that it has with all available
> parameters. The policy has not been very strict, but the goal in
> writing examples should be as little options as possible. I would use
> "example.torrent" instead of <filename>. Sometimes we have used
> <address> and I do not know why. I think using "example.com" would be
> better. Maybe this is just an accident.
>
> This raises some questions:
> - would everyone be ok with replacing all slots in all existing
> examples with actual examples?

My thinking about the examples is that they should only show common or
noteworthy uses. I think of it from the perspective of someone who
doesn't know how to run NSE: what command do I need to type to get some
output from this script? If that command works, great. If not, they can
start experimenting with other script arguments.

> - do we have support for multiple examples for each script?

Yes, I think so.

> - do we need a separate syntax line which would be close to the one used here?

I don't think so.

David Fifield
_______________________________________________
Sent through the nmap-dev mailing list
http://cgi.insecure.org/mailman/listinfo/nmap-dev
Archived at http://seclists.org/nmap-dev/