Re: Finalized NSE Documentation System

[Kris Katterjohn <katterjohn () gmail com>]

-----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#options
> > Where 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