Nmap Development mailing list archives
Re: Finalized NSE Documentation System
From: "Patrick Donnelly" <batrick.donnelly () gmail com>
Date: Tue, 8 Jul 2008 07:50:48 -0600
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/srcI 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
Current thread:
- Re: Finalized NSE Documentation System DePriest, Jason R. (Jul 02)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 02)
- <Possible follow-ups>
- Re: Finalized NSE Documentation System Kris Katterjohn (Jul 02)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 02)
- Re: Finalized NSE Documentation System Kris Katterjohn (Jul 02)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 02)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 02)
- Re: Finalized NSE Documentation System Fyodor (Jul 03)
- Re: Finalized NSE Documentation System Patrick Donnelly (Jul 08)