Finalized NSE Documentation System
|
View:
New views
9 Messages
—
Rating Filter:
Alert me
|
 |
Finalized NSE Documentation System
by Patrick Donnelly-2
::
Rate this Message:
Hey Folks,
There have been some changes to how the NSE Documentation System works since I last posted (see: http://seclists.org/nmap-dev/2008/q2/0739.html). The doc system is now built on LuaDoc. It has one dependency, LuaFileSystem, which can be downloaded here: http://luaforge.net/frs/?group_id=66 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. ==== FILE FORMAT AND TAGS ==== The documentation for a file should be in the following format: <file> --- File summary in one sentence. Continued description. -- continued description -- @tag description -- above tags continued description -- @tag2 description --- Function description. -- continued... --@tag description function dostuff() end </file> A file's summary uses the first sentence in the description for use as a "short" synopsis of its purpose in the index html document. 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. -- @summary This is the summary which can be used instead of what normally is the first sentence of the File's description. -- @output This is used to show the typical output of a script. Use "\n" to force a line break where you please. ==== 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 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. ==== 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. The documentation framework in nsedoc/src/luadoc/doclet/html/* follow use a form of tags that allow you to interweave Lua code with the documentation itself. Lua code is placed in <% code %> tags. Lua code in <%= %> tags are evaluated as a statement and written to the file. All other information in the document is placed in an output function a a string. An example: <head> <title><% =file_doc.title %></title> </head> <%if file_doc.name:sub(-4) == ".nse" then %> Script <% else %> File <% end %> becomes f:write("<head> <title>") f:write(file_doc.title) f:write("</title> </head>") if file_doc.name:sub(-4) == ".nse" then f:write("Script") else f:write("File") end You can see various looping and control constructs can influence how a file is constructed. ==== Please post any questions or comments here. Cheers, -- -Patrick Donnelly "One of the lessons of history is that nothing is often a good thing to do and always a clever thing to say." -Will Durant _______________________________________________ Sent through the nmap-dev mailing list http://cgi.insecure.org/mailman/listinfo/nmap-dev Archived at http://SecLists.Org |
|
|
Re: Finalized NSE Documentation System
by DePriest, Jason R.
::
Rate this Message:
On Sat, Jun 28, 2008 at 5:25 AM, Patrick Donnelly <> wrote:
[- - - - cut lots of things - - - - -] > > ==== > > Please post any questions or comments here. > > Cheers, > > -- > -Patrick Donnelly > I have a dumb question. Can the documentation be embedded in the script itself (like perl module files) or so we need to create a separate xml file for the docs? -Jason _______________________________________________ Sent through the nmap-dev mailing list http://cgi.insecure.org/mailman/listinfo/nmap-dev Archived at http://SecLists.Org |
|
|
Re: Finalized NSE Documentation System
by Kris Katterjohn-2
::
Rate this Message:
-----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 |
|
|
Re: Finalized NSE Documentation System
by Patrick Donnelly-2
::
Rate this Message:
Hi,
On Wed, Jul 2, 2008 at 3:45 PM, DePriest, Jason R. <jrdepriest@...> wrote: > On Sat, Jun 28, 2008 at 5:25 AM, Patrick Donnelly <> wrote: > [- - - - cut lots of things - - - - -] >> >> ==== >> >> Please post any questions or comments here. >> >> Cheers, >> >> -- >> -Patrick Donnelly >> > > I have a dumb question. Can the documentation be embedded in the > script itself (like perl module files) or so we need to create a > separate xml file for the docs? example script (anonFTP.nse) and library (stdnse.lua) you can look at (it seems I forgot to do that). Cheers, -- -Patrick Donnelly "One of the lessons of history is that nothing is often a good thing to do and always a clever thing to say." -Will Durant _______________________________________________ Sent through the nmap-dev mailing list http://cgi.insecure.org/mailman/listinfo/nmap-dev Archived at http://SecLists.Org |
|
|
Re: Finalized NSE Documentation System
by Patrick Donnelly-2
::
Rate this Message:
Hi Kris,
On Wed, Jul 2, 2008 at 4:56 PM, Kris Katterjohn <katterjohn@...> 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. >> 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? > 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 >> ==== 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. >> >> 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 :) Thanks, -- -Patrick Donnelly "One of the lessons of history is that nothing is often a good thing to do and always a clever thing to say." -Will Durant _______________________________________________ Sent through the nmap-dev mailing list http://cgi.insecure.org/mailman/listinfo/nmap-dev Archived at http://SecLists.Org |
|
|
Re: Finalized NSE Documentation System
by Kris Katterjohn-2
::
Rate this Message:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1 Patrick Donnelly wrote: > Hi Kris, > > On Wed, Jul 2, 2008 at 4:56 PM, Kris Katterjohn <katterjohn@...> 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 |
|
|
Re: Finalized NSE Documentation System
by Patrick Donnelly-2
::
Rate this Message:
On Wed, Jul 2, 2008 at 9:47 PM, Kris Katterjohn <katterjohn@...> wrote:
>>> 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 :) No I believe I get to feel really stupid; somehow that didn't get added (it's there now). Thanks, -- -Patrick Donnelly "One of the lessons of history is that nothing is often a good thing to do and always a clever thing to say." -Will Durant _______________________________________________ Sent through the nmap-dev mailing list http://cgi.insecure.org/mailman/listinfo/nmap-dev Archived at http://SecLists.Org |
|
|
Re: Finalized NSE Documentation System
by Fyodor
::
Rate this Message:
On Fri, Jun 27, 2008 at 10:25:30PM -0600, Patrick Donnelly wrote:
> > There have been some changes to how the NSE Documentation System works > since I last posted Hi Patrick. I'm glad to hear this, as I consider an NSE documentation system to be one of the most important projects for this summer. We can't have a successful system with hundreds or thousands of scripts and many libraries unless we have a great way to document those online. For example, Nessus has http://nessus.org/plugins/ and Metasploit has http://metasploit.com:55555/PAYLOADS . > The current version of NSEDoc can be seen in my branch at > nmap-exp/patrick/nsedoc/src I took a look and have a few comments: o I like that it has a template directory. I assume this will make it easy for me to add the Nmap.Org headers and footers to each page? o I noted previously that the scripts documentation had a .nse extension rather than .html. It looks like you've fixed that, but src/docs/index.html still tries to reference them with their old names. The same is true of the index on the left column of script documentation. The NSE libraries don't have this problem. They show as .lua on the sidebar (to clarify what they are documenting), but the actual link points to the documentation .html file. o It is good that you have 5 example scripts using the documentation, but it would be nice to document them more completely so they serve as shining examples of the system. For example, none of them have a description of more than 2 lines. o The Nmap pages are HTML, not XHTML. The concern is whether then Nmap page headers and footers will work with this. I think they might work just fine, since this is using very simple XHTML which might be compatable with normal HTML. Can you try adding the nmap.org header and footers? If you save the html from nmap.org, I think it will be easy to figure out where the content goes. o It is great that normal lua variables can still be used for some of the fields, such as categories. o You suggested having an index by script category. I think that is a great idea. o None of the current scripts show NSE arguments as far as I can tell. It would be nice to see an example of a script which takes arguments. Documenting the NSE arguments is one of the most important features IMHO, as we don't really have anywhere else to document them. I'm not sure what to do about arguments which are dealt with by libraries loaded by a script. If the scripts can point to the libraries they use, and those libraries document the options they take, that may be enough. For example, a script may use Kris' unpw library or Philip's upcoming SNMP library and, by virtue of that, accept NSE arguments specifying the password list or cummunity string to use. o The W3C XHTML verifier is great, but I don't think we need to include the button on every page. Especially if we end up sticking the code within html rather than xhtml. o We need to get all the scripts and libraries documented somehow. Sine we are starting relatively early (fewer than four dozen scripts are available now), it won't be as hard as if we had waited until we had hundreds of scripts. For new scripts, we'll require that they already have documentation. o Once we have the scripts and libraries documented, I'd like to generate full docs and post them on nmap.org. o There is also the matter of documenting the new documentation system in scripting.xml. o At some point we might even consider making the script output docbook xml format (in addition to html). Then we could more easily create nice PDFs. o I like that the format is very simple and clean. Personally, I think we have a winner here. I hope other people will check it out and send comments too. And after some of these issues are addressed, I'd like to get it posted! Cheers, Fyodor _______________________________________________ Sent through the nmap-dev mailing list http://cgi.insecure.org/mailman/listinfo/nmap-dev Archived at http://SecLists.Org |
|
|
Re: Finalized NSE Documentation System
by Patrick Donnelly-2
::
Rate this Message:
On Thu, Jul 3, 2008 at 2:45 AM, Fyodor <fyodor@...> wrote:
> On Fri, Jun 27, 2008 at 10:25:30PM -0600, Patrick Donnelly wrote: >> The current version of NSEDoc can be seen in my branch at >> nmap-exp/patrick/nsedoc/src > > I took a look and have a few comments: > > o I like that it has a template directory. I assume this will make it > easy for me to add the Nmap.Org headers and footers to each page? Yes. It's simple to modify the templates for the documents. Adding headers and footers should be as easy as pasting the html. > o I noted previously that the scripts documentation had a .nse > extension rather than .html. It looks like you've fixed that, but > src/docs/index.html still tries to reference them with their old > names. The same is true of the index on the left column of script > documentation. The NSE libraries don't have this problem. They > show as .lua on the sidebar (to clarify what they are documenting), > but the actual link points to the documentation .html file. This has been fixed. > o It is good that you have 5 example scripts using the documentation, > but it would be nice to document them more completely so they serve as > shining examples of the system. For example, none of them have a > description of more than 2 lines. I left some scripts the way they were to show a more "default" look to the file. The scripts I did document further were either simple to begin with or did things I don't fully understand. I'm hoping the community begins contributing detailed descriptions for the default scripts. > o The Nmap pages are HTML, not XHTML. The concern is whether then > Nmap page headers and footers will work with this. I think they > might work just fine, since this is using very simple XHTML which > might be compatable with normal HTML. Can you try adding the > nmap.org header and footers? If you save the html from nmap.org, I > think it will be easy to figure out where the content goes. Sure. > o None of the current scripts show NSE arguments as far as I can tell. > It would be nice to see an example of a script which takes > arguments. Documenting the NSE arguments is one of the most > important features IMHO, as we don't really have anywhere else to > document them. I'm not sure what to do about arguments which are > dealt with by libraries loaded by a script. If the scripts can > point to the libraries they use, and those libraries document the > options they take, that may be enough. For example, a script may > use Kris' unpw library or Philip's upcoming SNMP library and, by > virtue of that, accept NSE arguments specifying the password list or > cummunity string to use. I'll get a script in that demonstrates this. Getting the documentation to link to modules (libraries) it uses is another item I will add. I think having a link in the arguments section to the arguments of libraries' the script uses will be useful. > o The W3C XHTML verifier is great, but I don't think we need to > include the button on every page. Especially if we end up sticking > the code within html rather than xhtml. I'll get that removed, it's an artifact of the old LuaDoc file template. > o We need to get all the scripts and libraries documented somehow. > Sine we are starting relatively early (fewer than four dozen scripts > are available now), it won't be as hard as if we had waited until we > had hundreds of scripts. For new scripts, we'll require that they > already have documentation. I can try to get several scripts going in terms of documentation, but I feel I may not fully understand the techniques they are using. Perhaps starting it out will be enough and others will contribute more thorough descriptions as I mentioned earlier. > o There is also the matter of documenting the new documentation system > in scripting.xml. I'll get this done also. Cheers, -- -Patrick Donnelly "One of the lessons of history is that nothing is often a good thing to do and always a clever thing to say." -Will Durant _______________________________________________ Sent through the nmap-dev mailing list http://cgi.insecure.org/mailman/listinfo/nmap-dev Archived at http://SecLists.Org |
anonFTP.nse (1K) 
| Free Forum Powered by Nabble | Forum Help |