Re: Finalized NSE Documentation System

[Kris Katterjohn <katterjohn () gmail com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Patrick Donnelly wrote:
> Hey Folks,

Hey Patrick,

> 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 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.

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?

> A point of divergence from LuaDoc is the standard NSE fields, such as
> "id" and "description", are used in the documentation. If there is no
> commented file description, then the NSE field is used. The same is
> true for using the author field if the author tag in the file comment
> is missing.

I like that.

> ==== 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 ;)

> 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 :)

> Cheers,

Thanks,
Kris Katterjohn

[1] http://seclists.org/nmap-dev/2008/q2/0567.html
[2] http://luadoc.luaforge.net/manual.html#howto


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iQIVAwUBSGwHqP9K37xXYl36AQLf0Q//Vcn7oQ0vKK4DEP2gRltJ29FGdKOcTHf/
G1CoIwUtv0m2+gFZdNNDIZQz3zprXT9uqYJVQiolYebbw2rjayj2unDw/8z0xf4k
OeZkFtxWp7mGN4bUYvqaSLRSvRGORMiVYQJTPl6LryX6kn9qLsWoHYSkj4gjfk8Z
YleeKSIgQm55RYCsORlHcDydPzYMbdvUIOec2c1gzVQD/NzQzghquhpo0cQxM/X5
mRC9NgCzIx+SPte60/FpGtdTtf1YeV1a0perqj/riwiLTB9Kt9bim4nCS0Ql/hyW
RU8D2VPgPSDtid839OJJ82bXvGvMin1agtf+A2uKSb1jnH4HRZLAeHXU0VFeMrGy
KrjipzOpAzib5KIvp6WCpq2LcuJDGRJHPpQ1ntZpON2pvglsGN7ESBwUEB7sifbs
ZEOqwAszHBPD4derwIROGz3r+SJE5QKO7WhRwIe2m/2INS70des54fUsZGdXrEGO
2jxMthotNCYsDg66wrOs/sLPWIH6mD5+L5BlXbzqpZ6JfV6szb5ir0rpHfx8Zt/r
yl8Co/UeM+5O0BuwqyHFnJRyINx3cjaoobxHr1XTZr526nCk9+KJv05tQavWjZXX
NDnMyKGsC+GGn4igcrZI73HADRXvI8QgjVYkJG+uDZLrjAfChx9AZoS0ldkmslhx
5zCVroTlFB8=
=aNPF
-----END PGP SIGNATURE-----

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