Nmap Development: Re: Finalized NSE Documentation System

["Patrick Donnelly" <batrick.donnelly () gmail com>]

On Thu, Jul 3, 2008 at 2:45 AM, Fyodor <fyodor () insecure org> 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