Re: Finalized NSE Documentation System

[Fyodor <fyodor () insecure org>]

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