mailing list archives
Finalized NSE Documentation System
From: "Patrick Donnelly" <batrick.donnelly () gmail com>
Date: Fri, 27 Jun 2008 22:25:30 -0600
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:
The current version of NSEDoc can be seen in my branch at
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 summary in one sentence. Continued description.
-- continued description
-- @tag description
-- above tags continued description
-- @tag2 description
--- Function description.
-- () tag description
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:
In addition to those tags are "args", "summary", and "output". Documented below:
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.
This is the summary which can be used instead of what normally is
the first sentence of the File's description.
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
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
==== HOW IT WORKS ====
The system is well documented by LuaDoc here:
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:
<title><% =file_doc.title %></title>
<%if file_doc.name:sub(-4) == ".nse" then %>
<% else %>
<% end %>
if file_doc.name:sub(-4) == ".nse" then
You can see various looping and control constructs can influence how a
file is constructed.
Please post any questions or comments here.
"One of the lessons of history is that nothing is often a good thing
to do and always a clever thing to say."
Sent through the nmap-dev mailing list
Archived at http://SecLists.Org
- Finalized NSE Documentation System Patrick Donnelly (Jun 28)