Nmap Development mailing list archives
Re: Finalized NSE Documentation System
From: Kris Katterjohn <katterjohn () gmail com>
Date: Wed, 02 Jul 2008 22:47:31 -0500
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Patrick Donnelly wrote:
Hi Kris, On Wed, Jul 2, 2008 at 4:56 PM, Kris Katterjohn <katterjohn () gmail com> wrote:The current version of NSEDoc can be seen in my branch at nmap-exp/patrick/nsedoc/src There are three directories in this path of interest: nselib and scripts (some scripts from /nmap/scripts|nselib but with the new documentation), as well as docs which holds the current output (documentation) for the files in those directores.But when this is moved to /nmap, it will take the scripts and libraries straight from /nmap/scripts and /nmap/nselib, right?The current plan is NSEDoc will be packaged separately from Nmap. Developers should be able to download it to create documentation. Nmap will ship with documentation already made.
Oh OK, that's a good idea too :)
The tags are documented by LuaDoc here: http://luadoc.luaforge.net/manual.html#tags In addition to those tags are "args", "summary", and "output". Documented below: -- @args These are the args given to the file through --script-args switch. The first alphanumeric word (literally matching ([%w%p]+) in Lua) is used as the name for the argument, the rest is its description. This tag is only used for the file comment.Looking up %p, I see that that's for any punctuation characters, but what about spaces? What if the argument has a space in it because the user wants to acknowledge a scoped-down argument in the fashion you do here[1]? Probably not common at all, but it hit me initially.That's an interesting point. Perhaps we should require the "argument" should be surrounded by quotes, otherwise use the first alphanumeric-punctuated word?
Sounds good to me.
Maybe allow quotation marks around the argument name?
==== USE ==== The typical method for producing documentation is: "./nsedoc.lua -d docs scripts nselib". All the command line switches are documented here: http://luadoc.luaforge.net/manual.html#optionsWhere is this nsedoc.lua located?/nmap-exp/patrick/nsedoc/src/nsedoc.lua
Sorry, but I'm still not seeing it: kjak@Meryl:~/[...]/nmap-exp/patrick$ svn up <snip externals> At revision 8611. kjak@Meryl:~/[...]/nmap-exp/patrick$ find . -name 'nsedoc.lua' kjak@Meryl:~/[...]/nmap-exp/patrick$ cd nsedoc/src kjak@Meryl:~/[...]/nmap-exp/patrick/nsedoc/src$ ls anonFTP.nse docs luadoc luadoc.bat luadoc.lua.in nselib scripts kjak@Meryl:~/[...]/nmap-exp/patrick/nsedoc/src$ svn info nsedoc.lua nsedoc.lua: (Not a versioned resource) I'm going to feel really stupid now if it's my fault :)
==== HOW IT WORKS ==== The system is well documented by LuaDoc here: http://luadoc.luaforge.net/architecture.html#architecture I have substituted a parser for NSE that is mostly equivalent to LuaDoc's parser except it acquires NSE fields and makes substitutions.Can you add the require statements to the parser? I didn't notice these anywhere looking at the html docs. In the future I can see people having their own libraries and scripts, and having the documentation on their website. Since required libraries may or may not be shipped with Nmap proper, this can make it easy to see the requirements. Plus I'm the curious type ;)That sounds like a good idea. I'll see about adding that.
Great.
Please post any questions or comments here.So, from reading this[2], I take it the only way that something is added to the docs is if it starts with those three minuses? Because I was thinking that the doc system can use modifiers like Ruby's RDoc :startdoc:, :stopdoc: and :nodoc: . But if docs are *only* generated with the three minuses, then it probably doesn't matter. I'm just wondering about any gotchas :)Documentation system uses the three minuses as a start. No gotchas :)
Good stuff.
Thanks,
Thanks, Kris Katterjohn -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iQIVAwUBSGxL0f9K37xXYl36AQJSfBAAqVOSF6HqMPlVy7aGKP+jZdGzn7M1YZmP 8l8ieFKEktjPiDSWAQO6DwWQ2YTbS4OX2t/IpY5Rv40AGdTWg5b5KenjPbfaty5e GPXD6YYZWFhXB7IBy9H6IzaejiVpAgc8XhWvHRaZCFsz212Qy3nuSDcqmL2E0uFF VZDQaxaCn2rh9NiBuuDMbtxBJex8WxnKdOCg1yqr8HFTXBYqu1tUT/4XZqjVWKu7 TDEA5K/76OKWTE8Og90ruvCrT0SJ1AUPiX9TSXVU5rLRVbsXnUEyZ8ibY3ZU7ol6 oWkbeG0opVxoHxEkSH3s4hXnvd/Z3vW6dEYTsnL3SoyZnzb1RhJxpF0OEQGfaui/ bH8cPALK/kl+K78Hh57GsWggbhGk/NfYOBH5UXBD+aWj5APvzmAo1z8JZM5ozwGn vI3kFFHyWJRcjqtt3IBmxlJlcbyBkst4A5MPgseOxoEuZ6fGc84xIQpqVfRDMYhu GSV0lhV15LmK1lFB7S6IW6Z22XzvNUNZiFA6/k/ZbuRpEk+AH1izfwMV17W6MXU2 pnM38Z3yzqSNuEnw0wjokvv+aiJOzQA4iVYxB8Cg5JZNgem5REhnM7rTVkh95Ocd AXlEmh1lc1Sdv1JHpUhZ3QwuGYY4JdrC7SBCA+zlAdZVFhVTtSLL+wfaoWANMNAc CCov7X6PHNE= =b43k -----END PGP SIGNATURE----- _______________________________________________ Sent through the nmap-dev mailing list http://cgi.insecure.org/mailman/listinfo/nmap-dev Archived at http://SecLists.Org
Current thread:
- Re: Finalized NSE Documentation System DePriest, Jason R. (Jul 02)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 02)
- <Possible follow-ups>
- Re: Finalized NSE Documentation System Kris Katterjohn (Jul 02)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 02)
- Re: Finalized NSE Documentation System Kris Katterjohn (Jul 02)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 02)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 02)
- Re: Finalized NSE Documentation System Fyodor (Jul 03)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 08)