usage examples versus syntax

[Toni Ruottu <toni.ruottu () iki fi>]

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?
- do we have support for multiple examples for each script?
- do we need a separate syntax line which would be close to the one used here?

  just wondering, --Toni
_______________________________________________
Sent through the nmap-dev mailing list
http://cgi.insecure.org/mailman/listinfo/nmap-dev
Archived at http://seclists.org/nmap-dev/