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
Received on Jul 03 2008
Intro
