-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Patrick Donnelly wrote:
> Hi Kris,
>
> On Wed, Jul 2, 2008 at 4:56 PM, Kris Katterjohn <katterjohn_at_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#options
>>>
>> Where is this nsedoc.lua located?
>
> /nmap-exp/patrick/nsedoc/src/nsedoc.lua
>
Sorry, but I'm still not seeing it:
kjak_at_Meryl:~/[...]/nmap-exp/patrick$ svn up
<snip externals>
At revision 8611.
kjak_at_Meryl:~/[...]/nmap-exp/patrick$ find . -name 'nsedoc.lua'
kjak_at_Meryl:~/[...]/nmap-exp/patrick$ cd nsedoc/src
kjak_at_Meryl:~/[...]/nmap-exp/patrick/nsedoc/src$ ls
anonFTP.nse docs luadoc luadoc.bat luadoc.lua.in nselib scripts
kjak_at_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
Received on Jul 02 2008
Intro
